Stim/Response

This article describes how the stim/response system works for The Dark Mod. The name is taken from the Dromed Stim/Response system. However this does not mean that you should assume any other similarities. The system was described to me (sparhawk) and I coded it accordingly, but I have no Dromed experience, beyond some very simple maps, without any special features. I never got beyond the "Create a room and texture it" stage. :) So while this system may be similar on how it works as seen by the users, you can't assume that this is is more then a fleeting similarity as defined by it's common requirements.

How does it work?

The general concept is pretty easy to understand. The mapper populates his map with entities. Each of this entities, can be either a kind of actor (a stim) or an actee (the response). Any entity can be both at the same time, however stims don't affect the owner itself. So if the entity carries a stim and it triggers, it will not be act on himself, even if the entity has a response for that stim. Stims and responses are defined by numbers. The Dark Mod already defines some very common stims (like water) and reserves numbers for them. For a complete list you should take a look at thje darkmod_stim_response.script in the script folder. You will notice that there is one stim named USER. This stim has no special meaning. Instead it defines the lowest number that users can use for themself. So if you define new stims to be used in your maps, you should use USER+N for your individual stims. All numbers below USER are assumed to be known stims and may trigger specific actions if needed, which possibly includes specific SDK support code.

As explained above, stims and responses are identified by their id's (the numbers). Whenever a stim is active, the system evaluates all stims and checks if appropriate responses are within it's reach. A response is identified by having teh same id as the stim. When such a response is found, the response is triggered and a script action is executed for it. If the response doesn't have a scriptaction associated, nothing will happen, but this is usually a waste of CPU, unless the response is coded in C++ directly in the SDK. One major difference between stims and responses is, that responses have an action associated with it, while stims don't.

Stims and responses can be enabled and disabled at runtime. This is not only a feature, it is very important for the health of the system. If stims are not destroyed after they are used up, they will take up memory and hog your machine down after time. Also accumulating stims will cause the system to respond slower after time, as more and more stims have to be tested. For example: The arrows (like the water arrow) will spawn an entity that carries the water stim, when the arrow explodes. If that stim is not destroyed, it will continue to fire. Once a water arrow is exploded it doesn't makes sense though to keep it running, so it has to be destroyed. However, there is no definite rule when a stim has to be destroyed because it depends on their actual usage. Some stims may run throughout the game and others should be destroyed after they are used up.

How to set it up?

Bascially there are several methods to create a stim/response. The most obvious one is to add it in the SDK code, but this is probably the least prefered. For all practical purposes, stims and responses should be added either via scripting or the map editor, without the need of coding in the SDK environment.

Setting it up in the map editor

For this I use as an example a candle that should be stimmed by water and fire. The water stim will turn it off, while the fire stim will turn it back on. The actual water and fire stims don't need to be created here, because they are created through the water, resp. fire arrow.

The first thing you do is to create brush and assign a candle model to it. Then create one or more lights, that will carry the light of your candle, as the candle itself doesn't have lighting properties. Note down the names of the lights or change them to something you might recognize.

Add the following keys:

  "sr_class_1" "R"
  "sr_type_1" "STIM_WATER"
  "sr_state_1" "1"
  "sr_script_STIM_WATER" "response_water_action"
  "sr_argc" "2"
  "sr_argv_1" "ligth1_name"
  "sr_argv_2" "light2_name"
  "sr_model_1" "candle_turned_off"

  "sr_class_2" "R"
  "sr_type_2" "STIM_FIRE"
  "sr_state_2" "1"
  "sr_script_STIM_FIRE" "response_fire_action"
  "sr_model_2" "candle_turned_on"

Depending on type (Stim or response) some keys are only valid for stims and others only for responses while some others are shared. Since an entity can have multiple different stims and responses, each type has a number in the keyname. However some keys don't need the number. Since each stimtype can exist only once per entity, the script for a given stim can only exist once, even though the scriptname can be reused multiple times (which is not recommended though) or for different stimtypes.

If you want to have multiple stims/responses for the same entity just increase the number on the class.The numbers may have no gaps.

The following keys are mandatory and must be set for every stim/responsetype.

  "sr_class_1" "R"

This key defines wether the entity gets a stim (S) or a response (R). Other values will be ignored and nothing is created. The stim/response is attached to your entity when it spawns.

  "sr_type_1" "STIM_WATER"

This defines the id of the stim or response and must be defined for both classes. You can either use a name, which must be the same as provided by the darkmod_stim_response.script or a number. For user defined stimtypes only numbers are recognized. In case of predefined stmitypes you can also use the number, but using the name is more rcognizable. So in this case you could also write "sr_type_1" "2", which is the id for the water stim. Howevery, if you do this, you must keep in mind that the script key must use the same syntax. In this case instead of writing "sr_script_STIM_WATER" it would also need to be "sr_script_2".

  "sr_state_1" "1"

This key determines wether the stim or response is enabled (1) or disabled (0). If the stim/response is disabled it will not fire (or get triggered).

  "sr_script_STIM_WATER" "response_water_action"

This key defines the response action script that should handle the response when it is triggered. Note that the name must match the stim id. So if you have a numbered id, then you must name the key accordingly (i.e. "sr_type_1" "100" -> "sr_script_100"). For how to apply the ids, also look at the sr_type description above.

The now following keys are scripted and may be changed for different actions. This is for the default implementation though on the water stim. So if you want to do something different you can ignore these keys entirely and write your own script to handle the response.

  "sr_model_1" "candle_turned_off"

This key defines a model that should be swapped in for the existing model, when this response is triggered. In our case we want to replace it with a turned off candle (and possibly add a smoke particle trail for a few seconds).

  "sr_argc" "2"

This key defines how many lights you created for the given entity. In my case I used two. These lights are switched off.

  "sr_argv_1" "ligth1_name"
  "sr_argv_2" "light2_name"

These keys determine the names of the light entites, that need to be switched off when the candle is extuinguished. Consequently when the fire arrow is shot at them, these are the lights that should be relighted.

Stim/Response Key/Values

These can be found here: Stim/Response Key/Values