Item API¶

Item represents physical objects in the world: character bodies, weapons, containers, pickups, projectiles, and other interactive objects. It inherits the SubItem API, so animation fields are also available on items.

Position And Motion¶

Most position and motion values are converted by the bridge. The engine stores them multiplied by 1000; Lua reads and writes script units.

Property	Type	Read/Write	Detail
position_x	int	read/write	World X position.
position_y	int	read/write	World Y/depth position on the belt-scroller plane.
position_offset_x	int	read/write	Extra X offset used by some behaviours.
position_offset_y	int	read/write	Height offset from ground. Negative means airborne, 0 means grounded.
velocity_x	int	read/write	Per-frame X movement accumulator.
velocity_y	int	read/write	Per-frame Y/depth movement accumulator.
impulse_x	int	read/write	Horizontal impulse. Default physics adds this to velocity_x.
impulse_y	int	read/write	Vertical/height impulse. Default physics adds this to position_offset_y.
impulse_z	int	read/write	Depth impulse. Default physics adds this to velocity_y.
acceleration_x	int	read/write	Added to impulse_x after movement.
acceleration_y	int	read/write	Added to impulse_y after movement.
acceleration_z	int	read/write	Added to impulse_z after movement.
wall_thrown_flight	int	read/write	A throw's flight state for walls with a maxHeight (rails): 1 thrown but not yet airborne, 3 airborne, 2 landed while still in a thrown mode, 0 otherwise. The engine updates it every frame from the throw modes (0x10/0x12) and height; a body in state 3 is pushed over a rail it comes down on, one in state 1 is put back on the floor side. A script that throws a body itself can set 1 (or 3 when already airborne) to get the same rail behaviour.
is_in_the_air	bool	read	Pit-aware air check. True when position_offset_y < 0, while falling through a pit, or when there is no ground below.
unknownPosition4_62_66_X	int	read/write	Original engine position/scratch field. Use exact spelling.
unknownPosition4_62_66_Y	int	read/write	Original engine position/scratch field. Use exact spelling.

Collision And Body Data¶

Property	Type	Read/Write	Detail
collision_box_half_width	int	read	Current body box half-width. Exact bridge name is CollisionBoxHalfWidth.
collision_box_height	int	read	Current body box height.
collision_box_depth	int	read	Current body box depth.
last_hitbox_index	int	read/write	Last hitbox index used for collision checks. Reset when animation changes.
hit_pause_timer	int	read/write	Hit pause countdown. Default physics decrements it and exits early.
custom_hit_pause_delay_frames	int	read/write	Animation-frame delay after hit pause. The animation updater decrements this before advancing frames.
invincibility_timer	int	read/write	Timer used by invincibility logic.

Scripted attack policy¶

override_attack_damage = true uses attack_damage_override (non-negative) for authored character attack boxes. suppress_attack_hits = true suppresses those boxes entirely. Both character and container scans use the policy. It does not change projectile or throw damage. A script must clear the policy when it no longer applies; the value is saved in rollback state and reset on slot reuse.

Object Flags¶

These map to original status bits.

Property	Type	Read/Write	Detail
is_active	bool	read/write	Item/projectile active flag (status4 bit 7). Projectiles often clear this when switching to a hit animation. This is not an enemy existence test: normal enemy initialization leaves it clear. Use is_enabled and character health/state when selecting enemies.
is_obstacle	bool	read/write	Blocks movement as an obstacle.
effect_players_only	bool	read/write	Effect applies only to players.
has_weapon	bool	read/write	Character is holding a weapon.
weapon	Item	read	Held item if has_weapon and held_item_id are valid.
is_being_thrown	bool	read/write	Throw initiation flag.
can_land_safely	bool	read/write	Landing can return to a safe state.
is_jump_down_attack	bool	read/write	Jump-down attack status.
has_double_forward_tap	bool	read/write	Double-forward input status. Useful to clear when consuming dash-style inputs.
is_lying_on_the_floor	bool	read/write	Floor/lying status.
did_move_ended	bool	read/write	Move-ended status. Name follows the bridge field.
is_jump_attack	bool	read/write	Jump attack status.
is_blocking	bool	read/write	Blocking status.
is_vulnerable	bool	read/write	Can be hit.
is_knocked_down	bool	read/write	Knockdown status.
is_grabbing	bool	read/write	Currently grabbing another character.
is_being_grabbed	bool	read/write	Currently grabbed by another character.
is_attacking	bool	read/write	Attack status.
is_being_hit	bool	read/write	Hit reaction status.
is_hitting_something	bool	read/write	Low-level hit flag. Character also exposes is_hitting_someone.
was_hit_from_right	bool	read/write	Direction of the last incoming hit.

Weapon, Container, And Timers¶

