|
|
| (6 intermediate revisions by one user not shown) |
| Line 1: |
Line 1: |
| − | The level [[Modding:blueprint|blueprint]] is used to define the properties of fixed special levels. This is in contrast to the [[Modding:generator|generator]] blueprint which is used to construct random levels. Both tend to make heavy use of the [[Modding:level_API|level API]], [[Modding:level_MapNode|level object]], and [[Modding:generator_API|generator API]]. | + | The level [[Modding:blueprint|blueprint]] is used to define the properties of fixed special levels. This is in contrast to the [[Modding:generator|generator]] blueprint which is used to construct random levels. Both tend to make heavy use of the [[Modding:level_API|level API]], [[Modding:level_object|level object]], and [[Modding:generator_API|generator API]]. |
| | | | |
| | == Blueprint == | | == Blueprint == |
| − | Levels prototypes are only used for special levels and scripted levels, not random levels. They are declared using the Levels function with the ID as the first argument, and a prototype table as the second argument. They are stored by ID in a global table called levels.
| + | Level blueprints are registered with the ''register_level'' procedure. Registered blueprints are stored in a global Lua table called ''levels''. |
| − | {|class="wikitable" style="border: 2px solid darkred; border-spacing: 0; font-size: 90%; margin: 0.25em 0.5em;" | + | |
| − | ! colspan="3" style="background: darkred; color: yellow; font-size: 120%; text-align: center"|'''Level Prototype'''
| + | {{drltable|Level Blueprint|3|{{Table3Col |
| − | {{Table3Col
| + | |
| | |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=vertical-align:top; padding:0px 2px; | | |c2=vertical-align:top; padding:0px 2px; |
| | |c3=padding:0px 2px; | | |c3=padding:0px 2px; |
| − | |string|ID|The unique identifier used by the engine for this level. Instead of being included in the table, this must be passed as the first argument to the Levels function. | + | |<u>id</u> |{{modarg|string}}|The unique identifier used by the engine for this level. Passed as the first argument when registering a blueprint. |
| − | |string|name|The name displayed in the HUD. | + | |<u>name</u>|{{modarg|string}}|The level name displayed in the HUD. |
| − | |string|welcome|Optional message displayed on level entry. | + | |entry |{{modarg|string}}|Message recorded to mortem on level entry. |
| − | |integer|chance|Optional percent chance the level will appear. Defaults to 100. | + | |welcome |{{modarg|string}}|Message displayed on level entry. |
| − | |[[Modding:Functions$function_resolve_range|Range]]|level|Level range where the level may appear. | + | |level |{{modarg|range}} |dlevel range where the level may appear. |
| − | |string|entry|Optional mortem history message for level entry. | + | |<u>Create</u> |{{modarg|function}}| |
| − | }}
| + | |canGenerate |{{modarg|function}}| |
| − | |} | + | |OnRegister |{{modarg|function}}| |
| − | === Flags ===
| + | |OnCreate |{{modarg|function}}| |
| − | {{drltable|Level Flags|2|{{Table2Col | + | |OnDie |{{modarg|function}}| |
| − | |es=background: #333; | + | |OnDieCheck |{{modarg|function}}| |
| − | |c1=font-family:monospace; text-align:right; vertical-align:top; padding:0px 2px; | + | |OnPickup |{{modarg|function}}| |
| − | |c2=padding:0px 2px; | + | |OnPickupCheck |{{modarg|function}}| |
| − | |LF_NOHOMING|Causes homing phase devices to act like normal phase devices. | + | |OnUse |{{modarg|function}}| |
| − | |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. | + | |OnUseCheck |{{modarg|function}}| |
| − | |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.) | + | |OnKill |{{modarg|function}}| |
| − | |LF_RESPAWN|Causes monsters to randomly respawn as when playing the game on Nightmare! | + | |OnKillAll |{{modarg|function}}| |
| − | |LF_NORESPAWN|Prevents the Nightmare! respawn feature. | + | |OnEnter |{{modarg|function}}| |
| − | |LF_NUKED|This flag is automatically set when the level is nuked. | + | |OnFire |{{modarg|function}}| |
| − | |LF_NONUKE|Causes the thermonuclear bomb to have no effect when it is used. It is not respected by other nuke effects. | + | |OnFired |{{modarg|function}}| |
| − | |LF_ITEMSVISIBLE|Allows the player to see all items on the level (as with a [[Computer Map]]). | + | |OnExit |{{modarg|function}}| |
| − | |LF_BEINGSVISIBLE|Allows the player to see all beings on the level (as with a [[Tracking Map]]). | + | |OnTick |{{modarg|function}}| |
| | + | |OnCompletedCheck|{{modarg|function}}| |
| | + | |OnNuked |{{modarg|function}}| |
| | |}} | | |}} |
| | }} | | }} |
| | + | |
| | == Engine Hooks == | | == Engine Hooks == |
| − | {|class="wikitable" style="border: 2px solid darkred; border-spacing: 0; font-size: 90%; margin: 0.25em 0.5em;" | + | {{drltable|Level Hooks|2|{{Table2Col |
| − | ! colspan="2" style="background: darkred; color: yellow; font-size: 120%; text-align: center"|'''Level Hooks'''
| + | |
| − | {{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 ]] ({{modarg|being}}) |
| − | |void|[[#level_OnKill|OnKill]]() | + | |{{modarg|void}} |[[#level_oncreate |OnCreate ]] ({{modarg|item}}) |
| − | |void|[[#level_OnKillAll|OnKillAll]]()
| + | |{{modarg|void}} |[[#level_ondie |OnDie ]] ({{modarg|being}}) |
| − | |boolean|[[#level_IsCompleted|IsCompleted]]()
| + | |{{modarg|boolean}} |[[#level_ondiecheck |OnDieCheck ]] ({{modarg|being}}) |
| − | }}
| + | |{{modarg|void}} |[[#level_onpickup |OnPickup ]] ({{modarg|item}}, {{modarg|being}}) |
| − | |}
| + | |{{modarg|boolean}} |[[#level_onpickupcheck |OnPickupCheck ]] ({{modarg|item}}, {{modarg|being}}) |
| − | | + | |{{modarg|void}} |[[#level_onuse |OnUse ]] ({{modarg|item}}, {{modarg|being}}) |
| − | {{Anchor|level_Create}} | + | |{{modarg|boolean}} |[[#level_onusecheck |OnUseCheck ]] ({{modarg|item}}, {{modarg|being}}) |
| − | ;Create()
| + | |{{modarg|void}} |[[#level_onkill |OnKill ]] ({{modarg|being}}) |
| − | :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.
| + | |{{modarg|void}} |[[#level_onkillall |OnKillAll ]] () |
| − | ----
| + | |{{modarg|void}} |[[#level_onenter |OnEnter ]] () |
| − | {{Anchor|level_OnTick}}
| + | |{{modarg|boolean}} |[[#level_onfire |OnFire ]] ({{modarg|item}}, {{modarg|being}}) |
| − | ;OnTick()
| + | |{{modarg|void}} |[[#level_onfired |OnFired ]] ({{modarg|being}}) |
| − | :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.
| + | |{{modarg|void}} |[[#level_onexit |OnExit ]] () |
| − | ----
| + | |{{modarg|void}} |[[#level_ontick |OnTick ]] () |
| − | {{Anchor|level_OnEnter}}
| + | |{{modarg|boolean}} |[[#level_oncompletedcheck|OnCompletedCheck]] () |
| − | ;OnEnter()
| + | |{{modarg|void}} |[[#level_onnuked |OnNuked ]] () |
| − | :This is triggered just after the player enters the level.
| + | |}} |
| − | ----
| + | |
| − | {{Anchor|level_OnExit}} | + | |
| − | ;OnExit()
| + | |
| − | :This is triggered when the player leaves the level.
| + | |
| − | ----
| + | |
| − | {{Anchor|level_OnKill}}
| + | |
| − | ;OnKill()
| + | |
| − | :This hook is triggered whenever an enemy is killed.
| + | |
| − | ----
| + | |
| − | {{Anchor|level_OnKillAll}}
| + | |
| − | ;OnKillAll()
| + | |
| − | :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.
| + | |
| − | ----
| + | |
| − | {{Anchor|level_IsCompleted}}
| + | |
| − | ;IsCompleted() → '''boolean'''
| + | |
| − | :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.
| + | |
| − | | + | |
| − | == 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.
| + | |
| − | {|class="wikitable" style="border: 2px solid darkred; border-spacing: 0; font-size: 90%; margin: 0.25em 0.5em;"
| + | |
| − | ! colspan="3" style="background: darkred; color: yellow; font-size: 120%; text-align: center"|'''Level'''
| + | |
| − | {{Table3Col
| + | |
| − | |es=background: #333;
| + | |
| − | |c1=font-weight:bold; text-align:right; vertical-align:top; padding:0px 2px;
| + | |
| − | |c2=vertical-align:top; padding:0px 2px;
| + | |
| − | |c3=padding:0px 2px;
| + | |
| − | |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 ==
| + | |
| − | {{drltable|Level Interface|2|{{Table2Col
| + | |
| − | |es=background: #333;
| + | |
| − | |c1=font-weight:bold; text-align:right; vertical-align:top; padding:0px 2px;
| + | |
| − | |c2=padding:0px 2px;
| + | |
| − | |{{modarg|value}}|{{moddef|list|property_get|dot||string|property}}
| + | |
| − | |{{modarg|void}}|{{moddef|list|property_set|dot|string|property|value|value}} | + | |
| − | |{{modarg|boolean}}|{{moddef|list|flag_get|dot||Level Flag|flag}}
| + | |
| − | |{{modarg|void}}|{{moddef|list|flag_set|dot||Level Flag|flag|boolean|value}} | + | |
| − | |{{modarg|value}}|{{moddef|list|roll_weight|dot||list|list|integer|sum}}
| + | |
| − | |{{modarg|integer}}|{{moddef|list|weight_list_sum|dot||list|list}}
| + | |
| − | |{{modarg|void}}|{{moddef|list|place_tile|dot||table|translation|string|tile|integer|x|integer|y}} | + | |
| − | |{{modarg|void}}|{{moddef|list|player|dot||integer|x|integer|y}}
| + | |
| − | |{{modarg|integer}}|{{moddef|list|result|dot||integer|value}}
| + | |
| − | |{{modarg|boolean}}|{{moddef|list|eye_contact|dot||Coord|c1|Coord|c2}} | + | |
| − | |{{modarg|boolean}}|{{moddef|list|is_visible|dot||Coord|position}} | + | |
| − | |{{modarg|void}}|{{moddef|list|nuke|dot}} | + | |
| − | |{{modarg|void}}|{{moddef|list|explosion|dot||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'''
| + | |
| − | |{{modarg|boolean}}|{{moddef|list|light_flag_get|dot||Coord|position|LightFlag|flag}}
| + | |
| − | |{{modarg|void}}|{{moddef|list|light_flag_set|dot||Coord|position|LightFlag|flag|boolean|value}} | + | |
| − | |{{modarg|integer}}|{{moddef|list|hp_get|dot||Coord|position}}
| + | |
| − | |{{modarg|void}}|{{moddef|list|hp_set|dot||Coord|position|integer|value}}
| + | |
| − | |{{modarg|boolean}}|{{moddef|list|is_corpse|dot||Coord|position}} | + | |
| − | |{{modarg|boolean}}|{{moddef|list|scan|dot||Area|scan_area|Cell ID|good}}
| + | |
| − | |{{modarg|void}}|{{moddef|list|fill|dot||Cell ID|cell|Area|fill_area}} | + | |
| − | |{{modarg|void}}|{{moddef|list|flood|dot||Cell ID|tile|Area|flood_area}}
| + | |
| − | |{{modarg|void}}|{{moddef|list|scatter|dot||Area|scatter_area|Cell ID|good|Cell ID|fill|integer|count}} | + | |
| − | |{{modarg|void}}|{{moddef|list|scatter_put|dot||Area|scatter_area|table|translation|string|tile|Cell ID|good|integer|count}} | + | |
| − | |{{modarg|boolean}}|{{moddef|list|push_cell|dot||Coord|c|Coord|target|boolean|quiet}} | + | |
| − | ||'''Being-specific functions'''
| + | |
| − | |{{modarg|Being}}|{{moddef|list|get_being|dot||integer|index}}
| + | |
| − | |{{modarg|Being}}|{{moddef|list|get_being_by_uid|dot||integer|uid}}
| + | |
| − | |{{modarg|Being}}|{{moddef|list|drop_being|dot||Being ID|bid|Coord|position}}
| + | |
| − | |{{modarg|void}}|{{moddef|list|drop_being_ext|dot||table|being|Coord|position}}
| + | |
| − | |{{modarg|Being}}|{{moddef|list|summon|dot||Being ID|bid|integer|count}}
| + | |
| − | |{{modarg|Being}}|{{moddef|list|area_summon|dot||Area|where|Being ID|bid|integer|count}}
| + | |
| − | |{{modarg|void}}|{{moddef|list|clear_being|dot||Coord|position}} | + | |
| − | |{{modarg|list}}, {{modarg|integer}}|{{moddef|list|get_being_list|dot}}
| + | |
| − | |[[Modding:Being|Being ID]]|{{moddef|list|random_being|dot}}
| + | |
| − | |{{modarg|void}}|{{moddef|list|flood_monster|dot||Being ID|bid|integer|amount}}
| + | |
| − | |{{modarg|void}}|{{moddef|list|flood_monsters|dot||integer|amount}} | + | |
| − | |{{modarg|Being iterator}}|{{moddef|list|beings|dot}}
| + | |
| − | |{{modarg|Being iterator}}|{{moddef|list|beings_in_range|dot||Coord|position|integer|range}}
| + | |
| − | ||'''Item-specific functions'''
| + | |
| − | |{{modarg|Item}}|{{moddef|list|get_item|dot||integer|index}}
| + | |
| − | |{{modarg|Item}}|{{moddef|list|get_item_by_uid|dot||integer|uid}}
| + | |
| − | |{{modarg|Item}}|{{moddef|list|drop_item|dot||Item ID|iid|Coord|position}}
| + | |
| − | |{{modarg|void}}|{{moddef|list|drop_item_ext|dot||table|item|Coord|position}} | + | |
| − | |{{modarg|Item}}|{{moddef|list|drop|dot||Item ID|iid|integer|count}}
| + | |
| − | |{{modarg|Item}}|{{moddef|list|area_drop|dot||Area|where|Item ID|iid|integer|count}}
| + | |
| − | |{{modarg|void}}|{{moddef|list|try_destroy_item|dot||Coord|c}}
| + | |
| − | |{{modarg|list}}, {{modarg|integer}}|{{moddef|list|get_item_list|dot||integer|max_level|integer|unique_mult}}
| + | |
| − | |[[Modding:Item|Item ID]]|{{moddef|list|roll_item_type|dot||ItemType list|itypes|integer|max_level|integer|unique_mod}}
| + | |
| − | |[[Modding:Item|Item ID]]|{{moddef|list|roll_item|dot||integer|max_level|integer|unique_mod}}
| + | |
| − | |{{modarg|void}}|{{moddef|list|flood_items|dot||integer|amount|}} | + | |
| − | |{{modarg|Item iterator}}|{{moddef|list|items|dot}} | + | |
| − | |{{modarg|Item iterator}}|{{moddef|list|items_in_range|dot||Coord|position|integer|range}}
| + | |
| − | }}
| + | |
| | }} | | }} |
| | | | |
| − | {{moddef|desc|property_get|dot|value|string|property}} | + | {{Anchor|level_create}} |
| − | :Gets the value of the given level property. It is preferred to use the Lua dot indexing syntax instead.
| + | ;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. |
| − | {{moddef|desc|property_set|dot|string|property|value|value}}
| + | |
| − | :Sets the given level property to the given value. It is preferred to use the Lua dot indexing syntax instead.
| + | |
| − | ----
| + | |
| − | {{moddef|desc|flag_get|dot|boolean|Level Flag|flag}}
| + | |
| − | ;Level.flags[[[Modding:Constants#Level Flags|Level Flag]] flag] → '''boolean''' | + | |
| − | :Determines the current state of the given level flag. | + | |
| − | ----
| + | |
| − | {{moddef|desc|flag_set|dot||Level Flag|flag|boolean|value}}
| + | |
| − | ;Level.flags[[[Modding:Constants#Level Flags|Level Flag]] flag] = '''boolean''' value
| + | |
| − | :Sets the given level flag to the given value.
| + | |
| − | ----
| + | |
| − | {{moddef|desc|roll_weight|dot|value|list|list|integer|sum}}
| + | |
| − | :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.
| + | |
| − | ----
| + | |
| − | {{moddef|desc|weight_list_sum|dot|integer|list|list}}
| + | |
| − | :Returns the sum of the weight properties of all the items in the list.
| + | |
| − | ----
| + | |
| − | {{moddef|desc|place_tile|dot||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 and''or'' 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.
| + | |
| − | ----
| + | |
| − | {{moddef|desc|player|dot||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.
| + | |
| − | ----
| + | |
| − | {{moddef|desc|result|dot|integer|integer|value}}
| + | |
| − | :If ''value'' is given, updates the level's status and returns nil. If ''value'' is omitted, returns the current status.
| + | |
| − | ----
| + | |
| − | {{moddef|desc|eye_contact|dot|boolean|Coord|c1|Coord|c2}}
| + | |
| − | :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).
| + | |
| − | ----
| + | |
| − | {{moddef|desc|is_visible|dot|boolean|Coord|position}}
| + | |
| − | :Determines if the given position is visible to the player.
| + | |
| − | ----
| + | |
| − | {{moddef|desc|nuke|dot}}
| + | |
| − | :Triggers an immediate nuclear explosion as from a [[thermonuclear bomb]].
| + | |
| − | ----
| + | |
| − | {{moddef|desc|explosion|dot||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 [[explosions|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.
| + | |
| − | ----
| + | |
| − | {{moddef|desc|light_flag_get|dot|boolean|Coord|position|LightFlag|flag}}
| + | |
| − | ;Level.light[[[Modding:Coord|Coord]] position][[[Modding:Constants#LightFlag|LightFlag]] flag] → '''boolean'''
| + | |
| − | :Gets the value of the given light flag at the given position.
| + | |
| − | ----
| + | |
| − | {{moddef|desc|light_flag_set|dot||Coord|position|LightFlag|flag|boolean|value}}
| + | |
| − | ;Level.light[[[Modding:Coord|Coord]] position][[[Modding:Constants#LightFlag|LightFlag]] flag] = '''boolean''' value
| + | |
| − | ;Level.light[[[Modding:Constants#LightFlag|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.
| + | |
| − | ----
| + | |
| − | {{moddef|desc|hp_get|dot|integer|Coord|position}}
| + | |
| − | ;Level.hp[[[Modding:Coord|Coord]] position] → '''integer'''
| + | |
| − | :Gets the current hp of the cell at the given position.
| + | |
| − | ----
| + | |
| − | {{moddef|desc|hp_set|dot||Coord|position|integer|value}}
| + | |
| − | ;Level.hp[[[Modding:Coord|Coord]] position] = '''integer''' value
| + | |
| − | :Sets the current hp of the cell at the given position. Setting hp to 0 won't destroy a cell.
| + | |
| − | ----
| + | |
| − | {{moddef|desc|is_corpse|dot|boolean|Coord|position}}
| + | |
| − | :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.
| + | |
| − | ----
| + | |
| − | {{moddef|desc|scan|dot|boolean|Area|scan_area|Cell ID|good}}
| + | |
| − | :Determines if every cell in ''scan_area'' is ''good''.
| + | |
| − | ----
| + | |
| − | {{moddef|desc|fill|dot||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.
| + | |
| − | ----
| + | |
| − | {{moddef|desc|flood|dot||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.
| + | |
| − | ----
| + | |
| − | {{moddef|desc|scatter|dot||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''.
| + | |
| − | ----
| + | |
| − | {{moddef|desc|scatter_put|dot||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''.
| + | |
| − | ----
| + | |
| − | {{moddef|desc|push_cell|dot|boolean|Coord|c|Coord|target|boolean|quiet}}
| + | |
| − | :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).
| + | |
| − | ----
| + | |
| − | {{moddef|desc|get_being|dot|Being|integer|index}}
| + | |
| − | :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.
| + | |
| − | ----
| + | |
| − | {{moddef|desc|get_being_by_uid|dot|Being|integer|uid}}
| + | |
| − | :Returns the being with the given uid, or nil if that being doesn't exist or has been removed from the map.
| + | |
| − | ----
| + | |
| − | {{moddef|desc|drop_being|dot|Being|Being ID|bid|Coord|position}}
| + | |
| − | :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.
| + | |
| − | ----
| + | |
| − | {{moddef|desc|drop_being_ext|dot||table|being|Coord|position}}
| + | |
| − | :As Level.drop_being, except additional values are accetable for ''being'' as Level.drop_item_ext.
| + | |
| − | ----
| + | |
| − | {{moddef|desc|summon|dot|Being|Being ID|bid|integer|count}}
| + | |
| − | :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.
| + | |
| − | ----
| + | |
| − | {{moddef|desc|area_summon|dot|Being|Area|where|Being ID|bid|integer|count}}
| + | |
| − | :As Level.summon, but all the summoned beings are randomly placed in ''where'' rather than scattered across the whole map.
| + | |
| − | ----
| + | |
| − | {{moddef|desc|clear_being|dot||Coord|position}}
| + | |
| − | {{moddef|desc|clear_being|dot||integer|index}}
| + | |
| − | :Removes an item from the map at the given position, or from the given index in the item array.
| + | |
| − | ----
| + | |
| − | {{moddef|desc|get_being_list|dot|list,integer}}
| + | |
| − | :Returns the list and sum (ready to be used with [[#level_roll_weight|Level.roll_weight]]) for beings and beings groups according to Level.danger_level and DIFFICULTY. The result is cached.
| + | |
| | ---- | | ---- |
| − | {{moddef|desc|random_being|dot|Being ID}} | + | {{Anchor|level_cangenerate}} |
| − | :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. | + | ;canGenerate() → '''boolean''' |
| | + | :This function determines if a level can show up in a given game. If the function returns false the level will not appear. A common requirement is the difficulty be set to at least a certain value. |
| | ---- | | ---- |
| − | {{moddef|desc|flood_monster|dot||Being ID|bid|integer|amount}} | + | {{Anchor|level_onregister}} |
| − | :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). | + | ;OnRegister() |
| | + | :This function should store level specific objects (such as items, cells, medals, and badges). It is called by the engine during its loading phase. Using this hook is not necessary (there are plenty of other places to define objects) but it is considered good practice. |
| | ---- | | ---- |
| − | {{moddef|desc|flood_monsters|dot||integer|amount}} | + | {{Anchor|level_oncreate}} |
| − | :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. | + | ;OnCreate({{modarg|being}}) |
| | + | ;OnCreate({{modarg|item}}) |
| | + | :A hook chained to the [[Modding:being blueprint#being_oncreate|being]] and [[Modding:item blueprint#item_oncreate|item]] OnCreate methods. Since this hook is chained to both you may need to check the object's type to ensure it matches what you need. |
| | ---- | | ---- |
| − | {{moddef|desc|beings|dot|Being iterator}} | + | {{Anchor|level_ondie}} |
| − | :Gives an iterator over all beings in the level. | + | ;OnDie({{modarg|being}}) |
| | + | :A hook chained to the [[Modding:being blueprint#being_ondie|being]] OnDie method. |
| | ---- | | ---- |
| − | {{moddef|desc|beings_in_range|dot|Being iterator|Coord|position|integer|range}} | + | {{Anchor|level_ondiecheck}} |
| − | :Gives an iterator over all beings within '''range''' units of [[distance]] from '''position''' in the level.
| + | ;OnDieCheck({{modarg|being}}) → '''boolean''' |
| | + | :A hook chained to the [[Modding:being blueprint#being_ondiecheck|being]] OnDieCheck method. |
| | ---- | | ---- |
| − | {{moddef|desc|get_item|dot|Item|integer|index}} | + | {{Anchor|level_onpickup}} |
| − | :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. | + | ;OnPickup({{modarg|item}}, {{modarg|being}}) |
| | + | :A hook chained to the [[Modding:item blueprint#item_onpickup|item]] OnPickup method. |
| | ---- | | ---- |
| − | {{moddef|desc|get_item_by_uid|dot|Item|integer|uid}} | + | {{Anchor|level_onpickupcheck}} |
| − | :Returns the item with the given uid, or nil if that item doesn't exist or has been removed from the map. | + | ;OnPickupCheck({{modarg|item}}, {{modarg|being}}) → '''boolean''' |
| | + | :A hook chained to the [[Modding:item blueprint#item_onpickupcheck|item]] OnPickupCheck method. |
| | ---- | | ---- |
| − | {{moddef|desc|drop_item|dot|Item|Item ID|iid|Coord|position}} | + | {{Anchor|level_onuse}} |
| − | :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. | + | ;OnUse({{modarg|item}}, {{modarg|being}}) |
| | + | :A hook chained to the [[Modding:item blueprint#item_onuse|item]] OnUse method. |
| | ---- | | ---- |
| − | {{moddef|desc|drop_item_ext|dot||table|item|Coord|position}} | + | {{Anchor|level_onusecheck}} |
| − | :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.
| + | ;OnUseCheck({{modarg|item}}, {{modarg|being}}) → '''boolean''' |
| | + | :A hook chained to the [[Modding:item blueprint#item_onusecheck|item]] OnUseCheck method. |
| | ---- | | ---- |
| − | {{moddef|desc|drop|dot|Item|Item ID|iid|integer|count}} | + | {{Anchor|level_onkill}} |
| − | :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. | + | ;OnKill({{modarg|being}}) |
| | + | :Triggered whenever an enemy is killed. |
| | ---- | | ---- |
| − | {{moddef|desc|area_drop|dot|Item|Area|where|Item ID|iid|integer|count}} | + | {{Anchor|level_onkillall}} |
| − | :As Level.drop, but all dropped items are randomly placed in ''where'' rather than scattered across the whole map. | + | ;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. |
| | ---- | | ---- |
| − | {{moddef|desc|try_destroy_item|dot||Coord|c}} | + | {{Anchor|level_onenter}} |
| − | :Destroys an item at '''position''', if there is one to be found. | + | ;OnEnter() |
| | + | :Triggered just after the player enters the level. |
| | ---- | | ---- |
| − | {{moddef|desc|get_item_list|dot|list,integer|integer|max_level|integer|unique_mult}} | + | {{Anchor|level_onfire}} |
| − | :Returns the list and sum (ready to be used with [[#level_roll_weight|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. | + | ;OnFire({{modarg|item}}, {{modarg|being}}) |
| | + | :A hook chained to the [[Modding:item blueprint#item_onfire|item]] OnFire method. |
| | ---- | | ---- |
| − | {{moddef|desc|roll_item_type|dot|Item ID|ItemType list|itypes|integer|max_level|integer|unique_mod}} | + | {{Anchor|level_onfired}} |
| − | :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. | + | ;OnFired({{modarg|being}}) |
| | + | :A hook chained to the [[Modding:item blueprint#item_onfired|item]] OnFired method. |
| | ---- | | ---- |
| − | {{moddef|desc|roll_item|dot|Item ID|integer|max_level|integer|unique_mod}} | + | {{Anchor|level_onexit}} |
| − | :As Level.roll_item_type, but the item type of the result isn't restricted. | + | ;OnExit() |
| | + | :Triggered when the player leaves a level. This is a good place to assign level specific badges or medals as well as the best place to generate history entries for the mortem generation. |
| | ---- | | ---- |
| − | {{moddef|desc|flood_items|dot||integer|amount|}} | + | {{Anchor|level_ontick}} |
| − | :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''.
| + | ;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. |
| | ---- | | ---- |
| − | {{moddef|desc|items|dot|Item iterator}} | + | {{Anchor|level_oncompletedcheck}} |
| − | :Gives an iterator over all items in the level. | + | ;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. |
| | ---- | | ---- |
| − | {{moddef|desc|items_in_range|dot|Item iterator|Coord|position|integer|range}} | + | {{Anchor|level_onnuked}} |
| − | :Gives an iterator over all items within '''range''' units of [[distance]] from '''position''' in the level. | + | ;OnNuked() |
| | + | :Triggered when a nuke is detonated. |
