Character API¶

Character represents shared player and enemy combat behavior. It inherits the Item API and SubItem API, so physics and animation fields are available directly on a character.

Identity And Health¶

Property	Type	Read/Write	Detail
`is_player`	`bool`	read	True for player characters.
`is_enemy`	`bool`	read	True for enemy characters.
`display_name`	`string`	read/write	Name shown by UI or combat displays.
`maximum_health`	`int`	read/write	Maximum health.
`previous_health`	`int`	read/write	Last recorded health.
`health`	`int`	read/write	Current health. Setting it also updates visual health for this character.
`lives`	`int`	read/write	Player lives, or remaining extra health bars for an enemy. An enemy with zero current health can still be alive when this is positive.
`continues`	`int`	read/write	Continue count where applicable.
`score`	`int`	read/write	Score, mainly useful for player characters.

Combat Links¶

Property	Type	Read/Write	Detail
`victim`	`Character`	read	Resolved `attacked_character_id`, or `nil`.
`attacker`	`Character`	read	Resolved `attacker_character_id`, or `nil`.
`attacked_character_id`	`int`	read/write	Object ID of the current victim. Use `-1` to clear.
`attacker_character_id`	`int`	read/write	Object ID of the current attacker. Use `-1` to clear.
`previousAttackedCharacterId_1`	`int`	read/write	Original combo/history slot. Use exact spelling.
`previousAttackedCharacterId_2`	`int`	read/write	Original combo/history slot. Use exact spelling.
`previousAttackedCharacterId_3`	`int`	read/write	Original combo/history slot. Use exact spelling.
`last_attacked_character_id`	`int`	read/write	Last attacked character.

When changing facing during active attacks, clear stale victim links if the old victim should no longer be treated as connected:

local victim = character.victim
if victim ~= nil then
    victim.attacker_character_id = -1
end
character.attacked_character_id = -1

Damage, Combo, And State¶

Property	Type	Read/Write	Detail
`damage_taken`	`int`	read/write	Damage from the last hit. Modify before applying custom health logic.
`auxiliar_velocity_x`	`int`	read/write	Knocked/thrown auxiliary X velocity. Name follows the bridge.
`unknownCounter_9A`	`int`	read/write	Original behaviour counter. Use exact spelling.
`is_static_grab_attack`	`bool`	read/write	Static grab attack state.
`combo_count`	`int`	read/write	Current combo count.
`combo_reset_timer`	`int`	read/write	Frames until combo reset.
`can_advance_combo_count`	`bool`	read/write	Whether combo count can advance.
`is_hitting_someone`	`bool`	read/write	Character-level hit flag.
`is_vaulting`	`bool`	read/write	Vaulting over an opponent.
`run_timer`	`int`	read/write	Run timing state.
`thrown_hit_count`	`int`	read/write	Count of hits caused while thrown.
`being_comboed_count`	`int`	read/write	Count used while this character is being comboed.

Hit And Grab Methods¶

Method	Returns	Detail
`check_being_hit_or_grabbed()`	bool	Runs hit and grab checks. Player default physics calls this with grab enforcement disabled; enemy default physics uses default enforcement.
`check_being_hit()`	bool	Runs hit checks and updates hit-related fields.
`check_being_grabbed()`	bool	Runs grab checks.
`check_hitting_entities()`	bool	Runs this character's attack hitboxes against possible victims. A player hits enemies and containers, and other players with friendly damage on. An enemy hits players, and other enemies and containers only with enemies infighting on.
`check_grab_enforcement()`	bool	Checks grab enforcement rules.
`try_grab(target, check_vicinity = false, enforcement = true, snap_to_victim = false, allow_airborne = false)`	bool	Attempts to grab another character. `target` can be a character object or object ID. Airborne targets remain excluded unless explicitly enabled; the script must check its move's height range. For script-owned aerial choreography, use `enforcement = false` and supply the throw animation/offsets. All other eligibility checks remain in effect.
`cancel_grab(return_to_standing = true)`	nil	Cancels current grab state.
`check_pick_up_item()`	bool	Checks item pickup logic.
`break_held_weapon()`	bool	Breaks the held weapon if its logic names a `brokenWeapon`: the held item becomes that entity and its `breakSound` plays. Call it after a hit made with the weapon. False when there is nothing to break.
`set_weapon(weapon_item_id)`	nil	Assigns a weapon item object ID. A weapon created by the script lasts three drops, as Classic enemies' weapons do, before it vanishes on landing.
`dispose_weapon()`	nil	Drops or disposes the current weapon through original logic.

