DSB/Exposed functions

Introduction

Functions are given in the form:

function(arguments, ~[optional arguments]) = return value

If the terminology doesn't make sense, check DSB/Basic DSB Terminology.

Functions without a dsb_ prefix are part of base/, not the core engine.

Iterators

dsb_insts()

This is an iterator used in Lua's for loops. To iterate over all instances of objects in a DSB dungeon, use something like:

for i in dsb_insts()

dsb_in_obj(id)

Another iterator; see above for usage. This one is used to iterate all over all instances that are inside the given instance.

Bitmaps and Drawing

dsb_get_bitmap(name) = bitmap

Searches the dungeon's directory for the bitmap, and then graphics.dsb, and finally the default graphics.dat. Returns a truecolor bitmap, but the bitmap can be 256 colors on disk to save space. Don't specify a file extension as DSB will figure it out.

dsb_get_bitmap(name, relative_path) = bitmap

Same as above but with subdirectories. Example: "path/to/actual/file.ext"

dsb_get_mask_bitmap(name) = bitmap

This function loads a bitmap that requires two distinct regions of transparency that are used at different times, such as see-through door decorations or magic windows. The region that is transparent when the image is first blitted is represented by color 0, whereas the region that is "see through" is in the usual magenta color. This requires a 256 color bitmap.

dsb_new_bitmap(xsize, ysize) = bitmap

Creates a brand new bitmap and returns a reference to it.

dsb_destroy_bitmap(bitmap)

Completely destroys a bitmap. Rarely needed, as Lua's garbage collector will automatically scoop up out-of-scope bitmaps. You should only invoke this by hand if you know for sure why you need it.

dsb_clone_bitmap(bitmap) = bitmap

Creates a "virtual bitmap" clone of the specified bitmap. It shares the same actual memory, but can have different offsets. This is useful if you, for example, have several wallitems for which you want to draw the same image on different parts of the wall.

dsb_animate(bitmap, frames, frame_delay)

Sets up a bitmap that is a series of frames for animation.

dsb_bitmap_clear(bitmap, RGB)

Clears a bitmap to the specified RGB value. An RGB is specified as a table of { R, G, B }.

dsb_bitmap_blit(src_bmp, dest_bmp, x_src, y_src, x_dest, y_dest, width, height)

Blits one bitmap onto another.

dsb_bitmap_draw(src_bmp, dest_bmp, x, y, flip)

Draws the entire source bitmap on to the destination, taking any animation or offsets into account. Pass true to flip to horizontally flip the bitmap.

dsb_bitmap_width(bitmap) = integer

dsb_bitmap_height(bitmap) = integer

Returns the dimension of the bitmap.

dsb_bitmap_rect(bitmap, x_src, y_src, x_dest, y_dest, color, filled)

Draws a rectangle. Pass true to filled for a filled rectangle.

dsb_bitmap_textout(bitmap, font, string, x, y, alignment, color) = integer

Renders text onto a bitmap in the specified font and color, with the specified alignment: (LEFT, RIGHT, CENTER, or MULTILINE). Returns the number of lines printed.

dsb_dungeon_view(lev, x, y, dir, light) = bitmap

Return a rendering of the viewport.

dsb_viewport_distort(effect)

For viewport postprocessing

dsb_get_pixel(bmp, x, y) and dsb_set_pixel(bmp, x, y, rgb, [alpha])

These are used for per-pixel bitmap manipulation

dsb_override_floor(???) = ???

This function is called when your view changes to a different level. But what does it do?!

dsb_override_roof(???) = ???

This function is called when your view changes to a different level. But what does it do?!

Fonts and Text

dsb_get_font(name, relative_path) = font

Searches the same paths as dsb_get_bitmap, loading a font. Example with a subdirectory:

gfx["GAUDYMEDIEVALFONT"] = dsb_get_font("GAUDYMEDIEVAL", "fonts/gaudymedieval.pcx")

dsb_textformat(chars_per_line, y_offset_per_line, max_lines)

This controls the format of MULTILINE text output by dsb_bitmap_textout. The Y offsets are also used by the console (the text below the game view). By setting chars_per_line to something unreasonable, you can effectively disable word wrapping.

dsb_write(RGB, string)

Outputs the given text string in the given color to the console. (that is, a table of { R, G, B })

Sound and Music

dsb_get_sound(name) = sound

Searches the same paths as dsb_get_bitmap, loading a sound.

dsb_sound(sound, ~[loop]) = chan_handle

