Stim/Response Key/Values

Originally written by Ishtvan on http://forums.thedarkmod.com/topic/3960

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 resposes

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.

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 cube centered on the entity origin.

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_falloffexponent_N 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 magnitude is 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..

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_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.

Response only

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.

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++.