Creature variation token

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. More Info · V

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.

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		Conditional variant of [CV_CONVERT_TAG], see Arguments and conditional tokens. Uses [CVCT_MASTER], [CVCT_TARGET], and [CVCT_REPLACEMENT], just as the former.

Application

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

[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 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

[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_NEW_TOKEN:2:HUMANOID:CAN_SPEAK] will only add [CAN_SPEAK] if argument number two is "HUMANOID".

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