Plays the given sound. An optional boolean parameter allows you to specify if the sound should loop. Be careful, the only way to stop a looping sound is via dsb_stopsound, so don't lose the channel handle!

dsb_music(sound, ~[loop]) = chan_handle

Plays a sound file directly from disk instead of loading into memory first. This function only works with direct filenames, you can't send it a full path -- so your music file must be in the root of your dungeon directoy. If you use dsb_music, it will at least load it on demand and destroy it when it's finished, so your memory usage will be lower than if you loaded it directly as a sound.

dsb_3dsound(sound, lev, x, y, ~[loop]) = chan_handle

Plays the given sound as though it originated from the given location in the dungeon. An optional boolean parameter allows you to specify if the sound should loop. Note that base/util.lua also includes a useful function, explained next:

local_sound(id, sound) = chan_handle

Plays a sound that appears to originate from the location of a given instance.

dsb_music_to_background(?) = ?

Allows multiple music streams.

dsb_stopsound(chan_handle)

Stops the sound playing on a channel handle previously returned by a call to a sound playing function.

dsb_get_soundvol(chan_handle)

Obtains the current volume of the sound, ranging from 0 to 100.

dsb_set_soundvol(chan_handle, volume)

Adjusts the volume of the sound, with the volume range from 0 to 100.

Levels and Wallsets

dsb_level_getinfo(level) = x_size, y_size, light, xp_multiplier, wallset_name

Returns the basic info about a level.

dsb_level_tint(level, RGB, ~[level])

Tells DSB to tint the dynamically scaled and shaded objects in a level a certain way. By default, this is {0, 0, 0}, causing the dungeon to fade to black, just like DM, but if the ambient light color is different, or you are outdoors and fade to a misty grey instead of black, you will probably want to change this. The third parameter is to control the level of tint applied. The default is 64 but a value of over 200 or so will make everything so dark you can't see anything.

dsb_make_wallset(floor, roof, pers0, pers0alt, pers1, pers1alt, pers2, pers2alt, pers3, persl3alt, farwall3, farwall3alt, front1, front2, front3, patch1, patch2, patch3, patchside, window) = wallset

Creates a wallset from the specified bitmaps. Wallsets in DM 2.x ([CSBwin]) are easiest to use with this command, as they have a single very long wall, as opposed to assembling the front view out of "left" and "front" bitmaps. (see the next command)

dsb_make_wallset_ext(floor, roof, pers0, pers0alt, pers1, pers1alt, pers2, pers2alt, pers3, persl3alt, farwall3, farwall3alt, front1, front2, front3, left1, left1alt, left2, left2alt, left3, left3alt, patch1, patch2, patch3, patchside, window) = wallset

Creates a wallset from the specified bitmaps. This command takes 6 more arguments: 6 "left side" bitmaps. If you're using a converted DM2, DSB for RTC users, or WHACK wallset, you'll find this command useful.

dsb_level_wallset(level, wallset)

dsb_use_wallset(level, wallset) (Deprecated)

Tells DSB to use the specified wallset on the specified level.

Note: this function was formerly known as "dsb_use_wallset," and that is still a synonym for it, for now. In new dungeons, please use the new name.

dsb_alt_wallset(wallset, level, x, y, dir)

Tells DSB to use the specified wallset only on the given direction of the given tile. If CENTER is specified, it will use that wallset on all directions of the given tile.

dsb_wallset_flip_floor(wallset, flip)

Pass true to flip to automatically flip the floor every other step, like standard floors, or pass a bitmap to have a different bitmap show up when the floor is "flipped."

dsb_wallset_flip_roof(wallset, flip)

Pass true to flip to automatically flip the roof every other step, like standard floors, or pass a bitmap to have a different bitmap show up when the roof is "flipped."

dsb_override_floor(bitmap_name, flip)

Overrides the floor with the bitmap in the gfx table with the given name, regardless of what wallset is in use. Pass true to flip to automatically flip the floor every other step, like standard floors, or pass a second bitmap name to have a different bitmap show up when the floor is "flipped."

dsb_override_roof(bitmap_name, flip)

Overrides the roof with the bitmap in the gfx table with the given name, regardless of what wallset is in use. Pass true to flip to automatically flip the roof every other step, like standard roofs, or pass a second bitmap name to have a different bitmap show up when the roof is "flipped."

dsb_text2map(level, x_size, y_size, light, xp_multiplier, maptable)