Throw And Knockdown Methods¶

Method	Returns	Detail
`apply_throw(velocity_x, velocity_y, damage)`	nil	Releases a throw using throw data. `velocity_y` is converted to fixed-point units; `velocity_x` is passed as provided by the bridge method.
`check_thrown_knocking_other_characters()`	nil	Checks thrown-body collision against characters.
`check_thrown_knocking_items()`	nil	Checks thrown-body collision against containers/items.
`check_ground_bounce_effect(is_thrown_quake = false)`	nil	Runs ground bounce effect logic.
`apply_ground_bounce_effect(strength)`	nil	Applies screen/ground bounce strength.
`on_knockout_move_ended()`	nil	Runs cleanup when a knockout move ends.
`check_body_breaking_containers()`	bool	Checks body collision against breakable containers with extra width.

Movement And Physics Methods¶

Method	Returns	Detail
`set_animation(id, start_frame = 0)`	nil	Inherited from SubItem. Queues a new animation.
`apply_default_physics()`	bool	Runs local player or enemy default physics depending on the character type. Returns whether the physics step produced a blocking condition such as hit or hit connection.
`stop_movement()`	nil	Clears movement using the original character controller helper.
`copy_position_to(other_item_id, offset_x = 0, offset_y = 0)`	nil	Copies this character's item position to another item ID, applying offsets in script units.
`spawn_explosion(offset_x = 0, offset_y = 0, mode = 10, direction = 3)`	nil	Spawns an explosion effect at an offset.
`is_pressing_against_walls(include_screen_limits)`	bool	Checks walls and optionally screen limits.
`is_pressing_against_pits()`	bool	Checks pit borders (grounded pit boundary collision). Use this for the push-wall animation near pit edges.
`are_in_same_line(other_item_or_id)`	bool	Checks depth/body-line compatibility with another item or item ID.
`has_events()`	bool	True when the current animation has custom logic events.

Killer Mode¶

The custom game "killer enemies" setting (hasKillerEnemies) changes enemy attack animations (animations with hitboxes): their visual frames without a hitbox play for a single update, and an attack that hits a player (not blocking) restarts from frame 0 instead of knocking down. The engine applies this to animations it advances itself, including scripted enemies that only call set_animation. A script that times an attack's frames itself (writing current_animation_frame from its own counters) can honour it with these members:

Member	Returns	Detail
`is_killer_enemy`	bool	Read. Killer mode applies to this character's attacks (always false for players).
`killer_skips_frame(animation_id, frame)`	bool	True when killer mode shows the visual frame of attack animation `animation_id` that contains `frame` for a single update: killer mode applies, the animation has hitboxes and that visual frame has none.

A killer hit rewinds current_animation_frame to 0 during the hit check (apply_default_physics() or check_hitting_entities()); a script that sets the frame itself detects the restart by comparing the frame before and after the check:

local shown = e.current_animation_frame
if e.apply_default_physics() and shown ~= 0 and e.current_animation_frame == 0
    and e.is_killer_enemy then
    my_attack_frame = 0   -- restart the attack in the script's own timing
end

Score And UI Methods¶

Method	Returns	Detail
`add_score(points, update_visual_score = true)`	nil	Adds score and optionally updates score UI.
`update_visual_score()`	nil	Refreshes visual score.
`update_visual_health(other_object_id = -1, update_mutually = true, ignore_other = false)`	nil	Refreshes visual health.
`update_visual_health_of_other(other_object_id)`	nil	Refreshes another object's visual health.
`update_visual_lives()`	nil	Refreshes visual lives.
`distribute_score(score)`	nil	Distributes score to active players.
`distribute_score_based_on_damage(damage)`	nil	Distributes score using damage as input.
`check_combo_achievement(increment = 1)`	nil	Checks combo achievement logic.
`lose_life()`	bool	Runs lose-life logic.

Spawn Methods¶

Method	Returns	Detail
`try_spawn_item(...)`	bool	Inherited from Item. Spawns an item or projectile.
`try_spawn_shuriken(off_x, off_y, vel_x, vel_y, lifetime = 60)`	bool	Spawns a shuriken-style projectile using the original ninja helper. Unlike `try_spawn_item`, offsets and velocities are passed with the sign used by this helper.

Example: Custom Damage Reduction¶

return function()
    local character = game.this_character

    if character == nil then
        return true
    end

    if character.check_being_hit() then
        character.damage_taken = character.damage_taken / 2

        if character.damage_taken < 1 then
            character.damage_taken = 1
        end
    end

    return true
end