Modding:level blueprint (0.9.9.7)

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.

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

Engine Hooks

Level Hooks
void	Create ()
boolean	canGenerate ()
void	OnRegister ()
void	OnCreate (being)
void	OnCreate (item)
void	OnDie (being)
boolean	OnDieCheck (being)
void	OnPickup (item, being)
boolean	OnPickupCheck (item, being)
void	OnUse (item, being)
boolean	OnUseCheck (item, being)
void	OnKill (being)
void	OnKillAll ()
void	OnEnter ()
boolean	OnFire (item, being)
void	OnFired (being)
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

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.

---

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.

---

OnCreate(being)

OnCreate(item)

A hook chained to the being and 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.

---

OnDie(being)

A hook chained to the being OnDie method.

---

OnDieCheck(being) → boolean

A hook chained to the being OnDieCheck method.

---

OnPickup(item, being)

A hook chained to the item OnPickup method.

---

OnPickupCheck(item, being) → boolean

A hook chained to the item OnPickupCheck method.

---

OnUse(item, being)

A hook chained to the item OnUse method.

---

OnUseCheck(item, being) → boolean

A hook chained to the item OnUseCheck method.

---

OnKill(being)

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(item, being)

A hook chained to the item OnFire method.

---

OnFired(being)

A hook chained to the item OnFired method.

---

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.

---

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.