Stim/Response Key/Values

Note: There is now a stim/response editor accessed via the Dark Radiant entity menu which makes it easier to set these key/values. The editor settings will be shown below next to their equivalent key/values (work in progress.)

There are some useful notes regarding STIMs here: http://wiki.thedarkmod.com/index.php?title=User:VanishedOne

I added two new key/vals to stim response, and figured I would document them all here including the new ones.

In all of these, N is the number of the stim on the entity. It starts at 1 and goes up. Be aware of any stims that are defined on the entity in other places, like in the def file or in something inherited by it. Stims on the entity itself must start counting from the last one of these, so if the def file has 1 stim, the entitydef in the map would start at number 2.

Keys that can be used to set up both stims and responses

Key: sr_class_N Set to "S" for stim, "R" for response.

Key: sr_type_N Type of stim (e.g. STIM_WATER). See /script/darkmod_stim_response.script for a complete list of stim types.

Key: sr_state_N Set to "1" for enabled, "0" for disabled. This may be altered later with scripting.

Key: sr_chance_N Probability for this stim/response to fire/react. Set this to 0.3 if you want to have a 30% chance.

Stim only

Key: sr_use_bounds_N Set to "1" if you want to use the bounds of the entity as the basis for the intersection test. "0" (the default) uses a sphere centered on the entity origin.

Springheel: I cannot confirm this. After a lot of tests, it seems that the game is measuring the distance from the origin of the stim to the bounds of the response. It looks like the origin of the stim must be [radius + distance] => 4 in order to avoid stimming the response.

Tests intersection between the physical models of entities A and B, where A carries the stim and B perhaps has a response set. Used for 'immersion' in liquids. If A also has a radius set on the stim, the stim can be applied to B when the radius intersects with B's physical model.

Key: sr_collision_N Stim on entity A is applied to entity B when A and B collide.

Key: sr_radius_N Radius of the stim in doomunits. NOTE: If you set sr_use_bounds to "1", the radius is applied as an expansion of the entity bounding box in all directions. So if you select use bounds and set the radius to "0", this makes the stimmed region exactly equal to the stim bounds.

Key: sr_radius_final_N Final radius of the stim (i.e. the radius at the end of its lifetime). While the stim is active, the radius will linearly change within the [sr_radius..sr_radius_final] interval. The start value is defined by sr_radius, the end value by this spawnarg. Note that sr_radius_final is not necessarily larger than the sr_radius value, it's also possible to let a stim shrink. For this spawnarg to work, the sr_duration value must be greater than zero.

Key: sr_magnitude_N (float) The maximum magnitude of the stim at zero distance. If the responding entity's origin is exactly at the origin of the stimming entity (which is not always possible due to the collision boxes), this magnitude value is passed to the response effect scripts.

Key: sr_falloffexponent_N (float) The falloff exponent determining the magnitude in dependency of the distance. There is no limitation to this value, although only a few make sense.

0 = no falloff (magnitude is constantly at maximum value over the whole radius)

1 = linear falloff

2 = quadratic falloff

3 = etc.

The higher the number, the faster the magnitude is decreasing with the distance. The magnitude is reaching zero as soon as the distance of the responding object is greater than or equal to the stim radius, except for falloffexponent = 0 (no falloff). Negative values are allowed as well, this way it should be possible to actually increase the magnitude of a stim with larger distance. Don't know if that makes sense, though and I haven't tested it either.

For documentation purposes, this function is used to determine the actual magnitude: m(dist) = m0*[ 1 - dist/radius]^falloffExponent (math functions seem to be disabled for this wiki)

Key: sr_duration_N This specifies how long the stim is active before it gets disabled. If this is key is empty, the stim has infinite lifetime (apart from being disabled by scripts and such). Changing this value to 2000 will mean the stim is active for 2 seconds (apparently from map start).

Key: sr_time_interval_N When this stim is active, the firings will be spread out by this many milliseconds. So a stim with sr_time_interval = 500 will fire every half second when active. Used for optimization for stims that don't have to be checked that often.

Key: sr_max_fire_count_N (default: -1) This specifies the maximum number of stim firings that are possible for this stim. The default is -1 which means that it can be fired infinitely often. With each firing, the counter is decreased. When it reaches zero, the stim is entirely ignored from then on. Currently there is no way to reactivate a stim whose max_fire_count has been depleted. Stims that fail because of their sr_chance_N spawnarg decrease the counter as well.

Key: sr_timer_time_N (Format: hhhh:mm:ss:ms, for example: 0:3:20:0 which means 3 minutes and 20 secs) (s & r editor = Activation Timer.) This can be used to enable the stim after a certain amount of time. Depending on the sr_timer_waitforstart key the timer is started on spawn or on a "StartTimer" event. Use this to setup a stim that has its sr_state_N set to 0 at start and gets enabled after a certain amount of time. This is only effective if the sr_state is 0 (disabled) by the time this timer is elapsing (s & r editor = Active checkbox.)

