DSB/Exvars

This is a list of Exvars used by DSB's DSBBaseCode. Exvars marked Designer can be set by the dungeon designer to easily create different effects. Exvars marked Internal are best left alone unless you really know what you're doing.

air (boolean) - Designer

Found in: trigger, pad, teleporter, etc.
Used by: Most standard on_trigger events

air is used by triggers that are supposed to be activated by objects (monsters or items) flying over them.

air_only (boolean) - Designer

Found in: trigger, pad, teleporter, etc.
Used by: Most standard on_trigger events

air is used by triggers that are supposed to be activated only by objects (monsters or items) flying over them.

apower (integer) - Internal

Found in: poison_cloud
Used by: create_poison_cloud (base/damage.lua), etc.

apower is used to set the attacking power of a poison cloud. This determines the damage done and the size of the cloud. A LO cloud is around 30, a MON cloud is over 192.

bash_power (integer) - Designer

Found in: Doors
Used by: attack_door (base/methods.lua)

bash_power determines how well a door resists physical attack. 20 can be bashed by most moderately strong characters. 90 will require strength potions, but is doable.

Note: Some archetypes have a bash_power set as well. If no bash_power exvar is set for a given instance, the archetype's bash_power is used instead. Set bash_power = 9999 to create an unbashable instance of a bashable archetype.

champion (integer) - Designer

Found in: mirror
Used by: A mirror's on_click event

This stores the character id (returned by dsb_add_champion) of the character who is in that mirror. If the archetype's renderer_hack is "MIRROR" then the value of this exvar will be used to draw the champion's portrait inside of the mirror.

const_weight (boolean) - Designer

Found in: trigger, pad, etc.
Used by: Most standard on_trigger events

If const_weight is true, the instance will call its got_untriggered event when whatever was activating it ceases to do so.

count (integer) - Designer

Found in: Wall buttons, trigger, x_counter, etc.
Used by: Most standard on_trigger and on_click events

count keeps track of how many more times a wallitem or flooritem needs to be activated before it actually does anything. Every activation of the item decrements count by 1. Once count is 0, the item is triggered and count is set to nil. For example, a double lock that needs two keys of the same type simply uses count = 2. Not defining count is equivalent to having count = 1.

damage (integer) - Designer

Found in: shooter
Used by: shooter_shoot (base/msg_handlers.lua)

This sets the base damage of something shot out of a wall shooter. If this is unset, the value of power is used. It's useful if you want something to hit extra hard but not fly very far, or vice-versa.

delay (integer) - Designer

Found in: Most buttons and triggers
Used by: Most standard on_trigger events

delay puts a delay on any messages sent by the triggering of whatever instance. For example, a trigger that opens a pit on its own square after a few ticks would use delay, like in CSB's Supplies For The Quick room.

delta (integer) - Designer

Found in: shooter
Used by: shooter_shoot (base/msg_handlers.lua)

This sets how fast something shot out of a shooter loses velocity and power. If this exvar is unset, a standard value of 8 is used.

delta (integer) - Internal

Found in: Clouds
Used by: cloud_shrink (base/msg_handlers.lua)

This sets how fast a cloud should shrink. It must be set, and is typically set by the function that spawns the cloud. There isn't a lot of need to set it directly.

destroy (boolean) - Designer

Found in: Most buttons and triggers
Used by: Most standard on_trigger events

If destroy is true, the got_triggered function will call dsb_delete on the instance that operated the trigger. For example, all standard DM keyholes have destroy set.

disable_self (boolean) - Designer

Found in: Most buttons and triggers
Used by: Most standard on_trigger events

If disable_self is set to true, the instance will no longer respond after being triggered once.

door_state (integer) - Internal

Found in: Doors
Used by: door_tick, etc. (base/msg_handlers.lua)

Keeps track of whether a partially open door is moving up or down.

double (boolean) - Designer

Found in: shooter
Used by: shooter_shoot (base/msg_handlers.lua)

If double is true, a shooter will shoot both sides at the same time.

face (integer) - Designer

Found in: Teleporters
Used by: base_teleporter, etc. (base/triggers.lua)

Sets the facing of anything going through the teleporter.

fire_power (integer) - Designer

Found in: Doors
Used by: explode_door (base/util.lua)

fire_power determines how well a door resists fire attack. 20 can be exploded by any sort of fireball. 90 will require mon fireballs.

Note: See notes for bash_power above.

func (string) - Designer

