Spawn functions

default_spawn_is_valid

function default_spawn_is_valid(x: number, y: number, layer: LAYER): boolean

x: number
y: number
layer: LAYER

Returns boolean

Default function in spawn definitions to check whether a spawn is valid or not

define_extra_spawn

source

function define_extra_spawn(do_spawn: fun(p1: number, p2: number, p3: integer), is_valid: fun(p1: number, p2: number, p3: integer): boolean, num_spawns_frontlayer: integer, num_spawns_backlayer: integer): integer

do_spawn: fun(p1: number, p2: number, p3: integer)
is_valid: fun(p1: number, p2: number, p3: integer): boolean: Returning nil (or nothing): treated as false.
num_spawns_frontlayer: integer
num_spawns_backlayer: integer

Returns integer

Define a new extra spawn, these are semi-guaranteed level gen spawns with a fixed upper bound. The function nil do_spawn(float x, float y, LAYER layer) contains your code to spawn the thing, whatever it is. The function bool is_valid(float x, float y, LAYER layer) determines whether the spawn is legal in the given position and layer. Use for example when you can spawn only on the ceiling, under water or inside a shop. Set is_valid to nil in order to use the default rule (aka. on top of floor and not obstructed). To change the number of spawns use PostRoomGenerationContext:set_num_extra_spawns during ON.POST_ROOM_GENERATION No name is attached to the extra spawn since it is not modified from level files, instead every call to this function will return a new unique id.

define_procedural_spawn

source

function define_procedural_spawn(procedural_spawn: string, do_spawn: fun(p1: number, p2: number, p3: integer), is_valid: fun(p1: number, p2: number, p3: integer): boolean): PROCEDURAL_CHANCE

procedural_spawn: string
do_spawn: fun(p1: number, p2: number, p3: integer)
is_valid: fun(p1: number, p2: number, p3: integer): boolean: Returning nil (or nothing): treated as false.

Returns PROCEDURAL_CHANCE

Define a new procedural spawn, the function nil do_spawn(float x, float y, LAYER layer) contains your code to spawn the thing, whatever it is. The function bool is_valid(float x, float y, LAYER layer) determines whether the spawn is legal in the given position and layer. Use for example when you can spawn only on the ceiling, under water or inside a shop. Set is_valid to nil in order to use the default rule (aka. on top of floor and not obstructed). If a user disables your script but still uses your level mod nothing will be spawned in place of your procedural spawn.

door

source

function door(x: number, y: number, layer: LAYER, w: integer, l: integer, t: integer): integer

x: number
y: number
layer: LAYER
w: integer
l: integer
t: integer

Returns integer

Short for spawn_door.

get_missing_extra_spawns

source

function get_missing_extra_spawns(extra_spawn_chance_id: integer): integer, integer

extra_spawn_chance_id: integer

Returns integer, integer

Use to query whether any of the requested spawns could not be made, usually because there were not enough valid spaces in the level. Returns missing spawns in the front layer and missing spawns in the back layer in that order. The value only makes sense after level generation is complete, aka after ON.POST_LEVEL_GENERATION has run.

get_procedural_spawn_chance

source

function get_procedural_spawn_chance(chance_id: PROCEDURAL_CHANCE): integer

chance_id: PROCEDURAL_CHANCE

Returns integer

Get the inverse chance of a procedural spawn for the current level. A return value of 0 does not mean the chance is infinite, it means the chance is zero.

layer_door

source

function layer_door(x: number, y: number)

x: number
y: number

Short for spawn_layer_door.

spawn

source

-- spawn a jetpack next to the player
spawn(ENT_TYPE.ITEM_JETPACK, 1, 0, LAYER.PLAYER, 0, 0)

function spawn(entity_type: ENT_TYPE, x: number, y: number, layer: LAYER, vx: number, vy: number): integer

entity_type: ENT_TYPE
x: number
y: number
layer: LAYER
vx: number
vy: number

Returns integer

Short for spawn_entity.