Converts a table with a text-based map into a level. Each row of the table should represent a row of the dungeon, and contain a string with 0's or 1's representing walls and floors in that row. In this way, it is very similar to how dungeons are declared in an DSB for RTC users text file.

dsb_image2map(level, filename, light, xp_multiplier) (Deprecated)

Converts a bitmap image into a level. One pixel = one square. It must be a 256 color image, where color 0 represents walls, color 1 represents open space, and further colors can be used to represent various objects in the dungeon by means of a conversion table. This function is now mostly deprecated because everyone is using ESB anyway.

dsb_get_cell(level, x, y) = boolean

Returns a boolean specifying whether or not the given cell in the dungeon is a wall. Use dsb_fetch to find out anything else about what's there.

dsb_set_cell(level, x, y, value)

Sets whether the given cell in the dungeon is a wall or open space. A value of nil, false, or 0 represents open space. A value of true or any other integer represents a wall.

dsb_visited(level, x, y) = boolean

Returns whether the party has visited the given dungeon cell. A wall will never be visited, unless it wasn't a wall at some point in the past.

dsb_get_xp_multiplier(level) = integer

dsb_set_xp_multiplier(level, integer)

Gets or sets the XP multiplier for a given level of the dungeon.

Characters

dsb_add_champion(portrait_gfxname, first_name, last_name, health, stamina, mana, strength, dexterity, wisdom, vitality, anti-magic, anti-fire, luck, fighter_level, ninja_level, priest_level, wizard_level) = char_id

Adds a character to the roster and returns his/her id number, which can then be used for adjusting various stats or putting items in his/her pack. Note that the internal representations of the three bars and the 7 statistics are 10 times what is actually displayed. (That is, 100 health in-game is represented by 1000)

dsb_offer_champion(char_id, mode, take_function)

Offers the given char_id, with the options specified by "mode" available.

~[1 = resurrect, 2 = reincarnate, 3 = both]. The take_function is a Lua function that is executed if the offered character is resurrected or reincarnated. It is typically used to clear out the champion's mirror, or do something else to denote that the character is no longer available.

dsb_champion_toparty(ppos, char)

Adds the specified character at the specified party position. (Unlike dsb_offer_champion the player is given no choice, the character is just added) It will fail silently if that position is already occupied.

dsb_champion_fromparty(ppos)

Removes anyone at the specified party position. It will fail silently if no one is there. If the party is reduced to nothing, the game will revert to "ghost mode."

dsb_get_charname(char) = string

Returns the character's name.

dsb_get_bar(char, bar) = integer

dsb_set_bar(char, bar, integer)

Gets or sets the value of one of the character's three bars. (HEALTH, STAMINA or MANA)

dsb_get_stat(char, stat) = integer

dsb_set_stat(char, stat, integer)

Gets or sets the value of one of the character's stats. (STAT_STR, STAT_DEX, STAT_WIS, STAT_VIT, STAT_AMA, STAT_AFI, STAT_LUC)

dsb_get_maxbar(char, bar) = integer

dsb_set_maxbar(char, bar, integer) dsb_get_maxstat(char, stat) = integer dsb_set_maxstat(char, stat, integer)

As above, only pertaining to maximum values.

do_damage(ppos, char, type, amount)

This function will damage the given character at the given ppos the given amount of the given type (HEALTH, STAMINA, or MANA). The units specified here are as the player perceives them (that is, divided by ten from internal representations and the same scale used by monsters)

Defined in base/damage.lua.

dsb_get_load(char) = integer

dsb_get_maxload(char) = integer

Returns the load or max load of a given character.

dsb_get_food(char) = integer

dsb_set_food(char, integer) dsb_get_water(char) = integer dsb_set_water(char, integer)

Get or set the character's food and water values.

dsb_get_injury(char, location) = integer

dsb_set_injury(char, location, integer)

Gets or sets the amount of injury a given location on the given character has sustained. This number is 0 if the location is uninjured and can go up to 100, but anything nonzero will highlight it in red and use the "bandaged" bitmap.

dsb_replace_portrait(char, portrait_name)

Replaces the portrait of a character with the given image. This can happen on-the-fly at any time. Note that the portrait must be specified as a string, not an entry in the gfx table. That is, pass "portrait", not gfx.portrait.

dsb_get_portraitname(char) = portrait_name

Retrieves the name of a character's portrait.

dsb_set_portraitname(char, portrait_name)

An alias for dsb_replace_portrait (for symmetry).

dsb_replace_topimages(char, hands_image_name, portrait_background_image_name, death_image_name)