Found in: Most buttons and triggers
Used by: Most standard on_trigger events

Calls the specified function, with the following parameters: func(id, opby, func_data)

func_data (anything) - Designer

Found in: Most buttons and triggers
Used by: Most standard on_trigger events

This exvar is passed as the third parameter to func, above.

generates (string) - Designer

Found in: monster_generator
Used by: generate_monster (base/msg_handlers.lua)

Sets the type of monster that is generated by a monster generator.

hp (string) - Designer

Found in: monster_generator
Used by: generate_monster (base/msg_handlers.lua)

Sets the hp of monsters that are generated by a monster generator.

Important: This exvar is not used to set the hp of a monster itself. You need to use the function dsb_set_hp for that.

lev (integer) - Designer

Found in: Stairs and teleporters
Used by: base_teleporter, etc. (base/triggers.lua)

Sets the destination level of stairs or teleporters. If it is unset for stairs, it will be determined by the direction of the stairs.

light (integer) - Internal

Found in: light_controller
Used by: magic_light (base/magic.lua)

This exvar is used to store the current light level of a "light_controller" instance. Designers are advised to not spawn light_controllers directly and to use calls to magic_light instead.

mai_* (various) - Mostly Internal

Found in: Monster AI Routines
Used by: Many functions in base/monster_ai.lua

These exvars are used by the MonsterAI to store information about the monster's enviroment and plan its actions. A detailed understanding of monster AI would be required anyway, so the best way to learn what the AI variables are and how to use them is to read over the MonsterAI article as well as the code in monster_ai.lua.

max (string) - Designer

Found in: monster_generator
Used by: generate_monster (base/msg_handlers.lua)

Sets the maximum number of monsters that are generated at a time by a monster generator.

min (string) - Designer

Found in: monster_generator
Used by: generate_monster (base/msg_handlers.lua)

Sets the minimum number of monsters that are generated at a time by a monster generator.

msg (integer) - Designer

Found in: Most buttons and triggers
Used by: Most standard on_trigger events

The msg exvar specifies what message is to be sent when a button or trigger is triggered. Though it is internally an integer, in the base code, symbolic names are used for ease. For example, MSG_ACTIVATE, MSG_TOGGLE, etc.

opby (string or {string, string, ...}) - Designer

Found in: Most buttons and triggers
Used by: Most standard on_trigger events

opby stores the name of the arch (or arches) that will operate the instance. For example, a gold keyhole would have opby = "key_gold"; a keyhole that can take either a gold or iron key would be opby = { "key_gold", "key_iron" }

opby_class (string) - Designer

Found in: Most buttons and triggers
Used by: Most standard on_trigger events

opby_class stores the name of the class that will operate the instance. For example, a trigger requiring a torch will probably have opby_class = "TORCH", as there are actually four distinct objects that are torches (corresponding to four levels of illumination)

opby_empty_hand_only (boolean) - Designer

Found in: Wall triggers
Used by: Most standard on_trigger events

If true, the instance is only operated if it is clicked with an empty hand.

opby_func (string) - Designer

Found in: Most buttons and triggers
Used by: Most standard on_trigger events

opby_func stores the name of a function that will be called to determine if the trigger is operated. This function is of the form func(id, what, wallitem, teleporter). In this case, id is the trigger's instance, what is the triggering instance, and wallitem and teleporter are boolean variables denoting whether the trigger is a wallitem or teleporter (which frequently require special cases in their opbys).

opby_id (integer) - Designer

Found in: Most buttons and triggers
Used by: Most standard on_trigger events

opby_id stores one specific instance id that will operate the trigger instance. For example, an enchanted gold lock that requires one specific gold key to work. Be very careful with this one-- if the id is re-used for something else, it'll still be valid, and if the id is somehow destroyed, the item will no longer exist at all!

opby_monster (boolean) - Designer

Found in: Floor triggers
Used by: Most standard on_trigger events

If true, the instance can be operated by a monster walking (or, if air and/or air_only are used, flying) over it.

opby_party (boolean) - Designer

Found in: Floor triggers
Used by: Most standard on_trigger events

If true, the instance can be operated by the party stepping on it.

opby_party_carry (string or {string, string, ...}) - Designer

Found in: Floor triggers
Used by: Most standard on_trigger events

The instance is operated by the party carrying the item (or items) specified over it.

opby_thing (boolean) - Designer

Found in: Most buttons and triggers
Used by: Most standard on_trigger events

