Collectibles & Surfaces

Collectibles are items the player can pick up. Surfaces are interactive terrain the player can stand on, jump from, or climb. All positions are in logical pixels (400×300 space).

Collectibles

Coin

File: src/collectibles/coin.c / coin.h
Sprite: assets/sprites/collectibles/coin.png — 16×16 px display size
Pickup: AABB overlap with player. Plays gs->audio.coin on collection.

[[coins]]
x = 46.0
y = 236.0   # top edge in logical pixels

With defaults, every 1000 points (10 coins) earns a bonus life. Both coin_score and score_per_life are configurable in the level file.

Collected coins stay gone for the whole attempt. Losing a life respawns enemies, hazards, surfaces and stars, but not coins: score and the bonus-life threshold survive a death, so returning coins would let a player farm points and lives by dying on purpose. Coins come back only for a fresh attempt — Retry after game over, Replay, or loading a level — and the completion summary counts every coin collected during the attempt. Health stars and the last star do respawn after a life loss: they award no score, so each life simply meets the healing the level was designed with.

Star Yellow

File: src/collectibles/health_star.c / health_star.h (shared by all three star colours)
Sprite: assets/sprites/collectibles/star_yellow.png — 16×16 px display size
Pickup: AABB overlap. Restores 1 heart (up to MAX_HEARTS, 3). No score awarded.

The three colours are one collectible: a single HealthStar struct, health_stars_render() and health_star_get_hitbox(), and one collect_health_stars() loop in src/collision/game_collision.c. The level file and GameState still keep a separate array and texture per colour.

[[star_yellows]]
x = 272.0
y = 108.0

Star Green

File: src/collectibles/health_star.c / health_star.h (same HealthStar module as yellow; MAX_STAR_GREENS 16)
Sprite: assets/sprites/collectibles/star_green.png — 16×16 px
Pickup: Same as star yellow — restores 1 heart.

[[star_greens]]
x = 500.0
y = 80.0

Star Red

File: src/collectibles/health_star.c / health_star.h (same HealthStar module as yellow; MAX_STAR_REDS 16)
Sprite: assets/sprites/collectibles/star_red.png — 16×16 px
Pickup: Same as star yellow — restores 1 heart.

[[star_reds]]
x = 800.0
y = 100.0

Last Star

File: src/collectibles/last_star.c / last_star.h
Sprite: assets/sprites/collectibles/last_star.png
Display size: 24×24 px
Pickup: Collecting it sets collected = 1, snapshots the level-completion summary, and shows the completion overlay. With next_phase, terminal actions are Next Level, Replay, Level Select, and Exit; otherwise they are Replay, Level Select, and Exit. Up/Down or D-pad changes focus, Enter/Space/Start (or A) confirms, and Esc/Back (or B) exits. Only one instance per level, defined with [last_star].

[last_star]
x = 1492.0
y = 100.0

Surfaces

Platform (Ground Pillar)

File: src/surfaces/platform.c / platform.h
Sprite: assets/sprites/levels/grass_platform.png by default, or the pillar’s own tile_path — 48×48 tile, 9-slice rendered
Behaviour: Static ground pillar. The player can land on the top surface. Pillars are positioned on the floor and extend upward, sunk 16 px into the ground. Rendered before the floor so the pillar base sinks into the ground naturally.

[[platforms]]
x           = 80.0   # left edge in logical pixels
tile_height = 2      # height in 48px tiles (1–5)
tile_width  = 1      # width in 48px tiles (0 or omitted = 1)

Top surface Y for a pillar: FLOOR_Y − (tile_height × TILE_SIZE) + 16 = 268 − (h × 48).

Float Platform

File: src/surfaces/float_platform.c / float_platform.h
Sprite: assets/sprites/surfaces/float_platform.png — 48×16 px, 3-slice (left cap | centre fill | right cap)
Behaviour: Hovering one-way surface. Player lands on the top face only (one-way collision — can jump through from below). Three modes:

[[float_platforms]]
mode       = "STATIC"   # "STATIC" | "CRUMBLE" | "RAIL"
x          = 172.0
y          = 200.0
tile_count = 4          # width in 16px pieces (1–16)
rail_index = 0          # RAIL mode only: index into [[rails]]
t_offset   = 0.0        # RAIL mode only: starting position on rail
speed      = 0.0        # RAIL mode only: traversal speed in tiles/s