Property	Type	Read/Write	Detail
contained_item_pack_hash	int	read/write	Pack hash for an item contained by a container.
contained_item_entity_id	int	read/write	Entity type/id for contained item.
held_item_id	int	read/write	Object ID of held item.
weapon_health	int	read/write	Remaining durability of a weapon whose logic sets weaponHealth above 0; reading starts it at that configured budget on first use. Writes are clamped to 0 or more; lowering it while a player holds the weapon shows the usage indicator, and the weapon breaks when an attack ends with it at 0. Weapons without a configured weaponHealth do not use it (they keep the classic drop counter).
inside_for_two_players_only	bool	read/write	Container/item rule for two-player-only contents.
mode_specific_timer	int	read/write	Behaviour-mode timer.
grab_combo_count	int	read/write	Grab combo counter.
kill_count	int	read/write	Kill counter used by some behaviours.
grenadeVelocity_78	int	read/write	Original grenade-specific velocity field. Use exact spelling.
inner_timer	int	read/write	Generic inner timer. Projectiles use this as lifetime.
customDamage_28	int	read/write	Original custom damage field. Use exact spelling.
requested_knockdown_attack	bool	read/write	Requests knockdown attack handling.

Projectile Fields¶

Property	Type	Read/Write	Detail
projectile_damage	int	read/write	Damage for projectile hit checks.
projectile_hit_pause	int	read/write	Hit pause applied by projectile hits.
projectile_hit_sound_hash	int	read/write	Runtime hash of projectile hit sound; -1 makes the hit silent, 0 uses the entity's projectileHitSoundName.
projectile_hit_sound_pack_hash	int	read/write	Runtime hash of sound pack.
projectile_hit_sound_channel	int	read/write	Audio channel for projectile hit sound.

Methods¶

check_projectile_hits()¶

Runs projectile hit detection if is_active is true. Returns true when a hit was detected. Projectile scripts commonly use this result to decide whether to switch to an impact animation.

check_projectile_hit_target()¶

Runs the same active-projectile collision/damage pass as check_projectile_hits(), returning the hit entity ID or -1 for no hit. Character IDs are below game.first_item_id; container hits return item IDs. Use this instead of the boolean method when a projectile should react differently to characters and containers. Do not call both methods for the same collision pass.

is_pressing_against_containers()¶

Checks collision pressure against containers.

has_ground_below()¶

Pit-aware ground check. Use this for landing checks in custom aerial scripts; when an item is over a pit, the function returns false even if position_offset_y has reached 0.

is_falling_through_pit()¶

Returns true when the item is in the falling-through-pit state — the item has been marked as currently falling into a pit zone. Use this to detect when a character or item is actively falling into a pit.

is_on_pit()¶

Returns true when the item's position is inside a pit shape region. Unlike is_falling_through_pit, this checks only whether the current position overlaps a pit shape, regardless of fall state. Useful for detecting proximity to pit zones even before falling begins.

is_on_treadmill()¶

Returns true when the item's position is inside a treadmill shape region. Treadmills apply velocity to grounded entities; this method lets scripts detect when the entity is over one.

is_on_custom_shape(shape_index)¶

Returns true when the item's position is inside a custom shape region. Pass 1 for Custom1 shapes or 2 for Custom2 shapes. These shapes have no built-in engine effect and are intended for script-defined gameplay logic.

try_spawn_item(pack, name, anim, mode, off_x, off_y, vel_x, vel_y, lifetime = 60, projectile_damage = 0, projectile_hit_pause = 0, hit_sound_name = nil, hit_sound_pack = nil, hit_sound_channel = 0)¶

Spawns an item or projectile using the caller as the source object.

Important internal details:

• pack is hashed with get_pack_hash.
• name is hashed as the entity name.
• anim is converted to the internal doubled animation ID.
• off_x, off_y, vel_x, and vel_y are converted to fixed-point units.
• The bridge negates the provided offsets and velocities before passing them to the engine. This matches the original spawn helper's coordinate convention.
• lifetime initializes projectile lifetime state.
• The optional projectile hit fields are copied into the spawned item.

try_spawn_enemy(pack, entity_id, animation_id, mode, off_x, off_y)¶

Spawns an enemy by entity ID/type using the caller as the source object. The current implementation passes animation_id directly to the enemy spawn helper, so use the value expected by the target data.

update_position_and_check_world_collisions()¶

Applies position updates and world collision checks through the enemy/world collision helper. Returns true when vertical or horizontal collision occurred.

Call this in scripts that return false and own their movement.

get_nearest_opponent(in_same_line, forward_check, backward_check)¶

Returns the nearest opponent character or nil.

• in_same_line: require compatible depth/body-box line.
• forward_check: allow targets in front of the object.
• backward_check: allow targets behind the object.

predict_frame_being_hit(frames_into_the_future)¶

Returns a prediction from the hit scanner for when this item would be hit within the requested future window. Useful for parry, guard, dodge, or counter windows.

is_knocked_down_and_near_ground¶

Read-only bool. True when the object is knocked down and close enough to the ground for landing/ground impact logic.

Example: Manual Projectile Loop¶

return function()
    local item = game.this_item

    if item == nil then
        return true
    end

    local should_destroy = item.check_projectile_hits()

    item.velocity_x = item.velocity_x + item.impulse_x
    item.velocity_y = item.velocity_y + item.impulse_z
    item.inner_timer = item.inner_timer - 1

    if item.inner_timer <= 0 then
        should_destroy = true
    end

    if item.update_position_and_check_world_collisions() then
        should_destroy = true
    end

    if should_destroy then
        item.set_animation(48)
        item.is_active = false
    end

    return false
end