If true, the instance can be operated by any pickable-uppable thing.

pmsg (integer) - Internal

Found in: Torches
Used by: torch_light (base/util.lua)

Used to prevent torches from burning down very quickly when they are taken out of the hand repeatedly, by suppressing multiple messages from being sent.

power (integer) - Designer

Found in: Bomb potions
Used by: explode_thing (base/damage.lua)

This exvar is used to store the power level of a bomb potion. It is an integer from 1 (LO) to 6 (MON).

power (integer) - Designer

Found in: shooter
Used by: shooter_shoot (base/msg_handlers.lua)

This sets the base power of something shot out of a wall shooter. A good throw by a champion is around 60-80.

power (integer) - Internal

Found in: shield_controller
Used by: magic_shield (base/magic.lua)

This exvar is used to store the remaining power of a magical shield controlled by a a "shield_controller" instance. Designers are advised to not spawn shield_controllers directly and to use calls to magic_shield instead.

regen (string) - Designer

Found in: monster_generator
Used by: generate_monster (base/msg_handlers.lua)

Sets the amount of time (in ticks) before a monster generator will be able to generate another monster.

release (boolean) - Designer

Found in: sconce, etc.
Used by: wallitem_click (base/triggers.lua)

If this exvar is set to true, the instance will release an instance contained inside of it into the mouse hand when it is clicked.

Note: This is only used through wallitem_click and only works with one item. If the archetype can hold more than one item, you will have to call wallitem_take_object and wallitem_release_object directly. A simple example is below:

function alcove_click(self, id, what)
 	if (what) then
 		wallitem_take_object(self, id, what)
 	else
 		wallitem_release_object(self, id, what)
 	end
end

shoots (string) - Designer

Found in: shooter
Used by: shooter_shoot (base/msg_handlers.lua)

If this exvar is set, the shooter will spawn an instance of whatever archetype is named and shoot that. If it's not set, the shooter will try to shoot things already found in its square.

silent (boolean) - Designer

Found in: Various
Used by: Various

Many instances will click, clank or buzz by default when they are activated. Set silent to true to keep them from doing this.

sound (string) - Designer

Found in: Various
Used by: Various

Most instances that can be triggered somehow can have this exvar set to play a certain sound when the triggering occurs. For example, triggers, buttons, teleporters, and monster generators.

spin (integer) - Designer

Found in: Teleporters
Used by: base_teleporter, etc. (base/triggers.lua)

Gives a value added to the facing of anything going through the teleporter. For example, something facing NORTH entering a teleporter with a spin of 2 will come out facing SOUTH. Do not use negative values: Use 3 instead of -1, for example.

target (integer or {integer, integer, ... }) - Designer

Found in: Most buttons and triggers
Used by: Most standard on_trigger events

The target exvar specifies the target of a trigger's message. It can also be specified as a table of targets, to allow multiple instances to be targeted.

tc (integer) - Internal

Found in: trigger, pad, teleporter, etc.
Used by: Most standard on_trigger events

This variable stores a count of the number of items on the trigger. This is used to ensure pressure pads etc. work properly. It's also necessary for constant weight.

text (string) - Designer

Found in: Various
Used by: Various

This is used to set the text associated with any instance. A scroll's subrenderer will display this text on the scroll, for example. Most other types of instances without subrenderes will have the text displayed when the instance is viewed. Wallitems with the "WRITING" renderer_hack will use this exvar to determine what to display on the wall. Use a '/' to indicate a new line, upper case for the text and lower case for runes starting with an 'a' for a 'LO' symbol.

type (integer) - Internal

Found in: shield_controller
Used by: magic_shield (base/magic.lua)

This exvar is used to store the type of a magical shield controlled by a a "shield_controller" instance. Designers are advised to not spawn shield_controllers directly and to use calls to magic_shield instead.

x (integer) - Designer

Found in: Stairs and teleporters
Used by: base_teleporter, etc. (base/triggers.lua)

Sets the destination x coordinate of stairs or teleporters. If it is unset for stairs, the coordinate will remain the same.

y (integer) - Designer

Found in: Stairs and teleporters
Used by: base_teleporter, etc. (base/triggers.lua)

Sets the destination y coordinate of stairs or teleporters. If it is unset for stairs, the coordinate will remain the same.

zoable (boolean) - Designer

Found in: Doors
Used by: zo_explosion (base/util.lua)

If zoable is true, a door will respond to zo spells even if there is no button on it.