- 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.
Interaction token
v50.13 · v0.47.05 This article is about the current version of DF.Note that some content may still need to be updated. |
The following tokens can be used to define and use interactions. (It appears that, at least in order to make the big list make a little more sense, some examples of those may be necessary.)
Definitions
Token | Context | Arguments | Description |
---|---|---|---|
INTERACTION | Global | ID | Used to start defining a new interaction. The term "interaction ID" refers to the text specified within this token; this is used to make reference to the interaction in various other places. |
EXPERIMENT_ONLYv0.47.01 | Global | Disallows use of the interaction in play, but if the interaction animates or resurrects corpses, or has an I_SOURCE:EXPERIMENT tag, it can be used in worldgen. Animation and resurrection interactions do not need I_SOURCE:EXPERIMENT to work in worldgen. | |
I_SOURCE | Global | type | Defines what things are capable of triggering this interaction - multiple sources may be specified. Valid values:
|
IS_HIST_STRING_1 | Within I_SOURCE | text | Describes what the interaction did to a historical figure; this is displayed in legends mode following the name of the historical figure who performed the interaction and preceding the name of the targeted historical figure (or, in the case of [I_SOURCE:INGESTION], the historical figure from whom the consumed material was extracted).
[IS_HIST_STRING_1: cursed] |
IS_HIST_STRING_2 | Within I_SOURCE | text | Describes what the interaction did to a historical figure; this is displayed in legends mode after the name of the historical figure who was targeted by the interaction. In the case of [I_SOURCE:INGESTION], it is displayed after the name of the historical figure from whom the consumed material was extracted.
[IS_HIST_STRING_2: to assume the form of a lizard-like monster every full moon] |
IS_TRIGGER_STRINGv0.47.01 | Within I_SOURCE | text | Displayed as an announcement when the interaction is carried out during play. The text follows the name of the target unit, and is preceded by IS_TRIGGER_STRING_SECOND or IS_TRIGGER_STRING_THIRD. May be limited to [I_SOURCE:DEITY] and [I_SOURCE:EXPERIMENT] interactions at present; this still needs to be tested.
[IS_TRIGGER_STRING: been infected with a contagious ghoulish condition] |
IS_TRIGGER_STRING_SECONDv0.47.01 | Within I_SOURCE | text | Presented before the IS_TRIGGER_STRING when describing the event in the second person.
[IS_TRIGGER_STRING_SECOND: have] |
IS_TRIGGER_STRING_THIRDv0.47.01 | Within I_SOURCE | text | Presented before the IS_TRIGGER_STRING when describing the event in the third person.
[IS_TRIGGER_STRING_THIRD: has] |
IS_NAME | Within I_SOURCE | string | Generally used with [I_SOURCE:SECRET] interactions to describe what the secret is about (though it may be used to name any I_SOURCE). This name is engraved onto the appropriate secret-containing slabs from worldgen, and is used in legends mode when describing the secret being learnt by historical figures.
[IS_NAME:the secrets of life and death] |
IS_SPHERE | Within I_SOURCE:SECRET | sphere | Indicates the sphere to which this secret pertains. Only one sphere can be defined for each [I_SOURCE:SECRET] token, so several [I_SOURCE:SECRET] tokens are required to make a secret belong to multiple spheres. |
IS_SECRET_GOAL | Within I_SOURCE:SECRET | Secret Goal token | Indicates why somebody would want to learn the secret. Valid values:
However, currently only IMMORTALITY will result in a secret being pursued during world-gen. |
IS_SECRET | Within I_SOURCE:SECRET | Secret Flag | Indicates how the secret can be learned. Valid values:
|
IS_USAGE_HINT | Within I_SOURCE:DEITY | Usage Hint token | Indicates why a deity would choose to perform this interaction. See CDI:USAGE_HINT below for valid values - in this context, MINOR_BLESSINGv0.47.01, MEDIUM_BLESSINGv0.47.01, MINOR_CURSEv0.47.01, MEDIUM_CURSEv0.47.01, and MAJOR_CURSE are the only values that make sense. |
IS_REGION | Within I_SOURCE:REGION | Region type | Indicates what types of regions are capable of performing this interaction. This token may be specified several times per I_SOURCE to permit multiple terrain/alignment types. Valid values:
|
IS_FREQUENCY | Within I_SOURCE | Probability | When used with [I_SOURCE:REGION], determines how likely it is for the region(s) specified via [IS_REGION] to possess this interaction.
Note: it appears that regions aren't allowed to possess more than a single regional interaction at present. |
I_TARGET | Global | ID, type | Defines the targets available for subsequent use with [I_EFFECT] tokens. Multiple targets may be specified; the precise target(s) used with each interaction effect are indicated via their ID (see [IE_TARGET]). Valid values:
|
IT_LOCATION | Within I_TARGET | Location | This is often included after [I_TARGET] token to add more detail about the target. Valid values:
|
IT_MANUAL_INPUT | Within I_TARGET | text | Tells the adventure mode player what they should be selecting. If not specified, the player will only be able to target themselves. |
IT_AFFECTED_CREATURE | Within I_TARGET:CORPSE or I_TARGET:CREATURE | CREATURE:CASTE | Specifies specific creatures the interaction can target. |
IT_AFFECTED_CLASS | Within I_TARGET:CORPSE or I_TARGET:CREATURE | Creature class | Specifies creature classes the interaction can target. |
IT_IMMUNE_CREATURE | Within I_TARGET:CORPSE or I_TARGET:CREATURE | CREATURE:CASTE | Specifies specific creatures the interaction cannot target. |
IT_IMMUNE_CLASS | Within I_TARGET:CORPSE or I_TARGET:CREATURE | Creature class | Specifies creature classes the interaction cannot target. |
IT_REQUIRES | Within I_TARGET:CORPSE or I_TARGET:CREATURE | Creature token or property | Indicates that the target must have the specified property. Valid values:
|
IT_FORBIDDEN | Within I_TARGET:CORPSE or I_TARGET:CREATURE | Creature token or property | Indicates that the target must not have the specified property. Valid values are the same as for IT_REQUIRES. |
IT_CANNOT_TARGET_IF_ALREADY_AFFECTED | Within I_TARGET:CORPSE or I_TARGET:CREATURE | Prevents the interaction from targeting a creature that's already under the effect of the same interaction. | |
IT_CANNOT_HAVE_SYNDROME_CLASS | Within I_TARGET:CORPSE or I_TARGET:CREATURE | Syndrome class | Prevents the interaction from targeting a creature under the effects of a syndrome having the specified SYN_CLASS value. |
IT_MATERIAL | Within I_TARGET:MATERIAL | type | Specifies the type of material the interaction targets; currently only used for MATERIAL_EMISSION interaction effects. See Breath Attack Types. Valid values:
|
I_EFFECT | Global | type | Specifies what the interaction does to the targets. Multiple [I_EFFECT]s may be specified in a single interaction, and the same type may be used more than once. Valid values:
|
IE_ARENA_NAME | Within I_EFFECT | text | Allows the interaction effect to be applied directly to newly spawned creatures in arena mode. The specified name is used to represent it within the creature creation effects list. |
IE_TARGET | Within I_EFFECT | ID | Specifies which I_TARGET a particular interaction effect will be applied to. For example, in an interaction with the token [I_TARGET:B:CREATURE], 'B' is the ID used to indicate this target option. [I_EFFECT:ADD_SYNDROME] followed by [IE_TARGET:B] would therefore apply the syndrome to this target. Certain types of interaction effects require multiple IE_TARGET tokens in a specific order to function properly. A few effects do not require a target at all. |
IE_INTERMITTENT | Within I_EFFECT | Frequency | Only appears to work with [I_SOURCE:REGION] interactions. Indicates that the effect happens intermittently and specifies roughly how often. Regional interactions aren't able to use effects which lack this token. Valid values:
Note: DAILY, MONTHLY and YEARLY also exist in the string dump but don't appear to work at present. |
IE_IMMEDIATE | Within I_EFFECT | Indicates that the effect happens immediately. | |
IE_LOCATION | Within I_EFFECT | Location Hint | Prevents the interaction effect from manifesting unless the target is in a location which meets the specified criteria.
Valid values:
A depth of 1/7 is sufficient for IN_WATER and IN_MAGMA. Note: NO_THICK_FOG and OUTSIDE are accepted as valid location hints when specified with IE_LOCATION, but don't appear to work. It's possible that they're currently only implemented for use with |
IE_ADD_WEATHERv0.47.01 | Within I_EFFECT:CHANGE_WEATHER | type | Indicates what type of weather is added. Valid values:
|
IE_REMOVE_WEATHERv0.47.01 | Within I_EFFECT:CHANGE_WEATHER | type | Indicates what type of weather is removed. See above for a list of valid weather types. |
IE_GRIME_LEVEL | Within I_EFFECT:CLEAN | amount? | [IE_GRIME_LEVEL:2] appears in the default cleaning interaction, and may indicate amount of grime cleaned. |
IE_SYNDROME_TAG | Within I_EFFECT:CLEAN | syndrome trigger flag | When a creature cleans off a contaminant which is associated with a syndrome, the syndrome will be contracted if it has a matching trigger flag. This is what enables cats to become slightly inebriated when licking off alcohol. SYN_INGESTED appears to be the only syndrome trigger flag that works in this context. |
IE_PROPEL_FORCEv0.47.01 | Within I_EFFECT:PROPEL_UNIT | amount | Indicates the amount of force that the target will be propelled with. |
IE_ITEMv0.47.01 | Within I_EFFECT:CREATE_ITEM | <probability>:<quantity>:item token:material token | Defines what item will be created. |
IE_ITEM_QUALITYv0.47.01 | Within I_EFFECT:CREATE_ITEM | <quality> OR <minimum quality>:<maximum quality> | Defines what quality the created item shall have. Can either be specified in the form of a single, fixed quality (it seems that ARTIFACT can only be used in this manner), or a minimum and maximum level (in which case the quality is selected randomly). Valid values (numerals only except for ARTIFACT):
|
IE_SET_QUALITYv0.47.01 | Within I_EFFECT:CHANGE_ITEM_QUALITY | quality level | Defines a fixed quality level which the affected item(s) will be set to (decreasing or increasing in quality as necessary). See above for a list of valid quality levels (but note that ARTIFACT cannot be used in this effect). |
IE_CHANGE_QUALITYv0.47.01 | Within I_EFFECT:CHANGE_ITEM_QUALITY | amount | Determines how much the quality of the item(s) will be changed. For instance, improving a well-crafted -item- (quality level 1) by 2 will turn it into a superior-quality *item* (quality level 3). A negative value can be used to decrease quality. Quality cannot be increased beyond level 5 (masterwork) or decreased below level 0 (ordinary). |
CREATUREv0.47.01 | Within I_EFFECT:SUMMON_UNIT | <creature token>:<caste token> | Indicates which specific creature will be created when using this interaction. ANY can be used in place of a specific caste token. Only one [CREATURE] may currently be specified per interaction effect. |
IE_CREATURE_FLAGv0.47.01 | Within I_EFFECT:SUMMON_UNIT | <creature flag> | When this token is added to a random creature summoning effect, it narrows down the selection to creatures which have the specified creature flag. This token may be used multiple times per interaction effect; creatures which lack any of the indicated flags will never be summoned. |
IE_FORBIDDEN_CREATURE_FLAGv0.47.01 | Within I_EFFECT:SUMMON_UNIT | <creature flag> | When this token is added to a random creature summoning effect, any creature with the specified creature flag will be excluded from the selection. This token may be used multiple times per interaction effect; creatures which possess any of the indicated flags will never be summoned. |
IE_CREATURE_CASTE_FLAGv0.47.01 | Within I_EFFECT:SUMMON_UNIT | <caste flag> | When this token is added to a random creature summoning effect, it narrows down the selection to creatures which have the specified caste flag. This token may be used multiple times per interaction effect; creatures which lack any of the indicated flags will never be summoned. |
IE_FORBIDDEN_CREATURE_CASTE_FLAGv0.47.01 | Within I_EFFECT:SUMMON_UNIT | <caste flag> | When this token is added to a random creature summoning effect, it excludes any creature with the specified caste flag. This token may be used multiple times per interaction effect; creatures which possess any of the indicated flags will never be summoned. |
IE_HAVE_FAST_EFFORTLESS_GAIT_SPEEDv0.47.01 | Within I_EFFECT:SUMMON_UNIT | <minimum gait speed> | When this token is added to a random creature summoning effect, it narrows down the selection to creatures which have at least one gait with an <energy expenditure> of 0 and a <max speed> less than or equal to the specified <minimum gait speed> ("less than" because lower is faster in the scale used for gait speed). [2] |
IE_ALL_SLOW_EFFORTLESS_GAIT_SPEEDv0.47.01 | Within I_EFFECT:SUMMON_UNIT | <maximum gait speed> | When this token is added to a random creature summoning effect, it excludes any creatures which have at least one gait with an <energy expenditure> of 0 and a <max speed> value less than or equal to the specified <maximum gait speed> (note that larger values are slower in the scale used for gait speed). [3] |
IE_TIME_RANGEv0.47.01 | Within I_EFFECT:SUMMON_UNIT | <minimum ticks>:<maximum ticks> | The summoned unit vanishes in a puff of smoke once a certain amount of time has elapsed. The time limit is a randomly selected number of ticks within the specified minimum-maximum time range. The unit will persist indefinitely if this token is omitted. |
IE_MAKE_PET_IF_POSSIBLEv0.47.01 | Within I_EFFECT:SUMMON_UNIT | Makes the summoned unit behave as a pet of the unit who performed the summoning interaction. | |
GENERATED | Global | Indicates that this is a generated interaction. Cannot be specified in user-defined raws.
|
Usage
To enable a particular type of creature to use an interaction directly, the creature token [CAN_DO_INTERACTION:<interaction name>]
should be added to its creature raws (replacing '<interaction name>' with the ID of the desired interaction; for an interaction called [INTERACTION:CLEANING]
in the raws, the ID would be "CLEANING"), followed by a series of [CDI:...] tokens as detailed below.
Interactions can also be granted to individual creatures via syndromes using the syndrome effect token [CE_CAN_DO_INTERACTION]
followed by [CDI:INTERACTION:<interaction name>]
and additional CDI tokens as required.
The following is a list of valid CDI tokens. Precede them with "CDI:" in the style of [CDI:ADV_NAME:Clean]
, for example.
Token | Arguments | Description |
---|---|---|
INTERACTION | ID | Specifies which interaction can be performed. This is only needed following CE_CAN_DO_INTERACTION; there's no need to include this after CAN_DO_INTERACTION as the latter allows you to specify the interaction directly (as explained above). |
ADV_NAME | text | Specifies the name of the interaction as it will appear on the adventure mode 'powers/abilities' menu. |
TARGET | target ID, target types | Specifies how the creature chooses what to target. Target ID refers to an I_TARGET defined in the interaction itself. Multiple target types can be specified. If no target is specified, creature will target any available target within range, even through walls. Valid target types:
|
TARGET_RANGE | target ID, range | Determines the maximum distance from the interaction user (in tiles) at which something can be considered a valid target. For SOLID_GLOB, SHARP_ROCK, LIQUID_GLOB and FIREBALL breath attacks, also determines how far the projectiles can fly before falling to the ground. |
MAX_TARGET_NUMBER | ID, number | Specifies the maximum number of things that can be selected for a particular I_TARGET. |
LOCATION_HINT | Location Hint | Prevents CPU-controlled creatures from using the interaction unless they are in a location which meets the specified criteria. See above for a list of valid location hint values. |
USAGE_HINT | Usage hint token | Indicates when and how CPU-controlled creatures will use the interaction. If no hint is specified, the interaction will be used whenever a valid target is available[Verify]. Multiple usage hints may be specified. Valid values:
|
WAIT_PERIOD | number | The creature must wait the specified number of ticks before being able to use the interaction again. The delay defaults to 20 ticks if this is omitted. Setting it to 0 removes the delay altogether.
Note: A WAIT_PERIOD of 10 is 10 ticks long in fortress mode, but only 1 tick long in adventurer mode. |
FREE_ACTION | Indicates that performing the interaction doesn't take any time. | |
BP_REQUIRED | Body part criteria | Indicates that a particular body part must be present in order to perform the interaction. Criteria are BY_CATEGORY:category, BY_TYPE:type (GRASP, for example), or BY_TOKEN:token (uses the body part ID). See body token. |
VERBAL | Only creatures that can speak will be able to use the interaction. Might also be needed for VERBAL_SPEECH. | |
VERBAL_SPEECH | filename | Specifies what the creature says when they perform the interaction. Filename path is relative to /data/speech. |
CAN_BE_MUTUAL | Presumably allows two creatures with the same interaction to use it on each other simultaneously, for example, cats cleaning each other. | |
VERB | self:other:mutual | When a creature uses the interaction, a combat report message will be displayed in the form:
[interaction user(s)] [VERB text] [target creature (if applicable)] The 'self' text is presented when describing the interaction in the second person (that is, when the interaction is carried out by the player character in adventure mode), the 'other' text is presented when describing it in the third person, and the 'mutual' text is presented when the interaction is carried out in a mutual fashion. [CDI:VERB:lick:licks:lick each other] [CDI:VERB:gesture:gestures:NA] |
VERB_REVERSE | ? | ? |
TARGET_VERB | self:other | When a creature uses the interaction, a message will display, describing the target as doing this.
[CDI:TARGET_VERB:shudder and begin to move:shudders and begins to move] |
FLOW | Breath attack token | Can be used with interactions that have [I_EFFECT:MATERIAL_EMISSION] and [IT_LOCATION:CONTEXT_MATERIAL] (or [IT_MATERIAL:CONTEXT_MATERIAL]) to make the interaction emit a special flow type. Valid values: |
MATERIAL | Material token:Breath attack token | Can be used with interactions that have [I_EFFECT:MATERIAL_EMISSION] and [IT_LOCATION:CONTEXT_MATERIAL] (or [IT_MATERIAL:CONTEXT_MATERIAL]) to make the interaction emit the specified material in the manner described by the breath attack token used. |
Breath attacks
Breath attacks are controlled by the MATERIAL_EMISSION interaction, like so:
[CAN_DO_INTERACTION:MATERIAL_EMISSION] [CDI:ADV_NAME:Breath custom material] [CDI:USAGE_HINT:ATTACK] [CDI:BP_REQUIRED:BY_CATEGORY:MOUTH] [CDI:MATERIAL:LOCAL_CREATURE_MAT:CUSTOMMATERIAL:TRAILING_VAPOR_FLOW] [CDI:TARGET:C:LINE_OF_SIGHT] [CDI:TARGET_RANGE:C:15] [CDI:MAX_TARGET_NUMBER:C:1] [CDI:WAIT_PERIOD:50]
The most important part is this line:
[CDI:MATERIAL:LOCAL_CREATURE_MAT:CUSTOMMATERIAL:TRAILING_VAPOR_FLOW]
The CDI refers to CAN_DO_INTERACTION; the MATERIAL states that this line shows what the material is. LOCAL_CREATURE_MAT:CUSTOMMATERIAL is your material, and TRAILING_VAPOR_FLOW refers to the breath attack type. Other types are seen below. Also important is this line:
[CDI:TARGET:C:LINE_OF_SIGHT]
LINE_OF_SIGHT refers to where the target C may be; others include SELF_ALLOWED (presumably like LINE_OF_SIGHT, but with the creature allowed to target itself)