Replaces the top "hands", "portrait background" and "death" images. Pass the image names nil to leave the image alone, or 0 to go back to the default. Remember that we pass the image parameters as strings, and not a direct reference to the gfx table. Example: dsb_replace_topimages(char, nil, nil, "frozen_face_halk")

dsb_replace_charhand(char, hand_name)

Replaces the "hand" of a character with the given image. This can happen on-the-fly at any time. Note that the image must be specified as a string, not an entry in the gfx table. That is, pass "hand_image", not gfx.hand_image.

dsb_replace_inventory(char, inventory_image_name)

Replaces the inventory background of a character with the given image. This can happen on-the-fly at any time. Note that the background image must be specified as a string, not an entry in the gfx table. That is, pass "inventory", not gfx.inventory.

dsb_replace_methods(char, methods_table_name)

Replaces the default attack methods of a character with the given table of methods, or function returning a table. This can happen on-the-fly at any time. Note that the method table or function must be specified by name as a string, not as an actual table. It must a single global variable (not be contained in any other table).

dsb_xp_level(char, skill, subskill) = integer

dsb_xp_level_nobonus(char, skill, subskill) = integer

These functions return the character's level of mastery at a certain skill (a class such as 'ninja') and subskill (or 0 for no subskill). The "nobonus" form does not take temporary XP or level-boosting items into account. All references to the dsb_xp_level call are wrapped by function determine_xp_level(char, class, subskill) so that it can be overridden.

dsb_give_xp(char, skill, subskill, xp)

Gives the specified amount of XP in the specified skill and subskill (or 0 for no subskill).

Important: This function gives XP only. It doesn't deal with XP multipliers, leveling up, bonuses, or anything else.

More useful to most designers will be the helper function xp_up.

xp_up(char, skill, subskill, xp)

This function takes XP multipliers, leveling up, etc. into account.

Defined in base/xp.lua.

dsb_get_xp(char, skill, subskill) = xp

dsb_set_xp(char, skill, subskill, xp)

Gets or sets the character's amount of experience directly. Setting XP directly doesn't do anything with stats, leveling up or down, or anything of that sort, so it is of limited use unless you really know what you're doing.

dsb_get_temp_xp(char, skill, subskill) = xp

dsb_set_temp_xp(char, skill, subskill, xp)

Gets or sets a temporary XP bonus. This, too, is handled by xp_up automatically.

dsb_get_bonus(char, skill, subskill) = integer

dsb_set_bonus(char, skill, subskill, integer)

Gets or sets a level bonus associated with a given skill or subskill (or 0 for no subskill), such as what may be given by a magic item held in hand or worn around the neck.

The Party

Many of these commands include optional support for Multiple Parties. In a standard DM dungeon, you can ignore all of that.

dsb_party_coords(~[party]) = level, x, y, facing

Returns the ~[specified] party's location.

dsb_party_at(level, x, y) = party

Returns which party is at a specified location, or nil if no party is there.

dsb_party_place(level, x, y, facing, ~[party])

Places the ~[specified] party at a specific location.

dsb_get_pfacing(ppos) = direction

dsb_set_pfacing(ppos, direction)

Get or set the direction a given party position is facing relative to the rest of the party. (This changes when the members are attacked from monsters to the sides or behind)

dsb_get_idle(ppos) = integer

dsb_set_idle(ppos, integer)

Gets or sets the amount of time the given party position must be idle (that is, the attack method icons are ghosted). Note that these take party positions, not character numbers.

dsb_get_leader() = ppos

Returns the party position of the party's leader.

dsb_ppos_char(ppos, ~[party]) = char

Returns the character at the given party position, or nil if there isn't one.

If a party is specified, that party will be searched. If there is no party specified, only the current party will be searched. To search all parties, specify VARIABLE as the party.

dsb_char_ppos(char) = ppos

Returns the party position a given character occupies, or nil if he/she isn't in the party.

dsb_ppos_tile(ppos, ~[party]) = tile_dir

Returns the tile location that the given party position occupies.

A specific party can be optionally specified.

dsb_tile_ppos(tile_dir, ~[party]) = ppos

Returns the party position occupied by the given tile location, or nil if nobody is there.

A specific party can be optionally specified.

dsb_get_sleepstate() = boolean

Returns whether or not the party is asleep.

dsb_wakeup()

Wakes up the party if they are asleep.

dsb_current_inventory>() = ppos

If someone's inventory is being looked at, this returns the party position of the character that is being looked at. Otherwise, it returns nil.

