# platformer A small 3D platformer written from scratch in C. The only libraries are GLFW, GLEW and OpenGL. **Current scope:** a blank, flat world, one character (a box with a drop shadow), a third-person camera, and a gamepad. That's everything. The only goal right now is to **dial in character movement**: running, turning, jumping and falling should feel good before anything else gets built. --- ## Guiding principles These rules apply to every change. If a change breaks one, it needs a very good reason. 1. **Minimal files.** Each file has one purpose that you can explain in a sentence (`controls.c` reads the gamepad, `physics.c` applies gravity and collision, and so on). If you can't say what a file is for, it shouldn't exist. If a file starts doing two jobs, split it. 2. **Minimal dependencies.** We build from scratch on purpose. The runtime needs GLFW (window + gamepad), GLEW (OpenGL function loading), OpenGL, and the C standard library, and nothing else. There are no math libraries, no engines and no asset pipelines. This is deliberately the opposite of UE5-style bloat: we should understand every line that runs each frame. 3. **Minimal scope.** Start super small and grow one piece at a time. Today it's a blank world plus movement. Levels, enemies, audio and the rest wait until movement feels right. 4. **Readable implementation.** Someone with ~junior gamedev knowledge should be able to read any file top to bottom and follow it. That means plain C99, short functions, descriptive names, a comment on every *why*, and no clever macros or hidden control flow. ## Inspiration: Super Mario 64 SM64 is the reference point for both **what** we build and **how** we build it. **Scope.** Before SM64 had levels, its team spent a long time in a plain test space getting Mario's movement and the camera to feel right. We're following the same order: the blank world *is* the game until the controls feel great. **Development approach.** These ideas come from SM64's design: - **A small, purpose-built engine.** Write only what the game needs, and nothing general-purpose "just in case". - **Fixed-rate simulation.** Game logic runs at a fixed tick rate that doesn't depend on the render frame rate. SM64 ran its logic at 30 Hz. We use **60 Hz** because modern displays and gamepads make the lower input latency noticeable, and the per-tick math stays the same either way. - **An explicit player state machine.** SM64 has Mario "actions" (idle, walking, jumping, and so on). We start with four states (`IDLE`, `RUN`, `JUMP`, `FALL`) and add more only when a move requires it. - **Analog-magnitude movement.** How far you push the stick sets how fast you move. A radial deadzone keeps the full 0..1 range usable. - **Camera-relative controls.** "Up" on the stick means "away from the camera". The player orbits the camera with the right stick. - **A drop shadow for depth.** A dark blob directly under the character is the most important depth cue in a 3D platformer, and it tells you where you'll land. --- ## Dependencies | Library | Why | Gentoo package | |---|---|---| | GLFW 3.4 | window, GL context, keyboard, **gamepad** (`glfwGetGamepadState`, with built-in SDL controller mappings) | `media-libs/glfw` | | GLEW | loads OpenGL 3.3 core functions | `media-libs/glew` | | OpenGL 3.3 | rendering | `virtual/opengl` | | libm | `sinf`, `cosf`, `sqrtf`, ... | (libc) | Tools: a C99 compiler (`cc`/`gcc`/`clang`), `make`, `pkg-config`. ## Build & run ```sh make # build ./platformer make run # build and run make debug # -O0 -g with AddressSanitizer + UBSan make clean ``` ## Controls The game is designed for a gamepad (Xbox-style layout names; GLFW maps other pads to it). | Input | Action | |---|---| | Left stick | move (tilt amount = speed, relative to the camera) | | Right stick | orbit camera | | A (south button) | jump (hold longer to jump higher) | | Back / Select | reset player to spawn | | Start | quit | **Keyboard fallback** (only active when no gamepad is connected, for testing): WASD = move, arrow keys = camera, Space = jump, R = reset, Esc = quit. --- ## Architecture | File | Purpose | |---|---| | `src/main.c` | Entry point. Starts every module, runs the fixed-timestep game loop, shuts down. | | `src/config.h` | All tunable numbers in one place (speeds, gravity, camera, window). **Tune movement here.** | | `src/math3d.h` | Tiny header-only vector/matrix math (`Vec2`, `Vec3`, `Mat4`). | | `src/window.c/.h` | The window and OpenGL context (GLFW + GLEW), the clock, and swapping buffers. | | `src/controls.c/.h` | Reads the gamepad (or keyboard fallback) into one abstract `Input` struct. | | `src/world.c/.h` | The blank world: ground height and world boundaries. | | `src/physics.c/.h` | Gravity, velocity integration and ground collision for a generic `Body`. | | `src/player.c/.h` | The player's state machine. Turns `Input` into running, turning and jumping. | | `src/camera.c/.h` | Third-person orbit camera that follows the player. | | `src/render.c/.h` | Draws the ground grid, the player box and its drop shadow. Read-only. | **Dependency direction** (arrows mean "includes / calls"; there are no cycles): ``` main ──► window, controls, world, player, camera, render controls ──► window (keyboard fallback needs the window handle) player ──► physics, world, controls (Input struct only) physics ──► world camera ──► controls (Input struct only) render ──► player, camera, world (reads only, never modifies) everything ──► config.h, math3d.h ``` **One frame:** ``` window_poll_events() while (enough time has built up for a tick): // fixed 60 Hz controls_poll() -> Input player_update() (uses Input + the camera's yaw) camera_update() (follows the player's new position) render_frame() // once per display frame window_swap() ``` **Conventions:** Y is up, right-handed coordinates. 1 unit = 1 meter. Angles are in radians. `dt` is in seconds. Public functions are named `module_verb` (`player_update`, `camera_yaw`). A module keeps its private state in `static` variables inside its `.c` file, and there are no cross-file globals. --- ## Scaffolding workflow (current stage) Right now the files contain **prompts, not code**. Each file opens with a comment block made of these sections: - `PURPOSE` - `FITS IN` - `INTERFACE` (headers) or `IMPLEMENT` (sources) - `CONVENTIONS` - `NOT IN SCOPE` - `DONE WHEN` An implementing agent (or person) fills in each file from its prompt. Rules for filling in: 1. **Follow the interfaces in the headers exactly.** The names, struct fields and signatures are shared across files, so changing one breaks the others. If an interface truly has to change, update every prompt that mentions it. 2. **Keep the prompt block** at the top of each file. It becomes that file's documentation. 3. Respect `NOT IN SCOPE`. Leave it out, even when it's tempting to add. Suggested fill-in order (each step can be compiled before moving on): 1. `config.h`, `math3d.h` 2. `window.c/.h` 3. `controls.c/.h` 4. `world.c/.h` 5. `physics.c/.h` 6. `camera.c/.h` 7. `player.c/.h` 8. `render.c/.h` 9. `main.c` 10. `Makefile` ## Roadmap (explicitly *not* now) - Collision with real geometry (platforms, walls, slopes) - Loading levels - SM64-style extra moves: double/triple jump, long jump, wall kick, ground pound - Character model and animation - Audio - On-screen text/HUD - Interpolating render state between ticks