# 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 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 (5% inside the rule-of-thirds lines) leaves the camera completely still. While running, they can drift out to the thirds lines. When they stop, the camera eases until they sit on the zone's edge. 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) | | 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/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 frames the player inside a screen-space zone. | | `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() (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) - 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