dsb_lastmethod(ppos) = method, location, inst

Returns the last attack method invoked by the given ppos.

dsb_party_scanfor(arch) = id

Scans the entire party's inventory for a given arch. Returns the id for the first instance of that arch if it is found, or nil if nothing is found.

Multiple Parties

dsb_get_mpartyflag(flag) = value

dsb_set_mpartyflag(flag) dsb_clear_mpartyflag(flag) dsb_toggle_mpartyflag(flag)

Gets, sets, clears, or toggles the value of a Multiple Parties flag.

dsb_set_exviewinst(char, monster_id)

This will associate a given monster inst with a character. The monster must be in LIMBO. From then on, whenever that character is seen from a 3rd person perspective, that monster will be drawn to represent that character. Don't kill this monster or bad things will happen.

dsb_party_apush(party)

dsb_party_apop(party)

The game uses a "party stack" to keep track of which sub-party the various party-related commands affect. The currently viewed party is always at the bottom. When a party steps on a trigger, it is pushed onto the stack before the trigger is processed. This means things like dsb_party_coords will generally affect the "right" party. You can directly manipulate the stack with these commands, but be careful. If you're not sure what to do with these commands, you probably don't need them.

Interacting with Insts

dsb_spawn(object_arch, level, x, y, tile_location) = id

Spawns a new instance at the specified coordinates and returns its id.

Note that if "level" is negative, various Special Values can be used.

dsb_move(id, level, x, y, tile_location)

Moves an instance to the specified location. The Special Values can also be used.

dsb_reposition(id, tile_location)

Moves an instance to a new tile location on the same tile. Useful for rearranging monsters.

Note: dsb_spawn etc. will not always immediately put the spawned/moved object into position. During the processing of a triggering event (wallitem or flooritem), all spawns and moves will be queued until the end of the processing in order to avoid changing the dungeon state while the triggering objects are still being iterated over. In most cases, the change will not be noticable, but you should be wary of this fact, especially if you are expecting to be able to manipulate the just-moved object in the same function.

dsb_move_moncol(???) = ???

Allow moving a monster and automatically handle flyer collisions.

dsb_get_coords(id) = level, x, y, tile_location

Returns the coordinates of an instance. This is either the location in the dungeon, or, using special coordinates, its location in a character or monster's inventory, in limbo, etc.

dsb_fetch(level, x, y, tile_location) = id (or table of ids), ~[number]

Checks a specified location and returns what's there. If this is a special coordinate, it is either nil or just an id number. If this is a dungeon location (that is, a level >= 0) or if the special specifier TABLE is used for tile_location, it will return a table of ids. -1 can also be used for the y coordinate when using a special coordinate to return a table of all matching ids, for example, IN_OBJ will give everything inside that object. In these cases, a number is also returned matching the number of instances fetched (but can be ignored if you choose)

dsb_find_arch(id) = arch

Determines the arch of the given instance id. This is often needed in order to access information about the object's general type.

dsb_swap(id, new_arch)

Totally destroys the targeted instance and creates a new one at its location with its id number and the new archetype. Things like exvars are not preserved.

dsb_qswap(id, new_arch)

Quick-swaps an instance to a new archetype. That is, it changes only the arch, but no internal variables or exvars. This means that if the new arch is a radically different type, strange things will probably happen and the game might crash. It's quite handy for making push-buttons that change appearance and such, though.

dsb_delete(id)

Completely destroys an instance from the dungeon.

In most cases, it is better to send the instance an M_DESTROY message instead.

dsb_get_facedir(id) = direction

dsb_set_facedir(id, direction)

Gets or sets the direction a monster is facing or a flying instance is currently travelling.

dsb_shoot(id, level, x, y, direction, tile_pos, power, damage, delta, ~[damage_delta])

Sends the specified instance flying through the air. It originates at the given level, x, y, and tile_pos, flying in the given direction. Power and damage are variables used by the game to control how far the object flies and how hard it hits. Delta represents how much is subtracted from power each subtile of flight. Delta is also subtracted from damage, unless an optional damage delta is specified instead. When the instance runs out of power, it falls to the ground (or vanishes if flying_only is set on its archetype)

dsb_get_flystate(id) = power, direction, damage

Returns the information on a flying instance.

dsb_set_openshot(id)

This is a minor hack used to specify that the instance has been shot in open space (by a champion or monster, instead of by a wall shooter, for example) and thus should not have collision detection immediately. If this is not set, the instance will instantly run into the character or monster that was supposed to have "launched" it.

