CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

Aventures En Egipte (AEE) — a retro-style 2D game written in C++ using SDL3. The game uses a software-rendered 8-bit paletted graphics engine (320x200, 256 colors) with an OpenGL CRT shader pass, custom audio (JailAudio replacing SDL_Mixer), and GIF-based assets. The codebase and commit messages are in Valencian/Catalan.

Build

# Linux
cmake -B build
cmake --build build

# Windows (MinGW)
cmake -B build -G "MinGW Makefiles"
cmake --build build

Dependencies: SDL3, OpenGL. Uses CMake (minimum 3.10) with C++20.

The executable is output to the project root. The data/ folder contains runtime assets (GIF images, OGG music, GLSL shader) and must be in the working directory at runtime.

Architecture

Custom "Jail" Engine Libraries (prefix: J)

All engine modules are flat C-style APIs (no classes), prefixed by subsystem:

JG (source/jgame) — Game loop timing: init/finalize, fixed-timestep update via JG_ShouldUpdate()
JD8 (source/jdraw8) — 8-bit paletted software renderer. 320x200 screen buffer (JD8_Surface = Uint8*), palette-indexed blitting with color-key transparency, fade effects. JD8_Flip() converts the indexed buffer to ARGB, uploads to SDL texture, and renders through the CRT shader
JA (source/jail_audio) — Custom audio mixing using SDL3 audio streams directly (OGG via stb_vorbis, WAV). Manages music and sound channels independently
JI (source/jinput) — Input: keyboard state polling, key debouncing, cheat code detection
JF (source/jfile) — File I/O: supports loading from filesystem folder or a packed resource file (.jrf). Currently uses folder mode (data/)
shader (source/jshader) — OpenGL post-processing shader (CRT effect) applied to the back buffer

Game Modules

ModuleSequence (modulesequence.cpp/h) — Non-gameplay screens: intro, menu, slides, banners, credits, death screen. State machine entry point (state=1)
ModuleGame (modulegame.cpp/h) — Core gameplay loop. Owns and orchestrates all game objects. State=0
Sprite (sprite.cpp/h) — Base class for animated entities (frame/animation data via Entitat)
Prota (prota.cpp/h) — Player character ("Sam"), extends Sprite
Mapa (mapa.cpp/h) — Level map with tomb grid (16 tombs), items (treasure, keys, pharaoh, mummy, scroll, diamond), door logic
Momia (momia.cpp/h) — Enemy: mummies
Bola (bola.cpp/h) — Enemy: projectile ball
Marcador (marcador.cpp/h) — HUD/scoreboard
info (info.cpp/h) — Global game state namespace (room number, pyramid, money, diamonds, lives, etc.)

Main Loop (`main.cpp`)

A state machine alternates between ModuleSequence (state 1) and ModuleGame (state 0). Each module's Go() returns the next state (-1 to quit). Modules are allocated/freed each transition.

Key Conventions

All surfaces are 320x200 = 64000 bytes. Pixel coordinates assume this fixed resolution
Graphics loaded from GIF files, palettes extracted from GIF headers
Music files are numbered OGG files (00000001.ogg etc.)
trick.ini presence enables the secret character
The gif.h is a header-only GIF decoder; stb_vorbis.h is the stb single-header OGG decoder

3.3 KiB Raw Blame History