DmWiki - User contributions [en]

DSB/Subrenderers

2024-01-06T18:37:06Z

Sophia:

A subrenderer is a special Lua function that renders the large area in the lower-right corner of the inventory screen. In the default code provided in base/, subrenderers are used to create the chest and scroll, and concievably about anything else could be built.

See the stats and inventory screen renderers in base/render.lua for more information on subrenderers. (Another place to look is the implementation of chests and scrolls in base/objects.lua)

A subrenderer is called any time it is clicked or interacted with; it is also updated several times per second, but the actual rate can vary.

Any efforts to reconstruct the Amiga CSB magic map are quite welcome.

==Callbacks==

Some callback hooks that may be useful while working with subrenderers:

;inst_outgoing: something gets removed from a container

;inst_incoming: something gets added to a container

;on_unlook: called after an item is removed from the hover-on-eyeball examination

;after_from_r_hand: called after an item is removed from the active hand, which will close those subrenderers

[[Category:DSB|Subrenderers]]

DSB/Exposed functions

2018-12-20T19:41:46Z

Sophia: Conditions

==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 [[DSB/Base Code|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:

<code>
for i in dsb_insts()
</code>

;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)
;dsb_bitmap_blit(src_bmp, dest_bmp, x_src, y_src, x_dest, y_dest, src_width, src_height, final_width, final_height)
:Blits one bitmap onto another.
:This function takes either 8 or 10 parameters. In the 10 parameter version, the last two parameters define the size of the final bitmap to be rendered. This allows you to scale bitmaps dynamically. There's no anti-aliasing, so this works best with simple pixel images.

;dsb_bitmap_draw(src_bmp, dest_bmp, x, y, flip)
;dsb_bitmap_draw(src_bmp, dest_bmp, x, y, src_width, src_height, final_width, final_height, flip)
:Draws the entire source bitmap on to the destination, taking any animation or offsets into account. Pass true to the last parameter to horizontally flip the bitmap. Pass only 5 parameters to draw a simple bitmap at x,y, or pass 9 parameters to scale the bitmap dynamically.

;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) = {R,G,B},[alpha]
;dsb_set_pixel(bmp, x, y, {R,G,B}, [alpha])
:These are used for per-pixel bitmap manipulation.
:If the pixel queried with '''dsb_get_pixel()''' has an alpha channel, then the function returns two values: the {R,G,B} table, and an extra parameter containing the alpha. If there is no alpha, this second one will be '''nil'''.
:Alpha values for both '''dsb_get_pixel()''' and '''dsb_set_pixel()''' are in the range 0-255, where 0 is fully transparent and 255 is fully opaque.
:Here is a short example of how you might use these function to tint a bitmap:
:http://dungeon-master.com/forum/viewtopic.php?f=53&t=28859&p=135634#p135634

;dsb_rgb_to_hsv({R,G,B}) = {H,S,V}
;dsb_hsv_to_rgb({H,S,V}) = {R,G,B}
:Converts color model.

;dsb_screen_bitmap() = bitmap
:Takes a screenshot of the entire Windows screen and assigns it to a bitmap you can use later. If you're running the game in fullscreen mode, this will allow you to screenshot the entire game window. If you're running in Windowed mode, this will screenshot your visible Windows screen from the top/left 0,0 coordinate (probably not very useful in your dungeon!)

==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:
:<code>gfx["GAUDYMEDIEVALFONT"] = dsb_get_font("GAUDYMEDIEVAL", "fonts/gaudymedieval.pcx")</code>

;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 })

dsb_text_size(font, string) = width, height [DSB 0.54+]
: Returns the width and height in pixels of the supplied string for the specified font.

==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. As of DSB 0.70, passing a channel handle of -1 will stop all currently playing sounds (and release their handles).

;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/DSB for RTC users|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/DSB for RTC users|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_chartitle(char) = string
:Returns the character's lastname or title.