Key: sr_timer_waitforstart_N (0 or 1, default is 0) If this key is TRUE = "1", the timer has to be started by a StartTimer script event or the according response effect. If this is set to 0, the timer starts on spawning this entity (beware: the entities might be spawned quite some time before the map is actually started, on my testmap it sometimes took up to 20 seconds before the player is spawned, so this is not a very reliable measure).

Key: sr_timer_type_N | possible values: "RELOAD" or "SINGLESHOT" (default) When this is set to RELOAD, the timer is reactivated after the stim has been fired. This can be used to setup sophisticated time intervals. I intend to draw a graph explaining this, so if this is not yet in the wiki, you can bug greebo to do this. :)

Key: sr_bounds_mins_N and sr_bounds_maxs_N (Type: Vector, default is "0 0 0") These two vectors define the bounding box of the stim. This is measured relatively to the stim origin (which might be moving), not the entity origin. A vector pair of -10 -10 -50 and 10 10 150 defines a primarily vertical stim area.

Key: sr_velocity_N (type: Vector, default: "0 0 ") This defines the velocity of the stim in units per second. A vector of 0 0 -10 let's the stim move downward for 10 units per second for the stim duration time.

Response only

Key: sr_chance_timeout_N Many stims like the water arrow stim are firing rapidly multiple times a second, distorting the "effective" probability of a response going off. Use this to give the response a timeout before it can be evaluated again after a failed probability check.

Key: sr_random_effects_N If this spawnarg contains non-zero values, exactly this number of random response effects is chosen from the available ones. So, if you set sr_random_effects to 2 and there are 5 effects available, two are randomly chosen (may also be one of them twice). If only one effect is available, just this one is fired twice.

Key: sr_script_<STIM TYPE> First off, the name of this key: <STIM TYPE> should be replaced with the string name of one of the stim types. For example, sr_script_STIM_WATER defines the script to call in respone to a water stim. Apparently there can only be one of these per stim type. <STIM TYPE> can either be the name as a string (in case of default stims) or the number: sr_script_STIM_WATER sr_script_2 Both of which will have the same meaning, assuming that the water stim has the number two.

The value this key contains the name of the script function to call. If it's a local script, you must put it in the form of "<script object name>::<local function>" otherwise "<global function name>" works as well.

Note: When using the stim/response editor, you must right-click on the Response Effects field in order to enter an effect. Not sure how anyone would know that.

Also note, responses set on AI persist when the AI goes to ragdoll state.

Important note about writing response scripts

There's some subtlety about writing these response scriptfunctions. Global scriptfunctions must take two arguments: an entity argument and int threadnum argument. The first argument is the entity that was stimmed. Local response functions (those on the entity being stimmed) should not have the entity argument, only taking one argument, the threadnum. This is because the entity being stimmed is the same as the entity running the script, so the argument is passed implicitly as the "self" entity, just like the "this" pointer is passed implicitly in C++.

Examples

Damage Stim

An entity has a STIM_DAMAGE with a magnitude of 100 and a linear falloff (1). The further you're away from the stim origin, the smaller the magnitude gets.

Once an entity with a response to STIM_DAMAGE comes into range and the stim fires, the magnitude is passed on to the response entity. The response entity needs to have a response effect defined for the DAMAGE stim, which tells the code which damage entityDef (e.g. atdm:damage_simple) it should use and which entity should be damaged (this should be _SELF by default).

So, an example response setup can be found on the player:

// The damage response
"sr_class_3" "R"
"sr_type_3" "STIM_DAMAGE"
"sr_state_3" "1"
"sr_effect_3_1" "effect_damage"
"sr_effect_3_1_arg1" "_SELF"
"sr_effect_3_1_arg2" "atdm:damage_simple"

As soon as the player comes into the range of a damage stim, the distance-based magnitude is passed over and the code multiplies this magnitude with the "damage" value defined in atdm:damage_simple. E.g. if a magnitude of 30 is passed, the atdm:damage_simple's value of 10 ends up at 300 => insta-death.

If you want to have a constant magnitude which is not depending on the distance, you need to define a 0 falloff on the stim.

Remove torch damage if extinguished with water

If you have hot torches/ovens that damage the player if too close, but shouldn't if extinguished, first copy the name of the entity that has the damage stim. Then use the Stim/Response editor to add a Water Response, effect "Deactivate Stim", pasting/selecting the entity with the damage stim, and "Damage". (One would want a Fire Response, "Activate Stim" if they wished damage to return if reignited.)

See Also

• Stim/Response overview
• Triggers