Stim/Response Key/Values

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

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

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.

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