Bridge

File: src/surfaces/bridge.c / bridge.h
Sprite: assets/sprites/surfaces/bridge.png — 16×16 px brick tile
Behaviour: Tiled crumble walkway. Each brick under the player’s centre starts its own timer on first contact and falls BRIDGE_FALL_DELAY later, so only the bricks the player actually steps on drop, creating a time-limited path. Fallen bricks stay gone until the level resets after a life loss (or a fresh attempt).

Bricks do not cascade on their own: each brick falls only after the player steps on it.

[[bridges]]
x           = 1350.0
y           = 172.0
brick_count = 8   # number of 16×16 brick tiles (1–16)

Bouncepad

File: src/surfaces/bouncepad.c / bouncepad.h
Sprites: bouncepad_small.png, bouncepad_medium.png (wood), bouncepad_high.png
Sheet: 144×48 px, 3 columns × 1 row — Frame 0: extended, Frame 1: mid-compress, Frame 2: compressed (default idle state)
Behaviour: Spring pad that launches the player upward on landing. Plays a 3-frame squash/release animation (2→1→0, 80 ms/frame) then resets to idle. The small, medium and high pads stay in their three GameState arrays; player_update receives them as BouncepadList views (pointer + count) and reports the landed pad as a flat index across the lists, so nothing is copied per frame.

[[bouncepads_small]]
x         = 734.0
launch_vy = -380.0
pad_type  = "GREEN"

[[bouncepads_medium]]
x         = 310.0
launch_vy = -536.2
pad_type  = "WOOD"

[[bouncepads_high]]
x         = 1420.0
launch_vy = -700.0
pad_type  = "RED"

Rail

File: src/surfaces/rail.c / rail.h
Sprite: assets/sprites/surfaces/rail.png — 64×64 px, 4×4 grid of 16×16 bitmask tiles
Behaviour: A path of interconnected tiles that spike blocks and float platforms ride along. Each tile has a bitmask of connection directions (N/E/S/W) that drives the correct sprite selection. Objects riding a rail store a float t ∈ [0, tile_count) and call rail_get_world_pos() each step. w and h are 2–128 tiles and a RECT loop has at most 128 tiles. At an open (HORIZ) end without a cap, a spike block detaches and falls; float platforms always bounce.

[[rails]]
layout  = "RECT"   # "RECT" = closed rectangle | "HORIZ" = open horizontal line
x       = 444      # top-left tile x
y       = 35       # top-left tile y
w       = 10       # width in tiles
h       = 6        # height in tiles
end_cap = 0        # HORIZ only: 0 = open end (spike block detaches), 1 = bouncing end

Vine

File: src/surfaces/vine.c / vine.h
Sprites: assets/sprites/surfaces/vine_green.png, assets/sprites/surfaces/vine_brown.png — 16×48 px per tile
Behaviour: Press Up while overlapping to grab (without holding Jump), then Up/Down to climb and Left/Right to drift. Jump dismounts; leaving the grab area also detaches.

[[vines]]
x          = 88.0
y          = 172.0   # top tile y in logical pixels
tile_count = 2       # cropped height = 32 + (tile_count - 1) * 19 = 51 px
vine_type  = 0       # optional art variant: 0 = green, 1 = brown

For every climbable, tile_count is at least 1 and the whole stack must fit inside the world.

Ladder

File: src/surfaces/ladder.c / ladder.h
Sprite: assets/sprites/surfaces/ladder.png
Behaviour: Uses the same Up-to-grab, Up/Down climb, horizontal drift and Jump-to-dismount controls as vines.

[[ladders]]
x          = 1552.0
y          = 0.0       # top tile y
tile_count = 30        # height in tiles

Rope

File: src/surfaces/rope.c / rope.h
Sprite: assets/sprites/surfaces/rope.png
Behaviour: Same interaction model as the vine: Up to grab, Up/Down to climb, Left/Right to drift, and Jump to dismount. There is no rope-swing simulation.

[[ropes]]
x          = 460.0
y          = 172.0
tile_count = 1