Game API¶

The game object is the global bridge for Lua scripts. It exposes the current script context, frame state, entity lookup, free-slot lookup, music scheduling, clock control, wave control, and pack hashes.

The cinematic acquisition, event state, helper initialization, and selective controller/animation APIs are documented in Script-owned cinematics.

Context Properties¶

Property	Type	Read/Write	Internal source	Notes
this_character	Character	read	Current player or enemy object ID	nil for standalone item scripts.
this_player	Player	read	Current player object ID	nil unless the script is running for a player.
this_enemy	Enemy	read	Current enemy object ID	nil unless the script is running for an enemy.
this_item	Item	read	Current item object ID	Valid for standalone item scripts. Not used for player/enemy scripts because their item state is flattened on this_character.
pickup_item	Item or nil	read	Item being collected	Set only while an item's pickupScript runs. this_player is the prospective collector.
is_current_player	bool	read	Current context ID	True for player updates.
is_current_enemy	bool	read	Current context ID	True for enemy updates.

State Properties¶

Property	Type	Read/Write	Meaning
current_frame	int	read	Current frame in the simulation update.
global_timer	int	read	Total elapsed game timer.
level_id	int	read	Current level ID.
scene_id	int	read	Current scene or wave ID.
is_in_slow_motion	bool	read	True while slow motion is active.
slow_motion_frames_left	int	read/write	Remaining slow-motion frames. Setting this directly is equivalent to changing the game state timer.
number_of_active_enemies	int	read	Active enemies, including enemies that may not be alive.
number_of_alive_enemies	int	read	Alive enemies according to enemy health/state checks. Enemy count multiplier copies of spawn_scene_enemy spawns are left out, but it is never 0 while one is alive (see stages).
number_of_free_sub_items	int	read	Available sub-item effect slots.

Stage control¶

See Scripted stages for hook timing, units, rollback and visual isolation.

