v50 Steam/Premium information for editors
  • v50 information can now be added to pages in the main namespace. v0.47 information can still be found in the DF2014 namespace. See here for more details on the new versioning policy.
  • Use this page to report any issues related to the migration.
This notice may be cached—the current version can be found here.

Difference between revisions of "Creature variation token"

From Dwarf Fortress Wiki
Jump to navigation Jump to search
 
(15 intermediate revisions by 8 users not shown)
Line 1: Line 1:
−
{{Quality|Tattered|12:39, 1 November 2021 (UTC)}}
+
{{Quality|Exceptional}}
 
{{av}}
 
{{av}}
−
Creature variations are used to create creatures which are derived from another already-existing creature without having to duplicate every single token. They are defined as CREATURE_VARIATION objects, and the default variations are defined in c_variation_default.txt
+
{{Modding}}
 +
Creature variations are templates for creatures. In conjunction with {{token|COPY_TAGS_FROM|c}} they may be used to create [[animal person|creatures which are derived]] [[giant animal|from another already-existing creature]], thus the name, though their use-case is broader than that, in vanilla also covering [[gait]]s and [[Creature_token#ATTACK|attacks]]. They may either be embedded inside creatures (when using {{token|APPLY_CURRENT_CREATURE_VARIATION|c}}) or be defined as CREATURE_VARIATION objects. The default variations are defined in c_variation_default.txt
  
−
From the raws:
+
Creature variations can be contrasted with the other types of templates for creatures: [[Tissue_definition_token|tissue templates]], [[Material_definition_token|material templates]], and [[body_detail_plan_token|body detail plans]]. Creature variations are the newest of the four ([https://www.bay12games.com/dwarves/dev_2009.html#2009-12-15 from 2009]) and also the most advanced.
  
−
Order of application:
+
Creature variations can add/convert almost all tokens, but {{token|APPLY_CREATURE_VARIATION|c}} is an exception, so you can’t nest creature variations.
−
Remove tags are applied starting from the bottom, then convert tags from the bottom, then add tags from the top.
+
{{clear}}
−
 
 
−
Arguments:
 
−
If APPLY_CREATURE_VARIATION in the creature raws sends in arguments, you can use them below as !ARG1, !ARG2, etc.  The GAIT variations below have some examples.  In the creature raws, if an argument is of the form "5|6", for example, it'll be converted to "5:6" in the creature variation, so you can handle variable-token arguments with the | character.
 
−
 
 
−
Conditional tags:
 
−
Change TAG to CTAG and add, for example, CV_REMOVE_CTAG:1:YES:<regular stuff> to require !ARG1 to be YES to execute the changes.
 
  
 
{| {{prettytable}}
 
{| {{prettytable}}
Line 23: Line 18:
 
| {{text anchor|CV_NEW_TAG}}
 
| {{text anchor|CV_NEW_TAG}}
 
|
 
|
−
*token (plus any additional parameters)
+
*token (including token arguments)
−
| Adds a new token to the creature's variant.
+
| Adds the given token to the target creature. E.g. [CV_NEW_TAG:BIOME:ANY_FOREST] gives the creature [BIOME:ANY_FOREST].
  
 
|-
 
|-
 
| {{text anchor|CV_ADD_TAG}}
 
| {{text anchor|CV_ADD_TAG}}
 
|
 
|
−
*token
+
*token (including token arguments)
 
| Alias for CV_NEW_TAG.
 
| Alias for CV_NEW_TAG.
  
Line 35: Line 30:
 
| {{text anchor|CV_REMOVE_TAG}}
 
| {{text anchor|CV_REMOVE_TAG}}
 
|
 
|
−
*token
+
*leading token (name and) arguments
−
| Removes a token from the creature's variant.
+
| Removes all tokens from the target creature which start with the given chain of token arguments. E.g. [CV_REMOVE_TAG:BODY:HUMANOID_SIMPLE] would remove [BODY:HUMANOID_SIMPLE:3_EYES], but [CV_REMOVE_TAG:BODY:3_EYES] would not. Neither would [CV_REMOVE_TAG:BODY:HUMANOID_SIMPLE] be able to remove [BODY:HUMANOID_SIMPLE_NECK:3_EYES], as it looks for whole arguments. [CV_REMOVE_TAG:BODY] would remove both examples above, as they start with "BODY".
  
 
|-
 
|-
−
| {{text anchor|CV_NEW_CTAG}}
+
| {{text anchor|CV_CONVERT_TAG}}
 
|
 
|
−
*ARG number
+
| Starts a conversion block, containing one {{token|CVCT_MASTER|cv}}, one {{token|CVCT_TARGET|cv}}, and one {{token|CVCT_REPLACEMENT|cv}}. Note that multiple conversion blocks are applied in what might appear as "reverse" order (see [[creature_variation_token#Application|Application]]).
−
*token
 
−
| As CV_NEW_TAG, but only activates if !ARG(num) is YES, e.g. CV_NEW_CTAG:1:YES:<regular stuff> to require !ARG1 to be YES to execute the changes.
 
  
 
|-
 
|-
−
| {{text anchor|CV_ADD_CTAG}}
+
| {{text anchor|CVCT_MASTER}}
 
|
 
|
−
*ARG number
+
*leading token (name and) arguments
−
*token
+
| Specifies which tokens of the target creature may be converted, by looking at full arguments at the start of said token (like {{token|CV_REMOVE_TAG|cv}}).
−
| Alias for CV_NEW_CTAG.
+
 
 +
If no CVCT_MASTER is given, it is given no arguments, or the only argument it is given is blank (i.e. [CVCT_MASTER:]), all tokens of the target creature are selected.
  
 
|-
 
|-
−
| {{text anchor|CV_REMOVE_CTAG}}
+
| {{text anchor|CVCT_TARGET}}
 
|
 
|
−
*ARG number
+
*string
−
*token
+
| Locates the specified string within all tokens specified by CVCT_MASTER.
−
| As CV_REMOVE_TAG with conditions as described above.
+
 
 +
If no CVCT_TARGET is given, it is given no arguments, or the only argument it is given is blank (i.e. [CVCT_TARGET:]), the game will freeze when loading the creature.
  
 
|-
 
|-
−
| {{text anchor|CV_CONVERT_TAG}}
+
| {{text anchor|CVCT_REPLACEMENT}}
 
|
 
|
−
| Begins altering tokens within the creature's variant using the CVCT_MASTER, CVCT_TARGET, and CVCT_REPLACEMENT tokens below. If a variation template contains multiple CV_CONVERT_TAG blocks for the same CVCT_MASTER, the replacements will be applied [http://bay12games.com/dwarves/mantisbt/view.php?id=6393#c24231 in reverse order].
+
*string
 +
| Replaces the string specified by CVCT_TARGET within the tokens specified by CVCT_MASTER. This means the targeted part of a token can be changed anywhere in the token, e.g.
 +
[CV_CONVERT_TAG]
 +
[CVCT_MASTER:BODY]
 +
[CVCT_TARGET:2EYES]
 +
[CVCT_REPLACEMENT:2EYESTALKS]
 +
would affect both [BODY:QUADRUPED_NECK:2EYES:NOSE:2LUNGS:...] and [BODY:INSECT:2EYES:HEART:GUTS:BRAIN:MOUTH:2WINGS], converting them into [BODY:QUADRUPED_NECK:2''EYESTALKS'':NOSE:2LUNGS:...] and [BODY:INSECT:2''EYESTALKS'':HEART:GUTS:BRAIN:MOUTH:2WINGS] respectively.
 +
Colons can be included as part of both the target and the replacement string, e.g. given
 +
[CV_CONVERT_TAG]
 +
[CVCT_MASTER:BODY]
 +
[CVCT_TARGET:BASIC_1PARTBODY:BASIC_HEAD]
 +
[CVCT_REPLACEMENT:HUMANOID:3FINGERS]
 +
and [BODY:BASIC_1PARTBODY:BASIC_HEAD:HEART:GUTS:BRAIN:MOUTH:2EYESTALKS], you will get [BODY:HUMANOID:3FINGERS:HEART:GUTS:BRAIN:MOUTH:2EYESTALKS]. All occurrences of the target string are replaced, e.g. given
 +
[CV_CONVERT_TAG]
 +
[CVCT_MASTER:DESCRIPTION]
 +
[CVCT_TARGET:TRAIT]
 +
[CVCT_REPLACEMENT:modderiffic]
 +
and [DESCRIPTION:This is an example creature. It is TRAIT, very very TRAIT.], you will get [DESCRIPTION:This is an example creature. It is modderiffic, very very modderiffic.].
 +
 
 +
If no CVCT_REPLACEMENT is given, the target string is simply removed.
  
 
|-
 
|-
−
| {{text anchor|CVCT_MASTER}}
+
| {{text anchor|CV_NEW_CTAG}}
 
|
 
|
 +
*!ARG number
 +
*value for !ARG to match
 
*token
 
*token
−
| Specifies the token that will be modified.
+
| Conditional variant of {{token|CV_NEW_TAG|cv}}, see [[creature_variation_token#Arguments and conditional tokens|Arguments and conditional tokens]].
  
 
|-
 
|-
−
| {{text anchor|CVCT_TARGET}}
+
| {{text anchor|CV_ADD_CTAG}}
 
|
 
|
−
*value
+
*!ARG number
−
| Locates the specified parameter within the token specified by CVCT_MASTER.
+
*value for !ARG to match
 +
*token
 +
| Alias for CV_NEW_CTAG.
  
 
|-
 
|-
−
| {{text anchor|CVCT_REPLACEMENT}}
+
| {{text anchor|CV_REMOVE_CTAG}}
 
|
 
|
−
*value
+
*!ARG number
−
| Replaces the parameter specified by CVCT_TARGET within the token specified by CVCT_MASTER. If no replacement is specified, the target will simply be removed.
+
*value for !ARG to match
 +
*token
 +
| Conditional variant of {{token|CV_REMOVE_TAG|cv}}, see [[creature_variation_token#Arguments and conditional tokens|Arguments and conditional tokens]].
  
 
|-
 
|-
 
| {{text anchor|CV_CONVERT_CTAG}}
 
| {{text anchor|CV_CONVERT_CTAG}}
 
|
 
|
−
| As CV_CONVERT_TAG with conditions.
+
*!ARG number
 +
*value for !ARG to match
 +
| Conditional variant of {{token|CV_CONVERT_TAG|cv}}, see [[creature_variation_token#Arguments and conditional tokens|Arguments and conditional tokens]]. Uses {{token|CVCT_MASTER|cv}}, {{token|CVCT_TARGET|cv}}, and {{token|CVCT_REPLACEMENT|cv}}, just as the former.
 
|}
 
|}
  
−
Creature variations are templates that creatures (CREATURE objects) may use.
+
== Application ==
  
−
Creature variations are not the only kind of templates for creatures, there are also tissue templates (TISSUE_TEMPLATE objects using tissue definition tokens, material templates (MATERIAL_TEMPLATE objects using material definition tokens), and body detail plans (BODY_DETAIL_PLAN objects using body detail plan tokens). Creature variations are the newest one of these, from 2009, and also the most advanced of the four. The reason they are called "creature variations" is presumably because they were initially made for the giant animals and animal people, variations of existing creatures, but this name is misleading. Creature variations are very general type of template, and creatures using creature variations do not need to be based on any other like the giant animals and animal people are. More examples will be given below, but creature variations are already used in the vanilla raws for gaits and (sometimes) attacks.
+
The two ways of applying creature variations are {{token|APPLY_CREATURE_VARIATION|c}} and {{token|APPLY_CURRENT_CREATURE_VARIATION}}.
 +
APPLY_CURRENT_CREATURE_VARIATION takes all creature variation tokens before it in the creature raws (and after previous APPLY_CURRENT_CREATURE_VARIATION tokens, if they exist) and applies them. When tokens are added through APPLY_CURRENT_CREATURE_VARIATION, they are added in the place of APPLY_CURRENT_CREATURE_VARIATION.
  
−
Chapter 1 - How to use creature variations, and their basic tokens:
+
Creature variations have an unusual order of application. First, remove tokens are applied (bottom-up according to Toady in c_variation_default.txt, though this should never matter). Then, convert tokens are applied bottom-up (in "reverse" order). Finally, add tokens are applied from the top. This means that {{token|CV_REMOVE_TAG|cv}} won't remove any token added by the same creature variation. It is also why more general conversions can (must) be higher up when overlapping {{token|CVCT_MASTER|cv}}s are used. If they were not read bottom-up, e.g.
−
Creature variations may be used in two ways. They may either appear as fully fletched CREATURE_VARIATION objects in their own files (the default being c_variation_default.txt) and called using APPLY_CREATURE_VARIATION, or their tokens may live "freely" inside creature raws and called use APPLY_CURRENT_CREATURE_VARIATION. The latter is for when you would like to use the powers of creature variations, like removing tokens or "converting" parts of them, without having to define a new object for it. There are 11 creature definition tokens (not counting those applying them, they are creature tokens, being called on the creature level), but almost half of them are copies of the other with the difference that they are "conditional" (see Chapter 2), and as three of them are there for the completion of another one (and it's conditional twin), really there are only 3 functions performed by the creature variations: adding tokens, removing tokens, and "converting" tokens.
+
[CV_CONVERT_TAG]
 +
[CVCT_MASTER:BODY]
 +
[CVCT_TARGET:QUADRUPED]
 +
[CVCT_REPLACEMENT:HUMANOID]
 +
would convert [BODY:QUADRUPED_FRONT_GRASP:...] and [BODY:QUADRUPED_NECK:...] into [BODY:HUMANOID_FRONT_GRASP:...] and [BODY:HUMANOID_NECK:...] respectively, before
 +
[CV_CONVERT_TAG]
 +
[CVCT_MASTER:BODY]
 +
[CVCT_TARGET:QUADRUPED_FRONT_GRASP]
 +
[CVCT_REPLACEMENT:HUMANOID]
 +
[CV_CONVERT_TAG]
 +
[CVCT_MASTER:BODY]
 +
[CVCT_TARGET:QUADRUPED_NECK]
 +
[CVCT_REPLACEMENT:HUMANOID_NECK:3FINGERS]
 +
could convert them into the expected [BODY:HUMANOID:...] and [BODY:HUMANOID_NECK:3_FINGERS:...], as should be.
  
−
Adding tokens is done using CV_NEW_TAG or CV_ADD_TAG. CV_NEW_TAG takes any token (with arguments) as its own argument and adds it to the target creature. CV_ADD_TAG is seemingly an alias for CV_NEW_TAG, so it is unclear why they both exist. E.g. [CV_NEW_TAG:BIOME:ANY_FOREST] gives the creature [BIOME:ANY_FOREST].
+
== Arguments and conditional tokens ==
  
−
Removing tokens is done using CV_REMOVE_TAG. CV_REMOVE_TAG takes whole token (names and) arguments, and removes tokens that start that way. So [CV_REMOVE_TAG:BODY:HUMANOID_SIMPLE] would remove [BODY:HUMANOID_SIMPLE:3_EYES], but [CV_REMOVE_TAG:BODY:3_EYES] would not. Neither would [CV_REMOVE_TAG:BODY:HUMANOID_SIMPLE] be able to remove [BODY:HUMANOID_SIMPLE_NECK:3_EYES], as it looks for whole arguments. [CV_REMOVE_TAG:BODY] would remove all examples above, as they start with "BODY".
+
{{token|APPLY_CREATURE_VARIATION|cv}} may be given arguments (in addition to the required creature variation ID). These arguments will replace instances of "!ARG''n''", where ''n'' is the index of the argument given to APPLY_CREATURE_VARIATION; the first argument will replace any "!ARG1", the second any "!ARG2" and so on. You may use any number of arguments<sup>1</sup>.
 +
If you have an "!ARG''n''" of a higher number than the argument given the replacements will act oddly, depending on if ''n'' has more digits than the number of arguments given. E.g. [APPLY_CREATURE_VARIATION:EXAMPLE_CV:one:two:three], which has three arguments given, will leave all "!ARG5" in EXAMPLE_CV intact as "!ARG5", but "!ARG10" will become "one0".
  
−
"Converting" tokens is done using CV_CONVERT_TAG, CVCT_MASTER, CVCT_TARGET, and CVCT_REPLACEMENT. These are used in a block, with one of each in each block. CV_CONVERT_TAG starts the block. CVCT_MASTER selects which tokens may be converted, by looking at full arguments at the start of said token (like CV_REMOVE_TAG). If no CVCT_MASTER is given, it is given no arguments, or the only argument it is given is blank (i.e. [CVCT_MASTER:]), all tokens of the target creature are selected.
+
The pipe character "|" is turned into ":" when inserted, so single arguments in APPLY_CREATURE_VARIATION may be turned into multi-argument segments in the output. E.g. given
−
CVCT_TARGET and CVCT_REPLACEMENT are a search-and-replace for strings within the selected tokens. This means the targeted part of a token can be changed anywhere in the token, so e.g.
+
[CREATURE_VARIATION:DIMORPHIC_FEATHER_COLORS]
−
Code: [Select]
+
[CV_NEW_TAG:SELECT_CASTE:FEMALE]
 +
[CV_NEW_TAG:SET_TL_GROUP:BY_CATEGORY:ALL:FEATHER]
 +
[CV_NEW_TAG:TL_COLOR_MODIFIER:!ARG1]
 +
[CV_NEW_TAG:TLCM_NOUN:feathers:PLURAL]
 +
[CV_NEW_TAG:SELECT_CASTE:MALE]
 +
[CV_NEW_TAG:SET_TL_GROUP:BY_CATEGORY:ALL:FEATHER]
 +
[CV_NEW_TAG:TL_COLOR_MODIFIER:!ARG2]
 +
[CV_NEW_TAG:TLCM_NOUN:feathers:PLURAL]
 +
[CV_NEW_TAG:SELECT_CASTE:ALL]
 +
and [APPLY_CREATURE_VARIATION:DIMORPHIC_FEATHER_COLORS:BROWN|1:BLUE|10|GREEN|1|BLACK|1] we get
 +
[SELECT_CASTE:FEMALE]
 +
[SET_TL_GROUP:BY_CATEGORY:ALL:FEATHER]
 +
[TL_COLOR_MODIFIER:BROWN:1]
 +
[TLCM_NOUN:feathers:PLURAL]
 +
[SELECT_CASTE:MALE]
 +
[SET_TL_GROUP:BY_CATEGORY:ALL:FEATHER]
 +
[TL_COLOR_MODIFIER:BLUE:10:GREEN:1:BLACK:1]
 +
[TLCM_NOUN:feathers:PLURAL]
 +
[SELECT_CASTE:ALL]
 +
as the tokens added to the target creature.
  
−
[CV_CONVERT_TAG]
+
The conditional tags ({{token|CV_NEW_CTAG|cv}}/{{token|CV_ADD_CTAG|cv}}, {{token|CV_REMOVE_CTAG|cv}} and {{token|CV_CONVERT_CTAG|cv}}) are copies of CV_NEW_TAG/CV_ADD_TAG, CV_REMOVE_TAG and CV_CONVERT_TAG, except they only work if a numbered argument of APPLY_CREATURE_VARIATION has an arbitrary value. E.g. [CV_ADD_CTAG:2:HUMANOID:CAN_SPEAK] will only add [CAN_SPEAK] if argument number two is "HUMANOID".
−
[CVCT_MASTER:BODY]
 
−
[CVCT_TARGET:2EYES]
 
−
[CVCT_REPLACEMENT:2EYESTALKS]
 
  
−
would affect both [BODY:QUADRUPED_NECK:2EYES:NOSE:2LUNGS:...] and [BODY:INSECT:2EYES:HEART:GUTS:BRAIN:MOUTH:2WINGS], converting them into [BODY:QUADRUPED_NECK:2EYESTALKS:NOSE:2LUNGS:...] and [BODY:INSECT:2EYESTALKS:HEART:GUTS:BRAIN:MOUTH:2WINGS] respectively.
+
<sup>1</sup>Functionally. Up to 65537=2<sup>16</sup>+1 arguments have been tested, with no problems other than a long load time.
−
Colons can be included as part of both the target and the replacement string, e.g. given
 
−
Code: [Select]
 
  
−
[CV_CONVERT_TAG]
+
===Example===
−
[CVCT_MASTER:BODY]
 
−
[CVCT_TARGET:BASIC_1PARTBODY:BASIC_HEAD]
 
−
[CVCT_REPLACEMENT:HUMANOID:3FINGERS]
 
  
−
and [BODY:BASIC_1PARTBODY:BASIC_HEAD:HEART:GUTS:BRAIN:MOUTH:2EYESTALKS], you will get [BODY:HUMANOID:3FINGERS:HEART:GUTS:BRAIN:MOUTH:2EYESTALKS].
+
The following is an example of a creature variation, demonstrating most of the tokens and arguments mentioned above; with an explanation of how you would use it to change the properties of a cow.
−
All occurrences of the target string are replaced, e.g. given
 
−
Code: [Select]
 
  
−
[CV_CONVERT_TAG]
+
[CREATURE_VARIATION:CREATURE_EDIT]
−
[CVCT_MASTER:DESCRIPTION]
+
    [CV_CONVERT_CTAG:1:NAME]
−
[CVCT_TARGET:TRAIT]
+
        [CVCT_MASTER:NAME]
−
[CVCT_REPLACEMENT:modderiffic]
+
        [CVCT_TARGET:!ARG3:!ARG3s:!ARG4]
 +
        [CVCT_REPLACEMENT:!ARG5:!ARG5s:!ARG6]
 +
    [CV_CONVERT_CTAG:2:CNAME]
 +
        [CVCT_MASTER:CASTE_NAME]
 +
        [CVCT_TARGET:!ARG3:!ARG3s:!ARG4]
 +
        [CVCT_REPLACEMENT:!ARG5:!ARG5s:!ARG6]
 +
    [CV_NEW_CTAG:7:FC:SELECT_CASTE:FEMALE]
 +
    [CV_NEW_CTAG:7:FC:COLOR:!ARG8]
 +
    [CV_CONVERT_TAG]
 +
        [CVCT_MASTER:STATE_NAME:LIQUID]
 +
        [CVCT_TARGET:!ARG3's milk]
 +
        [CVCT_REPLACEMENT:!ARG5's milk]
 +
    [CV_CONVERT_TAG]
 +
        [CVCT_MASTER:STATE_ADJ:LIQUID]
 +
        [CVCT_TARGET:!ARG3's milk]
 +
        [CVCT_REPLACEMENT:!ARG5's milk]
 +
    [CV_NEW_CTAG:9:MRED:SELECT_CASTE:MALE]
 +
    [CV_NEW_CTAG:9:MREL:CASTE_COLOR:4:0:0]
 +
    [CV_NEW_CTAG:9:MYEL:SELECT_CASTE:MALE]
 +
    [CV_NEW_CTAG:9:MYEL:CASTE_COLOR:6:0:1]
  
−
and [DESCRIPTION:This is an example creature. It is TRAIT, very very TRAIT.], you will get [DESCRIPTION:This is an example creature. It is modderiffic, very very modderiffic.].
+
We add the following to a creature file.
−
If no CVCT_TARGET is given, it is given no arguments, or the only argument it is given is blank (i.e. [CVCT_TARGET:]), the game will freeze when loading the creature.
 
−
If no CVCT_REPLACEMENT is given, the target string is simply removed.
 
  
−
Creature variations have an unusual order of application. First, remove tokens are applied (bottom-up according to Toady's notes, but I don't think this could affect anything). Then, convert tokens are applied bottom-up (in "reverse" order). Finally, add tokens are applied from the top. This means that CV_REMOVE_TAG won't remove any token added by the same creature variations. It is also why more general conversions can (must) be higher up when overlapping CVCT_MASTERs are used. If they were not read bottom-up, e.g.
+
    [SELECT_CREATURE:COW]
−
Code: [Select]
+
        [APPLY_CREATURE_VARIATION:CREATURE_EDIT:X:CNAME:cow:bovine:super-cow:cowtastic:FC:7|0|1:MYEL]
  
−
[CV_CONVERT_TAG]
+
This will change the cow creature file so that the cows are now called "super-cows", which can be described as "cowtastic", are white colored and produce "super-cow's milk", and it will also change the color of the bulls to yellow.
−
[CVCT_MASTER:BODY]
 
−
[CVCT_TARGET:QUADRUPED]
 
−
[CVCT_REPLACEMENT:HUMANOID]
 
  
−
would convert [BODY:QUADRUPED_FRONT_GRASP:...] and [BODY:QUADRUPED_NECK:...] into [BODY:HUMANOID_FRONT_GRASP:...] and [BODY:HUMANOID_NECK:...] respectively, before
+
Here is a step-by-step explanation of what is happening in order of the arguments:
−
Code: [Select]
 
  
−
[CV_CONVERT_TAG]
+
* "X" doesn't match the first CTAG argument of "NAME", so we have decided not to change the overall name of the creature.
−
[CVCT_MASTER:BODY]
+
* "CNAME" does match the second CTAG so we are changing the name of a caste which matches arguments !ARG3 & !ARG4, as well as looking for specific liquids with state names that contain !ARG3 followed by the characters "'s milk".
−
[CVCT_TARGET:QUADRUPED_FRONT_GRASP]
+
* Using arguments 3 & 4 we look for a caste name that matches "cow:cows:bovine" and any liquid name or adjective that matches "cow's milk".
−
[CVCT_REPLACEMENT:HUMANOID]
+
* The caste name and liquids do exist, so !ARG5 & !ARG6 now declare what we want to change these names to; in this case the caste name "super-cow:super-cows:cowtastic" and liquid name and adjective "super-cow's milk".
−
[CV_CONVERT_TAG]
+
* Now we declare that we want CTAG argument 7 to match "FC" which means we will select the [FEMALE] caste and add a color to it which is decided by the next argument !ARG8.
−
[CVCT_MASTER:BODY]
+
* We need to choose three digits but they need to be separated by ":". Using this character here will move us onto the next argument, so we separate the digits with "|" instead choosing "7|0|1" (white), for a white cow (not necessarily represented by the graphics).
−
[CVCT_TARGET:QUADRUPED_NECK]
+
* The next argument has multiple CTAGs numbered "9", but with different arguments. Either option will use [SELECT_CASTE:MALE] but we can choose between the argument MRED or MYEL. We have chosen MYEL which adds the tag [CASTE_COLOR:6:0:1] (yellow) for us, giving the male caste (in this case a bull) yellow as a caste color.
−
[CVCT_REPLACEMENT:HUMANOID_NECK:3FINGERS]
 
−
 
 
−
could convert them into the expected [BODY:HUMANOID:...] and [BODY:HUMANOID_NECK:3_FINGERS:...].
 
−
 
 
−
APPLY_CURRENT_CREATURE_VARIATION takes all creature variation tokens before it in the creature raws (and after previous APPLY_CURRENT_CREATURE_VARIATION tokens, if they exist) and applies them. When tokens are added through APPLY_CURRENT_CREATURE_VARIATION, they are added in the place of APPLY_CURRENT_CREATURE_VARIATION.
 
−
 
 
−
 
 
−
Chapter 2 - Arguments and conditional tokens:
 
−
APPLY_CREATURE_VARIATION may be given arguments. These arguments will replace instances of "!ARGn", where n is the index of the argument given to APPLY_CREATURE_VARIATION; the first argument will replace any "!ARG1", the second any "!ARG2" and so on. You may use any number of arguments**.
 
−
If you have an "!ARGn" of a higher number than the argument given the replacements will act oddly, depending on if n has more digits than the number of arguments given. E.g. [APPLY_CREATURE_VARIATION:EXAMPLE_CV:one:two:three], which has three arguments given, will leave all "!ARG5" in EXAMPLE_CV intact as "!ARG5", but "!ARG10" will become "one0".
 
−
 
 
−
The pipe character "|" is turned into ":" when inserted, so single arguments in APPLY_CREATURE_VARIATION may be turned into multi-argument segments in the output. E.g. given
 
−
Code: [Select]
 
−
 
 
−
[CREATURE_VARIATION:DIMORPHIC_FEATHER_COLORS]
 
−
[CV_NEW_TAG:SELECT_CASTE:FEMALE]
 
−
[CV_NEW_TAG:SET_TL_GROUP:BY_CATEGORY:ALL:FEATHER]
 
−
[CV_NEW_TAG:TL_COLOR_MODIFIER:!ARG1]
 
−
[CV_NEW_TAG:TLCM_NOUN:feathers:PLURAL]
 
−
[CV_NEW_TAG:SELECT_CASTE:MALE]
 
−
[CV_NEW_TAG:SET_TL_GROUP:BY_CATEGORY:ALL:FEATHER]
 
−
[CV_NEW_TAG:TL_COLOR_MODIFIER:!ARG2]
 
−
[CV_NEW_TAG:TLCM_NOUN:feathers:PLURAL]
 
−
[CV_NEW_TAG:SELECT_CASTE:ALL]
 
−
 
 
−
and [APPLY_CREATURE_VARIATION:DIMORPHIC_FEATHER_COLORS:BROWN|1:BLUE|10|GREEN|1|BLACK|1] we get
 
−
Code: [Select]
 
−
 
 
−
[SELECT_CASTE:FEMALE]
 
−
[SET_TL_GROUP:BY_CATEGORY:ALL:FEATHER]
 
−
[TL_COLOR_MODIFIER:BROWN:1]
 
−
[TLCM_NOUN:feathers:PLURAL]
 
−
[SELECT_CASTE:MALE]
 
−
[SET_TL_GROUP:BY_CATEGORY:ALL:FEATHER]
 
−
[TL_COLOR_MODIFIER:BLUE:10:GREEN:1:BLACK:1]
 
−
[TLCM_NOUN:feathers:PLURAL]
 
−
[SELECT_CASTE:ALL]
 
−
 
 
−
as the tokens added to the target creature.
 
−
 
 
−
The conditional tags (CV_NEW_CTAG/CV_ADD_CTAG, CV_REMOVE_CTAG and CV_CONVERT_CTAG) are copies of CV_NEW_TAG/CV_ADD_TAG, CV_REMOVE_TAG and CV_CONVERT_TAG, except they only work if a numbered argument of APPLY_CREATURE_VARIATION has an arbitrary value. E.g. [CV_NEW_TOKEN:2:HUMANOID:CAN_SPEAK] will only add [CAN_SPEAK] if argument number two is "HUMANOID".
 
−
CV_CONVERT_CTAG still uses CVCT_MASTER, CVCT_TARGET, and CVCT_REPLACEMENT.
 
−
 
  
 +
==See Also==
 +
* [[Creature token]]
 +
* [[Tissue definition token]]
 +
* [[Material definition token]]
 +
* [[Body detail plan token]]
  
 
{{Category|Modding}}
 
{{Category|Modding}}
 
{{Category|Tokens}}
 
{{Category|Tokens}}
−
 
 
[[ru:Creature variation token]]
 
[[ru:Creature variation token]]

Latest revision as of 16:12, 2 April 2024

xTATTEREDx  · +FINE+  · *SUPERIOR*  · ≡EXCEPTIONAL≡  · ☼MASTERWORK☼
v50.14 · v0.47.05
This article is about the current version of DF.
Note that some content may still need to be updated.

Modding
Tokens
Audio · Biome · Graphics · Interaction · Mod info · Plant · Speech · Sphere · Syndrome · World
Body tokens
Body · Body detail plan · Bodygloss · Tissue
Creature tokens
Creature · Creature mannerism · Personality · Creature variation · Procedural graphics layer
Descriptor tokens
Descriptor color · Color · Descriptor pattern · Descriptor shape
Entity tokens
Entity · Ethic · Language · Value · Position
Job tokens
Building · Labor · Reaction · Skill · Unit type
Item tokens
Item type · Item definition · Ammo · Armor · Instrument · Tool · Trap component · Weapon
Material tokens
Material type · Material definition · Inorganic material definition
v · t · e


Creature variations are templates for creatures. In conjunction with [COPY_TAGS_FROM] they may be used to create creatures which are derived from another already-existing creature, thus the name, though their use-case is broader than that, in vanilla also covering gaits and attacks. They may either be embedded inside creatures (when using [APPLY_CURRENT_CREATURE_VARIATION]) or be defined as CREATURE_VARIATION objects. The default variations are defined in c_variation_default.txt

Creature variations can be contrasted with the other types of templates for creatures: tissue templates, material templates, and body detail plans. Creature variations are the newest of the four (from 2009) and also the most advanced.

Creature variations can add/convert almost all tokens, but [APPLY_CREATURE_VARIATION] is an exception, so you can’t nest creature variations.

Token Arguments Description
CV_NEW_TAG
  • token (including token arguments)
 Adds the given token to the target creature. E.g. [CV_NEW_TAG:BIOME:ANY_FOREST] gives the creature [BIOME:ANY_FOREST].
CV_ADD_TAG
  • token (including token arguments)
 Alias for CV_NEW_TAG.
CV_REMOVE_TAG
  • leading token (name and) arguments
 Removes all tokens from the target creature which start with the given chain of token arguments. E.g. [CV_REMOVE_TAG:BODY:HUMANOID_SIMPLE] would remove [BODY:HUMANOID_SIMPLE:3_EYES], but [CV_REMOVE_TAG:BODY:3_EYES] would not. Neither would [CV_REMOVE_TAG:BODY:HUMANOID_SIMPLE] be able to remove [BODY:HUMANOID_SIMPLE_NECK:3_EYES], as it looks for whole arguments. [CV_REMOVE_TAG:BODY] would remove both examples above, as they start with "BODY".
CV_CONVERT_TAG Starts a conversion block, containing one [CVCT_MASTER], one [CVCT_TARGET], and one [CVCT_REPLACEMENT]. Note that multiple conversion blocks are applied in what might appear as "reverse" order (see Application).
CVCT_MASTER
  • leading token (name and) arguments
 Specifies which tokens of the target creature may be converted, by looking at full arguments at the start of said token (like [CV_REMOVE_TAG]).

If no CVCT_MASTER is given, it is given no arguments, or the only argument it is given is blank (i.e. [CVCT_MASTER:]), all tokens of the target creature are selected.

CVCT_TARGET
  • string
 Locates the specified string within all tokens specified by CVCT_MASTER.

If no CVCT_TARGET is given, it is given no arguments, or the only argument it is given is blank (i.e. [CVCT_TARGET:]), the game will freeze when loading the creature.

CVCT_REPLACEMENT
  • string
 Replaces the string specified by CVCT_TARGET within the tokens specified by CVCT_MASTER. This means the targeted part of a token can be changed anywhere in the token, e.g. 
[CV_CONVERT_TAG]
	[CVCT_MASTER:BODY]
	[CVCT_TARGET:2EYES]
	[CVCT_REPLACEMENT:2EYESTALKS]

would affect both [BODY:QUADRUPED_NECK:2EYES:NOSE:2LUNGS:...] and [BODY:INSECT:2EYES:HEART:GUTS:BRAIN:MOUTH:2WINGS], converting them into [BODY:QUADRUPED_NECK:2EYESTALKS:NOSE:2LUNGS:...] and [BODY:INSECT:2EYESTALKS:HEART:GUTS:BRAIN:MOUTH:2WINGS] respectively. Colons can be included as part of both the target and the replacement string, e.g. given 

[CV_CONVERT_TAG]
	[CVCT_MASTER:BODY]
	[CVCT_TARGET:BASIC_1PARTBODY:BASIC_HEAD]
	[CVCT_REPLACEMENT:HUMANOID:3FINGERS]

and [BODY:BASIC_1PARTBODY:BASIC_HEAD:HEART:GUTS:BRAIN:MOUTH:2EYESTALKS], you will get [BODY:HUMANOID:3FINGERS:HEART:GUTS:BRAIN:MOUTH:2EYESTALKS]. All occurrences of the target string are replaced, e.g. given 

[CV_CONVERT_TAG]
	[CVCT_MASTER:DESCRIPTION]
	[CVCT_TARGET:TRAIT]
	[CVCT_REPLACEMENT:modderiffic]

and [DESCRIPTION:This is an example creature. It is TRAIT, very very TRAIT.], you will get [DESCRIPTION:This is an example creature. It is modderiffic, very very modderiffic.].

If no CVCT_REPLACEMENT is given, the target string is simply removed.

CV_NEW_CTAG
  • !ARG number
  • value for !ARG to match
  • token
 Conditional variant of [CV_NEW_TAG], see Arguments and conditional tokens.
CV_ADD_CTAG
  • !ARG number
  • value for !ARG to match
  • token
 Alias for CV_NEW_CTAG.
CV_REMOVE_CTAG
  • !ARG number
  • value for !ARG to match
  • token
 Conditional variant of [CV_REMOVE_TAG], see Arguments and conditional tokens.
CV_CONVERT_CTAG
  • !ARG number
  • value for !ARG to match
 Conditional variant of [CV_CONVERT_TAG], see Arguments and conditional tokens. Uses [CVCT_MASTER], [CVCT_TARGET], and [CVCT_REPLACEMENT], just as the former.

Application[edit]

The two ways of applying creature variations are [APPLY_CREATURE_VARIATION] and [APPLY_CURRENT_CREATURE_VARIATION]. APPLY_CURRENT_CREATURE_VARIATION takes all creature variation tokens before it in the creature raws (and after previous APPLY_CURRENT_CREATURE_VARIATION tokens, if they exist) and applies them. When tokens are added through APPLY_CURRENT_CREATURE_VARIATION, they are added in the place of APPLY_CURRENT_CREATURE_VARIATION.

Creature variations have an unusual order of application. First, remove tokens are applied (bottom-up according to Toady in c_variation_default.txt, though this should never matter). Then, convert tokens are applied bottom-up (in "reverse" order). Finally, add tokens are applied from the top. This means that [CV_REMOVE_TAG] won't remove any token added by the same creature variation. It is also why more general conversions can (must) be higher up when overlapping [CVCT_MASTER]s are used. If they were not read bottom-up, e.g. 

[CV_CONVERT_TAG]
	[CVCT_MASTER:BODY]
	[CVCT_TARGET:QUADRUPED]
	[CVCT_REPLACEMENT:HUMANOID]

would convert [BODY:QUADRUPED_FRONT_GRASP:...] and [BODY:QUADRUPED_NECK:...] into [BODY:HUMANOID_FRONT_GRASP:...] and [BODY:HUMANOID_NECK:...] respectively, before 

[CV_CONVERT_TAG]
	[CVCT_MASTER:BODY]
	[CVCT_TARGET:QUADRUPED_FRONT_GRASP]
	[CVCT_REPLACEMENT:HUMANOID]
[CV_CONVERT_TAG]
	[CVCT_MASTER:BODY]
	[CVCT_TARGET:QUADRUPED_NECK]
	[CVCT_REPLACEMENT:HUMANOID_NECK:3FINGERS]

could convert them into the expected [BODY:HUMANOID:...] and [BODY:HUMANOID_NECK:3_FINGERS:...], as should be.

Arguments and conditional tokens[edit]

[APPLY_CREATURE_VARIATION] may be given arguments (in addition to the required creature variation ID). These arguments will replace instances of "!ARGn", where n is the index of the argument given to APPLY_CREATURE_VARIATION; the first argument will replace any "!ARG1", the second any "!ARG2" and so on. You may use any number of arguments1. If you have an "!ARGn" of a higher number than the argument given the replacements will act oddly, depending on if n has more digits than the number of arguments given. E.g. [APPLY_CREATURE_VARIATION:EXAMPLE_CV:one:two:three], which has three arguments given, will leave all "!ARG5" in EXAMPLE_CV intact as "!ARG5", but "!ARG10" will become "one0".

The pipe character "|" is turned into ":" when inserted, so single arguments in APPLY_CREATURE_VARIATION may be turned into multi-argument segments in the output. E.g. given 

[CREATURE_VARIATION:DIMORPHIC_FEATHER_COLORS]
	[CV_NEW_TAG:SELECT_CASTE:FEMALE]
		[CV_NEW_TAG:SET_TL_GROUP:BY_CATEGORY:ALL:FEATHER]
			[CV_NEW_TAG:TL_COLOR_MODIFIER:!ARG1]
				[CV_NEW_TAG:TLCM_NOUN:feathers:PLURAL]
	[CV_NEW_TAG:SELECT_CASTE:MALE]
		[CV_NEW_TAG:SET_TL_GROUP:BY_CATEGORY:ALL:FEATHER]
			[CV_NEW_TAG:TL_COLOR_MODIFIER:!ARG2]
				[CV_NEW_TAG:TLCM_NOUN:feathers:PLURAL]
	[CV_NEW_TAG:SELECT_CASTE:ALL]

and [APPLY_CREATURE_VARIATION:DIMORPHIC_FEATHER_COLORS:BROWN|1:BLUE|10|GREEN|1|BLACK|1] we get 

[SELECT_CASTE:FEMALE]
	[SET_TL_GROUP:BY_CATEGORY:ALL:FEATHER]
		[TL_COLOR_MODIFIER:BROWN:1]
			[TLCM_NOUN:feathers:PLURAL]
[SELECT_CASTE:MALE]
	[SET_TL_GROUP:BY_CATEGORY:ALL:FEATHER]
		[TL_COLOR_MODIFIER:BLUE:10:GREEN:1:BLACK:1]
			[TLCM_NOUN:feathers:PLURAL]
[SELECT_CASTE:ALL]

as the tokens added to the target creature.

The conditional tags ([CV_NEW_CTAG]/[CV_ADD_CTAG], [CV_REMOVE_CTAG] and [CV_CONVERT_CTAG]) are copies of CV_NEW_TAG/CV_ADD_TAG, CV_REMOVE_TAG and CV_CONVERT_TAG, except they only work if a numbered argument of APPLY_CREATURE_VARIATION has an arbitrary value. E.g. [CV_ADD_CTAG:2:HUMANOID:CAN_SPEAK] will only add [CAN_SPEAK] if argument number two is "HUMANOID".

1Functionally. Up to 65537=216+1 arguments have been tested, with no problems other than a long load time.

Example[edit]

The following is an example of a creature variation, demonstrating most of the tokens and arguments mentioned above; with an explanation of how you would use it to change the properties of a cow. 

[CREATURE_VARIATION:CREATURE_EDIT]
    [CV_CONVERT_CTAG:1:NAME]
        [CVCT_MASTER:NAME]
        [CVCT_TARGET:!ARG3:!ARG3s:!ARG4]
        [CVCT_REPLACEMENT:!ARG5:!ARG5s:!ARG6]
    [CV_CONVERT_CTAG:2:CNAME]
        [CVCT_MASTER:CASTE_NAME]
        [CVCT_TARGET:!ARG3:!ARG3s:!ARG4]
        [CVCT_REPLACEMENT:!ARG5:!ARG5s:!ARG6]
    [CV_NEW_CTAG:7:FC:SELECT_CASTE:FEMALE]
    [CV_NEW_CTAG:7:FC:COLOR:!ARG8]
    [CV_CONVERT_TAG]
        [CVCT_MASTER:STATE_NAME:LIQUID]
        [CVCT_TARGET:!ARG3's milk]
        [CVCT_REPLACEMENT:!ARG5's milk]
    [CV_CONVERT_TAG]
        [CVCT_MASTER:STATE_ADJ:LIQUID]
        [CVCT_TARGET:!ARG3's milk]
        [CVCT_REPLACEMENT:!ARG5's milk]
    [CV_NEW_CTAG:9:MRED:SELECT_CASTE:MALE]
    [CV_NEW_CTAG:9:MREL:CASTE_COLOR:4:0:0]
    [CV_NEW_CTAG:9:MYEL:SELECT_CASTE:MALE]
    [CV_NEW_CTAG:9:MYEL:CASTE_COLOR:6:0:1]

We add the following to a creature file. 

    [SELECT_CREATURE:COW]
        [APPLY_CREATURE_VARIATION:CREATURE_EDIT:X:CNAME:cow:bovine:super-cow:cowtastic:FC:7|0|1:MYEL]

This will change the cow creature file so that the cows are now called "super-cows", which can be described as "cowtastic", are white colored and produce "super-cow's milk", and it will also change the color of the bulls to yellow.

Here is a step-by-step explanation of what is happening in order of the arguments:

  • "X" doesn't match the first CTAG argument of "NAME", so we have decided not to change the overall name of the creature.
  • "CNAME" does match the second CTAG so we are changing the name of a caste which matches arguments !ARG3 & !ARG4, as well as looking for specific liquids with state names that contain !ARG3 followed by the characters "'s milk".
  • Using arguments 3 & 4 we look for a caste name that matches "cow:cows:bovine" and any liquid name or adjective that matches "cow's milk".
  • The caste name and liquids do exist, so !ARG5 & !ARG6 now declare what we want to change these names to; in this case the caste name "super-cow:super-cows:cowtastic" and liquid name and adjective "super-cow's milk".
  • Now we declare that we want CTAG argument 7 to match "FC" which means we will select the [FEMALE] caste and add a color to it which is decided by the next argument !ARG8.
  • We need to choose three digits but they need to be separated by ":". Using this character here will move us onto the next argument, so we separate the digits with "|" instead choosing "7|0|1" (white), for a white cow (not necessarily represented by the graphics).
  • The next argument has multiple CTAGs numbered "9", but with different arguments. Either option will use [SELECT_CASTE:MALE] but we can choose between the argument MRED or MYEL. We have chosen MYEL which adds the tag [CASTE_COLOR:6:0:1] (yellow) for us, giving the male caste (in this case a bull) yellow as a caste color.

See Also[edit]

Retrieved from "https://dwarffortresswiki.org/index.php?title=Creature_variation_token&oldid=298899"