User:Kernelmethod/Sandbox
Modding Tutorial: Snapjaw Wizards!
Welcome! If you're looking to get started with modding Caves of Qud, this tutorial is a good place to start.
In this tutorial, we're going to add a new creature to the game -- the great and mystical snapjaw wizard. Along the way we're going to be helped by my friends Rulimispruce, legendary sprouting orb and Pyovya, legendary mopango.
< | Howdy! |
< | Let's get started! |
Getting started
TODO:
- Setting up development environment
- Where to find game files.
- Player.log
- How to perform a wish
- The _Quickstart game option
Prerequisites:
- Have played through a good chunk of Qud
Basic concepts
XML
- What is XML?
- Tags vs attributes
Wishes
Creating a mod
- Adding new mod with
manifest.json
to theMods/
folder. - At the end of this section, modders should have a no-op mod that appears in their mods list.
SnapjawWizard
├── manifest.json
└── preview.png
Your first creature
Adding a new creature to Creatures.xml
In your mod directory, create a new folder called ObjectBlueprints/
, and within that folder open up a new file in your text editor called Creatures.xml
. Let's start by adding the following to Creatures.xml
:
<?xml version="1.0" encoding="utf-8" ?>
<objects>
</objects>
Save this file! Before continuing, make sure your mod directory looks something like this:
SnapjawWizard
├── manifest.json
├── ObjectBlueprints
│ └── Creatures.xml
└── preview.png
With that out of the way, let's start adding our new snapjaw wizard to Creatures.xml
:
<?xml version="1.0" encoding="utf-8" ?>
<objects>
<object Name="Pyovya_SnapjawWizard_Snapjaw Wizard" Inherits="Snapjaw">
</object>
</objects>
Let's break this down:
- The
object
tag tells Qud that we want to add a new creature. - The
Name
attribute is a unique identifier for our new creature (it's not the name of the creature as it appears in-game -- we'll get to that shortly). You'll use this identifier whenever you want to wish for a new snapjaw wizard. - The
Inherits
attribute says that our new creature should "inherit" all of the properties of theSnapjaw
creature.
< | Hey, why'd you add the Pyovya_SnapjawWizard bit to the front of the name of the creature? Why not just call it a Snapjaw Wizard ?
|
So far we haven't actually added anything to our new creature; for all intents and purposes it's a plain ol' snapjaw. Let's change that by adding some parts.
< | What's a part? |
< | A part is a special piece of code that can be added to a creature to modify its appearance, behavior, stats, and any number of other things. There are a lot of parts -- over a thousand! You won't need to worry about most of them; many of them are highly-customized bits of code written for just one or two creatures. For instance, there's a CryptSitterBehavior part that is used exclusively by crypt sitters.
|
We're going to add two new parts to our creature: Render
and Description
.
<?xml version="1.0" encoding="utf-8" ?>
<objects>
<object Name="Pyovya_SnapjawWizard_Snapjaw Wizard" Inherits="Snapjaw">
<part Name="Description" Short="A great hero of the snapjaws." />
<part Name="Render" DisplayName="snapjaw wizard" Tile="Assets_Content_Textures_Creatures_sw_snapjaw_warrior.bmp" ColorString="&Y" DetailColor="R" />
</object>
</objects>
Before I did into the new XML we've added, save Creatures.xml
. Reload your mods, start a new game and wish for a Pyovya_SnapjawWizard_Snapjaw Wizard
. You should a new snapjaw like the one below show up:
(IMAGE HERE, INCLUDING DESCRIPTION OF SNAPJAW)
Congrats! You've successfully added a snapjaw wizard to your game.
< | I did? |
Well, it's still a little bare-bones, but you have indeed created a new creature called a snapjaw wizard
and spawned it in your game! Give yourself a pat on the back, Rulimispruce.
< | *rustling noises* |
Now, back to the parts that you just added:
- The
Description
part changes (as you might guess) the description of the creature when you look at it. - The
Render
attribute changes the creature's appearance, as well as its name (as it appears in-game). This tag has the following attributes:DisplayName
: how the creature's name is displayed in-game.Tile
: a .png or .bmp ("bitmap") image that's used to display the creature. Check out Modding:Tiles for more information. In the snippet above, I just used the tile for snapjaw warriors to get us started.ColorString
andDetailColor
: these are the primary and secondary colors used to color in the tile that you supply. You can look at Modding:Colors & Object Rendering for a full list of all of the available colors; in this case, we usedY
(white) as the primary color andM
(magenta) as the detail color.
Using custom tiles
Instead of having our snapjaw wizards look like off-color snapjaw warriors, let's add a snazzy new tile to the game to use for our wizards! Just pop open a pixel editor, create a 16px x 24px black-and-white tile, save it as a --
< | I'm just a lil old sprouting orb, I don't know how to do any of those things. |
Ah, alright, fair enough. Well in that case, feel free to download the tile that I've already made for you here:
DOWNLOAD LINK FOR NEW TILE
In your mod directory, create a new folder called Textures/
; in that folder, create a new subfolder called Pyovya_SnapjawWizard/
; and in there, create another subfolder called Creatures/
. Save snapjaw_wizard.png
there, so that your mod folder now looks like this:
SnapjawWizard
├── manifest.json
├── ObjectBlueprints
│ └── Creatures.xml
├── preview.png
└── Textures
└── Pyovya_SnapjawWizard
└── snapjaw_wizard.png
Now, let's change the Render
part for our wizards to use this new tile:
<part Name="Render" DisplayName="snapjaw wizard" Tile="Pyovya_Snapjaw/snapjaw_wizard.png" ColorString="&Y" DetailColor="R" />
Now when you spawn a snapjaw hero, it'll look something like this:
IMAGE
Cool!
Filling out your new creature
Let's keep adding some more stuff to our snapjaw wizard to round them out a bit more. First of all, like any good wizard, they need a walking stick and some books. Let's give them some clothes to equip while we're at it. Add the following XML to your creature:
<inventoryobject Blueprint="Walking Stick" />
<inventoryobject Blueprint="Woven Tunic" Number="1" />
<inventoryobject Blueprint="Sandals" Number="1" />
<inventoryobject Blueprint="StandaloneMarkovBook" Number="2-3" />
Let's give our wizard the Cudgel skill as well, so that they're a little bit better at fighting with that walking stick:
<skill Name="Cudgel" />
TODO: stats
TODO
<property Name="Role" Value="Artillery" />
TODO
<tag Name="DynamicObjectsTable:Snapjaws" />
<tag Name="AggregateWith" Value="Pyovya_SnapjawWizard_Snapjaw Wizard" />
<tag Name="BaseObject" Value="*noinherit" />
FINAL VERSION OF CREATURE XML BEFORE GOING TO THE NEXT SECTION
Using your creature as a base: Elemental Wizards
< | Hold up a second. How is this creature a wizard? It doesn't have any kind of magic spells! |
I was just getting to that!
So far, we've sketched out most of the properties, skills, and stats that a snapjaw wizard should have. Now we're going to create two types of wizards: fire wizards and ice wizards. Under your definition of the Pyovya_SnapjawWizard_Snapjaw Wizard
creature in Creatures.xml
, add two new creatures:
<?xml version="1.0" encoding="utf-8" ?>
<objects>
<!--
Skipped: the XML that defines the "Pyovya_SnapjawWizard_Snapjaw Wizard" creature
-->
<object Name="Pyovya_SnapjawWizard_Flame Wizard" Inherits="Pyovya_SnapjawWizard_Snapjaw Wizard">
</object>
<object Name="Pyovya_SnapjawWizard_Ice Wizard" Inherits="Pyovya_SnapjawWizard_Snapjaw Wizard">
</object>
</objects>
Referencing the Modding:Colors & Object Rendering page, we're going to change our fire wizard's detail color to red. We're also going to give them the Flaming Ray mutation:
<object Name="Pyovya_SnapjawWizard_Flame Wizard" Inherits="Pyovya_SnapjawWizard_Snapjaw Wizard">
<part Name="Render" DisplayName="snapjaw wizard of {{R|fire}}" Tile="Pyovya_SnapjawWizard/snapjaw_wizard.png" ColorString="&Y" DetailColor="R" />
<mutation Name="FlamingHands" Level="1" BodyPartType="Hands" CreateObject="false" />
</object>
TODO: explain syntax for changing text color.
TODO: explain what's going on in the <mutation>
tag.
<object Name="Pyovya_SnapjawWizard_Ice Wizard" Inherits="Pyovya_SnapjawWizard_Snapjaw Wizard">
<part Name="Render" DisplayName="snapjaw wizard of {{C|ice}}" Tile="Pyovya_SnapjawWizard/snapjaw_wizard.png" ColorString="&Y" DetailColor="R" />
<mutation Name="FreezingHands" Level="1" BodyPartType="Hands" CreateObject="false" />
</object>
TODO:
- Inherit from the Snapjaw Hero
- Add mutations, change colors