DF2014:Creature variation token
|This article is about the current version of DF.|
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.
||Adds the given token to the target creature. E.g. [CV_NEW_TAG:BIOME:ANY_FOREST] gives the creature [BIOME:ANY_FOREST].|
||Alias for CV_NEW_TAG.|
||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 |
||Specifies which tokens of the target creature may be converted, by looking at full arguments at the start of said token (like |
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.
||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.
||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.
||Conditional variant of |
||Alias for CV_NEW_CTAG.|
||Conditional variant of |
||Conditional variant of |
The two ways of applying creature variations are
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
[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_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".
1Functionally. Up to 65537=216+1 arguments have been tested, with no problems other than a long load time.
|Tokens||Ammo • Armor • Biome • Building • Body • Body detail plan • Bodygloss • Creature • Creature variation • Descriptor color • Descriptor pattern • Descriptor shape • Entity • Item • Item definition • Instrument • Interaction • Labor • Language • Material • Material definition • Inorganic material definition • Plant • Position • Skill • Syndrome • Tissue definition • Tool • Trap component • Unit type • Weapon • World|