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.
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 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_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_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.
Key: sr_duration_N When this is set, the stim will last just for the specified time and disable itself afterwards. Measured from the time the stim is enabled, so it's possible to setup a stim that is disabled at spawn time (e.g. for projectiles) and begins "firing" later for the given amount of 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.
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++.