dsb_collide(id, lev, x, y, tile, direction) = { {id, tile}, ~[...] }

Performs collision detection on a flying object for the specified location. This is useful when directly moving monsters around (e.g., via dsb_move) so that they will not apparently move "through" flying missiles.

dsb_set_flyreps(???, ???, ...) = ???

Allows you to set the number of update repetitions that a flying object performs per tick. For example, a value of 8 will cause the object to move 8 sub-tiles per tick, or 4 full tiles.

dsb_get_gfxflag(id, flag) = value

dsb_set_gfxflag(id, flag) dsb_clear_gfxflag(id, flag) dsb_toggle_gfxflag(id, flag)

Gets, sets, clears, or toggles the value of a Graphics Flag for a given instance.

dsb_get_charge(id) = integer

dsb_set_charge(id, integer)

Gets or sets the charge of a given instance. This is normally used by limited-use items but it can have other applications. It is used to set the size of clouds and spells, too. It must be a number from 0 to 63.

dsb_get_crop(id) = integer

dsb_set_crop(id, integer)

Gets or sets how much a door is cropped in its display. This is used when they open and close.

dsb_spawnburst_begin()

dsb_spawnburst_end()

Begins or ends a Spawnburst.

dsb_push_mouse(id)

A shortcut command to push the specified instance into the mouse hand.

dsb_pop_mouse() = id

A shortcut command to pop anything in the mouse hand out, returning its id at the same time.

dsb_valid_inst(id) = ternary value

Returns true if the instance exists, false if it doesn't but the id is valid, and nil if it is not a valid instance id.

clone_arch(object_arch) = new arch

Creates a new arch type. See a simple example.

Monsters

Monsters are insts as well, and (almost?) all commands that affect insts will work just the same on monsters, but monsters have their own specialized functionality as well.

dsb_get_hp(id) = integer

dsb_set_hp(id, integer)

Gets or sets a monster's HP. Please note that this function has nothing to do with how to get or set a character's HP. In addition, the scale used by monster HP is not scaled up by a factor of 10.

dsb_get_maxhp(id) = integer

dsb_set_maxhp(id, integer)

Gets or sets a monster's max HP.

dsb_set_tint(id, RGB, ~[intensity])

Sets the 'tint' of a monster, to give it a glowing effect. Monsters flash when they are hit by various spells. There is finally an optional intensity level parameter, set at 127 by default with a range of 0 to 255. 0 Being completely black.

dsb_ai(id, message, data) ~[= result]

Sends an Monster AI message to the given monster.

If data is QUERY then the function will return information on the given value, rather than setting it. For example, dsb_ai(id, AI_FEAR, QUERY) will return the monster's current level of fear. Monster AI documentation.

dsb_ai_boss(id) = boss_id

Returns the given monster id's boss. The "boss" is the monster in each tile who controls when the entire group moves and attacks. This allows DSB monsters to all be distinct entities, but move in DM-style groups.

dsb_ai_promote(id)

Promotes the given monster id to be the boss of its tile.

dsb_ai_subordinates(boss_id) = { {id, tile}, [...] }

Returns all monsters who are subordinate to the given boss.

Messaging

dsb_msg(delay, id, message, data, ~[sender])

Sends the specified Messages to the specified instance after the specified delay. Messages are simply integers. The object responds to the message as specified by its msg_handler, defined in its archetype. See base/msg_handlers.lua for many examples of what can be done with message handlers. Normally it doesn't matter where a message comes from. However, it is possible to assert the sender of the message, in the rare cases where it is needed. (See DSB/Messages for more information on how to use messages)

dsb_msg_chain(id, target_id)

This causes the first instance to relay any messages it receives to the second instance. This is useful for making ceiling pits close at the same time floor pits do, and other situations where an instance should pass messages along.

dsb_delay_msgs_to(id, delay)

Delays all messages bound for a given instance by the specified delay.

dsb_enable(id)

Enables an instance. This will clear its INACTIVE flag as well as make sure any events, triggerings, etc. that should happen do happen. This function is easier and safer to use than setting the flag directly.

dsb_disable(id)

Disables an instance. This will set its INACTIVE flag and make sure that any objects on it stop triggering it.

dsb_toggle(id)

See the previous two.

Light

dsb_get_light(handle) = lightlevel

dsb_set_light(handle, lightlevel)

