Assets

All visual assets live in the assets/ directory, organized into categorized subdirectories. Sprites are PNG files (loaded via SDL2_image), sounds are WAV files in assets/sounds/, and fonts are in assets/fonts/.

assets/
├── fonts/                  ← TrueType fonts
├── sounds/                 ← Audio files (see Sounds page)
│   ├── collectibles/
│   ├── entities/
│   ├── hazards/
│   ├── levels/
│   ├── player/
│   ├── screens/
│   ├── surfaces/
│   └── unused/
└── sprites/                ← PNG sprite sheets and textures
    ├── backgrounds/        ← Parallax background layers
    ├── collectibles/       ← Coins, stars
    ├── entities/           ← Enemy sprites
    ├── foregrounds/        ← Fog, water, lava, clouds
    ├── hazards/            ← Spike, saw, flame sprites
    ├── levels/             ← Level tilesets and themes
    ├── player/             ← Player sprite sheet
    ├── screens/            ← HUD, menu assets
    ├── surfaces/           ← Platforms, bridges, vines, etc.
    └── unused/             ← Reserve assets for future use

Coordinate note: All game objects use logical space (400x300). SDL scales to the 800x600 OS window 2x. A 48x48 sprite appears as 96x96 physical pixels on screen.

Per-Level Asset Configuration

Several visual elements are configurable per TOML level file, allowing different themes without changing code:

Floor Tile

floor_tile_path = "assets/sprites/levels/grass_tileset.png"

Any 48×48 PNG tile can be substituted here. The engine 9-slice renders it across FLOOR_Y to form the ground.

Parallax Background Layers

[[background_layers]]
path  = "assets/sprites/backgrounds/sky_blue.png"
speed = 0.0

[[background_layers]]
path  = "assets/sprites/backgrounds/glacial_mountains.png"
speed = 0.2

Layers are TOML array-of-tables and are drawn in array order (first = furthest back). speed is the parallax scroll factor: 0.0 = static sky, 1.0 = locks to camera, 0.1–0.5 = typical mid-ground parallax. Up to 8 layers are supported. See Level Design for the full list of available background images and suggested speeds.

Foreground Strip and Fog Layers

foreground_layers currently select the level foreground strip texture used by the water/lava renderer; the active runtime takes the last valid configured path. Atmospheric overlays are configured separately with fog_layers and loaded into the fog system.

[[foreground_layers]]
path  = "assets/sprites/foregrounds/water.png"
speed = 0.0

[[fog_layers]]
path = "assets/sprites/foregrounds/fog_1.png"

[[fog_layers]]
path = "assets/sprites/foregrounds/fog_2.png"

Currently Used Assets

Backgrounds — assets/sprites/backgrounds/

Foregrounds — assets/sprites/foregrounds/

Player — assets/sprites/player/

Entities — assets/sprites/entities/

Collectibles — assets/sprites/collectibles/

Hazards — assets/sprites/hazards/

Surfaces — assets/sprites/surfaces/

Levels — assets/sprites/levels/

Screens — assets/sprites/screens/

Fonts — assets/fonts/

Player Sprite Sheet — player.png

Sheet dimensions: 192 x 288 px Grid: 4 columns x 6 rows Frame size: 48 x 48 px

Animation Row Map

Frame Source Rect Formula

frame.x = anim_frame_index * FRAME_W;   // column x 48
frame.y = ANIM_ROW[anim_state] * FRAME_H; // row x 48

Horizontal Flipping

When player->facing_left == 1, the sprite is drawn with SDL_FLIP_HORIZONTAL via SDL_RenderCopyEx. This means the same right-facing animation frames are used for both directions — no duplicate assets needed.

Unused Assets

The following asset is stored in assets/sprites/unused/ and is not loaded by the game. It is available as a reserve for future use.

Additional background variants are stored alongside used backgrounds in assets/sprites/backgrounds/:

Additional tilesets are stored in assets/sprites/levels/:

Sprite Sheet Analysis

To inspect any sprite sheet’s exact dimensions and pixel layout:

python3 .agents/scripts/analyze_sprite.py assets/sprites/<category>/<sprite>.png

Frame Math Reference

Sheet width  = cols x frame_w
Sheet height = rows x frame_h

source_x = (frame_index % cols) * frame_w
source_y = (frame_index / cols) * frame_h

Loading an Asset

// In game_init or an entity's init function:
SDL_Texture *tex = IMG_LoadTexture(gs->renderer, "assets/sprites/collectibles/coin.png");
if (!tex) {
    fprintf(stderr, "Failed to load coin.png: %s\n", IMG_GetError());
    return -1;
}

// At cleanup (reverse init order):
if (tex) { SDL_DestroyTexture(tex); tex = NULL; }