spawn_apep

source

function spawn_apep(x: number, y: number, layer: LAYER, right: boolean): integer

x: number
y: number
layer: LAYER
right: boolean

Returns integer

Spawns apep with the choice if it going left or right, if you want the game to choose use regular spawn functions with ENT_TYPE.MONS_APEP_HEAD

spawn_companion

source

function spawn_companion(companion_type: ENT_TYPE, x: number, y: number, layer: LAYER): integer

companion_type: ENT_TYPE
x: number
y: number
layer: LAYER

Returns integer

Spawn a companion (hired hand, player character, eggplant child)

spawn_critical

source

function spawn_critical(entity_type: ENT_TYPE, x: number, y: number, layer: LAYER, vx: number, vy: number): integer

entity_type: ENT_TYPE
x: number
y: number
layer: LAYER
vx: number
vy: number

Returns integer

Short for spawn_entity_nonreplaceable.

spawn_door

source

function spawn_door(x: number, y: number, layer: LAYER, w: integer, l: integer, t: integer): integer

x: number
y: number
layer: LAYER
w: integer
l: integer
t: integer

Returns integer

Spawn a door to another world, level and theme and return the uid of spawned entity. Uses level coordinates with LAYER.FRONT and LAYER.BACK, but player-relative coordinates with LAYER.PLAYERn

spawn_entity

source

-- spawn megajelly on top of player using absolute coordinates on level start
set_callback(function()
    local x, y, layer = get_position(players[1].uid)
    spawn_entity(ENT_TYPE.MONS_MEGAJELLYFISH, x, y+3, layer, 0, 0)
end, ON.LEVEL)

-- spawn clover next to player using player-relative coordinates
set_callback(function()
    spawn(ENT_TYPE.ITEM_PICKUP_CLOVER, 1, 0, LAYER.PLAYER1, 0, 0)
end, ON.LEVEL)

function spawn_entity(entity_type: ENT_TYPE, x: number, y: number, layer: LAYER, vx: number, vy: number): integer

entity_type: ENT_TYPE
x: number
y: number
layer: LAYER
vx: number
vy: number

Returns integer

Spawn an entity in position with some velocity and return the uid of spawned entity. Uses level coordinates with LAYER.FRONT and LAYER.BACK, but player-relative coordinates with LAYER.PLAYER(n), where (n) is a player number (1-4).

spawn_entity_nonreplaceable

source

function spawn_entity_nonreplaceable(entity_type: ENT_TYPE, x: number, y: number, layer: LAYER, vx: number, vy: number): integer

entity_type: ENT_TYPE
x: number
y: number
layer: LAYER
vx: number
vy: number

Returns integer

Same as spawn_entity but does not trigger any pre-entity-spawn callbacks, so it will not be replaced by another script

spawn_entity_over

source

function spawn_entity_over(entity_type: ENT_TYPE, over_uid: integer, x: number, y: number): integer

entity_type: ENT_TYPE
over_uid: integer
x: number
y: number

Returns integer

Spawn an entity of entity_type attached to some other entity over_uid, in offset x, y

spawn_entity_snapped_to_floor

source

function spawn_entity_snapped_to_floor(entity_type: ENT_TYPE, x: number, y: number, layer: LAYER): integer

entity_type: ENT_TYPE
x: number
y: number
layer: LAYER

Returns integer

Spawns an entity directly on the floor below the tile at the given position. Use this to avoid the little fall that some entities do when spawned during level gen callbacks.

spawn_grid_entity

source

function spawn_grid_entity(entity_type: ENT_TYPE, x: number, y: number, layer: LAYER): integer

entity_type: ENT_TYPE
x: number
y: number
layer: LAYER

Returns integer

Spawn a grid entity, such as floor or traps, that snaps to the grid.

spawn_layer_door

source

function spawn_layer_door(x: number, y: number)

x: number
y: number

Spawn a door to backlayer.

spawn_liquid

source

function spawn_liquid(entity_type: ENT_TYPE, x: number, y: number)