API	Access	Meaning
custom_value_1 .. custom_value_16	read/write	Signed integers saved in game snapshots; persist across scenes and levels.
scripted_camera	read/write	Bypass automatic camera scrolling while true.
camera_x, camera_y	read/write	Viewport position in pixels, positive right/down.
screen_width	read	Current playable width in pixels.
half_playable_extra_width	read	Half of the extra width widescreen adds on each side of the classic 320-pixel view (40 with widescreen on, 0 with it off), scaled like screen_width for the current level. Add it to classic-layout X positions to keep them centred: screen_width is the classic width plus twice this value.
difficulty_index	read	Zero-based difficulty index.
has_instant_spawns	read	The custom game "instant spawns" setting. Scripted stages pace their own spawns: honour it by dropping spawn delays.
has_ninpo_kage_bunshin	read	The Ninpo Kage Bunshin game mode: each player trails three shadow clones showing where it was 5, 10 and 15 frames ago. A script that runs its own player attacks can attack from those positions too.
enemies_multiplier	read	The custom game enemy count multiplier, 1 to 8. The engine doubles stage spawns itself; a script that runs its own enemies applies it on its own.
enemies_velocity_numerator	read	Numerator of the enemy speed multiplier in effect (the custom game setting, otherwise the difficulty's). Scale a per-tick movement by numerator / denominator.
enemies_velocity_denominator	read	Denominator of the enemy speed multiplier, at least 1.
enemy_capacity	read	Number of enemy slots; first enemy object ID is 4.
scene_enemies_cleared	read	All scene enemy loadcues consumed, spawn delay elapsed, no active enemies. With scriptedEnemies, only active enemies count.
spawn_scene_enemy(index)	method returning int	Spawn one enemies1 cue in a scriptedEnemies scene; enemy object ID or -1.
spawn_scene_item(index)	method returning int	Spawn one items cue in a scriptedItems scene; item/sub-item ID or -1. Camera filtering and automatic cursors are bypassed.
change_scene(index)	method returning bool	Start normal entrance for a zero-based scene in the current level. Return immediately after a successful request.
complete_scene()	method returning bool	Leave the current scene through its sceneExitCodeId exit (walk/fade or stage clear), then enter the next scene normally. False outside active gameplay, so repeated calls cannot restart the transition. Prefer it to advance_wave()/advance_level() when the exit presentation must play; see Scripted stages.

For read-only camera-path queries, temporary art presentation, cinematic fades and an existing-actor view mask, see stage presentation. These APIs keep the live gameplay level and wave intact.

Lookup Methods¶

Method	Returns	Detail
get_player(id)	Player or nil	Returns nil for negative IDs. Throws if a non-negative ID is not a player ID.
get_enemy(id)	Enemy or nil	Returns nil for negative IDs. Throws if a non-negative ID is not an enemy ID.
get_character(id)	Character or nil	Resolves player or enemy IDs. Logs a warning and returns nil for item/sub-item IDs.
get_item(id)	Item or nil	Returns nil for negative IDs. Throws if a non-negative ID is not an item ID.
get_sub_item(id)	SubItem or nil	Returns nil for negative IDs. Throws if a non-negative ID is not a sub-item ID.
get_free_enemy(consider_players_count)	Enemy or nil	Finds the first available enemy slot. The optional argument defaults to true.
get_free_item()	Item or nil	Finds the first available item slot.
get_free_sub_item()	SubItem or nil	Finds the first available sub-item slot.
get_entity(id)	Player, Enemy, Item, SubItem or nil	Resolves any object ID to its actual wrapper; nil for invalid IDs. See Script-owned cinematics.

Object IDs are laid out by range: players first, then enemies from ID 4 (enemy_capacity slots), then items, then sub-items.

Property	Type	Meaning
first_item_id	int	Object ID of the first item slot. IDs below it are characters (players and enemies), so id < game.first_item_id tells a character hit from an item hit (see check_projectile_hit_target() in the Item API).
item_capacity	int	Number of item slots, starting at first_item_id.
first_sub_item_id	int	Object ID of the first sub-item slot.
sub_item_capacity	int	Number of sub-item (render-only effect) slots, starting at first_sub_item_id.

Use get_character for attacker and victim IDs. Use specific lookups only when you know the ID range.

Game Control Methods¶

Method	Returns	Detail
set_clock(seconds)	nil	Stores the timer as seconds * 100 internally.
clock_value	int	Read-only remaining whole seconds. With scriptedClock, use this with set_clock() to implement a custom countdown.
reset_clock()	nil	Resets the level timer through the game controller.
set_slow_motion(frames)	nil	Sets slow_motion_frames_left.
schedule_go_forward_effect()	nil	Schedules the "GO!" indicator.
random(range)	int	Returns 0..range-1 from the game's deterministic RNG (the same sequence enemy AI uses, so it is replay and netplay safe). range is 2–65535; smaller values return 0.
schedule_quake(amplitude_pixels, duration_frames)	nil	Schedules a fixed-amplitude alternating playfield quake for the current entity. Amplitude is 1–8 pixels and duration is 1–600 display frames; invalid values or a missing entity context are ignored. Schedule any accompanying sound separately.
schedule_music(music_name, pack_name)	nil	Queues background music. If pack_name is omitted or nil, the current game pack is used.
is_next_wave_non_scrolling()	bool	True when the next wave does not require scrolling.
get_number_of_active_players()	int	Counts active player slots.
kill_all_enemies(exception_id)	nil	Defeats all active enemies except the optional object ID. Defaults to no exception.
advance_level()	nil	Advances to the next level. Skips the next level's scene initialisation when called from Lua: use complete_scene() on the last scene, with a stage-clear exit, instead.
advance_wave()	nil	Advances to the next scene/wave.
get_potential_score()	int	Calculates current potential score from game state.
update_alternative_palette()	nil	Reapplies alternative palette rules.
get_pack_hash(pack_name)	int	Returns the runtime hash used by engine data for a pack name.

Cinematics and scene flow¶

These game members are documented with the systems they drive:

Members	Documented in
begin_cinematic(pack_name, script_name, owner_id, max_ticks), end_cinematic(keep_camera), is_cinematic, cinematic_tick, cinematic_owner_id	Script-owned cinematics
get_cinematic_value(index), set_cinematic_value(index, value), is_cinematic_actor(id)	Script-owned cinematics
update_entity_controller(id), update_entity_animation(id), schedule_cinematic_quake(amplitude, frames)	Script-owned cinematics
get_entity(id), first_item_id, item_capacity, first_sub_item_id, sub_item_capacity	Script-owned cinematics and the lookup tables above
get_scene_camera_path(level_id, scene_id), get_previous_presentation(level_id, scene_id), get_previous_known_presentation(level_id, scene_id)	Stage presentation
set_cinematic_presentation(level_id, scene_id), set_cinematic_dark_presentation(), restore_cinematic_presentation(), cinematic_fade, cinematic_hide_existing_entities	Stage presentation
complete_scene(), change_scene(index), spawn_scene_enemy(index), spawn_scene_item(index), scene_enemies_cleared, scene hooks	Scripted stages

Example: Safe Wave End¶

return function()
    if game.number_of_alive_enemies == 0 then
        game.schedule_go_forward_effect()
        game.advance_wave()
    end

    return true
end

Example: Resolve A Stored Target¶

return function()
    local character = game.this_character

    if character == nil then
        return true
    end

    local target_id = character.custom_value_1

    if target_id >= 0 then
        local target = game.get_character(target_id)

        if target ~= nil and target.health > 0 then
            character.is_facing_right = target.position_x > character.position_x
        end
    end

    return true
end

game.schedule_music_fade(duration_frames) schedules a fade of the currently playing music. The duration uses 60 Hz host frames; zero stops immediately. It uses the normal music effect queue during rollback.