;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 [http://www.dungeon-master.com/forum/viewtopic.php?f=53&t=28487&p=106622#p106622 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 [[DSB/Multiple Parties|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.

;dsb_get_caster() = ppos
:Returns the current spell caster.

==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 [[DSB/Multiple Parties|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.

;dsb_party_contains(ppos) = party_id
:Returns the party containing a given character ppos

==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 [[DSB/Special Values|Special Values]] can be used.

;dsb_move(id, level, x, y, tile_location)
:Moves an instance to the specified location. The [[DSB/Special Values|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_get_coords_prev(id) = level, x, y, tile_location
:Returns the object's coordinates before its most recent movement.

;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(id, repetitions)
:Allows you to set the number of update repetitions (default value is 1) that a flying object performs per tick. For example, a value of 8 will cause the id flying 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 [[DSB/Graphics Flag|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 [[DSB/Spawnburst|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 [http://www.dungeon-master.com/forum/viewtopic.php?f=53&t=28613&p=111165#p111165 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 [[DSB/Monster AI|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. [[DSB/Monster AI|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 [[DSB/Messages|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.

;dsb_add_msgtype(code_name,int_value) = none?
:Adds a new message type to the system. Values above 100000 are reserved for the base code.
:Custom msg types will presumably still be handled the same way the built in ones are, so may be useful for triggering events on custom archs.
:Hmm. This could get messy if you combine msgtypes with importable archs...

==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==
:Conditions (i.e., status variables) are added to the game by modifying the conditions table, which is defined in base/conditions.lua. See that file for examples.
:The scope of the condition is either PARTY (affects the whole party) or INDIVIDUAL (affects one person). You can also specify images for the condition, like a subrenderer_image or a portrait_image. PARTY conditions can instead have an overlay_image that goes over the entire game's viewport.
:If update_rate is > 0, the specified update_func 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
:
;dsb_add_condition(type, inventory_gfx, portrait_gfx, update_freq, function, [flags]) = condition_id (Deprecated)
:Adds a condition (status variable) to the list of those available, but see above.

;dsb_replace_condition(condition_id, type, inventory_gfx, portrait_gfx, update_freq, function) (Deprecated)
:Replaces the information for the condition with the given id with the new condition.

;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 = true, game_draw = true })
: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: <code>draw_function(bitmap, mouse_x, mouse_y)</code>
:The click_func, if provided, will be executed every time the mouse is clicked. It is of the form: <code>click_func(mouse_x, mouse_y, mouse_buttons)</code>
: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 (a table of booleans) that allows a fade in/fade out. The game_draw allows you to have the game view drawn in the background. So, for example, for a fullscreen view that fades in and draws the game view.
: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 [[DSB/Subrenderers|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 [[DSB/Global Flags|Global Flag]].

;dsb_hide_mouse(~[bool])
;dsb_show_mouse()
:Functions to make the mouse pointer appear or disappear. dsb_hide_mouse Takes an optional parameter of true to allow the pointer to return after a successful melee attack, after moving the mouse.
;dsb_mouse_state() = x, y, button1, button2
:Gets the current state of the mouse: its current x,y position relative to the entire game screen, and '''true''' or '''false''' for button1 or button2 currently being pressed (left mouse button and right mouse button respectively).

;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 [[DSB/Locking Flags|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.
:While larger ranges will not cause errors per-se, the output of dsb_rand seems to be a 15 bit range (0-32767) modulused across the input range

;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 <code>g_disabled_runes[8] = false</code>.

;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 [http://www.dungeon-master.com/forum/viewtopic.php?f=53&t=28613&p=111165#p111165 example].

;dsb_import_arch(lua_filename,local_name) = none?
:Loads and runs a named lua file relative to the dungeon's directory. The file is loaded with the ROOT_NAME variable set to the given local name, so that the code being loaded can use that to avoid interfering with the parent codebase. Can only be used from the objects.lua file. Several examples are found in the test_dungeon. [http://dungeon-master.com/forum/viewtopic.php?f=53&t=27277&p=83877&hilit=dsb_import_arch#p83877 Some][http://dungeon-master.com/forum/viewtopic.php?f=53&t=29188&p=128330&hilit=dsb_import_arch#p128330 more][http://dungeon-master.com/forum/viewtopic.php?f=53&t=28859&sid=c8dec8095c76d7ce5937980e94499ceb&p=130029#p130029 info]

;dsb_include_file(shortname, filetype, filename)
:When compiling a DSB dungeon for distribution, most sounds and graphics are automatically compiled into a new '''graphics.dsb'''. Music however is normally left as a file to be streamed on-demand from the filesystem. This lowers the memory required by DSB and speeds up loading time. However, if you prefer, you can force music (and other files) to be included in the '''graphics.dsb''' by using this command. For example: '''dsb_include_file("MYMUSIC", "ogg", "mypath/mymusic.ogg")'''.

==Pending Documentation==
;dsb_override_floor(???) = ???
;dsb_override_roof(???) = ???
;dsb_cache_invalidate(???) = ???
;dsb_tileptr_exch(???) = ???
;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_get_pendingspell(???) = ???
;dsb_set_pendingspell(???) = ???

[[Category:DSB|Exposed functions]]

DSB/Exposed functions

2012-11-18T18:34:17Z

Sophia: /* Bitmaps and Drawing */

==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 [[DSB/Base Code|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:

<code>
for i in dsb_insts()
</code>

;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)
;dsb_set_pixel(bmp, x, y, {R,G,B}, [alpha])
:These are used for per-pixel bitmap manipulation.
:If the pixel queried with '''dsb_get_pixel()''' has an alpha channel, then the function returns two values: the {R,G,B} table, and an extra parameter containing the alpha. If there is no alpha, this second one will be '''nil'''.
:Alpha values for both '''dsb_get_pixel()''' and '''dsb_set_pixel()''' are in the range 0-255, where 0 is fully transparent and 255 is fully opaque.
:Here is a short example of how you might use these function to tint a bitmap:
:http://dungeon-master.com/forum/viewtopic.php?f=53&t=28859&p=135634#p135634

;dsb_rgb_to_hsv({R,G,B}) = {H,S,V}
;dsb_hsv_to_rgb({H,S,V}) = {R,G,B}
:Converts color model.

;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:
:<code>gfx["GAUDYMEDIEVALFONT"] = dsb_get_font("GAUDYMEDIEVAL", "fonts/gaudymedieval.pcx")</code>

;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/DSB for RTC users|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/DSB for RTC users|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 [http://www.dungeon-master.com/forum/viewtopic.php?f=53&t=28487&p=106622#p106622 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 [[DSB/Multiple Parties|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 [[DSB/Multiple Parties|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 [[DSB/Special Values|Special Values]] can be used.

;dsb_move(id, level, x, y, tile_location)
:Moves an instance to the specified location. The [[DSB/Special Values|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 [[DSB/Graphics Flag|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 [[DSB/Spawnburst|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 [http://www.dungeon-master.com/forum/viewtopic.php?f=53&t=28613&p=111165#p111165 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 [[DSB/Monster AI|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. [[DSB/Monster AI|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 [[DSB/Messages|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: <code>draw_function(bitmap, mouse_x, mouse_y)</code>
:The click_func, if provided, will be executed every time the mouse is clicked. It is of the form: <code>click_func(mouse_x, mouse_y, mouse_buttons)</code>
: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 [[DSB/Subrenderers|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 [[DSB/Global Flags|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 [[DSB/Locking Flags|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 <code>g_disabled_runes~[8] = false</code>.

;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 [http://www.dungeon-master.com/forum/viewtopic.php?f=53&t=28613&p=111165#p111165 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(???) = [http://dungeon-master.com/forum/viewtopic.php?f=53&t=27277&p=83877&hilit=dsb_import_arch#p83877 ?][http://dungeon-master.com/forum/viewtopic.php?f=53&t=29188&p=128330&hilit=dsb_import_arch#p128330 ?][http://dungeon-master.com/forum/viewtopic.php?f=53&t=28859&sid=c8dec8095c76d7ce5937980e94499ceb&p=130029#p130029 ?]
;dsb_get_pendingspell(???) = ???
;dsb_set_pendingspell(???) = ???

[[Category:DSB|Exposed functions]]

DSB/Exposed functions

2012-11-18T18:33:15Z

Sophia: /* Bitmaps and Drawing */

==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 [[DSB/Base Code|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:

<code>
for i in dsb_insts()
</code>

;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)
;dsb_set_pixel(bmp, x, y, {R,G,B}, [alpha])
:These are used for per-pixel bitmap manipulation.
:If the pixel queried with '''dsb_get_pixel()''' has an alpha channel, then the function returns two values: the {R,G,B} table, and an extra parameter containing the alpha. If there is no alpha, this second one will be '''nil'''.
:Alpha values for both '''dsb_get_pixel()''' and '''dsb_set_pixel()''' are in the range 0-255, where 0 is fully transparent and 255 is fully opaque.
:Here is a short example of how you might use these function to tint a bitmap:
:http://dungeon-master.com/forum/viewtopic.php?f=53&t=28859&p=135634#p135634

:dsb_rgb_to_hsv({R,G,B}) = {H,S,V}
:dsb_hsv_to_rgb({H,S,V}) = {R,G,B}
:Converts color model.

;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:
:<code>gfx["GAUDYMEDIEVALFONT"] = dsb_get_font("GAUDYMEDIEVAL", "fonts/gaudymedieval.pcx")</code>

;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/DSB for RTC users|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/DSB for RTC users|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 [http://www.dungeon-master.com/forum/viewtopic.php?f=53&t=28487&p=106622#p106622 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 [[DSB/Multiple Parties|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 [[DSB/Multiple Parties|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 [[DSB/Special Values|Special Values]] can be used.

;dsb_move(id, level, x, y, tile_location)
:Moves an instance to the specified location. The [[DSB/Special Values|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 [[DSB/Graphics Flag|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 [[DSB/Spawnburst|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 [http://www.dungeon-master.com/forum/viewtopic.php?f=53&t=28613&p=111165#p111165 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 [[DSB/Monster AI|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. [[DSB/Monster AI|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 [[DSB/Messages|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: <code>draw_function(bitmap, mouse_x, mouse_y)</code>
:The click_func, if provided, will be executed every time the mouse is clicked. It is of the form: <code>click_func(mouse_x, mouse_y, mouse_buttons)</code>
: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 [[DSB/Subrenderers|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 [[DSB/Global Flags|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 [[DSB/Locking Flags|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 <code>g_disabled_runes~[8] = false</code>.

;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 [http://www.dungeon-master.com/forum/viewtopic.php?f=53&t=28613&p=111165#p111165 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(???) = [http://dungeon-master.com/forum/viewtopic.php?f=53&t=27277&p=83877&hilit=dsb_import_arch#p83877 ?][http://dungeon-master.com/forum/viewtopic.php?f=53&t=29188&p=128330&hilit=dsb_import_arch#p128330 ?][http://dungeon-master.com/forum/viewtopic.php?f=53&t=28859&sid=c8dec8095c76d7ce5937980e94499ceb&p=130029#p130029 ?]
;dsb_get_pendingspell(???) = ???
;dsb_set_pendingspell(???) = ???

[[Category:DSB|Exposed functions]]

DSB/Exposed functions

2012-11-13T23:07:34Z

Sophia:

==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 [[DSB/Base Code|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:

<code>
for i in dsb_insts()
</code>

;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:
:<code>gfx["GAUDYMEDIEVALFONT"] = dsb_get_font("GAUDYMEDIEVAL", "fonts/gaudymedieval.pcx")</code>

;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/DSB for RTC users|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/DSB for RTC users|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 [http://www.dungeon-master.com/forum/viewtopic.php?f=53&t=28487&p=106622#p106622 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 [[DSB/Multiple Parties|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 [[DSB/Multiple Parties|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 [[DSB/Special Values|Special Values]] can be used.

;dsb_move(id, level, x, y, tile_location)
:Moves an instance to the specified location. The [[DSB/Special Values|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 [[DSB/Graphics Flag|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 [[DSB/Spawnburst|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 [http://www.dungeon-master.com/forum/viewtopic.php?f=53&t=28613&p=111165#p111165 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 [[DSB/Monster AI|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. [[DSB/Monster AI|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 [[DSB/Messages|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: <code>draw_function(bitmap, mouse_x, mouse_y)</code>
:The click_func, if provided, will be executed every time the mouse is clicked. It is of the form: <code>click_func(mouse_x, mouse_y, mouse_buttons)</code>
: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 [[DSB/Subrenderers|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 [[DSB/Global Flags|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 [[DSB/Locking Flags|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 <code>g_disabled_runes~[8] = false</code>.

;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 [http://www.dungeon-master.com/forum/viewtopic.php?f=53&t=28613&p=111165#p111165 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(???) = [http://dungeon-master.com/forum/viewtopic.php?f=53&t=27277&p=83877&hilit=dsb_import_arch#p83877 ?][http://dungeon-master.com/forum/viewtopic.php?f=53&t=29188&p=128330&hilit=dsb_import_arch#p128330 ?][http://dungeon-master.com/forum/viewtopic.php?f=53&t=28859&sid=c8dec8095c76d7ce5937980e94499ceb&p=130029#p130029 ?]
;dsb_get_pendingspell(???) = ???
;dsb_set_pendingspell(???) = ???

[[Category:DSB|Exposed functions]]

DSB/Exposed functions

2012-11-13T23:05:47Z

Sophia:

==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 [[DSB/Base Code|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:

<code>
for i in dsb_insts()
</code>

;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:
:<code>gfx["GAUDYMEDIEVALFONT"] = dsb_get_font("GAUDYMEDIEVAL", "fonts/gaudymedieval.pcx")</code>

;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/DSB for RTC users|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/DSB for RTC users|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 [http://www.dungeon-master.com/forum/viewtopic.php?f=53&t=28487&p=106622#p106622 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 [[DSB/Multiple Parties|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 [[DSB/Multiple Parties|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 [[DSB/Special Values|Special Values]] can be used.

;dsb_move(id, level, x, y, tile_location)
:Moves an instance to the specified location. The [[DSB/Special Values|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 [[DSB/Graphics Flag|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 [[DSB/Spawnburst|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 [http://www.dungeon-master.com/forum/viewtopic.php?f=53&t=28613&p=111165#p111165 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 [[DSB/Monster AI|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. [[DSB/Monster AI|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 [[DSB/Messages|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: <code>draw_function(bitmap, mouse_x, mouse_y)</code>
:The click_func, if provided, will be executed every time the mouse is clicked. It is of the form: <code>click_func(mouse_x, mouse_y, mouse_buttons)</code>
: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==
;dsb_subrenderer_target() = bitmap
:Returns a bitmap to be drawn upon. Use only in a [[DSB/Subrenderers|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 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 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 [[DSB/Global Flags|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 [[DSB/Locking Flags|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 <code>g_disabled_runes~[8] = false</code>.

;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 [http://www.dungeon-master.com/forum/viewtopic.php?f=53&t=28613&p=111165#p111165 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(???) = [http://dungeon-master.com/forum/viewtopic.php?f=53&t=27277&p=83877&hilit=dsb_import_arch#p83877 ?][http://dungeon-master.com/forum/viewtopic.php?f=53&t=29188&p=128330&hilit=dsb_import_arch#p128330 ?][http://dungeon-master.com/forum/viewtopic.php?f=53&t=28859&sid=c8dec8095c76d7ce5937980e94499ceb&p=130029#p130029 ?]
;dsb_get_pendingspell(???) = ???
;dsb_set_pendingspell(???) = ???

[[Category:DSB|Exposed functions]]

DSB/Messages

2012-11-13T23:05:25Z

Sophia:

Base messages as defined by DSB and used in ESB are the following:
* Activate (M_ACTIVATE) - Enables instances, opens pits, closes doors, triggers generators, etc.
* Deactivate (M_DEACTIVATE) - Disables instances, closes pits, opens doors, etc.
* Toggle (M_TOGGLE) - Enables a disabled instance and disables an enabled one.
* Next Tick (M_NEXTTICK) - Tells instances to proceed. Makes doors continue to open and close, monster generators re-enable, etc.
* Expire (M_EXPIRE) - Triggers an on_expire event, or simply destroys the instance if there is no such event.
* Clean Up (M_CLEANUP) - Deletes the targeted instance from the target list of all instances in the dungeon.
* Reset Counter (M_RESET) - Sets a counter back to its default value.
* Destroy (M_DESTROY) - Removes the instance from the dungeon. This can cause Lua errors if triggers etc. target it and it isn't sent a Clean Up first.
Define new messages with dsb_add_msgtype.

There is also a special set of messages that can be sent to the special target SYSTEM, either from dsb_msg or from a msgzone.

They take some extra parameters, which can be either sent as data with the msg, or added as parameters to the call to dsb_msgzone.
(i.e., this special case of dsb_msgzone takes 10 parameters instead of the usual 8)
The extra parameters are noted after the name of the system message. If a 0 is listed, just pass 0.

* SYS_MAGIC_PPOS (ppos, 0) = Sets the currently displayed spellcaster to the specified ppos.
* SYS_MAGIC_RUNE (ppos, rune_number) = Stores the specified rune into the specified ppos's pending spell.
* SYS_MAGIC_BACK (ppos, 0) = Deletes the last rune from the specified ppos's pending spell.
* SYS_MAGIC_CAST (ppos, 0) = Casts the current spell for the specified ppos. Does a bit of internal processing and then calls sys_spell_cast.
* SYS_METHOD_OBJ (ppos, location) = Shows the attack method dialogue for a given ppos from a given location
* SYS_METHOD_SEL (inst, method) = Selects the given attack method for the given instance. (Note: Currently, if the method was not first popped up via * SYS_METHOD_OBJ, this will do nothing.)
* SYS_METHOD_CLEAR (ppos, 0) = Clears the attack method for the given ppos.

[[Category:DSB|Messages]]

DSB/Messages

2012-11-13T22:52:06Z

Sophia:

DSB/Events and System Functions

2012-08-07T18:12:38Z

Sophia:

== System Functions ==
When certain things happen globally, or values are needed, the game engine will call sys_ functions.


All of them are contained in base/system.lua (except for the rendering-related ones, in base/render.lua), so look there for now. If anyone wants to wiki-ize the list, feel free. I'll be working mostly on things that I haven't documented somewhere else. -- Sophia


== Events ==
When certain things happen to a specific object, the game engine (or, sometimes, the [[DSB/Base Code|Base Code]]) will call various events associated with an object arch.

;on_throw(self, id, location)
:The '''location''' is where the object is thrown "from," via an attack method. It is '''nil''' if the object is thrown from the mouse hand. In that case, if you need to assume the throw came from some inventory zone, you can use the global variable mouse_throwing_hand.
:See also base/methods.lua: method_throw_obj.

;on_impact(self, id, hit_what, hit_ppos)
:This function is called when an inst hits something. If it hits a monster or object, hit_what will be set to an inst id. If it hits a party member, hit_what will be nil, hit_ppos will be the party position that it hit.
:See also base/damage.lua: '''explode_thing''', '''poisonbomb_thing''', etc.

;on_deplete(self, id)
:When an inst with charges consumes its last charge, this event is called. If this event doesn't exist, but the arch has a '''convert_deplete''' property, a '''dsb_swap''' is executed. Otherwise, the object is deleted.

;on_click(self, id, clicked_with, cx, cy)
:Used on a mirror, or a compass. The cx and cy values are the exact coordinates (relative to the upper left corner of the object's bitmap) that you clicked on, making it possible to define custom "click zones" with a bit of hacking.

;on_look(self, id, whose_eye) = new_id
:This is called when you click on someone's eye with an inst. If it returns an id, that id is shown, instead of the one actually held to the eye.

;on_drop(self, id)
:Called when an inst is dropped. If it returns true, the inst can't be dropped.

;on_zone_drop(self, drop_zone_id, dropped_obj_id)
:Called when an inst is dropped into a drop zone (i.e., an alcove). If it returns true, the alcove won't accept the inst.

;on_trigger(self, id, trigger_id)
:Called when something is put on a flooritem. (If trigger_id is nil, it's the party)

;off_trigger(self, id, trigger_id)
:Called when something comes off a flooritem. (If trigger_id is nil, it's the party)

;on_turn(self, id, dir)
:Useful for the compass, for example.

;on_fly(id, x, y, tile, face, flytimer)
:Used in the '''test_dungeon''', see crazy axe.

;on_consume
:See ''function eatdrink'', where you need to set a foodval or waterval property for the arch type.

;on_spawn
:Fired when created, such as a monster death cloud of dust.

;on_melee_damage_monster
:An event for hooking attack methods of specific weapons

;on_monster_move_into
;Event for objects that handle monster movement in special ways

;on_teleport
:Called when teleporting the object.

Also for the inventory there are events such as <code>to_feet(id, who)</code>, <code>from_feet(id, who)</code>, <code>to_neck(id, who)</code>, <code>from_neck(id, who)</code>, <code>to_r_hand</code>, <code>from_r_hand</code>, <code>to_l_hand</code>, <code>from_l_hand</code> and I just found <code>after_from_r_hand</code> and <code>after_from_l_hand</code> which pleases me greatly... Where I've finally found a <code>to_anywhere</code> and <code>from_anywhere</code> event.

Not an 'event' as such but we also have <code>flying_away</code>, <code>flying_toward</code>, <code>flying_side</code> properties to assign if necessary for a bitmap.

;potion_effect(id, who, base_power)
:Create your own potions and effects.

;hit_sound
:Used for weapons, assigning a sound.

;namechanger(id, who_look)
:Used with the bones object or a Ven Bomb for example.

;subrenderer(id)
:Yeah, this is a good one... See the objects.lua

;objzone_check(id, putting_in, zone)
:See the objects.lua

Things such as stairs are objects of course and have events such as <code>on_trigger</code>, <code>off_trigger</code>, <code>on_turn</code>, <code>on_try_move</code>, ...

[[Category:DSB|Events and System Functions]]

DSB/Locking Flags

2011-04-20T22:28:59Z

Sophia: Created page with "; LOCK_ACTUATORS : Triggers will not work ; LOCK_MOVEMENT : Party cannot move ; LOCK_MOUSE : Mouse clicks will not work at all ; LOCK_MAGIC : Cannot enter runes or cast spells ; ..."

; LOCK_ACTUATORS : Triggers will not work
; LOCK_MOVEMENT : Party cannot move
; LOCK_MOUSE : Mouse clicks will not work at all
; LOCK_MAGIC : Cannot enter runes or cast spells
; LOCK_INVENTORY : Cannot view inventories
; LOCK_ATTACK : Cannot trigger attack methods
; LOCK_FLYERS : Flying objects will not update
; LOCK_CONDITIONS : Timed conditions will not update
; LOCK_MESSAGES : Message timers will not run
; LOCK_ALL_TIMERS : No game timers will run at all

DSB/DSB for RTC users

2011-04-16T18:41:55Z

Sophia: /* Floor Triggers */

Here are some tips and tricks for using DSB if you're used to using RTC.

==Floor Triggers==
Unlike in RTC, DSB floor triggers need not be on the CENTER of the tile. By placing them on one of the other directions, you can respond only to objects that are in that position.

It may also be important to note that unlike in RTC (I think?), no guarantee is made as to the order that multiple triggers on one tile will execute. If you need to do a complex set of tasks in a specific order, write some custom Lua code. You can also use one trigger linked to multiple targets, but you should also be aware that there is no guarantee of the order that two messages arriving in the same tick will be processed.

As of DSB 0.45 or so, the DSB message queue has been changed so that messages arriving from the same originator will arrive in order. This means that to rapidly enable and then disable something, you can continue using the RTC idiom of sending it two Toggle messages (necessary in RTC to avoid using a relay) but you can also send it an Activate and then a Deactivate and it will work properly.

To summarize:
* Multiple messages from the same originator to the same target - Will arrive in the order sent
* Multiple messages from the same originator to different targets - Will arrive in the order sent
* Multiple messages from different originators to the same target - No guarantees are made as to order

==Alcoves==
DSB alcoves are, in general, much simpler than RTC alcoves. To do complicated things in response to objects put into an alcove, put a floor trigger on the same square as the alcove and use that instead. In particular, DSB alcoves have no concept of constant weight; you will need to use a floor trigger. A CENTER'd floor trigger will respond to anything put in any alcove on that tile. To respond only to a single alcove on a tile with multiple alcoves, put the trigger on the same direction as the alcove. (That is, to respond only to the alcove on the NORTH side of the tile, put the floor trigger in the NORTH tile position, not in the CENTER)

==WALLITEM_RELAY==
The "x_relay" arch is designed to be an accurate emulation of RTC's WALLITEM_RELAY, but for new dungeons, DSB's own native "msg_sender" arch includes more functionality, including the ability to specify a repeat rate. For really complex relays, you're best off just converting their functionality to Lua code.

However, one of the most common applications of relays, increasing the number of targets and/or changing the message type, is not even needed in DSB: while RTC has a maximum of eight targets per trigger and they must all be sent the same message, DSB allows an effectively unlimited number, and in addition, each target can have a different message. For example :

<code>
exvar[trigger_id] = { target = {id1, id2, id3}, msg = {M_ACTIVATE, M_TOGGLE, M_DEACTIVATE} }
</code>

This will cause <code>trigger_id</code> to send M_ACTIVATE to id1, M_TOGGLE to id2, and M_DEACTIVATE to id3.

ESB's target editor takes care of all of this automatically.

==Door Buttons==
DSB door buttons are treated the same as any other button. Unlike RTC door buttons, they must be explicitly given a message and a target if you create them by hand. ESB will take care of automatically linking door buttons with their doors. Of course, the upside to this slightly greater complexity is that door buttons in DSB can do anything that any other button can do, not just open a door on the same tile.

==Wallsets==
RTC wallsets should work, unmodified, in DSB as "ext wallsets," using dsb_make_wallset_ext.

==PNG and Alpha Channels==
DSB supports PNG images now, so they also should work unmodified.

[[Category:DSB|DSB for RTC users]]

DSB/DSB for RTC users

2011-04-16T18:38:45Z

Sophia: /* Floor Triggers */

Here are some tips and tricks for using DSB if you're used to using RTC.

==Floor Triggers==
Unlike in RTC, DSB floor triggers need not be on the CENTER of the tile. By placing them on one of the other directions, you can respond only to objects that are in that position.

It may also be important to note that unlike in RTC (I think?), no guarantee is made as to the order that multiple triggers on one tile will execute. If you need to do a complex set of tasks in a specific order, write some custom Lua code. You can also use one trigger linked to multiple targets, but you should also be aware that there is no guarantee of the order that two messages arriving in the same tick will be processed.

As of DSB 0.45 or so, the DSB message queue has been changed so that messages arriving at the same target from the same originator will arrive in order. This means that to rapidly enable and then disable something, you can continue using the RTC idiom of sending it two Toggle messages (necessary in RTC to avoid using a relay) but you can also send it an Activate and then a Deactivate and it will work properly.

==Alcoves==
DSB alcoves are, in general, much simpler than RTC alcoves. To do complicated things in response to objects put into an alcove, put a floor trigger on the same square as the alcove and use that instead. In particular, DSB alcoves have no concept of constant weight; you will need to use a floor trigger. A CENTER'd floor trigger will respond to anything put in any alcove on that tile. To respond only to a single alcove on a tile with multiple alcoves, put the trigger on the same direction as the alcove. (That is, to respond only to the alcove on the NORTH side of the tile, put the floor trigger in the NORTH tile position, not in the CENTER)

==WALLITEM_RELAY==
The "x_relay" arch is designed to be an accurate emulation of RTC's WALLITEM_RELAY, but for new dungeons, DSB's own native "msg_sender" arch includes more functionality, including the ability to specify a repeat rate. For really complex relays, you're best off just converting their functionality to Lua code.

However, one of the most common applications of relays, increasing the number of targets and/or changing the message type, is not even needed in DSB: while RTC has a maximum of eight targets per trigger and they must all be sent the same message, DSB allows an effectively unlimited number, and in addition, each target can have a different message. For example :

<code>
exvar[trigger_id] = { target = {id1, id2, id3}, msg = {M_ACTIVATE, M_TOGGLE, M_DEACTIVATE} }
</code>

This will cause <code>trigger_id</code> to send M_ACTIVATE to id1, M_TOGGLE to id2, and M_DEACTIVATE to id3.

ESB's target editor takes care of all of this automatically.

==Door Buttons==
DSB door buttons are treated the same as any other button. Unlike RTC door buttons, they must be explicitly given a message and a target if you create them by hand. ESB will take care of automatically linking door buttons with their doors. Of course, the upside to this slightly greater complexity is that door buttons in DSB can do anything that any other button can do, not just open a door on the same tile.

==Wallsets==
RTC wallsets should work, unmodified, in DSB as "ext wallsets," using dsb_make_wallset_ext.

==PNG and Alpha Channels==
DSB supports PNG images now, so they also should work unmodified.

[[Category:DSB|DSB for RTC users]]

DSB/DSB for RTC users

2011-04-16T18:34:03Z

Sophia:

Here are some tips and tricks for using DSB if you're used to using RTC.

==Floor Triggers==
Unlike in RTC, DSB floor triggers need not be on the CENTER of the tile. By placing them on one of the other directions, you can respond only to objects that are in that position.

It may also be important to note that unlike in RTC (I think?), no guarantee is made as to the order that multiple triggers on one tile will execute. If you need to do a complex set of tasks in a specific order, write some custom Lua code. You can also use one trigger linked to multiple targets, but you should also be aware that there is no guarantee of the order that two messages arriving in the same tick will be processed.

If you want to rapidly enable and disable something, the best way is to continue using the RTC idiom of sending it two toggle messages. In RTC, this was necessary to avoid using a relay; in DSB, this is not the case (see WALLITEM_RELAY below) but sending an activate and a deactivate that arrive in the same tick may arrive in the wrong order, leading to undesired results.

==Alcoves==
DSB alcoves are, in general, much simpler than RTC alcoves. To do complicated things in response to objects put into an alcove, put a floor trigger on the same square as the alcove and use that instead. In particular, DSB alcoves have no concept of constant weight; you will need to use a floor trigger. A CENTER'd floor trigger will respond to anything put in any alcove on that tile. To respond only to a single alcove on a tile with multiple alcoves, put the trigger on the same direction as the alcove. (That is, to respond only to the alcove on the NORTH side of the tile, put the floor trigger in the NORTH tile position, not in the CENTER)

==WALLITEM_RELAY==
The "x_relay" arch is designed to be an accurate emulation of RTC's WALLITEM_RELAY, but for new dungeons, DSB's own native "msg_sender" arch includes more functionality, including the ability to specify a repeat rate. For really complex relays, you're best off just converting their functionality to Lua code.

However, one of the most common applications of relays, increasing the number of targets and/or changing the message type, is not even needed in DSB: while RTC has a maximum of eight targets per trigger and they must all be sent the same message, DSB allows an effectively unlimited number, and in addition, each target can have a different message. For example :

<code>
exvar[trigger_id] = { target = {id1, id2, id3}, msg = {M_ACTIVATE, M_TOGGLE, M_DEACTIVATE} }
</code>

This will cause <code>trigger_id</code> to send M_ACTIVATE to id1, M_TOGGLE to id2, and M_DEACTIVATE to id3.

ESB's target editor takes care of all of this automatically.

==Door Buttons==
DSB door buttons are treated the same as any other button. Unlike RTC door buttons, they must be explicitly given a message and a target if you create them by hand. ESB will take care of automatically linking door buttons with their doors. Of course, the upside to this slightly greater complexity is that door buttons in DSB can do anything that any other button can do, not just open a door on the same tile.

==Wallsets==
RTC wallsets should work, unmodified, in DSB as "ext wallsets," using dsb_make_wallset_ext.

==PNG and Alpha Channels==
DSB supports PNG images now, so they also should work unmodified.

[[Category:DSB|DSB for RTC users]]

DSB/Exposed functions

2010-12-19T22:05:53Z

Sophia: /* Levels and Wallsets */

==Introduction==
Functions are given in the form:
;function(arguments, ~[optional arguments]) = return value
:If the terminology doesn't make sense, check [DSBTerms].
Functions without a dsb_ prefix are part of [[DSB/Base Code|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:

<code>
for i in dsb_insts()
</code>

;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_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:
:<code>gfx["GAUDYMEDIEVALFONT"] = dsb_get_font("GAUDYMEDIEVAL", "fonts/gaudymedieval.pcx")</code>

;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_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_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
:Returns the basic info about a level.

;dsb_level_tint(level, RGB)
: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.

;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/DSB for RTC users|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/DSB for RTC users|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_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 [http://www.dungeon-master.com/forum/viewtopic.php?f=53&t=28487&p=106622#p106622 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 [[DSB/Multiple Parties|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 [[DSB/Multiple Parties|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 [[DSB/Special Values|Special Values]] can be used.

;dsb_move(id, level, x, y, tile_location)
:Moves an instance to the specified location. The [[DSB/Special Values|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 [[DSB/Graphics Flag|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 [[DSB/Spawnburst|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 [http://www.dungeon-master.com/forum/viewtopic.php?f=53&t=28613&p=111165#p111165 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 [[DSB/Monster AI|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. [[DSB/Monster AI|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 [[DSB/Messages|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.

;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: <code>draw_function(bitmap, mouse_x, mouse_y)</code>
:The click_func, if provided, will be executed every time the mouse is clicked. It is of the form: <code>click_func(mouse_x, mouse_y, mouse_buttons)</code>
: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.

==Subrenderers==
;dsb_subrenderer_target() = bitmap
:Returns a bitmap to be drawn upon. Use only in a [[DSB/Subrenderers|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 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)
:Creates an object zone associated with the given id at the given x and y coordinates on the given subrenderer 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.

If the target id is SYSTEM, it will create a clickzone to control the engine instead. In those cases, two additional parameters must be specified, to pass information to the system. Allowable messages are:
* SYS_METHOD_OBJ, ppos, location = Shows the attack method dialogue for a given ppos from a given location

* SYS_METHOD_SEL, inst, method = Selects the given attack method for the given instance. (Note: Currently, if the method was not first popped up via SYS_METHOD_OBJ, this will do nothing.)

* SYS_METHOD_CLEAR, ppos, 0 = Clears the attack method for the given ppos.

==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 [[DSB/Global Flags|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 [[DSB/Locking Flags|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 <code>g_disabled_runes~[8] = false</code>.

;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 [http://www.dungeon-master.com/forum/viewtopic.php?f=53&t=28613&p=111165#p111165 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(???) = ???

[[Category:DSB|Exposed functions]]

DSB/Messages

2010-03-25T18:55:17Z

Sophia: New page: Base messages as defined by DSB and used in ESB are the following: * Activate (M_ACTIVATE) - Enables instances, opens pits, closes doors, triggers generators, etc. * Deactivate (M_DEACTIVA...

DSB/Exposed functions

2010-03-25T18:42:50Z

Sophia:

==Introduction==
Functions are given in the form:
;function(arguments, ~[optional arguments]) = return value
:If the terminology doesn't make sense, check [DSBTerms].
Functions without a dsb_ prefix are part of [[DSB/Base Code|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:

<code>
for i in dsb_insts()
</code>

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

;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_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) = font
:Searches the same paths as dsb_get_bitmap, loading a font.

;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_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_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
:Returns the basic info about a level.

;dsb_level_tint(level, RGB)
: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.

;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/DSB for RTC users|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_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/DSB for RTC users|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_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 [http://www.dungeon-master.com/forum/viewtopic.php?f=53&t=28487&p=106622#p106622 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 [[DSB/Multiple Parties|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 [[DSB/Multiple Parties|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 [[DSB/Special Values|Special Values]] can be used.

;dsb_move(id, level, x, y, tile_location)
:Moves an instance to the specified location. The [[DSB/Special Values|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_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 [[DSB/Graphics Flag|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 [[DSB/Spawnburst|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.

==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 [[DSB/Monster AI|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. [[DSB/Monster AI|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 [[DSB/Messages|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.

;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 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)
: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: <code>draw_function(bitmap, mouse_x, mouse_y)</code>
The click_func, if provided, will be executed every time the mouse is clicked. It is of the form:
<code>click_func(mouse_x, mouse_y, mouse_buttons)</code>
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.
The full-screen renderer will run until any of its associated functions returns something other than false or nil.

==Subrenderers==
;dsb_subrenderer_target() = bitmap
:Returns a bitmap to be drawn upon. Use only in a [[DSB/Subrenderers|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 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)
:Creates an object zone associated with the given id at the given x and y coordinates on the given subrenderer 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.

If the target id is SYSTEM, it will create a clickzone to control the engine instead. In those cases, two additional parameters must be specified, to pass information to the system. Allowable messages are:
* SYS_METHOD_OBJ, ppos, location = Shows the attack method dialogue for a given ppos from a given location

* SYS_METHOD_SEL, inst, method = Selects the given attack method for the given instance. (Note: Currently, if the method was not first popped up via SYS_METHOD_OBJ, this will do nothing.)

* SYS_METHOD_CLEAR, ppos, 0 = Clears the attack method for the given ppos.

==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 [[DSB/Global Flags|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 [[DSB/Locking Flags|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 <code>g_disabled_runes~[8] = false</code>.

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

==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(???) = ???

[[Category:DSB|Exposed functions]]

Main Page

2010-03-25T18:35:09Z

Sophia:

<big>Welcome to the Dungeon master Wiki</big>

This wiki is dedicated to [http://dmweb.free.fr/ Dungeon Master], its engine, its clones, and to [http://www.dungeon-master.com/forum/viewtopic.php?t=23916 custom dungeons]

For information about the original games (mainly '''Dungeon Master''', '''Chaos Strikes back''' and '''Dungeon Master II'''), the [http://dmweb.free.fr/ Dungeon Master Encyclopaedia] is the best place.

== Clones ==
* [[CSBwin]] - A clone based on the original source code by [[User:Paul Stevens|Paul Stevens]]
* [[DM Java]] - A clone written in Java
* [[DSB|Dungeon Strikes Back]] - A Lua-powered DM clone
* [[RTC|Return to Chaos]] - A Clone of DM

== Custom Dungeons ==
* [[Conflux|Conflux III]] - A CSBwin dungeon created by [[Zyx]]

DSB/DSB for RTC users

2010-03-25T18:34:36Z

Sophia:

Here are some tips and tricks for using DSB if you're used to using RTC.

==Floor Triggers==
Unlike in RTC, DSB floor triggers need not be on the CENTER of the tile. By placing them on one of the other directions, you can respond only to objects that are in that position.

It may also be important to note that unlike in RTC (I think?), no guarantee is made as to the order that multiple triggers on one tile will execute. If you need to do a complex set of tasks in a specific order, write some custom Lua code. You can also use one trigger linked to multiple targets, but you should also be aware that there is no guarantee of the order that two messages arriving in the same tick will be processed.

If you want to rapidly enable and disable something, the best way is to continue using the RTC idiom of sending it two toggle messages. In RTC, this was necessary to avoid using a relay; in DSB, this is not the case (see WALLITEM_RELAY below) but sending an activate and a deactivate that arrive in the same tick may arrive in the wrong order, leading to undesired results.

==Alcoves==
DSB alcoves are, in general, much simpler than RTC alcoves. To do complicated things in response to objects put into an alcove, put a floor trigger on the same square as the alcove and use that instead. In particular, DSB alcoves have no concept of constant weight; you will need to use a floor trigger. A CENTER'd floor trigger will respond to anything put in any alcove on that tile. To respond only to a single alcove on a tile with multiple alcoves, put the trigger on the same direction as the alcove. (That is, to respond only to the alcove on the NORTH side of the tile, put the floor trigger in the NORTH tile position, not in the CENTER)

==WALLITEM_RELAY==
The "x_relay" arch is designed to be an accurate emulation of RTC's WALLITEM_RELAY, but for new dungeons, DSB's own native "msg_sender" arch includes more functionality, including the ability to specify a repeat rate. For really complex relays, you're best off just converting their functionality to Lua code.

However, one of the most common applications of relays, increasing the number of targets and/or changing the message type, is not even needed in DSB: while RTC has a maximum of eight targets per trigger and they must all be sent the same message, DSB allows an effectively unlimited number, and in addition, each target can have a different message. For example :

<code>
exvar~[[trigger_id]] = { target = {id1, id2, id3}, msg = {M_ACTIVATE, M_TOGGLE, M_DEACTIVATE} }
</code>

This will cause <code>trigger_id</code> to send M_ACTIVATE to id1, M_TOGGLE to id2, and M_DEACTIVATE to id3.

ESB's target editor takes care of all of this automatically.

==Door Buttons==
DSB door buttons are treated the same as any other button. Unlike RTC door buttons, they must be explicitly given a message and a target if you create them by hand. ESB will take care of automatically linking door buttons with their doors. Of course, the upside to this slightly greater complexity is that door buttons in DSB can do anything that any other button can do, not just open a door on the same tile.

==Wallsets==
RTC wallsets should work, unmodified, in DSB as "ext wallsets," using dsb_make_wallset_ext.

==PNG and Alpha Channels==
DSB supports PNG images now, so they also should work unmodified.

[[Category:DSB|DSB for RTC users]]