entity_type: ENT_TYPE
x: number
y: number

function spawn_liquid(entity_type: ENT_TYPE, x: number, y: number, velocityx: number, velocityy: number, liquid_flags: integer, amount: integer)

entity_type: ENT_TYPE
x: number
y: number
velocityx: number
velocityy: number
liquid_flags: integer
amount: integer

function spawn_liquid(entity_type: ENT_TYPE, x: number, y: number, velocityx: number, velocityy: number, liquid_flags: integer, amount: integer, blobs_separation: number)

entity_type: ENT_TYPE
x: number
y: number
velocityx: number
velocityy: number
liquid_flags: integer
amount: integer
blobs_separation: number

Spawn liquids, always spawns in the front layer, will have fun effects if entity_type is not a liquid (only the short version, without velocity etc.). Don't overuse this, you are still restricted by the liquid pool sizes and thus might crash the game. liquid_flags - not much known about, 2 - will probably crash the game, 3 - pause_physics, 6-12 is probably agitation, surface_tension etc. set to 0 to ignore amount - it will spawn amount x amount (so 1 = 1, 2 = 4, 3 = 6 etc.), blobs_separation is optional

spawn_mushroom

source

function spawn_mushroom(x: number, y: number, l: LAYER): integer

x: number
y: number
l: LAYER

Returns integer

function spawn_mushroom(x: number, y: number, l: LAYER, height: integer): integer

x: number
y: number
l: LAYER
height: integer

Returns integer

Spawns and grows mushroom, height relates to the trunk, without it, it will roll the game default 3-5 height Regardless, if there is not enough space, it will spawn shorter one or if there is no space even for the smallest one, it will just not spawn at all Returns uid of the base or -1 if it wasn't able to spawn

spawn_on_floor

source

function spawn_on_floor(entity_type: ENT_TYPE, x: number, y: number, layer: LAYER): integer

entity_type: ENT_TYPE
x: number
y: number
layer: LAYER

Returns integer

Short for spawn_entity_snapped_to_floor.

spawn_over

source

function spawn_over(entity_type: ENT_TYPE, over_uid: integer, x: number, y: number): integer

entity_type: ENT_TYPE
over_uid: integer
x: number
y: number

Returns integer

Short for spawn_entity_over

spawn_player

source

function spawn_player(player_slot: integer, x?: number, y?: number, layer?: LAYER): integer

player_slot: integer
x?: numberoptional
y?: numberoptional
layer?: LAYERoptional

Returns integer

Spawn a player in given location, if player of that slot already exist it will spawn clone, the game may crash as this is very unexpected situation If you want to respawn a player that is a ghost, set in his Inventory health to above 0, and time_of_death to 0 and call this function, the ghost entity will be removed automatically

spawn_playerghost

source

function spawn_playerghost(char_type: ENT_TYPE, x: number, y: number, layer: LAYER): integer

char_type: ENT_TYPE
x: number
y: number
layer: LAYER

Returns integer

Spawn the PlayerGhost entity, it will not move and not be connected to any player, you can then use steal_input and send_input to control it or change it's player_inputs to the input of real player so he can control it directly

spawn_tree

source

function spawn_tree(x: number, y: number, layer: LAYER): integer

x: number
y: number
layer: LAYER

Returns integer

function spawn_tree(x: number, y: number, layer: LAYER, height: integer): integer

x: number
y: number
layer: LAYER
height: integer

Returns integer

Spawns and grows a tree

spawn_unrolled_player_rope

source

function spawn_unrolled_player_rope(x: number, y: number, layer: LAYER, texture: TEXTURE): integer

x: number
y: number
layer: LAYER
texture: TEXTURE

Returns integer

function spawn_unrolled_player_rope(x: number, y: number, layer: LAYER, texture: TEXTURE, max_length: integer): integer

x: number
y: number
layer: LAYER
texture: TEXTURE
max_length: integer

Returns integer

Spawns an already unrolled rope as if created by player