# platformer A small 3D platformer written from scratch in C. The only libraries are GLFW, GLEW and OpenGL. **Current scope:** a flat test world scattered with box platforms, a small wall course, and a 55 m cliff parkour course (behind spawn: generated, branching, with moving platforms), 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 test world of plain box platforms 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 test world (flat ground plus plain box platforms to jump on) *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 started with four states (`IDLE`, `RUN`, `JUMP`, `FALL`) and add more only when a move requires it (so far `SKID` and `WALL_HANG`). - **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 framing camera, not a leash.** Like Lakitu, the camera doesn't pin the player to the center of the screen. A player standing inside the resting zone leaves the camera completely still. The zone sits 5% inside the rule-of-thirds lines, except that its top edge is at half the window height, which keeps the view ahead open for upcoming obstacles. Running toward or away from the camera lets the player drift 5% past the zone (to the bottom thirds line, or just above halfway at the top). Running sideways is different: the camera works ahead of the player, carrying them to the *trailing* thirds line so there's open screen in the direction they're heading, and slowly swings toward ~30° off directly behind them. Controls stay camera-relative, so holding sideways through the swing makes the player arc, SM64-style. When they stop, the camera eases until they sit on the zone's edge. After 2 s without touching the camera, it also slowly eases into looking down at the player at ~15°. Off-center shots are intentional: they're where the cinematic feel comes from. Clicking the right stick glides the camera behind the player with them centered, and the zone rules pick up again from there. - **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 (around the player; their spot on screen is kept) | | Right stick click | recenter: swing the camera behind the player, centered | | A (south button) | jump (hold longer to jump higher); press again within 0.2 s of landing for a second jump 1.75× as high (a press up to 0.1 s early counts) | | Left stick pulled back at full run | skid; press A during the skid for a retreat jump (2× height, toward the stick; landing it also opens the second-jump window) | | Jump into a violet wall (second, retreat or wall jump) | wall hang: cling for 0.5 s sliding slowly down; A jumps off, mirrored away from the wall | | Back / Select | reset player to spawn | | Start | quit | If a connected pad is ignored, the console prints `"" (GUID ...) has no gamepad mapping`. Add a mapping line for that GUID to `EXTRA_GAMEPAD_MAPPINGS` in `src/controls.c` (the Xbox Elite Series 2 over USB is already there). **Keyboard fallback** (only active when no gamepad is connected, for testing): WASD = move, arrow keys = camera, C = recenter 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/level.c/.h` | What's in the test level: seeded random platforms, the wall course, the generated cliff course, and how moving platforms move. | | `src/world.c/.h` | The level while the game runs: stores the boxes, moves the moving ones each tick, answers geometry queries and boundaries. | | `src/physics.c/.h` | Gravity, velocity integration, and floor/wall/ceiling 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 frames the player inside a screen-space zone. | | `src/render.c/.h` | Draws the ground grid, the platforms, the player box, its drop shadow, and the FPS counter. 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 world ──► level (level.c only uses world.h's Box type; it never calls 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 world_update() (moving platforms move first, so the player rides them) controls_poll() -> Input player_update() (uses Input + the camera's yaw) camera_update() (re-frames 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) - Richer level geometry: slopes, moving platforms, step-up onto small ledges, hand-built or loaded levels - Camera collision (the camera can currently pass through tall platforms) - Loading levels - SM64-style extra moves: triple jump, long jump, ground pound (the second jump, the skid's retreat jump and the wall hang/wall jump exist) - Character model and animation - Audio - On-screen text/HUD beyond the FPS counter in the top-right corner - Interpolating render state between ticks