Editing User:Deon

= Greetings =
I'm a dedicated member of our great community so I wanted to organize a bit some of my things I already wrote for the community which are lost in swarms of forum threads.
They may be useful for someone.
I don't have a time for now to organize them but I hope they are understandable.

= Guides =

== What is a tileset and how the graphics are determined? ==
http://www.bay12games.com/forum/index.php?topic=21176.msg227109#msg227109

== Essential tags of a creature ==
http://www.bay12games.com/forum/index.php?topic=21045.msg225768#msg225768

= Game Modifications =

[http://http://www.bay12games.com/forum/index.php?topic=18703.0 Middle-Earth mod (39+ compatible)]

[http://http://www.bay12games.com/forum/index.php?topic=18623.0 Mods and components for Mod Base]

=How to=

==How to add a new creature==

Let's add a completely new creature with a custom body which will be modular (will not overwrite any content) and will be easy to install.
Note that even if the creature was designed right it won't appear in your world until you generate a new one.

I want to make a tripod creature.
It has 3 legs, a tentacle as tail and a hand with 3 sharp fingers instead of head with a single eye on the palm.

===Adding the body===

'''Body template'''

File with a name body_template.txt

 body_template
 
 [OBJECT:BODY]
 
 [BODY:BODY1]
 [BP:BP1:bodypart1]
 [BP:BP2:bodypart2]
 [BP:BP3:bodypart3]

Let's start with a body. I will use [[Body tokens]], you can read their descriptions there.
Make a body_tripod.txt text file in your /raw/objects folder.
According to the template the first string shold be the file name without the extension (.txt) and then you announce that the type of the content is body ([OBJECT:BODY]). Then we'll add a tripod body with no bodyparts still.

So now we have

 creature_tripod
 
 [OBJECT:BODY]
 
 [BODY:TRIPOD]

Now we want to start to build the body structure.
The main rule here is that if some bodypart was connected to another it should be listed after that.
I.e. if we had an eye which is connected to the head we should announce the head first and the eye next.

So we will start with the main "carrier" - upper body, other parts are connected to it or to other parts which are connected to it.
 [BP:UB:upper body][UPPERBODY]
* "BP" here indicates that it is a part of the announced BODY structure (TRIPOD).
* "UB" is a unique (inside this creature) identintificator.
* "upper body" is the displayed name. [UPPERBODY] token means that this is the main part where the chest armor would be worn if the creature could wear armor and also it can be "cloven asunder" etc.

 [BP:LB:lower body][COBTYPE:UPPERBODY][LOWERBODY]
* [CONTYPE:UPPERBODY] means that this part is connected to the part of this body which has the "UPPERBODY" token. Surprisingly it's UB (upper body) :).
* It could be [CON:UB] also, CONTYPE tries to attach the bodypart to every another part with the listed token while the CON connects to a single bodypart with the indicated unique identificator (UB for the upper body).

Let's add a front leg.
 [BP:FL:front leg][CONTYPE:UPPERBODY][LIMB][STANCE]

BP, FL, "front leg", CONTYPE are the same things as before. However there're 2 new tokens.
*[LIMB] means that this part is a limb and can be easily lopped off, also it allows wrestling with it.
*[STANCE] means that the creature uses this bodypart to stand. If the half of the total number of STANCE bodyparts is damaged the creature falls on the ground and cannot get up.

Two rear legs are added the same way, but they're connected to the lower body. 
 [BP:RRL:right rear leg][CONTYPE:LOWERBODY][LIMB][STANCE][RIGHT]
 [BP:LRL:left rear leg][CONTYPE:LOWERBODY][LIMB][STANCE][LEFT]
"Right" and "left" tokens do not require any special explanation.

Now we want a tail which can be used as a tentacle to wrestle and grab things.
 [BP:TAILT:tail tentacle][CONTYPE:LOWERBODY][LIMB][GRASP]
* Here goes the "GRASP" token, it allows creatures to pick up items and grab bodyparts.

So now we have.

 creature_tripod
 
 [OBJECT:BODY]
 
 [BODY:TRIPOD]
 [BP:UB:upper body][UPPERBODY][LOWERBODY]
 [BP:FL:front leg][CONTYPE:UPPERBODY][LIMB][STANCE]
 [BP:RRL:right rear leg][CONTYPE:LOWERBODY][LIMB][STANCE][RIGHT]
 [BP:LRL:left rear leg][CONTYPE:LOWERBODY][LIMB][STANCE][LEFT]
 [BP:TAILT:tail tentacle][CONTYPE:LOWERBODY][LIMB][GRASP]

Is it all right? No! We forgot the head-arm with a single eye.
We could make more bodyparts to finish the picture but I want to teach you how to use BODYGLOSS.

Simply BODYGLOSS just renames the things while leaving the contents unharmed.
Let's use a bit of imagination here.
We already have a head on other creatures and a single eye from cyclops.

Bodygloss syntax is:
 [BODYGLOSS:ID:original:new]
Where "ID" = unique identificator, "original" = the original name and the "new" is the name which replaces the original one.
So you use the already present bodypart but add a bodygloss reference after that to rename it while leaving it's functions. I'll show you.

But we wanted 3 fingers for the palm-head. They are not related to the structure above because they should be connected to the head which is not listed there. So let's make them as a new body.
 [BODY:HEAD_3FINGERS]
 [BP:HF1:first head finger][CONTYPE:HEAD][SMALL][DIGIT]
 [BP:HF2:second head finger][CONTYPE:HEAD][SMALL][DIGIT]
 [BP:HF3:third head finger][CONTYPE:HEAD][SMALL][DIGIT]
We use contype because it's safer to connect to an object with any ID and a [HEAD] token (it should definitely be on any kind of head) than to the specialized ID which may appear wrong.

Now let's make the bodygloss I described. Remember the syntax. We rename the usual head to head-palm and the usual cyclops'es eye to "eye on the palm"
 [BODYGLOSS:HEAD_PALM:head:head-palm]
 [BODYGLOSS:EYE_PALM:eye:eye on the palm]
Don't forget that every ID I use I take from my head, you can call it anything you want, just make it reasonable for modders to understand what the heck is that.

The full content of our new body file is.
 creature_tripod
 
 [OBJECT:BODY]
 
 [BODY:TRIPOD]
 [BP:UB:upper body][UPPERBODY][LOWERBODY]
 [BP:FL:front leg][CONTYPE:UPPERBODY][LIMB][STANCE]
 [BP:RRL:right rear leg][CONTYPE:LOWERBODY][LIMB][STANCE][RIGHT]
 [BP:LRL:left rear leg][CONTYPE:LOWERBODY][LIMB][STANCE][LEFT]
 [BP:TAILT:tail tentacle][CONTYPE:LOWERBODY][LIMB][GRASP]

 [BODY:HEAD_3FINGERS]
 [BP:HF1:first head finger][CONTYPE:HEAD][SMALL][DIGIT]
 [BP:HF2:second head finger][CONTYPE:HEAD][SMALL][DIGIT]
 [BP:HF3:third head finger][CONTYPE:HEAD][SMALL][DIGIT]

 [BODYGLOSS:HEAD_PALM:head:head-palm]

 [BODYGLOSS:EYE_PALM:eye:eye on the palm]

Note that I leave empty lines between neighbouring structures, it's not necessary but it greatly improves the code's readability.

Let's look a bit forward and describe how the body is added to the creature. If you add no body to the creture it won't have any body parts to damage. The token is [BODY:<contents>]. Remember the order of body parts: '''if the A is connected to B then B should be listed before A'''.

We will need organs for our creature, I want a brain, a heart, lungs, organs, spine and guts. They are already present in body_default.txt so I'll use them. Don't be afraid to borrow bodyparts from original file or other files and don't hesistate to use bodygloss.

So a bit later we will have to put the full body in the creature information like this:
 [BODY:TRIPOD:HEAD:HEAD_3FINGERS:1EYE:BRAIN:HEART:2LUNGS:ORGANS:GUTS:SPINE]
Notice that I borrowed HEAD, 1EYE, BRAIn, HEART, 2LUNGS, ORGANS, GUTS and SPINE from body_default.txt.

The bodyglosses in creature raws are listed in 1 token and divided by ":" symbols.
 [BODYGLOSS:HEAD_PALM:EYE_PALM]

===Adding the creature===

'''Creature template'''

File with a name creature_template.txt

 creature_template
 
 [OBJECT:CREATURE]
 
 [CREATURE:CREATURE1]
 [NAME:creature:creatures:creature]
 [TILE:'C'][COLOR:1:0:1]
 [PREFSTRING:prefstring]

At first we should make a file. Let's call it "creature_tripod.txt". According to the syntax it should have the 1st string "creature_tripod" and then "[OBJECT:CREATURE]".
Let's make a tripod creature. I will use [[Creature tokens|creature tokens]], you can get the full list there.

 creature_tripod
 
 [OBJECT:CREATURE]
 
 [CREATURE:TRIPOD]
 [NAME:tripod:tripods:tripod]
 [TILE:'t'][COLOR:2:0:1]
 [PREFSTRING:three legs]
 [PREFSTRING:tentacle-tail]
I changed the tile and the [[Color|color]] (it will be displayed as a green "t" now).
Perfstring determines verbal characteristics of the creature, it's used for situations like "Urist McDwarf likes the Tripods for their three legs). Each prefstring is a separate token.

Now we want it to have a specific body. I already showed the right syntax and content in the "making the body" section so it will have (considering bodyglosses):
 [BODY:TRIPOD:HEAD:HEAD_3FINGERS:1EYE:BRAIN:HEART:2LUNGS:ORGANS:GUTS:SPINE]
 [BODYGLOSS:HEAD_PALM:EYE_PALM]

But the creature has no attacks. It will "push" it's victims which is not effective at all.
Let's add a few attack moves.
 [ATTACK:MAIN:BYTOKEN:TAILT:slash:slashes:1:4:GORE][ATTACKFLAG_WITH]
 [ATTACK:MAIN:BYTYPE:HEAD:scratch:scratches:1:4:SLASH][ATTACKFLAG_WITH][ATTACKFLAG_CANLATCH]
 [ATTACK:SECOND:BYTYPE:STANCE:kick:kicks:1:3:KICK][ATTACKFLAG_WITH]
* The first one one will enable it to attack with a specific bodypart (BYTOKEN) with the id "TAILT" (tail tentacle) and it will lash the target with the GORE type damage. ATTACKFLAG_WITH will add to the combat message the "with it's tail tentacle" string.
* The second one uses BYTYPE relation which means that the creature will attack with any of the bodyparts which has the HEAD token. ATTACKFLAG_CANLATCH means that it can latch on it's victim upon attack.
* The third one is SECONDARY so it will happen only if the first 2 are unavaliable (i.e. the tentacle is lopped off and the head-palm is grabbed). It uses BYTYPE relation so it will use any of the bodyparts with the "STANCE".

Don't forget to add the size parameter, it determines most things. I want it to be a bit bigger than a cow (cow's DF size is 9)
 [SIZE:10]
Also it will have the ablity to learn to swim and it will have a standard base swimming speed.
 [SWIMS_LEARNED][SWIMSPEED:2500]

So now we have the file creature_tripod.txt with the following contents:
 creature_tripod
 
 [OBJECT:CREATURE]
 
 [CREATURE:TRIPOD]
 [NAME:tripod:tripods:tripod]
 [TILE:'t'][COLOR:2:0:1]
 [PREFSTRING:three legs]
 [PREFSTRING:tentacle-tail]
 [BODY:TRIPOD:HEAD:HEAD_3FINGERS:1EYE:BRAIN:HEART:2LUNGS:ORGANS:GUTS:SPINE]
 [BODYGLOSS:HEAD_PALM:EYE_PALM]
 [ATTACK:MAIN:BYTOKEN:TAILT:slash:slashes:1:4:GORE][ATTACKFLAG_WITH]
 [ATTACK:MAIN:BYTYPE:HEAD:scratch:scratches:1:4:SLASH][ATTACKFLAG_WITH][ATTACKFLAG_CANLATCH]
 [ATTACK:SECOND:BYTYPE:STANCE:kick:kicks:1:3:KICK][ATTACKFLAG_WITH]
 [SWIMS_LEARNED][SWIMSPEED:2500]

But we need to do more to actually see the creature in game.
* We need to add biomes information (where the creature dwells).
* We need to add information about it's behaviour (size of clusters, how often is it spawned, is it roaming etc.)

Let's start with the biome information. Click the link to see the full list of the [[Biome tokens|biome tokens]].
I want tripods to live in all swamps and marshes, this I add
 [BIOME:ANY_WETLAND]
I want it to travel in loose clusters of 4-8.
 [CLUSTER_SIZE:4:8]
 [LOOSE_CLUSTERS]
Also I want it to attack it my adventurers so I set is as a wandering creature and a predator.
 [LARGE_ROAMING]
 [LARGE_PREDATOR]
At last let's set it's max world population and numbers for a fortress mode (min and max per year if they come).
 [POPULATION_NUMBER:8:16]

Let's add a few more "reasonable" tokens to make it more real.
 [MAXAGE:40:50]
 [DIURNAL]
 [FAT:2]
 [STANDARD_FLESH]
 [HOMEOTHERM:10067]
Thus we set the min/max life duration, a diurnal way of life, number of fat, avaliability of standard flesh and body temperature.

Now we have the finished creature file: creature_tripod.txt

 creature_tripod
 
 [OBJECT:CREATURE]
 
 [CREATURE:TRIPOD]
 [NAME:tripod:tripods:tripod]
 [TILE:'t'][COLOR:2:0:1]
 [PREFSTRING:three legs]
 [PREFSTRING:tentacle-tail]
 [BODY:TRIPOD:HEAD:HEAD_3FINGERS:1EYE:BRAIN:HEART:2LUNGS:ORGANS:GUTS:SPINE]
 [BODYGLOSS:HEAD_PALM:EYE_PALM]
 [ATTACK:MAIN:BYTOKEN:TAILT:slash:slashes:1:4:GORE][ATTACKFLAG_WITH]
 [ATTACK:MAIN:BYTYPE:HEAD:scratch:scratches:1:4:SLASH][ATTACKFLAG_WITH][ATTACKFLAG_CANLATCH]
 [ATTACK:SECOND:BYTYPE:STANCE:kick:kicks:1:3:KICK][ATTACKFLAG_WITH]
 [SWIMS_LEARNED][SWIMSPEED:2500]
 [BIOME:ANY_WETLAND]
 [CLUSTER_SIZE:4:8]
 [LOOSE_CLUSTERS]
 [LARGE_ROAMING]
 [LARGE_PREDATOR]
 [MAXAGE:40:50]
 [DIURNAL]
 [FAT:2]
 [STANDARD_FLESH]
 [HOMEOTHERM:10067]

Note that this creature is a dangerous one in the fortress mode because it doesn't have the [MEANDERER] token (random movement) so it will go straightly for your dwarves.