Player API¶

try_special_move() attempts a defensive or offensive special from the current input, using the same height, move availability and health/meter admission checks as native controls. It returns true only when the move starts. Use it for scripted cancels before releasing a victim or resetting state. A successful call also invokes the entity's specialMoveScript once, if present.

Player extends Character with human input state and player-specific timers. Because of flattening, a player also exposes character, item, and sub-item fields directly.

Identity And State¶

Property	Type	Read/Write	Detail
is_alive	bool	read	True when the player is active or can continue. Exact bridge name is IsAlive.
player_index	int	read	Player slot/object index.
character	Character	read	Same object, exposed for interface symmetry.
input_state	InputButtons	read/write	Raw input bitmask. Prefer boolean helpers unless you are deliberately editing raw input.
back_attack_pressed	bool	read/write	The back attack button's (X) smooth-controls replay: true on the frames after a press, while back_attack_spam_timer runs. It never reflects the classic controls back attack (attack and jump together); read back_attack_input_pressed for the back attack as the native standing move reads it.
is_special_attack_ready	bool	read	True when the player can use special attack logic.
is_selecting_game_over	bool	read/write	Game-over selection state.

Input Timers¶

Property	Type	Read/Write	Detail
special_spam_timer	int	read/write	Special input buffer/spam timer.
attack_spam_timer	int	read/write	Attack input buffer/spam timer.
jump_spam_timer	int	read/write	Jump input buffer/spam timer.
back_attack_spam_timer	int	read/write	Back attack input buffer/spam timer.
hold_direction_frames	int	read/write	Frames a direction has been held.
extra_delay_after_move	int	read/write	Extra delay state after a move.
hold_b_attack_timer	int	read/write	Held attack timer.
hold_b_attack_ready	bool	read/write	Held attack ready flag.
hold_b_release_timer	int	read/write	Held attack release timer.
hold_x_button_consumed	bool	read/write	Tracks whether hold-X input has already been consumed.

Held Inputs¶

Held input properties are true while the button or direction is held.

Property	Detail
is_holding_up	Up is held.
is_holding_down	Down is held.
is_holding_left	Absolute left is held.
is_holding_right	Absolute right is held.
is_holding_forward	Direction the player is facing is held.
is_holding_backward	Opposite of facing direction is held.
is_holding_button_a	Special button is held.
is_holding_button_b	Attack button is held.
is_holding_button_c	Jump button is held.
is_holding_button_x	X button is held (back attack).
is_holding_button_y	Y button is held (pick-up / contextual action).
is_holding_button_z	Z button is held (super move).

forward and backward are computed from is_facing_right. If the player is facing right, forward means right; if facing left, forward means left.

Pressed Inputs¶

Pressed input properties are true only on the frame the input was pressed.

Property	Detail
pressed_up	Up was just pressed.
pressed_down	Down was just pressed.
pressed_forward	Forward was just pressed relative to facing direction.
pressed_backward	Backward was just pressed relative to facing direction.
pressed_button_a	Special was just pressed.
pressed_button_b	Attack was just pressed.
pressed_button_c	Jump was just pressed.
pressed_button_z	Z button was just pressed (super move).
pick_up_pressed	The pick up input was just pressed, as the native standing move reads it for this player's controls setting: the pick up button (Y) with modern controls, attack with classic (three button) controls. Use it before check_pick_up_item() so a scripted player picks up like the native ones.
back_attack_input_pressed	The back attack input, as the native standing move reads it for this player's controls setting: the back attack button (X) with modern controls, attack and jump held together with classic (three button) controls. A held input stays true until the move that uses it sets hold_x_button_consumed = true (the native back attack does), and is false again until it is released. Use it, rather than back_attack_pressed, for a scripted standing back attack.
held_weapon_input	What this frame's inputs ask of the held weapon, as the native standing move reads them: 0 nothing, 1 throw it (attack and jump together, or the back attack with attack or jump held, in classic controls; the pick up button with a direction held; never a melee only weapon), 2 the pick up button alone: pick up an item, or drop the weapon if there is none. 0 without a weapon.

Previous Held Input¶

Property	Type	Read/Write	Detail
previous_held_buttons	HoldInputButtons	read/write	Previous-frame held input bitmask.
previous_held_buttons2	HoldInputButtons	read/write	Secondary previous held input bitmask.
was_previously_holding_left	bool	read/write	Previous-frame left state.
was_previously_holding_right	bool	read/write	Previous-frame right state.
last_tap_was_right	bool	read/write	Direction of last tap.

Air-control scripts often clear previous_held_buttons after applying an initial tap impulse, so the impulse is not applied repeatedly.

Methods¶

has_input_combo(combo_string)¶

Checks recent input history. Existing logic events use strings like "v>b"; scripts may also use readable comma-separated sequences where supported by the input-chain parser.

if player.has_input_combo("v>b") then
    player.set_animation(46)
    return false
end

check_grab_while_moving()¶

Runs the original grab-while-moving logic. Use in custom walking or dash states that still need normal grab contact.

safe_land()¶

Returns the player to the safe standing/landing state through knockout move cleanup logic.

respawn()¶

Respawns the player in the current scene.

update_position_and_check_world_collisions()¶

Players override the item implementation and use the player world-collision helper. Returns true when vertical or horizontal collision occurred.

Example: Consume A Defensive Input¶

return function()
    local player = game.this_player

    if player == nil then
        return true
    end

    if player.is_holding_button_x and not player.hold_x_button_consumed then
        player.hold_x_button_consumed = true
        player.set_animation(40)
        return false
    end

    return true
end

Example: Absolute And Relative Direction¶

return function()
    local player = game.this_player

    if player == nil then
        return true
    end

    -- Absolute direction changes facing.
    if player.is_holding_left then
        player.is_facing_right = false
    elseif player.is_holding_right then
        player.is_facing_right = true
    end

    -- Relative direction starts an attack in front of the player.
    if player.pressed_forward and player.pressed_button_b then
        player.set_animation(48)
        return false
    end

    return true
end