Player Module

The player module is split across focused files under src/player/. player.h is the public API; player_internal.h holds private sprite/hitbox constants shared by implementation files.

Lifecycle at a Glance

player_init
  ├── IMG_LoadTexture("assets/sprites/player/player.png")
  ├── 48x48 frame setup from 192x288 sheet (4 cols x 6 rows)
  ├── default spawn (overridden by LevelDef)
  └── player_apply_default_physics

per frame
  ├── player_handle_input        -> move_dir, run, jump/climb intent
  ├── player_update              -> jump buffer, motion, gravity, collisions, animation
  ├── player_render              -> draw current frame with camera offset
  └── player_get_hitbox          -> inset AABB for damage/collision checks

player_reset                     -> restore spawn/state; keep texture + tunable physics
player_cleanup                   -> SDL_DestroyTexture

Public API

int player_init(Player *player, SDL_Renderer *renderer);
void player_apply_default_physics(Player *player);
void player_handle_input(Player *player, Mix_Chunk *snd_jump,
                         SDL_GameController *ctrl,
                         const VineDecor *vines, int vine_count,
                         const LadderDecor *ladders, int ladder_count,
                         const RopeDecor *ropes, int rope_count);
void player_update(Player *player, float dt, Mix_Chunk *snd_jump,
                   const Platform *platforms, int platform_count,
                   const FloatPlatform *float_platforms, int float_platform_count,
                   const Bouncepad *bouncepads, int bouncepad_count,
                   const VineDecor *vines, int vine_count,
                   const LadderDecor *ladders, int ladder_count,
                   const RopeDecor *ropes, int rope_count,
                   const Bridge *bridges, int bridge_count,
                   const SpikePlatform *spike_platforms, int spike_platform_count,
                   const int *floor_gaps, int floor_gap_count,
                   int *out_bounce_idx,
                   int *out_fp_landed_idx,
                   int prev_fp_landed_idx,
                   int world_w);
void player_render(Player *player, SDL_Renderer *renderer, int cam_x);
SDL_Rect player_get_hitbox(const Player *player);
void player_reset(Player *player);
void player_cleanup(Player *player);

Initialization

player_init returns 0 after loading the required player texture and -1 if the texture cannot be loaded, allowing game_init to clean up the partially initialized runtime.

Default display size is 48×48 logical pixels. PLAYER_FLOOR_SINK = 16 sinks the frame into the floor to compensate for transparent sprite padding.

Movement Physics

Current movement uses acceleration and friction, not instant velocity reset.

LevelDef.physics can override these values; -1.0 keeps engine defaults and 0.0 is a valid override. See Level Design — TOML Reference for the complete [physics] table syntax, including camera lookahead overrides.

Jumping

player_update receives snd_jump so buffered/coyote jumps can play the same guarded jump sound as direct jumps.

Climbables

The same climb state supports vines, ladders, and ropes.

Player.climb_source identifies the active climbable type: 0 = vine, 1 = ladder, 2 = rope.

Animation

player_animation.c selects an AnimState, then maps it to a linear frame index on the 4-column sheet.

Walk animation starts only when horizontal velocity exceeds WALK_ANIM_MIN_VX = 8.0f; this avoids foot-shuffling during tiny acceleration/friction speeds.

Hitbox

r.x = (int)player->x + PLAYER_PHYS_PAD_X;
r.y = (int)player->y + PLAYER_PHYS_PAD_TOP;
r.w = player->w - 2 * PLAYER_PHYS_PAD_X;
r.h = player->h - PLAYER_PHYS_PAD_TOP - PLAYER_FLOOR_SINK;

Sprite analysis confirms the art envelope fits this inset: visible art is roughly 18×16 px inside the 48×48 frame.