When this is in some finalized form, I'll compile it into an "offline" guide.. eventually. This took me long enough as it is.
First, some basic terms:
- Archetypes and Instances = The term "object" is somewhat ambiguous, so these terms are used instead. An archetype (abbreviated arch) is a general category, such as "Axe" or "Iron Keyhole." An instance (abbreviated inst) is one specific thing that is found in the dungeon. "Screamer Slice" is an archetype, one particular slice from a Screamer you just killed is an instance.
- Exvars = For reasons of speed and space, many instances don't have a full representation in Lua. Instead, exvars (external variables) can be used to store essential information about an instance that its archetype doesn't have. For example, the power of a ful bomb, or the target of a pushbutton.
- Party position = Usually represented "ppos" in the code, this is a number from 0 to 3 that refers to the slot occupied by a given character. This is different than the character id.
Functions are given in the form:
function(arguments, [optional arguments]) = return value
- 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: Select all
for i in dsb_insts() - dsb_in_obj(id)
Another iterator; see above for usage. This one is used to iterate all over all instances that are inside the given instance. - dsb_write(RGB, string)
Outputs the given text string in the given color to the console. An RGB is specified as a table of { R, G, B }. - 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_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_get_sound(name) = sound
Searches the same paths as dsb_get_bitmap, loading a sound. - dsb_get_font(name) = font
Searches the same paths as dsb_get_bitmap, loading a font. - dsb_new_bitmap(xsize, ysize) = bitmap
Creates a brand new bitmap and returns a handle 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. - dsb_bitmap_clear(bitmap, RGB)
Clears a bitmap to the specified RGB value. (that is, 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
Returns the width of a bitmap. - dsb_bitmap_height(bitmap) = integer
Returns the height of a 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)
Renders text onto a bitmap in the specified font, with the specified alignment. (LEFT, RIGHT, CENTER, or MULTILINE) - 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_animate(bitmap, frames, frame_delay)
Sets up a bitmap that is a series of frames for animation. - 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 the useful helper fucntion local_sound(id, sound) that 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 dsb_sound or dsb_3dsound. - 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, RTC, or WHACK wallset, you'll find this command useful. - dsb_level_wallset(level, wallset)
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. However, 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_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_level_getinfo(level) = x_size, y_size, light, xp_multiplier
Returns the basic info about a level. - 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 RTC text file. - dsb_image2map(level, filename, light, xp_multiplier)
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 colorconvert table like this:Functions can also be embedded in colorconvert by prefixing them with the _ (underscore) character. The function is then called, allowing more variation in what the color can represent. See test_dungeon/dungeon.lua for further examples of how this is used.Code: Select all
colorconvert = { [color_number] = {wall_or_floor, "name of object", orientation }, ... } - dsb_party_coords() = level, x, y, facing
Returns the party's location. - dsb_party_place(level, x, y, facing)
Places the 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_spawn(object_arch, level, x, y, tile_location) = id
Spawns a new instance at the specified coordinates and returns its id.
Note that if "level" is negative, various special values can be used.
These are defined in base/global.lua.- PARTY = x is a Party position, y is in an inventory slot.
- IN_OBJ = x is the inst id of the instance the targeted instance is inside,
y is a given slot (but can be 0) - CHARACTER = x is a Character id, y is an inventory slot.
- MOUSE_HAND = x and y are ignored.
- LIMBO = x and y are ignored.
- dsb_move(id, level, x, y, tile_location)
Moves an instance to the specified location. The special coordinates from above can be used. - dsb_reposition(id, tile_location)
Moves an instance to a new tile location on the same tile. Useful for rearranging monsters.
Important Note: dsb_spawn, dsb_reposition and dsb_move 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_spawnburst_begin()
- dsb_spawnburst_end()
Begins or ends a spawnburst. During a spawnburst, the on_trigger event of a newly spawned instance is put into a queue, rather than being immediately executed. This will prevent oddities when a trigger whose exvars have not yet been defined has an instance spawned on top of it that should trigger it. If you prefer to spawn all instances first and then go back and define your exvars, as opposed to defining exvars immediately after a dsb_spawn, you should use these functions. Otherwise, they are generally only useful in automatically generated dungeon files. - 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_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_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 arche 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_swap(id, new_arch)
A full swap. It totally destroys the targeted instance and creates a new one at its location with its id number. It's "safer" than qswap, but things like exvars are not preserved. - dsb_delete(id)
Completely destroys an instance from the dungeon. - 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_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_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_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_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 threw 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_msg(delay, id, message, data, [sender])
Sends the specified message 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. It can also be used to emulate some of the behavior of RTC's "WALLITEM_RELAY," but a more thorough implementation of this is given by the "x_relay" arch. For details, see base/objects.lua. - 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 makes this function 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_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. - 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. - 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. - dsb_add_condition(type, inventory_gfx, portrait_gfx, update_freq, function) = condition_id
Adds a condition (status variable) to the list of those available. The type is either PARTY (affects the whole party), INDIVIDUAL (affects one person), or BAD_INDIVIDUAL (affects one person, gives the "mouth" icon a red border). 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:Code: Select all
function update_func(char, condition_strength) return new_condition_strength end - 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. - dsb_get_gfxflag(id, flag) = value
Gets the value of a graphics flag for a given instance. For information on what these flags are please see base/global.lua. - dsb_set_gfxflag(id, flag)
Sets a graphics flag for a given instance. - dsb_clear_gfxflag(id, flag)
Clears a graphics flag for a given instance. - dsb_toggle_gfxflag(id, flag)
Toggles a graphics flag for a given instance. - dsb_get_gameflag(flag) = value
Gets the value of a global gameplay flag. For information on what these flags are please see base/global.lua. - dsb_set_gameflag(flag)
Sets a global gameplay flag. - dsb_clear_gameflag(flag)
Clears a global gameplay flag. - dsb_toggle_gameflag(flag)
Toggles a global gameplay flag. - dsb_get_charge(id) = integer
Gets 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. - dsb_set_charge(id, integer)
Sets the charge of a given instance. See previous function. - 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_get_hp(id) = integer
- dsb_set_hp(id, integer)
Gets or sets a monster's HP. - dsb_get_maxhp(id) = integer
- dsb_set_maxhp(id, integer)
Gets or sets a monster's max HP. - dsb_set_tint(id, RGB)
Sets the 'tint' of a monster, to give it a glowing effect. Monsters flash when they are hit by various spells. - dsb_ai(id, message, data) [= result]
Sends an AI message to the given monster.
If data = 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.
Currently supported AI messages are:- AI_TIMER = Sets the monster's movement timer directly
- AI_MOVE = Tells the monster to move in a direction. An optional second parameter can specify which way the monster should face.
- AI_TURN = Tells the monster to turn in a direction
- AI_FEAR = Makes the monster afraid and run away
- AI_DELAY_ACTION = Makes the monster pause for the number of ticks specified
- AI_STUN = Disorients the monster
- AI_HAZARD = Tells the monster is it in a bad location and needs to move
- AI_WALL_BELIEF = Tells the monster what to do about fake walls
- AI_SEE_PARTY = Tells the monster that it sees the party
- AI_TARGET (takes two parameters) = Sets where the monster wants to go
- AI_MOVE_NOW = Gives the monster a turn immediately (used when trying to fuse Lord Chaos, for example)
- 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_subordinates(boss_id) = { {id, tile}, [...] }
Returns all monsters who are subordinate to the given boss. - 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_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, and so on) - 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 altering maximum 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_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 unlike many of the other functions, these take party positions, not character numbers. - 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_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. This can happen on-the-fly at any time. Note that the method table must be specified by name as a string, not as an actual table. The table 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 and subskill (or 0 for no subskill). The "nobonus" form does not take temporary XP or level-boosting items into account. - 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 xp_up(char, skill, subskill, xp), that does take these things into account. xp_up is 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. This doesn't do anything with stats, leveling up or down, or anything of that sort, so these functions may be 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. - dsb_get_leader() = ppos
Returns the party position of the party's leader. - dsb_ppos_char(ppos) = char
Returns the character at the given party position, or nil if there isn't one. - 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) = tile_dir
Returns the tile location that the given party position occupies. - dsb_tile_ppos(tile_dir) = ppos
Returns the party position occupied by the given tile location, or nil if nobody is there. - dsb_get_charname(char) = string
Returns the character's name. - dsb_get_sleepstate() = boolean
Returns whether or not the party is asleep. - dsb_wakeup()
Wakes up the party if they are asleep. - 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. 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. - 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_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_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.
Note:
To simply damage a character, you're best off just using the function do_damage(ppos, char, type, amount), defined in base/damage.lua. - 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." - dsb_rand(min, max) = integer
Generates a random integer between min and max, inclusive. - 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. For example:After executing this code, the variable val would have the value of 5.Code: Select all
num = 5 str = "num" val = dsb_lookup_global(str)
If you don't know what this is for, you probably don't need it. - 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_delay_func(delay, function)
Executes the given function after the given delay in ticks. References to Lua functions cannot be saved, so 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_subrenderer_target() = bitmap
Returns a bitmap to be drawn upon. Use only in a subrenderer. 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) - 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.
- dsb_update_sysicons()
If the sysicons table has been changed, this lets the engine know. You probably won't need to mess with this, but see how the "chewing" animation is done in base/util.lua to get an idea of how it works. - dsb_lastmethod(ppos) = method, location, inst
Returns the last attack method invoked by the given ppos. - dsb_update_strings()
If the system strings 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 become mostly deprecated, though it is still necessary if you're changing the "HEALTH", "STAMINA" or "MANA" on the main inventory screen. - 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)
Enables 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. - dsb_rune_disable(rune)
Disallows the specified magical rune for use in spells. - 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.
draw_function(bitmap, mouse_x, mouse_y)
The click_func, if provided, will be executed every time the mouse is clicked. It is of the form:
click_func(mouse_x, mouse_y, mouse_buttons)
Update_func, if provided, will be executed every game tick. It takes no parameters.
If mouse is nil or false, no mouse pointer will be drawn. If it is true, the standard "yellow arrow" mouse pointer will be drawn. If it is a bitmap, that bitmap will be drawn as the mouse pointer.
The full-screen renderer will run until any of its associated functions returns something other than false or nil. - 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.