Difference between revisions of "Modding:level blueprint (0.9.9.7)"

Revision as of 18:52, 22 December 2012 (view source) Yaflhdztioxo (Talk | contribs) (→‎Blueprint) ← Older edit		Revision as of 19:19, 22 December 2012 (view source) Yaflhdztioxo (Talk | contribs) (→‎Engine Hooks) Newer edit →
Line 53:		Line 53:
	== Engine Hooks ==		== Engine Hooks ==
−	{|class="wikitable" style="border: 2px solid darkred; border-spacing: 0; font-size: 90%; margin: 0.25em 0.5em;"	+
−	! colspan="2" style="background: darkred; color: yellow; font-size: 120%; text-align: center"|'''Level Hooks'''	+	{{drltable|Level Hooks|2|{{Table2Col
−	{{Table2Col	+
	|es=background: #333;		|es=background: #333;
−	|c1=font-weight:bold; text-align:right; vertical-align:top; padding:0px 2px;	+	|c1=font-family:monospace; text-align:right; vertical-align:top; padding:0px 2px;
	|c2=padding:0px 2px;		|c2=padding:0px 2px;
−	|void|[[#level_Create|Create]]()	+	|{{modarg|void}}    |[[#level_create          |<u>Create</u>  ]] ()
−	|void|[[#level_OnTick|OnTick]]()	+	|{{modarg|boolean}} |[[#level_cangenerate    |canGenerate    ]] ()
−	|void|[[#level_OnEnter|OnEnter]]()	+	|{{modarg|void}}    |[[#level_onregister      |OnRegister      ]] ()
−	|void|[[#level_OnExit|OnExit]]()	+	|{{modarg|void}}    |[[#level_oncreate        |OnCreate        ]] ()
−	|void|[[#level_OnKill|OnKill]]()	+	|{{modarg|void}}    |[[#level_ondie          |OnDie          ]] ()
−	|void|[[#level_OnKillAll|OnKillAll]]()	+	|{{modarg|boolean}} |[[#level_ondiecheck      |OnDieCheck      ]] ()
−	|boolean|[[#level_IsCompleted|IsCompleted]]()	+	|{{modarg|void}}    |[[#level_onpickup        |OnPickup        ]] ()
−	}}	+	|{{modarg|boolean}} |[[#level_onpickupcheck  |OnPickupCheck  ]] ()
−	|}	+	|{{modarg|void}}    |[[#level_onuse          |OnUse          ]] ()
		+	|{{modarg|boolean}} |[[#level_onusecheck      |OnUseCheck      ]] ()
		+	|{{modarg|void}}    |[[#level_onkill          |OnKill         ]] ()
		+	|{{modarg|void}}    |[[#level_onkillall      |OnKillAll       ]] ()
		+	|{{modarg|void}}    |[[#level_onenter        |OnEnter        ]] ()
		+	|{{modarg|void}}    |[[#level_onfire          |OnFire          ]] ()
		+	|{{modarg|void}}    |[[#level_onfired        |OnFired        ]] ()
		+	|{{modarg|void}}    |[[#level_onexit          |OnExit          ]] ()
		+	|{{modarg|void}}    |[[#level_ontick          |OnTick          ]] ()
		+	|{{modarg|boolean}} |[[#level_oncompletedcheck|OnCompletedCheck]] ()
		+	|{{modarg|void}}   |[[#level_onnuked        |OnNuked        ]] ()
		+	|}}
		+	}}
−	{{Anchor|level_Create}}	+
−	;Create()	+	{{Anchor|level_create}}
−	:This function should create the layout of the level. It also usually sets up the initial being and item locations. The player's initial location should be set here using Level.player.	+	;Create()
		+	:This function should create the layout of the level. It also usually sets up the initial being and item locations. The player's initial location should be set here as well.
		+	----
		+	{{Anchor|level_cangenerate}}
		+	;canGenerate() &rarr; '''boolean'''
		+	:xxx
		+	----
		+	{{Anchor|level_onregister}}
		+	;OnRegister()
		+	:xxx
		+	----
		+	{{Anchor|level_oncreate}}
		+	;OnCreate()
		+	:xxx
		+	----
		+	{{Anchor|level_ondie}}
		+	;OnDie()
		+	:xxx
		+	----
		+	{{Anchor|level_ondiecheck}}
		+	;OnDieCheck() &rarr; '''boolean'''
		+	:xxx
		+	----
		+	{{Anchor|level_onpickup}}
		+	;OnPickup()
		+	:xxx
		+	----
		+	{{Anchor|level_onpickupcheck}}
		+	;OnPickupCheck() &rarr; '''boolean'''
		+	:xxx
		+	----
		+	{{Anchor|level_onuse}}
		+	;OnUse()
		+	:xxx
		+	----
		+	{{Anchor|level_onusecheck}}
		+	;OnUseCheck() &rarr; '''boolean'''
		+	:xxx
		+	----
		+	{{Anchor|level_onkill}}
		+	;OnKill()
		+	:Triggered whenever an enemy is killed.
		+	----
		+	{{Anchor|level_onkillall}}
		+	;OnKillAll()
		+	:Triggered when a kill is made and there are no more enemies on a level.  This hook is fired AFTER OnKill and can be fired again if more enemies are spawned. By default, the "relatively safe" message is displayed.
		+	----
		+	{{Anchor|level_onenter}}
		+	;OnEnter()
		+	:Triggered just after the player enters the level.
	----		----
−	{{Anchor|level_OnTick}}	+	{{Anchor|level_onfire}}
−	;OnTick()	+	;OnFire()
−	:This is called every 0.1s of game time. This will happen many times for each of the player's moves, so be careful about putting intense calculations here.	+	:xxx
	----		----
−	{{Anchor|level_OnEnter}}	+	{{Anchor|level_onfired}}
−	;OnEnter()	+	;OnFired()
−	:This is triggered just after the player enters the level.	+	:xxx
	----		----
−	{{Anchor|level_OnExit}}	+	{{Anchor|level_onexit}}
−	;OnExit()	+	;OnExit()
−	:This is triggered when the player leaves the level.	+	:xxx
	----		----
−	{{Anchor|level_OnKill}}	+	{{Anchor|level_ontick}}
−	;OnKill()	+	;OnTick()
−	:This hook is triggered whenever an enemy is killed.	+	:Triggered every 0.1s of game time. This will happen many times for each of the player's moves so be careful about putting intense calculations here.
	----		----
−	{{Anchor|level_OnKillAll}}	+	{{Anchor|level_oncompletedcheck}}
−	;OnKillAll()	+	;OnCompletedCheck() &rarr; '''boolean'''
−	:After OnKill has triggered, if there are no enemies left on the level, the OnKillAll will be triggered. It is possible for OnKillAll to trigger again later if more enemies are spawned. By default, the "relatively safe" message is displayed.	+	:Called by the engine when trying to determine if a special level should be counted as 'completed' for statistics purposes. This is only called for special levels, not scripted levels. By default a level is considered complete if all enemies are dead.
	----		----
−	{{Anchor|level_IsCompleted}}	+	{{Anchor|level_onnuked}}
−	;IsCompleted() &rarr; '''boolean'''	+	;OnNuked()
−	:The game calls this hook to determine if the game statistics should count the level as completed. This is only called for special levels, not scripted levels. By default, all enemies must be dead for the level to be complete.	+	:Triggered when a nuke is detonated.
	== Properties ==		== Properties ==

---

Revision as of 19:19, 22 December 2012

The level blueprint is used to define the properties of fixed special levels. This is in contrast to the generator blueprint which is used to construct random levels. Both tend to make heavy use of the level API, level object, and generator API.

Contents 1 Blueprint 1.1 Flags 2 Engine Hooks 3 Properties 4 API

Blueprint

Level blueprints are registered with the register_level procedure. Registered blueprints are stored in a global Lua table called levels.

Level Blueprint
id	string	The unique identifier used by the engine for this level. Passed as the first argument when registering a blueprint.
name	string	The level name displayed in the HUD.
entry	string	Message recorded to mortem on level entry.
welcome	string	Message displayed on level entry.
level	range	dlevel range where the level may appear.
Create	function
canGenerate	function
OnRegister	function
OnCreate	function
OnDie	function
OnDieCheck	function
OnPickup	function
OnPickupCheck	function
OnUse	function
OnUseCheck	function
OnKill	function
OnKillAll	function
OnEnter	function
OnFire	function
OnFired	function
OnExit	function
OnTick	function
OnCompletedCheck	function
OnNuked	function

Flags

Level Flags
LF_NOHOMING	Causes homing phase devices to act like normal phase devices.
LF_UNIQUEITEM	Used by the level generation code to keep track of whether a unique item has dropped on the current level (in order to prevent multiple uniques from dropping on one level). This flag also causes a level feeling to occur indicating that a unique item is present.
LF_BONUS	This flag is automatically set for so-called special levels like Halls of Carnage. (It is not set for those special levels like Hellgate that replace normal levels, only by those reached from red stairs.)
LF_RESPAWN	Causes monsters to randomly respawn as when playing the game on Nightmare!
LF_NORESPAWN	Prevents the Nightmare! respawn feature.
LF_NUKED	This flag is automatically set when the level is nuked.
LF_NONUKE	Causes the thermonuclear bomb to have no effect when it is used. It is not respected by other nuke effects.
LF_ITEMSVISIBLE	Allows the player to see all items on the level (as with a Computer Map).
LF_BEINGSVISIBLE	Allows the player to see all beings on the level (as with a Tracking Map).

Engine Hooks

Level Hooks
void	Create ()
boolean	canGenerate ()
void	OnRegister ()
void	OnCreate ()
void	OnDie ()
boolean	OnDieCheck ()
void	OnPickup ()
boolean	OnPickupCheck ()
void	OnUse ()
boolean	OnUseCheck ()
void	OnKill ()
void	OnKillAll ()
void	OnEnter ()
void	OnFire ()
void	OnFired ()
void	OnExit ()
void	OnTick ()
boolean	OnCompletedCheck ()
void	OnNuked ()

Create()

This function should create the layout of the level. It also usually sets up the initial being and item locations. The player's initial location should be set here as well.

---

canGenerate() → boolean

xxx

---

OnRegister()

xxx

---

OnCreate()

xxx

---

OnDie()

xxx

---

OnDieCheck() → boolean

xxx

---

OnPickup()

xxx

---

OnPickupCheck() → boolean

xxx

---

OnUse()

xxx

---

OnUseCheck() → boolean

xxx

---

OnKill()

Triggered whenever an enemy is killed.

---

OnKillAll()

Triggered when a kill is made and there are no more enemies on a level. This hook is fired AFTER OnKill and can be fired again if more enemies are spawned. By default, the "relatively safe" message is displayed.

---

OnEnter()

Triggered just after the player enters the level.

---

OnFire()

xxx

---

OnFired()

xxx

---

OnExit()

xxx

---

OnTick()

Triggered every 0.1s of game time. This will happen many times for each of the player's moves so be careful about putting intense calculations here.

---

OnCompletedCheck() → boolean

Called by the engine when trying to determine if a special level should be counted as 'completed' for statistics purposes. This is only called for special levels, not scripted levels. By default a level is considered complete if all enemies are dead.

---

OnNuked()

Triggered when a nuke is detonated.

Properties

These are properties of the global Level variable. They are changed by the engine as the player moves from level to level. For some of the read-only properties, rawset can be used to create a lua property that shadows the pascal property, tricking APIs that are implemented in lua. This is particularly useful for tricking the generator API into using a custom style.

Level
Word	status	This is for use by level designers. It is preferred to access it through Level.result.
string	name	This is the level name as displayed on the HUD.
Byte	name_number	This controls the "LevX" part of the level name. If zero, it won't be displayed.
Byte	danger_level	Level generation parameter that corresponds to depth.
Byte	style	The style (tile set) used by the level generation functions. This property is read-only.
string	special_exit	The sid of the level that red stairs lead to on the current level number. This property is read-only.
string	special_name	The sid of the current level prototype or the empty string for random levels. This property is read-only.
DWord	item_array_size	Length of the sparse array that stores all the items on the level. This property is read-only.
DWord	being_array_size	Length of the sparse array that stores all the beings on the level. This property is read-only.

API

Level Interface
value	Level.property_get(string property)
void	Level.property_set(property value, ) → string
boolean	Level.flag_get(Level Flag flag)
void	Level.flag_set(Level Flag flag, boolean value)
value	Level.roll_weight(list list, integer sum)
integer	Level.weight_list_sum(list list)
void	Level.place_tile(table translation, string tile, integer x, integer y)
void	Level.player(integer x, integer y)
integer	Level.result(integer value)
boolean	Level.eye_contact(Coord c1, Coord c2)
boolean	Level.is_visible(Coord position)
void	Level.nuke()
void	Level.explosion(Coord position, integer radius, integer delay, integer damage_dice, integer damage_sides, Color color, Sound ID sound, DamageType damagetype, ExplosionFlag List flags, Cell ID content)
	Cell-specific functions
boolean	Level.light_flag_get(Coord position, LightFlag flag)
void	Level.light_flag_set(Coord position, LightFlag flag, boolean value)
integer	Level.hp_get(Coord position)
void	Level.hp_set(Coord position, integer value)
boolean	Level.is_corpse(Coord position)
boolean	Level.scan(Area scan_area, Cell ID good)
void	Level.fill(Cell ID cell, Area fill_area)
void	Level.flood(Cell ID tile, Area flood_area)
void	Level.scatter(Area scatter_area, Cell ID good, Cell ID fill, integer count)
void	Level.scatter_put(Area scatter_area, table translation, string tile, Cell ID good, integer count)
boolean	Level.push_cell(Coord c, Coord target, boolean quiet)
	Being-specific functions
Being	Level.get_being(integer index)
Being	Level.get_being_by_uid(integer uid)
Being	Level.drop_being(Being ID bid, Coord position)
void	Level.drop_being_ext(table being, Coord position)
Being	Level.summon(Being ID bid, integer count)
Being	Level.area_summon(Area where, Being ID bid, integer count)
void	Level.clear_being(Coord position)
list, integer	Level.get_being_list()
Being ID	Level.random_being()
void	Level.flood_monster(Being ID bid, integer amount)
void	Level.flood_monsters(integer amount)
Being iterator	Level.beings()
Being iterator	Level.beings_in_range(Coord position, integer range)
	Item-specific functions
Item	Level.get_item(integer index)
Item	Level.get_item_by_uid(integer uid)
Item	Level.drop_item(Item ID iid, Coord position)
void	Level.drop_item_ext(table item, Coord position)
Item	Level.drop(Item ID iid, integer count)
Item	Level.area_drop(Area where, Item ID iid, integer count)
void	Level.try_destroy_item(Coord c)
list, integer	Level.get_item_list(integer max_level, integer unique_mult)
Item ID	Level.roll_item_type(ItemType list itypes, integer max_level, integer unique_mod)
Item ID	Level.roll_item(integer max_level, integer unique_mod)
void	Level.flood_items(integer amount)
Item iterator	Level.items()
Item iterator	Level.items_in_range(Coord position, integer range)

Level.property_get(string property) → value

Gets the value of the given level property. It is preferred to use the Lua dot indexing syntax instead.

---

Level.property_set(property value, ) → string

Sets the given level property to the given value. It is preferred to use the Lua dot indexing syntax instead.

---

Level.flag_get(Level Flag flag) → boolean

Level.flags[Level Flag flag] → boolean

Determines the current state of the given level flag.

---

Level.flag_set(Level Flag flag, boolean value)

Level.flags[Level Flag flag] = boolean value

Sets the given level flag to the given value.

---

Level.roll_weight(list list, integer sum) → value

Randomly chooses an item from the list according to the weight property of the list items. Sum must be the sum of the weights of all the list items.

---

Level.weight_list_sum(list list) → integer

Returns the sum of the weight properties of all the items in the list.

---

Level.place_tile(table translation, string tile, integer x, integer y)

Places the map tile given by translation and tile on the map at the position given by x and y. translation should be a table that maps single character strings to either cell ids, or to tables. These tables have their first array element be a cell id, but they may also contain a being andor item key that is mapped to a being or item id respectively. Level.drop_being_ext and Level.drop_item_ext syntax is allowed. tile should be a string of characters that are defined in translation. Line breaks correspond to line breaks on the map.

---

Level.player(integer x, integer y)

Sets the initial position of the player for a special or scripted level. This should be called in the Create hook; after that it has no meaningful effect.

---

Level.result(integer value) → integer

If value is given, updates the level's status and returns nil. If value is omitted, returns the current status.

---

Level.eye_contact(Coord c1, Coord c2) → boolean

Determines whether or not there is a line-of-sight path between c1 and c2. This calculation ignores light flags (such that two beings can have eye contact even if they aren't visible to each other).

---

Level.is_visible(Coord position) → boolean

Determines if the given position is visible to the player.

---

Level.nuke()

Triggers an immediate nuclear explosion as from a thermonuclear bomb.

---

Level.explosion(Coord position, integer radius, integer delay, integer damage_dice, integer damage_sides, Color color, Sound ID sound, DamageType damagetype, ExplosionFlag List flags, Cell ID content)

Creates an explosion centered at the given position with the given parameters. radius is the size of the explosion. delay is the delay in milliseconds between animation frames (typically this is around 40). damage_dice and damage_sides determine the damage roll for the explosion. For a no-damage explosion, both should be 0. The default damage type is fire. content determines the cell that is randomly created wherever the explosion does enough damage. By default, there are no flags and there is no content. Only some colors are supported, and these are automatically translated into 3 color combinations used by the explosion animation. The supported colors are LIGHTBLUE, BLUE, MAGENTA, GREEN, LIGHTRED, YELLOW, and the default RED.

---

Level.light_flag_get(Coord position, LightFlag flag) → boolean

Level.light[Coord position][LightFlag flag] → boolean

Gets the value of the given light flag at the given position.

---

Level.light_flag_set(Coord position, LightFlag flag, boolean value)

Level.light[Coord position][LightFlag flag] = boolean value

Level.light[LightFlag flag] = boolean value

Sets the value of the given light flag at the given position. For the syntax without a position, the light flag will be set at every position on the map.

---

Level.hp_get(Coord position) → integer

Level.hp[Coord position] → integer

Gets the current hp of the cell at the given position.

---

Level.hp_set(Coord position, integer value)

Level.hp[Coord position] = integer value

Sets the current hp of the cell at the given position. Setting hp to 0 won't destroy a cell.

---

Level.is_corpse(Coord position) → boolean

Determines whether the given position has a corpse in it. This counts the cell with id "corpse" as a corpse even though it otherwise isn't a corpse as far as the engine is concerned.

---

Level.scan(Area scan_area, Cell ID good) → boolean

Determines if every cell in scan_area is good.

---

Level.fill(Cell ID cell, Area fill_area)

Sets every cell in the given area to the area. fill_area is optional; it defaults to the full map.

---

Level.flood(Cell ID tile, Area flood_area)

Changes CELLSET_FLOORS and CF_LIQUID tiles in the area to tile. If tile has CF_HAZARD, then it will destroy items.

---

Level.scatter(Area scatter_area, Cell ID good, Cell ID fill, integer count)

Chooses count random tiles in scatter_area (possibly with duplicates) and sets any chosen cells that are good to fill.

---

Level.scatter_put(Area scatter_area, table translation, string tile, Cell ID good, integer count)

Chooses count random subareas with upper-left corner in scatter_area of the size appropriate of tile (using the first line length and number of lines to define a rectangular area). There may be duplicates or overlaps. For each subarea, if the area is already filled with good, then it is replaced with tile (according to translation). See Level.place_tile for the semantics of translation and tile.

---

Level.push_cell(Coord c, Coord target, boolean quiet) → boolean

Swaps the content of the cells located in c and target: this will only occur successfully if target is a part of CELLSET_FLOORS. If target has the CF_HAZARD flag, the cell on c activates its OnDestroy hook. quiet, when set to true, includes messages (mostly specific to barrels, the only object pushed in the base game).

---

Level.get_being(integer index) → Being

Returns the being at the given index in the sparse being array. A being's index won't change as long as it is in the array.

---

Level.get_being_by_uid(integer uid) → Being

Returns the being with the given uid, or nil if that being doesn't exist or has been removed from the map.

---

Level.drop_being(Being ID bid, Coord position) → Being

Drops a newly created being in the given position. bid can also be an actual being object, although this should not be used for beings that are already on the map. If the position is occupied, the being will be dropped nearby. The dropped being is returned. If the function fails, nil is returned.

---

Level.drop_being_ext(table being, Coord position)

As Level.drop_being, except additional values are accetable for being as Level.drop_item_ext.

---

Level.summon(Being ID bid, integer count) → Being

Creates new beings of the type given by bid and amount given by count and scatters them around the map. The last dropped being (if any) is returned. count is optional and defaults to 1.

---

Level.area_summon(Area where, Being ID bid, integer count) → Being

As Level.summon, but all the summoned beings are randomly placed in where rather than scattered across the whole map.

---

Level.clear_being(Coord position)

Level.clear_being(integer index)

Removes an item from the map at the given position, or from the given index in the item array.

---

Level.get_being_list() → list,integer

Returns the list and sum (ready to be used with Level.roll_weight) for beings and beings groups according to Level.danger_level and DIFFICULTY. The result is cached.

---

Level.random_being() → Being ID

Returns a random being chosen according to weights from the current level's list. This will never choose a group. The returned id is always a string id.

---

Level.flood_monster(Being ID bid, integer amount)

Add the given monster type to the level in an amount specified by the total danger value amount (so it scales appropriately with Level.flood_monsters).

---

Level.flood_monsters(integer amount)

Adds monsters to the level using the normal algorithm for random levels. The amount is a total danger value such as a value returned by Generator.being_weight.

---

Level.beings() → Being iterator

Gives an iterator over all beings in the level.

---

Level.beings_in_range(Coord position, integer range) → Being iterator

Gives an iterator over all beings within range units of distance from position in the level.

---

Level.get_item(integer index) → Item

Returns the item at the given index in the sparse item array. An item's index won't change as long as it is in the array.

---

Level.get_item_by_uid(integer uid) → Item

Returns the item with the given uid, or nil if that item doesn't exist or has been removed from the map.

---

Level.drop_item(Item ID iid, Coord position) → Item

Drops a newly created item in the given position. iid can also be an actual item object, although this should not be used for items that are already on the map. If the position is occupied, the item will be dropped nearby. The dropped item is returned. If the function fails, nil is returned.

---

Level.drop_item_ext(table item, Coord position)

As Level.drop_item, except additional values are acceptable for item. If item is a table, the first list element is passed used to determine which item to drop. For other key-value pairs in the table, the property of the dropped item that corresponds to the key will be set to the value.

---

Level.drop(Item ID iid, integer count) → Item

Creates new items of the type given by iid and amount given by count and scatters them around the map. The last dropped item (if any) is returned. count is optional and defaults to 1.

---

Level.area_drop(Area where, Item ID iid, integer count) → Item

As Level.drop, but all dropped items are randomly placed in where rather than scattered across the whole map.

---

Level.try_destroy_item(Coord c)

Destroys an item at position, if there is one to be found.

---

Level.get_item_list(integer max_level, integer unique_mult) → list,integer

Returns the list and sum (ready to be used with Level.roll_weight) for items according to max_level, and unique_mult. max_level defaults to Level.danger_level, and is used to determine which items fall in the proper level range. Unique items' weights are multiplied by unique_mult (which defaults to 1). The result is cached.

---

Level.roll_item_type(ItemType list itypes, integer max_level, integer unique_mod) → Item ID

Returns a random item chosen from among the given item types according to weights from the list specified by max_level and unique_mod. The returned id is always a string id.

---

Level.roll_item(integer max_level, integer unique_mod) → Item ID

As Level.roll_item_type, but the item type of the result isn't restricted.

---

Level.flood_items(integer amount)

Adds items to the level according to the normal algorithm for random levels (not counting special features). The number of items is given by amount.

---

Level.items() → Item iterator

Gives an iterator over all items in the level.

---

Level.items_in_range(Coord position, integer range) → Item iterator

Gives an iterator over all items within range units of distance from position in the level.