Gets or sets the light level on the given light handle, which is an integer from 0 to 9. The light level displayed is the sum of the dungeon level's base light level plus the 10 light handles. Currently, light handle 0 is used for light spells, handle 1 is used for torches, and 2 is used by illumulets.

Conditions

dsb_add_condition(type, inventory_gfx, portrait_gfx, update_freq, function, ~[flags]) = condition_id

Adds a condition (status variable) to the list of those available. The type is either PARTY (affects the whole party) or INDIVIDUAL (affects one person). For individual conditions, two graphics can be specified, one that affects the inventory screen, the other that affects the portrait area. If type is PARTY the third parameter portrait_gfx is now considered as overlay_gfx and will be seen in the dungeon view port. We can apply an underwater effect for example, as the overlay includes support for alpha channels if you want transparent parts.

If update_freq is > 0, the specified function will be called at the specified number of ticks. The function takes the following form:

  function update_func(char, condition_strength)
    return new_condition_strength
  end

Flags can be specified to control other aspects of the condition's appearance on the inventory screen. These flags are COND_MOUTH_RED, COND_MOUTH_GREEN, COND_EYE_RED, and COND_EYE_GREEN. These flags only affect INDIVIDUAL conditions. There was formerly a condition type called BAD_INDIVIDUAL that was an INDIVIDUAL condition with COND_MOUTH_RED. It is now deprecated. Please don't use it in new code.

dsb_replace_condition(condition_id, type, inventory_gfx, portrait_gfx, update_freq, function)

Replaces the information for the condition with the given id with the new condition. Good for changing conditions on the fly, but keep in mind that the fact that you've changed the condition won't be saved.

dsb_get_condition(char, condition) = strength

Returns the strength of the specified condition for the specified character (or, in the case of conditions for the whole party, pass PARTY as the character)

dsb_set_condition(char, condition, strength)

Sets the strength of the condition. See previous function.

Popups and Readouts

dsb_damage_popup(ppos, damage_type, integer)

Shows the amount of damage taken by a character in a little popup over the character's name or portrait. The type is either HEALTH, STAMINA, or MANA, and a different background icon is displayed for each. The amount of damage shown should be in units as the player perceives them, not internal (so, divided by ten from internal representations)-- the default functions in base/damage.lua take care of this for you.

dsb_attack_damage(integer)

This causes a number in a little explosion to appear in the area occupied by the attack icons. This is used for showing the amount of damage inflicted upon a monster by a melee attack.

dsb_attack_text(string)

This causes text to momentarily appear in the area occupied by the attack icons. This is used for things like "CAN'T REACH" or "NEED AMMO."

Fullscreen

dsb_fullscreen(bitmap_or_func, click_func, update_func, mouse, fade)

This engages the full-screen renderer, and is used for cut scenes or other interludes. If the first parameter passed is a bitmap, that bitmap will be displayed. If the first parameter is instead a function, that function will be executed every frame. The draw function will be passed the bitmap to draw to, the mouse's x location, and the mouse's y location, in the form: draw_function(bitmap, mouse_x, mouse_y)

The click_func, if provided, will be executed every time the mouse is clicked. It is of the form: click_func(mouse_x, mouse_y, mouse_buttons)

Update_func, if provided, will be executed every game tick. It takes no parameters.

If mouse is nil or false, no mouse pointer will be drawn. If it is true, the standard "yellow arrow" mouse pointer will be drawn. If it is a bitmap, that bitmap will be drawn as the mouse pointer.

There is an optional 5th parameter that allows a fade in/fade out.

The full-screen renderer will run until any of its associated functions returns something other than false or nil, and the game logic does not advance while in dsb_fullscreen.

Subrenderers and System Renderers

dsb_subrenderer_target() = bitmap

Returns a bitmap to be drawn upon. Use only in a Subrenderer.

dsb_objzone(bitmap, id, number, x, y)

Creates an object zone associated with the given id at the given x and y coordinates on the given subrenderer or system bitmap. This object zone can be used to access instances that are stored inside of the given instance. See the implementation of chests in base/objects.lua for more information and examples.

dsb_msgzone(bitmap, id, number, x, y, width, height, msg, ~[data1, data2])

Creates an object zone associated with the given id at the given x and y coordinates on the given subrenderer or system bitmap, with the given width and height. When it is clicked, the specified message will be sent to the instance. This can allow fairly complicated user interfaces in subrenderers.

The third parameter, number, allows you to override/replace zones by specifying an existing handle. It also allows msgzones to have more information about where you clicked, because the zone number you clicked is passed as the msg's data parameter. If you don't care about any of this, just keep incrementing the number for every new zone. (See DSB/Messages for more information on how to use messages)

