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 "Interaction token"

From Dwarf Fortress Wiki
Jump to navigation Jump to search
Line 120: Line 120:
 
| {{text anchor|I_TARGET}}
 
| {{text anchor|I_TARGET}}
 
| Global
 
| Global
| id, type
+
| ID, type
| Specifies what things this interaction acts upon. Can be specified multiple times. Valid values:
+
| Defines the targets available for subsequent use with [[Interaction_token#I_EFFECT|[I_EFFECT]] tokens. Multiple targets may be specified; the precise target(s) used with each interaction effect are indicated via their ID (see [[Interaction_token#IE_TARGET|[IE_TARGET]]). Valid values:
* CORPSE - Also includes pieces of corpses
+
* CORPSE - The target is a [[Item_token#CORPSE|CORPSE]] or [[Item_token#CORPSEPIECE|CORPSEPIECE]] item.
* CREATURE
+
* CREATURE - The target is a [[Creature|unit]].
* MATERIAL
+
* MATERIAL - This is a valid target for use in [[Interaction_token#I_EFFECT|[I_EFFECT:MATERIAL_EMISSION]]] interaction effects, and is used to set the material or flow type of the emission. This information, in turn, is either obtained from an [[Interaction_token#IT_MATERIAL|[IT_MATERIAL]]] token or by using [[Interaction_token#IT_LOCATION|[IT_LOCATION:CONTEXT_MATERIAL]]]. Using the latter implies that the precise emission info will be provided when defining [[Interaction_token#Breath_attacks|how an interaction user can use the interaction in question via CDI tokens]], enabling one to create 'template' material emission interactions such as the MATERIAL_EMISSION and MATERIAL_EMISSION_WITH_HIDE interactions included in the vanilla raws.
* LOCATION
+
* LOCATION - The target is a [[tile|local map tile]]. If used with [[Interaction_token#IT_LOCATION|[IT_LOCATION:CONTEXT_CREATURE_OR_LOCATION]]], creatures at the target tile are also valid targets.
  
 
|-
 
|-
Line 131: Line 131:
 
| Within I_TARGET
 
| Within I_TARGET
 
| Location
 
| Location
| Narrows down exactly what the interaction targets. Valid values:
+
| This is often included after [[Interaction_token#I_TARGET|[I_TARGET]]] token to add more detail about the target. Valid values:
* CONTEXT_REGION - Can only be used by IS_REGION interactions.
+
* CONTEXT_CREATURE - Used with CREATURE to target the whole unit.
* CONTEXT_CREATURE
+
* CONTEXT_BP - Used with CREATURE to target the body part specified in [[Interaction_token#BP_REQUIRED|[CDI:BP_REQUIRED]]].
* CONTEXT_CREATURE_OR_LOCATION - Lets projectiles be aimed at specific creatures.
+
* CONTEXT_LOCATION - Used with LOCATION to target only a tile.
* CONTEXT_ITEM - Used when the target is a CORPSE.
+
* CONTEXT_CREATURE_OR_LOCATION - Used with LOCATION to allow for targetting of both creatures and tiles.
* CONTEXT_BP - Use body part from CDI:BP_REQUIRED token (below).
+
* CONTEXT_ITEM - Used with CORPSE.
* CONTEXT_LOCATION
+
* CONTEXT_REGION - Can only be used by [[Interaction_token#I_SOURCE|[I_SOURCE:REGION]]] interactions.
* CONTEXT_MATERIAL
+
* CONTEXT_MATERIAL - Used with MATERIAL if you want an [[Interaction_token#I_EFFECT|[I_EFFECT:MATERIAL_EMISSION]]] to obtain the emission material/flow type from [[Interaction_token#MATERIAL|[CDI:MATERIAL]]] or [[Interaction_token#FLOW|[CDI:FLOW]]].
* RANDOM_NEARBY_LOCATION{{version|0.47.01}} - id, number? - Targets a location from somewhere random within a number of squares from the I_TARGET's location.
+
* RANDOM_NEARBY_LOCATION{{version|0.47.01}} - Used with LOCATION. Targets a location from somewhere random within a number of squares from another [I_TARGET:LOCATION]. For example, [I_TARGET:B:LOCATION] with [RANDOM_NEARBY_LOCATION:A:5] will randomly select a tile lying somewhere within a radius of 5 tiles from [I_TARGET:A:LOCATION]. A walkable path between the two locations must exist.
  
 
|-
 
|-
Line 206: Line 206:
 
| Within I_TARGET:MATERIAL
 
| Within I_TARGET:MATERIAL
 
| type
 
| type
| Specifies the type of material the interaction targets. Valid values:
+
| Specifies the type of material the interaction targets; currently only used for [[Interaction_token#I_EFFECT|MATERIAL_EMISSION]] interaction effects. See [[Interaction_token#Breath_Attacks_Types|Breath Attack Types]]. Valid values:
 
* FLOW:Breath attack token - Specifies an attack not made of any material.
 
* FLOW:Breath attack token - Specifies an attack not made of any material.
 
* MATERIAL:[[Material token]]:Breath attack token - Specifies an attack made of a specific material.
 
* MATERIAL:[[Material token]]:Breath attack token - Specifies an attack made of a specific material.
* CONTEXT_MATERIAL - Use material from CDI:MATERIAL token (below).
+
* CONTEXT_MATERIAL - Use material from [[Interaction_token#MATERIAL|[CDI:MATERIAL]]] token.
  
 
|-
 
|-
Line 216: Line 216:
 
| type
 
| type
 
| Specifies what the interaction does to the targets. Can be specified multiple times. Valid values:
 
| Specifies what the interaction does to the targets. Can be specified multiple times. Valid values:
* ANIMATE - Raises the target corpse/bodypart as a zombie. The zombie will always be hostile to life and will retain no information about its original personality/loyalties. Syndromes can also be specified within this tag. If present on a regional interaction, the region will have undead wildlife.
+
* ADD_SYNDROME - Adds one or more syndromes to a valid creature target.  You must specify the syndrome details just below this interaction effect using the [SYNDROME] tag followed by the relevant syndrome tokens. See [[syndrome#The anatomy of a syndrome|here]] for more information.
* ADD_SYNDROME - Adds one or more syndromes.  You must specify the syndrome details just below this interaction effect using the [SYNDROME] tag followed by the relevant syndrome tokens. See [[syndrome#The anatomy of a syndrome|here]] for more information.
+
* ANIMATE - Raises the target corpse/bodypart as an [[undead]] unit. The zombie will always be hostile to life and will retain no information about its original personality/loyalties. Syndromes can also be specified within this tag. If a regional interaction contains this effect, affected regions will have undead wildlife.
* RESURRECT - Returns the creature to life.  This can be used on parts that are not FIT_FOR_RESURRECTION, but only the main part (with an UPPERBODY attached) will remain loyal to its original faction.  Syndromes can also be specified within this tag.
+
* RESURRECT - Takes a target corpse and returns the creature to life.  This can be used on parts that are not FIT_FOR_RESURRECTION, but only the main part (with an UPPERBODY attached) will remain loyal to its original faction.  Syndromes can also be specified within this tag.
* CLEAN - Cleans off most liquids/dust covering the creature. See [IE_GRIME_LEVEL] and [IE_SYNDROME_TAG].
+
* CLEAN - Removes [[Contaminant|contaminants]] from a valid creature target. See [[Interaction_token#IE_GRIME_LEVEL|[IE_GRIME_LEVEL]]] and [[Interaction_token#IE_SYNDROME_TAG|[IE_SYNDROME_TAG]]].
 
* CONTACT - Causes the creatures to touch.
 
* CONTACT - Causes the creatures to touch.
 
* MATERIAL_EMISSION - Causes a particular material to be emitted. Used by [[evil weather]] and the MATERIAL_EMISSION interaction.
 
* MATERIAL_EMISSION - Causes a particular material to be emitted. Used by [[evil weather]] and the MATERIAL_EMISSION interaction.
 
* HIDE - Allows the creature to hide even if another creature can see it.
 
* HIDE - Allows the creature to hide even if another creature can see it.
* CREATE_ITEM{{version|0.47.01}} - Creates an item as described by [IE_ITEM] and [IE_ITEM_QUALITY].
+
* CREATE_ITEM{{version|0.47.01}} - Creates an item as described by [[Interaction_token#IE_ITEM|[IE_ITEM]]] and [[Interaction_token#IE_ITEM_QUALITY|[IE_ITEM_QUALITY]]].
* CHANGE_ITEM_QUALITY{{version|0.47.01}} - Alters an item's quality level by the amount indicated in [IE_CHANGE_QUALITY]. When targeting a unit, all items equipped by that unit will be affected.
+
* CHANGE_ITEM_QUALITY{{version|0.47.01}} - Alters an item's quality level by the amount indicated in [[Interaction_token#IE_CHANGE_QUALITY|[IE_CHANGE_QUALITY]]]. When targeting a unit, all items equipped by that unit will be affected.
* SUMMON_UNIT{{version|0.47.01}} - Creates a new unit at the target location. The type of unit can either be specified using the [CREATURE] token, or made to be randomly selected as indicated by a variety of flag-based tokens: [IE_CREATURE_FLAG], [IE_FORBIDDEN_CREATURE_FLAG], [IE_CREATURE_CASTE_FLAG] and/or [IE_FORBIDDEN_CREATURE_CASTE_FLAG]. See also [IE_TIME_RANGE] and [IE_MAKE_PET_IF_POSSIBLE].
+
* SUMMON_UNIT{{version|0.47.01}} - Creates a new unit at the target. The type of unit can either be specified using the [[Interaction_token#CREATURE|[CREATURE]]] token, or made to be randomly selected as indicated by a variety of flag-based tokens: [[Interaction_token#IE_CREATURE_FLAG|[IE_CREATURE_FLAG]]], [[Interaction_token#IE_FORBIDDEN_CREATURE_FLAG|[IE_FORBIDDEN_CREATURE_FLAG]]], [[Interaction_token#IE_CREATURE_CASTE_FLAG|[IE_CREATURE_CASTE_FLAG]]] and/or [[Interaction_token#IE_FORBIDDEN_CREATURE_CASTE_FLAG|[IE_FORBIDDEN_CREATURE_CASTE_FLAG]]]. See also [[Interaction_token#IE_TIME_RANGE|[IE_TIME_RANGE]]] and [[Interaction_token#IE_MAKE_PET_IF_POSSIBLE|[IE_MAKE_PET_IF_POSSIBLE]]].
* PROPEL_UNIT{{version|0.47.01}} - Applies a force specified using [IE_PROPEL_FORCE] to a unit to knock it back.
+
* PROPEL_UNIT{{version|0.47.01}} - Applies a force specified using [[Interaction_token#IE_PROPEL_FORCE|[IE_PROPEL_FORCE]]] to a unit to knock it back.
* CHANGE_WEATHER{{version|0.47.01}} - Changes the weather as specified by [IE_ADD_WEATHER] and/or [IE_REMOVE_WEATHER].
+
* CHANGE_WEATHER{{version|0.47.01}} - Changes the weather as specified by [[Interaction_token#IE_ADD_WEATHER|[IE_ADD_WEATHER]]] and/or [[Interaction_token#IE_REMOVE_WEATHER|[IE_REMOVE_WEATHER]]].
 
* RAISE_GHOST{{version|0.47.01}} - Present in version 0.47.01 and accepted as a valid I_EFFECT token, but does not have an effect currently.
 
* RAISE_GHOST{{version|0.47.01}} - Present in version 0.47.01 and accepted as a valid I_EFFECT token, but does not have an effect currently.
  
Line 234: Line 234:
 
| Within I_EFFECT
 
| Within I_EFFECT
 
| ID
 
| ID
| Specifies which I_TARGET this effect will be applied to
+
| Specifies which [[Interaction_token#I_TARGET|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.
  
 
|-
 
|-

Revision as of 16:01, 7 March 2020

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.

Interaction Definitions

Token Context Arguments Description


EXPERIMENT_ONLY Global No arguments This disallows use of the interaction in play and also encourages usage specifically to create experimental populations[1]
I_SOURCE Global type Defines what things are capable of triggering this interaction. Can be specified multiple times. Valid values:
  • REGION - The interaction takes place in particular types of regions in the world.
  • SECRET - The interaction is a secret that can be learned by particular individuals.
  • DISTURBANCE - The interaction is triggered when disturbing a tomb.
  • DEITY - The interaction is inflicted upon mortals by the gods.
  • ATTACK - The interaction is triggered by an attack during combat.
  • INGESTION - The interaction is triggered by eating or drinking something.
  • CREATURE_ACTION - The interaction is triggered by an explicit action.
  • UNDERGROUND_SPECIAL - The interaction takes place in curious underground structures.
  • EXPERIMENT - This interaction is triggered by experimenting [2]
IS_HIST_STRING_1 Within I_SOURCE text Describes what the interaction did to a historical figure. Displayed after the name of the historical figure that performed the interaction.

[IS_HIST_STRING_1: cursed]

IS_HIST_STRING_2 Within I_SOURCE text Describes what the interaction did to a historical figure. Displayed after the name of the historical figure that was targeted by the interaction.

[IS_HIST_STRING_2: to assume the form of a lizard-like monster every full moon]

IS_FREQUENCY Within I_SOURCE Number Presumably, the probability of biome specified by [IS_REGION] to have this interaction.
IS_NAME Within I_SOURCE string Generally used with secrets, describes what the secret is about.
IS_REGION Within I_SOURCE:REGION Region type Indicates what types of regions are capable of performing this interaction. Can be specified multiple times. Valid values:
  • ANY
  • ANY_TERRAIN
  • NORMAL_ALLOWED
  • EVIL_ALLOWED
  • GOOD_ALLOWED
  • SAVAGE_ALLOWED
  • EVIL_ONLY
  • GOOD_ONLY
  • SAVAGE_ONLY
  • Region type - SWAMP, DESERT, FOREST, MOUNTAINS, OCEAN, LAKE, GLACIER, TUNDRA, GRASSLAND, HILLS
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, thus, several [I_SOURCE:SECRET] tokens are required to create a valid custom secret which belongs to several different spheres.
IS_SECRET_GOAL Within I_SOURCE:SECRET Secret Goal token Indicates why somebody would want to learn the secret. Valid values:
  • STAY_ALIVE
  • MAINTAIN_ENTITY_STATUS
  • START_A_FAMILY
  • RULE_THE_WORLD
  • CREATE_A_GREAT_WORK_OF_ART
  • CRAFT_A_MASTERWORK
  • BRING_PEACE_TO_THE_WORLD
  • BECOME_A_LEGENDARY_WARRIOR
  • MASTER_A_SKILL
  • FALL_IN_LOVE
  • SEE_THE_GREAT_NATURAL_SITES
  • IMMORTALITY

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:
  • SUPERNATURAL_LEARNING_POSSIBLE - the secret can be learned by supernatural means
  • MUNDANE_RESEARCH_POSSIBLE - the secret can be researched by mundane means
  • MUNDANE_TEACHING_POSSIBLE - the secret can be taught to apprentices
  • MUNDANE_RECORDING_POSSIBLE:objects/text/(book_title).txt:objects/text/(book_topic).txt - the secret can be written in books with the specified title. If this tag is present, a slab will be created upon learning the secret by supernatural means.
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, MEDIUM_BLESSINGv0.47.01, MEDIUM_CURSEv0.47.01, MINOR_BLESSINGv0.47.01, MINOR_CURSEv0.47.01, and MAJOR_CURSE are the only values that make sense.
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:
  • CONTEXT_CREATURE - Used with CREATURE to target the whole unit.
  • CONTEXT_BP - Used with CREATURE to target the body part specified in [CDI:BP_REQUIRED].
  • CONTEXT_LOCATION - Used with LOCATION to target only a tile.
  • CONTEXT_CREATURE_OR_LOCATION - Used with LOCATION to allow for targetting of both creatures and tiles.
  • CONTEXT_ITEM - Used with CORPSE.
  • CONTEXT_REGION - Can only be used by [I_SOURCE:REGION] interactions.
  • CONTEXT_MATERIAL - Used with MATERIAL if you want an [I_EFFECT:MATERIAL_EMISSION] to obtain the emission material/flow type from [CDI:MATERIAL] or [CDI:FLOW].
  • RANDOM_NEARBY_LOCATIONv0.47.01 - Used with LOCATION. Targets a location from somewhere random within a number of squares from another [I_TARGET:LOCATION]. For example, [I_TARGET:B:LOCATION] with [RANDOM_NEARBY_LOCATION:A:5] will randomly select a tile lying somewhere within a radius of 5 tiles from [I_TARGET:A:LOCATION]. A walkable path between the two locations must exist.
IT_MANUAL_INPUT Within I_TARGET text Tells the player what they should be selecting. If not specified, the player will only be able to target himself.
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:
  • FIT_FOR_ANIMATION - Any corpse or body part that can become a zombie (heads, hands, etc.)
  • FIT_FOR_RESURRECTION - The target corpse's UPPERBODY must be attached.
  • HAS_BLOOD
  • MORTAL
  • NO_AGING
  • STERILE
  • Creature token: BLOODSUCKER, CAN_LEARN, CAN_SPEAK, CRAZED, EXTRAVISION, MISCHIEVOUS (or MISCHIEVIOUS), NO_CONNECTIONS_FOR_MOVEMENT, NO_DIZZINESS, NO_DRINK, NO_EAT, NO_FEVERS, NO_PHYS_ATT_GAIN, NO_PHYS_ATT_RUST, NO_SLEEP, NO_THOUGHT_CENTER_FOR_MOVEMENT, NOBREATHE, NOEMOTION, NOEXERT, NOFEAR, NONAUSEA, NOPAIN, NOSTUN, NOT_LIVING, NOTHOUGHT, OPPOSED_TO_LIFE, PARALYZEIMMUNE, SUPERNATURAL, TRANCES, UTTERANCES
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:
  • FLOW:Breath attack token - Specifies an attack not made of any material.
  • MATERIAL:Material token:Breath attack token - Specifies an attack made of a specific material.
  • CONTEXT_MATERIAL - Use material from [CDI:MATERIAL] token.
I_EFFECT Global type Specifies what the interaction does to the targets. Can be specified multiple times. Valid values:
  • ADD_SYNDROME - Adds one or more syndromes to a valid creature target. You must specify the syndrome details just below this interaction effect using the [SYNDROME] tag followed by the relevant syndrome tokens. See here for more information.
  • ANIMATE - Raises the target corpse/bodypart as an undead unit. The zombie will always be hostile to life and will retain no information about its original personality/loyalties. Syndromes can also be specified within this tag. If a regional interaction contains this effect, affected regions will have undead wildlife.
  • RESURRECT - Takes a target corpse and returns the creature to life. This can be used on parts that are not FIT_FOR_RESURRECTION, but only the main part (with an UPPERBODY attached) will remain loyal to its original faction. Syndromes can also be specified within this tag.
  • CLEAN - Removes contaminants from a valid creature target. See [IE_GRIME_LEVEL] and [IE_SYNDROME_TAG].
  • CONTACT - Causes the creatures to touch.
  • MATERIAL_EMISSION - Causes a particular material to be emitted. Used by evil weather and the MATERIAL_EMISSION interaction.
  • HIDE - Allows the creature to hide even if another creature can see it.
  • CREATE_ITEMv0.47.01 - Creates an item as described by [IE_ITEM] and [IE_ITEM_QUALITY].
  • CHANGE_ITEM_QUALITYv0.47.01 - Alters an item's quality level by the amount indicated in [IE_CHANGE_QUALITY]. When targeting a unit, all items equipped by that unit will be affected.
  • SUMMON_UNITv0.47.01 - Creates a new unit at the target. The type of unit can either be specified using the [CREATURE] token, or made to be randomly selected as indicated by a variety of flag-based tokens: [IE_CREATURE_FLAG], [IE_FORBIDDEN_CREATURE_FLAG], [IE_CREATURE_CASTE_FLAG] and/or [IE_FORBIDDEN_CREATURE_CASTE_FLAG]. See also [IE_TIME_RANGE] and [IE_MAKE_PET_IF_POSSIBLE].
  • PROPEL_UNITv0.47.01 - Applies a force specified using [IE_PROPEL_FORCE] to a unit to knock it back.
  • CHANGE_WEATHERv0.47.01 - Changes the weather as specified by [IE_ADD_WEATHER] and/or [IE_REMOVE_WEATHER].
  • RAISE_GHOSTv0.47.01 - Present in version 0.47.01 and accepted as a valid I_EFFECT token, but does not have an effect currently.
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 Currently only appears to work with [I_SOURCE:REGION] interactions. Indicates that the effect happens intermittently and specifies roughly how often. Valid values:
  • WEEKLY

note: DAILY, MONTHLY and YEARLY also exist in the string dump but aren't currently supported.

IE_IMMEDIATE Within I_EFFECT Indicates that the effect happens immediately.
IE_LOCATION Within I_EFFECT Location Hint Indicates where the effect can take place. Valid values:
  • IN_WATER
  • IN_MAGMA
  • NO_WATER
  • NO_MAGMA
  • NO_THICK_FOG
  • OUTSIDE

A depth of 1/7 appears to be sufficient for IN_WATER and IN_MAGMA.

IE_ARENA_NAME Within I_EFFECT text Allows the interaction to be applied to newly spawned creatures in Arena mode.
IE_ADD_WEATHERv0.47.01 Within I_EFFECT:CHANGE_WEATHER type Indicates what type of weather is added. The available weather types are: FOG_MIST, STRATUS_NIMBUS, FOG_THICK, FOG_NORMAL, FRONT_OCCLUDED, FRONT_COLD, CUMULUS_MULTI, CUMULUS_MED, CIRRUS, CUMULUS_NIMBUS, STRATUS_PROPER, and STRATUS_ALTO.
IE_REMOVE_WEATHERv0.47.01 Within I_EFFECT:CHANGE_WEATHER type Indicates what type of weather is removed. The available weather types are: FOG_MIST, STRATUS_NIMBUS, FOG_THICK, FOG_NORMAL, FRONT_OCCLUDED, FRONT_COLD, CUMULUS_MULTI, CUMULUS_MED, CIRRUS, CUMULUS_NIMBUS, STRATUS_PROPER, and STRATUS_ALTO.
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 flag Indicates that cleaning off materials will activate their syndromes if they have this flag.
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 Defines what quality the created item shall have. In the example shrine effect ITEM_BLESSING is ARTIFACT. Other values are two of any from 1 to 5. They are intended to be a minimum and maximum, but as of 47.01 there is a bug that makes it only work if they are two of the same number.

0 = ordinary

1 = well-crafted

2 = finely crafted

3 = superior quality

4 = exceptional

5 = masterwork

IE_CHANGE_QUALITYv0.47.01 Within I_EFFECT:CHANGE_ITEM_QUALITY amount How much the item(s) shall be improved. 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 to below level 0 (ordinary).
IE_TIME_RANGEv0.47.01 Within I_EFFECT:SUMMON_UNIT minimum, maximum 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.
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.

GENERATED Global Indicates that this is a generated interaction. Cannot be specified in user-defined raws.


Interaction Usage

In order to actually use an interaction, add the creature token [CAN_DO_INTERACTION:NAME] followed by a series of [CDI:...] tokens. Interactions can also be granted through syndromes using the token [CE_CAN_DO_INTERACTION] (plus the same series of CDI tokens).

The following CDI tokens can be specified:

Token Arguments Description
INTERACTION id Specifies which interaction can be performed. Only to be used with syndromes, since CE_CAN_DO_INTERACTION does not allow specifying the interaction ID directly.
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:
  • LINE_OF_SIGHT - the source needs to be able to see the target
  • TOUCHABLE - the source needs to be able to touch the target
  • DISTURBER_ONLY - the target must be whoever disturbed the source
  • SELF_ALLOWED - the target can be the source
  • SELF_ONLY - the target must be the source
TARGET_RANGE target ID, range Specifies how far away the target can be, in tiles. For SOLID_GLOB, LIQUID_GLOB and FIREBALL breath attacks, also determines how far the projectiles will fly before falling to the ground.
LOCATION_HINT Location Hint (see above) ?
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. Valid values:
  • MINOR_BLESSINGv0.47.01 - Used in divination dice blessings. Targets the roller.
  • MINOR_CURSEv0.47.01 - Used in divination dice curses. Targets the roller.
  • MEDIUM_BLESSINGv0.47.01 - Used in divination dice blessings. Targets the roller.
  • MEDIUM_CURSEv0.47.01 - Used in divination dice curses. Targets the roller.
  • MAJOR_CURSE - Used in disturbance curses and deity curses. Targets the tomb disturber/temple defiler.
  • GREETING - Creatures will target 'friendly' creatures, usually at random.
  • CLEAN_SELF - Creature targets itself when covered in liquids or dust.
  • CLEAN_FRIEND - Same, but targets other friendly units.
  • ATTACK - Targets enemy creatures in combat. If the interaction specifies SELF_ONLY, CPU-controlled creatures will never use it.
  • FLEEING - Used when fleeing an enemy. Creature will target itself.
  • NEGATIVE_SOCIAL_RESPONSE - Used when a creature is expressing contempt (for example, to a murderer). Used for spitting by civilised races.
  • TORMENT
  • DEFENDv0.47.01 - Used in combat. Creature will target itself.
ADV_NAME text Specifies the interaction's name when used in Adventurer mode.
MAX_TARGET_NUMBER ID, number Specifies the maximum number of things that can be selected for a particular I_TARGET.
WAIT_PERIOD number Controls how often the interaction can be used.
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.
FREE_ACTION Indicates that performing the interaction doesn't take any time.
VERB self:other:mutual When a creature uses the interaction, a message will display, describing the source as doing this.
VERB_REVERSE ? ?
TARGET_VERB self:other When a creature uses the interaction, a message will display, describing the target as doing this.
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, or BY_TOKEN:token.
FLOW Breath attack token Causes the interaction to create an effect not made of any material. Only makes sense for FIREBALL, FIREJET, or DRAGONFIRE.
MATERIAL Material token:Breath attack token Causes the interaction to create an effect made of a specific material. Doesn't make sense for FIREBALL, FIREJET, or DRAGONFIRE.

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), SELF_ONLY (preferable for undirected attacks and TOUCHABLE (for up-close attacks, as trailing flows tend to be).

Breath Attack Types

When using types of MATERIAL the format would be: [CDI:MATERIAL:material:sub-material:action-type] action-type being like SOLID_GLOB or UNDIRECTED_VAPOR

When using types of FLOW the format would just be: [CDI:FLOW:FIREBALL]

Token Usage Type Description
TRAILING_DUST_FLOW MATERIAL Lets out a cloud of solid dust. Appears to use cave-in dust physics, causing this to fling around anything it comes in contact with, making it capable of smashing creatures into the ground and flinging them over walls. Creature will attack as normal.
TRAILING_VAPOR_FLOW MATERIAL Shoots a trail of liquid mist at the target which can condense and trigger contact syndromes. Creature will attack as normal.
TRAILING_GAS_FLOW MATERIAL Shoots a trail of gas substance at the target which can be inhaled. Creature will attack as normal.
TRAILING_ITEM_FLOW:item token MATERIAL Shoots a "cloud" of items at the target, leaving piles of this item on the floor. Note that this does not create the actual items or use falling item mechanics (meaning no flying daggers or Touhou-style barrages, unfortunately). Instead, this token acts as TRAILING_GAS_FLOW, except that the material will use its normal temperature - for example, a breath attack of steel anvils will envelop the target in a "burst of steel". Creature will attack as normal.
SHARP_ROCKv0.47.01 MATERIAL Shoots a sharpened solid chunk of spinning substance at the creature, leaving symbols similar to broken arrows, essentially, a projectile weapon. If the cooldown rate is short enough, some creatures with this breath attack will not move, preferring instead to hold position and shoot shards at you, even when you are literally right next to them.
SOLID_GLOB MATERIAL Shoots a solid glob of spinning substance at the creature, leaving symbols similar to broken arrows, essentially, a projectile weapon. If the cooldown rate is short enough, some creatures with this breath attack will not move, preferring instead to hold position and shoot globs at you, even when you are literally right next to them.
LIQUID_GLOB MATERIAL Shoots a liquid glob of substance at the target. Contact syndromes will take effect if the glob hits the target's exposed skin.
SPATTER_POWDER MATERIAL Creates a pile of powder at the specified location.
SPATTER_LIQUID MATERIAL Creates a pool of liquid at the specified location.
UNDIRECTED_GAS MATERIAL Creature occasionally releases a cloud of gas substance. Similar to TRAILING_GAS_FLOW, but undirected, thus affecting a larger area but losing the distance. Creature will attack as normal.
UNDIRECTED_VAPOR MATERIAL Creature occasionally releases a cloud of liquid mist. Similar to TRAILING_VAPOR_FLOW, but undirected, thus affecting a larger area but losing the distance. Creature will attack as normal.
UNDIRECTED_DUST MATERIAL Creature occasionally releases a cloud of solid dust, which will spread and dissipate. Similar to TRAILING_DUST_FLOW, but undirected, thus affecting a larger area but losing the distance - range is roughly the same as that of a cave-in. Creature will attack as normal. DO NOT USE THIS TAG UNLESS YOU WANT TO KILL THE CREATURE AND EVERYTHING NEAR IT AND SEND PEOPLE FLYING. You know you want to.
UNDIRECTED_ITEM_CLOUD:item token MATERIAL Creature occasionally releases a "cloud" of items at the target, leaving piles of this item on the floor. The same comments apply as TRAILING_ITEM_FLOW. Creature will attack as normal.
WEB_SPRAY MATERIAL Emits a burst of webs that entangle target creatures.
DRAGONFIRE FLOW Emits a wide cone of dragon fire that burns target creatures at a scorching 50000 °U . For this you want FLOW instead of a material.
FIREJET FLOW Emits a narrow cone of fire that burns target creatures at 11000 °U . For this you want FLOW instead of a material.
FIREBALL FLOW Emits a fireball that burns the target creature. For this you want FLOW instead of a material.
WEATHER_CREEPING_GAS MATERIAL Creates a cloud of gas that appears at the edge of the map and slowly creeps across the map. Not usable by creatures.
WEATHER_CREEPING_VAPOR MATERIAL Creates a cloud of creeping vapor. Not usable by creatures.
WEATHER_CREEPING_DUST MATERIAL Creates a cloud of creeping dust. Not usable by creatures.
WEATHER_FALLING_MATERIAL MATERIAL Causes it to start raining a particular material. If the material is solid at the outdoor temperatures, it will snow the material instead. Regardless of the nature of the material, being caught in it will give dwarves the bad thought of being 'caught in freakish weather lately'. Not usable by creatures.

Keep in mind that you can use multiple breath attacks, which appears to make the creature choose between them at random. Creatures cannot use the WEATHER effects, these being reserved for regional interactions.

One major difference between GAS, VAPOR, and DUST is that if the material cannot exist in the specified state at the current temperature, it will automatically be created at a temperature allowing it to exist. So if you create a vapor spray that uses rock or metal as a material, that spray will be created at the material's melting point, setting everything it touches on fire. You can also create a freezing spray by using a custom material that has extremely low melting and/or boiling points.

If you give a creature a material breath attack, be aware that it will be caught in the attack more frequently than its targets. Make sure to make your creatures immune to their own breath weapons!

See Also