Global Data, Utility Functions, and Misc.

dsb_get_gameflag(flag) = value

dsb_set_gameflag(flag) dsb_clear_gameflag(flag) dsb_toggle_gameflag(flag)

Gets, sets, clears, or toggles the value of a Global Flag.

dsb_hide_mouse()

dsb_show_mouse()

Functions to make the mouse pointer appear or disappear.

dsb_lock_game(~[flag])

dsb_unlock_game(~[flag])

Functions to lock or unlock the game. Complete locking prevents most timers from running (though animations and delayed functions still will), processing any player input, or triggering anything. If you lock the game and forget to unlock it, it will be left in an unplayable state, so be very careful how you use this! Note that this takes effect immediately (that is, even before any queued moves), which may not always be what you want. You can also lock only certain parts of the game, using the locking flags.

dsb_rand(min, max) = integer

Generates a random integer between min and max, inclusive.

You should always use this function for random number generation, not anything built into Lua.

dsb_linesplit(string, split) = lines, number_of_lines

A utility function that splits up a string into individual lines (placing the number of lines returned in number_of_lines) demarcated by the split character. "/" (slash) is a common choice for a a split character. See the implementation of scrolls in base/objects.lua for an example.

dsb_forward(direction) = x, y

A utility function that, given a direction, returns the x and y offsets of which way is "forward." One will always be 1 or -1, the other will always be 0.

dsb_tileshift(location, direction) = location

A utility function that shifts the specified location in the specified direction. If you don't know what this is for, you probably don't need it.

dsb_lookup_global(string) = variable

Returns the variable named by the specified string. If you don't know what this is for, you probably don't need it.

dsb_delay_func(delay, function)

Executes the given function after the given delay in ticks. References to Lua functions cannot be saved, so queued functions will not be saved. This should be something nonvital if the game is not locked, and should happen quickly. In most cases, using a message on a delay, which is saved, would work better.

dsb_update_inventory_info()

If the inventory_info has been changed, this lets the engine know. Note that this state is not saved.

dsb_update_system()

If the system strings or player colors have been changed, this lets the engine know. This may or may not be useful. With the moving of most inventory rendering into Lua-controlled subrenderers, this function has limited use.

dsb_export(string)

Normally, Lua global variables aren't saved in savegames, however, a few usually need to be. If you need to store a global variable, add it to the export list with this function. Note that dsb_export requires a string giving the name of the variable. Don't pass the variable itself! You should also note that if you have a very long export list, you're probably doing something that could be done more easily with specialized code or more careful use of instances with exvars. If you don't know what this is for, you probably don't need it.

dsb_viewport(x, y)

Sets the viewport. Odds are you should leave this one alone.

dsb_rune_enable(rune) (Deprecated)

dsb_rune_disable(rune) (Deprecated)

Enables or disables the specified magical rune for use in spells. All runes are enabled by default, just like in original DM. The rune is specified as an integer, where 1 = LO, 2 = UM, 7 = YA, and so on.

These functions are now deprecated. You should manipulate the g_disabled_runes table directly. For example, disabling the VI rune (rune 8) is as simple as g_disabled_runes~[8] = false.

dsb_game_end(~[bool])

Shows a game ending screen. Normally it's a bit more fun than the screen you get when the party dies, but if you pass it a boolean 'true', it will just show the standard blue "The End" screen.

clone_arch(object_arch) = new arch

This function creates a new arch type, from the original passed in as a parameter. See a simple example.

Pending Documentation

dsb_override_floor(???) = ???

dsb_override_roof(???) = ???

dsb_add_msgtype(???) = ???

dsb_include_file(???) = ???

dsb_music(???) = ???

dsb_screen_bitmap(???) = ???

dsb_cache_invalidate(???) = ???

dsb_tileptr_exch(???) = ???

dsb_party_contains(???) = ???

dsb_party_viewing(???) = ???

dsb_party_affecting(???) = ???

dsb_checksound(???) = ???

dsb_get_gamelocks(???) = ???

dsb_get_light_total(???) = ???

dsb_set_light_totalmax(???) = ???

dsb_get_exviewinst(???) = ???

dsb_wallset_flip_floor(???) = ???

dsb_wallset_flip_roof(???) = ???

dsb_import_arch(???) = ???

dsb_get_pendingspell(???) = ???

dsb_set_pendingspell(???) = ???