summaryrefslogtreecommitdiff
path: root/platformer
diff options
context:
space:
mode:
authorSchark <jordan@schark.online>2026-09-23 23:09:55 -0400
committerSchark <jordan@schark.online>2026-09-23 23:09:55 -0400
commitdab65412376d1b73381446f969c1461c24169811 (patch)
tree27adfec438a9bd9f3c96a740ab54016df5f68b80 /platformer
parentaf03f388cbcff795158ea8345b5c876470229e8b (diff)
downloadgamedev-dab65412376d1b73381446f969c1461c24169811.tar.gz
gamedev-dab65412376d1b73381446f969c1461c24169811.zip
Base prompts
Diffstat (limited to '')
-rw-r--r--platformer/.gitignore3
-rw-r--r--platformer/README.md176
-rw-r--r--platformer/src/camera.c51
-rw-r--r--platformer/src/camera.h52
-rw-r--r--platformer/src/config.h84
-rw-r--r--platformer/src/controls.c75
-rw-r--r--platformer/src/controls.h46
-rw-r--r--platformer/src/main.c67
-rw-r--r--platformer/src/math3d.h77
-rw-r--r--platformer/src/physics.c40
-rw-r--r--platformer/src/physics.h36
-rw-r--r--platformer/src/player.c73
-rw-r--r--platformer/src/player.h48
-rw-r--r--platformer/src/render.c65
-rw-r--r--platformer/src/render.h31
-rw-r--r--platformer/src/window.c44
-rw-r--r--platformer/src/window.h43
-rw-r--r--platformer/src/world.c29
-rw-r--r--platformer/src/world.h40
19 files changed, 1080 insertions, 0 deletions
diff --git a/platformer/.gitignore b/platformer/.gitignore
new file mode 100644
index 0000000..a64aa5d
--- /dev/null
+++ b/platformer/.gitignore
@@ -0,0 +1,3 @@
+# Build output
+/build/
+/platformer
diff --git a/platformer/README.md b/platformer/README.md
new file mode 100644
index 0000000..cea08bd
--- /dev/null
+++ b/platformer/README.md
@@ -0,0 +1,176 @@
+# 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
diff --git a/platformer/src/camera.c b/platformer/src/camera.c
new file mode 100644
index 0000000..00f8d4a
--- /dev/null
+++ b/platformer/src/camera.c
@@ -0,0 +1,51 @@
+/*
+ * ============================================================
+ * FILE: camera.c
+ *
+ * PURPOSE: A player-controlled third-person orbit camera, in the spirit of
+ * SM64's "Lakitu" camera but much simpler. A good camera matters as
+ * much for movement feel as the movement code itself.
+ *
+ * FITS IN: Implements camera.h. Reads Input.look (controls.h) and the
+ * player's position (passed in by main.c). Produces matrices for
+ * render.c and a yaw for player.c.
+ *
+ * IMPLEMENT:
+ * - camera_init(c, follow_point):
+ * target = follow_point + (0, CAMERA_TARGET_HEIGHT, 0) (snap, no smoothing)
+ * yaw = 0 (camera sits on +Z looking toward -Z)
+ * pitch = CAMERA_PITCH_DEFAULT
+ * distance = CAMERA_DISTANCE
+ * compute position.
+ *
+ * - camera_update(c, in, follow_point, dt):
+ * 1. Orbit: yaw += in->look.x * CAMERA_YAW_SPEED * dt
+ * pitch += in->look.y * CAMERA_PITCH_SPEED * dt
+ * Clamp pitch to [CAMERA_PITCH_MIN, CAMERA_PITCH_MAX], wrap yaw with
+ * wrap_angle(). Check the sign by feel: pushing the right stick RIGHT
+ * should swing the camera so the view turns right (the camera moves
+ * left around the player). Flip the sign if it feels backwards and
+ * leave a comment.
+ * 2. Follow: move target toward (follow_point + target height) with
+ * frame-rate-independent exponential smoothing:
+ * t = 1 - expf(-CAMERA_FOLLOW_RATE * dt)
+ * target = vec3_lerp(target, desired, t)
+ * Comment WHY: a camera that snaps rigidly to the player looks jittery,
+ * and a little lag lets you see the motion.
+ * 3. Recompute position with the YAW CONVENTION in camera.h.
+ *
+ * - camera_yaw(): return c->yaw.
+ * - camera_view(): mat4_look_at(position, target, (0,1,0)).
+ * - camera_projection(c, aspect): mat4_perspective(CAMERA_FOV_DEG converted to
+ * radians, aspect, CAMERA_NEAR, CAMERA_FAR).
+ *
+ * CONVENTIONS: Radians internally; FOV converted once from degrees.
+ *
+ * NOT IN SCOPE: Camera collision, auto-recenter, shake, look-ahead.
+ * (Good candidates for later tuning, not for now.)
+ *
+ * DONE WHEN: The right stick orbits smoothly all the way around the player,
+ * pitch stops at its limits, and the camera trails the running
+ * player slightly without jitter.
+ * ============================================================
+ */
diff --git a/platformer/src/camera.h b/platformer/src/camera.h
new file mode 100644
index 0000000..ead4bc9
--- /dev/null
+++ b/platformer/src/camera.h
@@ -0,0 +1,52 @@
+/*
+ * ============================================================
+ * FILE: camera.h
+ *
+ * PURPOSE: Public interface for the third-person orbit camera: it sits
+ * on a sphere around the player and the right stick moves it
+ * around that sphere.
+ *
+ * FITS IN: main.c calls camera_update() each tick AFTER player_update().
+ * player_update() receives camera_yaw() so "stick up" means "away
+ * from the camera". render.c reads camera_view()/camera_projection().
+ *
+ * INTERFACE: Use these exact names:
+ *
+ * typedef struct Camera {
+ * Vec3 target; the smoothed point we look at (near the player)
+ * float yaw; orbit angle around the target, radians
+ * float pitch; angle above horizontal, radians
+ * float distance; meters from target
+ * Vec3 position; derived eye position (recomputed in camera_update)
+ * } Camera;
+ *
+ * void camera_init(Camera *c, Vec3 follow_point);
+ * void camera_update(Camera *c, const Input *in, Vec3 follow_point, float dt);
+ * follow_point = the player's feet position; the camera adds
+ * CAMERA_TARGET_HEIGHT itself.
+ * float camera_yaw(const Camera *c);
+ * Mat4 camera_view(const Camera *c);
+ * Mat4 camera_projection(const Camera *c, float aspect);
+ *
+ * YAW CONVENTION (player.c relies on this, so keep it exact):
+ * position = target + distance * ( sin(yaw)*cos(pitch),
+ * sin(pitch),
+ * cos(yaw)*cos(pitch) )
+ * So on the ground plane, the camera's
+ * forward (toward target) = (-sin(yaw), 0, -cos(yaw))
+ * right = ( cos(yaw), 0, -sin(yaw))
+ *
+ * Include "math3d.h" and "controls.h".
+ *
+ * CONVENTIONS: Include guard: CAMERA_H.
+ *
+ * NOT IN SCOPE: Collision with geometry, automatic "behind the player"
+ * recentering, cutscene/fixed cameras, zoom levels.
+ *
+ * DONE WHEN: player.c and render.c can be written against this header alone.
+ * ============================================================
+ */
+#ifndef CAMERA_H
+#define CAMERA_H
+
+#endif /* CAMERA_H */
diff --git a/platformer/src/config.h b/platformer/src/config.h
new file mode 100644
index 0000000..1aa6447
--- /dev/null
+++ b/platformer/src/config.h
@@ -0,0 +1,84 @@
+/*
+ * ============================================================
+ * FILE: config.h
+ *
+ * PURPOSE: Every tunable number in the game, in one place. When movement
+ * "feels wrong", this is the first (and usually only) file to edit.
+ *
+ * FITS IN: Included by almost every .c file. Contains only #defines,
+ * with no functions, no types and no includes.
+ * Nothing in the game should hard-code a number that appears here.
+ *
+ * INTERFACE: Plain #define constants, float literals with an `f` suffix.
+ * Give EVERY constant a one-line comment that says what it
+ * changes about the *feel*, e.g. "higher = snappier stops".
+ * Use these exact names (other files depend on them). The
+ * values are starting points for tuning:
+ *
+ * Window
+ * WINDOW_WIDTH 1280
+ * WINDOW_HEIGHT 720
+ * WINDOW_TITLE "platformer"
+ * SKY_COLOR_R/G/B 0.45f 0.65f 0.90f (clear color)
+ *
+ * Simulation timing
+ * TICK_HZ 60 (fixed logic rate; SM64 used 30)
+ * TICK_DT (1.0f / TICK_HZ) (seconds per tick)
+ * MAX_FRAME_TIME 0.25f (clamp to avoid a "spiral of death"
+ * after a stall / breakpoint)
+ *
+ * Input
+ * MOVE_DEADZONE 0.20f (radial, left stick)
+ * LOOK_DEADZONE 0.20f (radial, right stick)
+ *
+ * Player: ground movement
+ * PLAYER_MAX_SPEED 9.0f m/s at full stick tilt
+ * PLAYER_GROUND_ACCEL 30.0f m/s^2 speeding up toward target speed
+ * PLAYER_GROUND_FRICTION 40.0f m/s^2 slowing down with no input
+ * PLAYER_TURN_RATE 12.0f rad/s max facing rotation on ground
+ *
+ * Player: air movement
+ * PLAYER_AIR_CONTROL 0.30f 0..1 multiplier on accel + turn rate in air
+ * PLAYER_JUMP_VELOCITY 14.0f m/s upward at jump start (~2.4 m apex)
+ * PLAYER_JUMP_CUT 0.50f vel.y multiplier when A released while rising
+ *
+ * Physics
+ * GRAVITY 40.0f m/s^2 (stronger than real 9.8 on purpose:
+ * platformers feel floaty with real gravity)
+ * TERMINAL_VELOCITY 50.0f m/s max fall speed
+ *
+ * Player: size (used by render, and later by collision)
+ * PLAYER_HALF_WIDTH 0.4f m
+ * PLAYER_HEIGHT 1.6f m (body.pos is the player's FEET)
+ *
+ * Camera
+ * CAMERA_DISTANCE 10.0f m from target
+ * CAMERA_TARGET_HEIGHT 1.0f m above player's feet to look at
+ * CAMERA_PITCH_DEFAULT 0.35f rad above horizontal
+ * CAMERA_PITCH_MIN 0.05f rad
+ * CAMERA_PITCH_MAX 1.20f rad
+ * CAMERA_YAW_SPEED 2.5f rad/s at full right-stick tilt
+ * CAMERA_PITCH_SPEED 1.5f rad/s at full right-stick tilt
+ * CAMERA_FOLLOW_RATE 8.0f 1/s; higher = camera catches up faster
+ * CAMERA_FOV_DEG 60.0f vertical field of view
+ * CAMERA_NEAR 0.1f
+ * CAMERA_FAR 500.0f
+ *
+ * World
+ * WORLD_HALF_EXTENT 100.0f m; the ground is a square of 2x this per side
+ * GRID_SPACING 1.0f m between grid lines
+ * GRID_MAJOR_EVERY 10 every Nth line drawn brighter
+ *
+ * CONVENTIONS: 1 unit = 1 meter, seconds, radians (degrees only for the FOV,
+ * converted where it's used). Include guard: CONFIG_H.
+ *
+ * NOT IN SCOPE: Runtime config files, command-line parsing, hot-reload.
+ *
+ * DONE WHEN: Every constant above exists with a comment, and no other
+ * file contains a magic number for any of these concepts.
+ * ============================================================
+ */
+#ifndef CONFIG_H
+#define CONFIG_H
+
+#endif /* CONFIG_H */
diff --git a/platformer/src/controls.c b/platformer/src/controls.c
new file mode 100644
index 0000000..850a1ae
--- /dev/null
+++ b/platformer/src/controls.c
@@ -0,0 +1,75 @@
+/*
+ * ============================================================
+ * FILE: controls.c
+ *
+ * PURPOSE: Turns the physical gamepad (primary) or keyboard (fallback)
+ * into the abstract Input struct from controls.h. Getting
+ * the analog feel right here (the deadzone and stick scaling)
+ * matters as much as the player code for movement feel.
+ *
+ * FITS IN: main.c calls controls_poll() once per fixed tick. It uses
+ * GLFW's gamepad API directly and window_handle() (window.h)
+ * only for keyboard reads. It's the only file that reads raw
+ * input devices.
+ *
+ * IMPLEMENT:
+ * - Private state: the previous tick's button states (for the "pressed"
+ * edges), e.g. `static bool s_prev_jump, s_prev_reset, s_prev_quit;`
+ *
+ * - Finding a gamepad (keep it simple; this also handles hot-plugging):
+ * each poll, loop GLFW_JOYSTICK_1..GLFW_JOYSTICK_LAST and use the first
+ * jid where glfwJoystickIsGamepad(jid) is true, then read it with
+ * glfwGetGamepadState(jid, &state). GLFW 3.4 has SDL's controller
+ * mapping database built in, so Xbox/PlayStation/Switch pads all show
+ * up in the standard layout. Print a line to stdout when the active
+ * pad connects or disconnects (glfwGetGamepadName), so it's clear
+ * which device is in use.
+ *
+ * - Gamepad mapping:
+ * move.x = GLFW_GAMEPAD_AXIS_LEFT_X
+ * move.y = -GLFW_GAMEPAD_AXIS_LEFT_Y (GLFW reports up as NEGATIVE,
+ * so flip it: up = forward = +y)
+ * look.x = GLFW_GAMEPAD_AXIS_RIGHT_X
+ * look.y = -GLFW_GAMEPAD_AXIS_RIGHT_Y
+ * jump = GLFW_GAMEPAD_BUTTON_A
+ * reset = GLFW_GAMEPAD_BUTTON_BACK
+ * quit = GLFW_GAMEPAD_BUTTON_START
+ *
+ * - RADIAL deadzone (write a small static helper, used for both sticks):
+ * len = length of the raw (x, y)
+ * if len < deadzone -> (0, 0)
+ * else rescale so the edge of the deadzone maps to 0 and full tilt maps
+ * to 1: new_len = (len - deadzone) / (1 - deadzone), clamped to 1,
+ * keeping the original direction.
+ * WHY radial and not per-axis: a per-axis deadzone snaps diagonals
+ * to the cardinal directions and makes slow walking feel "sticky". SM64
+ * also computes one magnitude from the whole stick and uses it for speed.
+ * Also clamp the final length to 1, because some pads report corners past 1.
+ * Use MOVE_DEADZONE / LOOK_DEADZONE from config.h.
+ *
+ * - Keyboard fallback, used ONLY when no gamepad is connected:
+ * W/S/A/D -> move (normalize diagonals so the length is <= 1)
+ * Arrow keys -> look
+ * Space -> jump, R -> reset, Esc -> quit
+ * Read keys with glfwGetKey(window_handle(), key).
+ * Esc also quits when a gamepad IS connected (so you can always exit).
+ *
+ * - Edge detection: pressed = down_now && !down_last_tick. Then store
+ * down_now for next tick.
+ *
+ * - Zero the whole Input at the start of controls_poll so no stale data leaks.
+ *
+ * CONVENTIONS: `s_` prefix for statics. <GLFW/glfw3.h> is included here (not
+ * in controls.h).
+ *
+ * NOT IN SCOPE: Rebinding, loading an external gamecontrollerdb.txt,
+ * rumble, triggers/shoulder buttons (add them when a move needs
+ * them), input recording/replay.
+ *
+ * DONE WHEN: With a pad: a small stick tilt gives a small |move|, full
+ * tilt gives ~1.0, the resting stick gives exactly (0, 0), and each
+ * A press sets jump_pressed for exactly one tick. Unplugging the
+ * pad switches to the keyboard without a crash, and plugging it back
+ * in switches back.
+ * ============================================================
+ */
diff --git a/platformer/src/controls.h b/platformer/src/controls.h
new file mode 100644
index 0000000..dbbe936
--- /dev/null
+++ b/platformer/src/controls.h
@@ -0,0 +1,46 @@
+/*
+ * ============================================================
+ * FILE: controls.h
+ *
+ * PURPOSE: Defines `Input`, the one abstract snapshot of what the player
+ * is asking for this tick. Gameplay code reads Input and never
+ * reads a raw device, so the player and camera don't care whether
+ * a gamepad or the keyboard produced it.
+ *
+ * FITS IN: main.c calls controls_poll() once per fixed tick and passes the
+ * Input to player_update() and camera_update().
+ *
+ * INTERFACE: Use these exact names:
+ *
+ * typedef struct Input {
+ * Vec2 move; left stick after the deadzone. Length is 0..1.
+ * +x = right, +y = FORWARD (stick pushed up).
+ * Vec2 look; right stick after the deadzone. Length is 0..1.
+ * +x = orbit camera right, +y = tilt camera up.
+ * bool jump_held; A is down this tick
+ * bool jump_pressed; A went down THIS tick (true for one tick only)
+ * bool reset_pressed; Back/Select went down this tick (one tick only)
+ * bool quit_pressed; Start (or Esc) went down this tick (one tick only)
+ * bool using_gamepad; true if a gamepad produced this Input (debug info)
+ * } Input;
+ *
+ * void controls_init(void); call after window_init()
+ * void controls_poll(Input *out); call once per FIXED TICK (not once per
+ * frame). The "pressed" edges are
+ * worked out tick-to-tick, so a press
+ * is never lost or counted twice.
+ *
+ * Include <stdbool.h> and "math3d.h" (for Vec2).
+ *
+ * CONVENTIONS: Include guard: CONTROLS_H.
+ *
+ * NOT IN SCOPE: Rebinding, multiple players, mouse look, rumble.
+ *
+ * DONE WHEN: player.c and camera.c can be written against Input alone,
+ * without including GLFW.
+ * ============================================================
+ */
+#ifndef CONTROLS_H
+#define CONTROLS_H
+
+#endif /* CONTROLS_H */
diff --git a/platformer/src/main.c b/platformer/src/main.c
new file mode 100644
index 0000000..4e9e07a
--- /dev/null
+++ b/platformer/src/main.c
@@ -0,0 +1,67 @@
+/*
+ * ============================================================
+ * FILE: main.c
+ *
+ * PURPOSE: Entry point. Starts every module, runs the game loop, and shuts
+ * everything down. It should read like a table of contents for the
+ * game, with NO gameplay logic of its own.
+ *
+ * FITS IN: The top of the dependency graph. Includes window.h, controls.h,
+ * world.h, player.h, camera.h, render.h, config.h.
+ *
+ * IMPLEMENT:
+ * - Startup (in this order, and if any step fails, clean up what
+ * already started and return 1):
+ * window_init() -> controls_init() -> world_init()
+ * player_init(&player, world_spawn_point())
+ * camera_init(&camera, player.body.pos)
+ * render_init()
+ *
+ * - Game loop with a FIXED TIMESTEP + accumulator (explain it in a comment;
+ * this is the most important idea in the file):
+ *
+ * previous = window_time(); accumulator = 0;
+ * while (!window_should_close()):
+ * now = window_time();
+ * frame_time = now - previous; previous = now;
+ * if frame_time > MAX_FRAME_TIME: frame_time = MAX_FRAME_TIME
+ * accumulator += frame_time;
+ *
+ * window_poll_events();
+ *
+ * while accumulator >= TICK_DT: // 0, 1 or several ticks
+ * controls_poll(&input);
+ * if input.quit_pressed: window_request_close();
+ * if input.reset_pressed: player_reset(&player, world_spawn_point());
+ * player_update(&player, &input, camera_yaw(&camera), TICK_DT);
+ * camera_update(&camera, &input, player.body.pos, TICK_DT);
+ * accumulator -= TICK_DT;
+ *
+ * render_frame(&camera, &player, window_aspect());
+ * window_swap();
+ *
+ * WHY the fixed timestep: the game behaves the same (identical jump
+ * height, identical speeds) no matter the monitor's refresh rate or a
+ * dropped frame, which is exactly what you need when tuning movement. SM64
+ * ran logic at 30 Hz; we use TICK_HZ (60).
+ * WHY player before camera: the camera then follows where the player IS,
+ * not where it was a tick ago. SM64 updates Mario before the camera too.
+ *
+ * - Debug readout for tuning (a few times per second, not every frame):
+ * window_set_title() with something like
+ * "platformer | RUN | speed 7.42 m/s | y 1.83 | pad"
+ * using player_state_name(), forward_speed, body.pos.y and
+ * input.using_gamepad. This is our "HUD" until text rendering exists.
+ *
+ * - Shutdown in reverse order: render_shutdown() -> window_shutdown().
+ *
+ * CONVENTIONS: `int main(void)`. Game objects (Player, Camera, Input) are
+ * local variables in main, passed by pointer. No globals.
+ *
+ * NOT IN SCOPE: Menus, pause, command-line args, state interpolation.
+ *
+ * DONE WHEN: `make run` opens the window. The player can run, turn and jump
+ * with a gamepad, the camera orbits, Back resets, Start quits, and
+ * the title bar shows live state/speed.
+ * ============================================================
+ */
diff --git a/platformer/src/math3d.h b/platformer/src/math3d.h
new file mode 100644
index 0000000..316e418
--- /dev/null
+++ b/platformer/src/math3d.h
@@ -0,0 +1,77 @@
+/*
+ * ============================================================
+ * FILE: math3d.h
+ *
+ * PURPOSE: The small amount of vector/matrix math the game needs, written
+ * by hand so we don't pull in a math library.
+ *
+ * FITS IN: Header-only (every function is `static inline`). Included by
+ * any file that does math. Depends only on <math.h>.
+ *
+ * INTERFACE: Use these exact names:
+ *
+ * Constants
+ * M3D_PI 3.14159265358979f (C99 doesn't guarantee M_PI)
+ *
+ * Types (plain structs, passed and returned BY VALUE since they're small)
+ * typedef struct { float x, y; } Vec2;
+ * typedef struct { float x, y, z; } Vec3;
+ * typedef struct { float m[16]; } Mat4; COLUMN-MAJOR, element (row r,
+ * col c) is m[c*4 + r], so it can
+ * go straight to glUniformMatrix4fv
+ * with transpose = GL_FALSE.
+ *
+ * Scalar helpers
+ * float clampf(float v, float lo, float hi);
+ * float approachf(float current, float target, float max_step);
+ * moves current toward target by at most max_step, never overshoots.
+ * (Used for acceleration/friction.)
+ * float wrap_angle(float a);
+ * returns a in (-PI, PI].
+ * float approach_angle(float current, float target, float max_step);
+ * like approachf but takes the SHORT way around the circle.
+ * (Used for turning the player.)
+ *
+ * Vec2
+ * Vec2 vec2_make(float x, float y);
+ * float vec2_length(Vec2 v);
+ *
+ * Vec3
+ * Vec3 vec3_make(float x, float y, float z);
+ * Vec3 vec3_add(Vec3 a, Vec3 b);
+ * Vec3 vec3_sub(Vec3 a, Vec3 b);
+ * Vec3 vec3_scale(Vec3 v, float s);
+ * float vec3_dot(Vec3 a, Vec3 b);
+ * Vec3 vec3_cross(Vec3 a, Vec3 b);
+ * float vec3_length(Vec3 v);
+ * Vec3 vec3_normalize(Vec3 v); returns (0,0,0) for zero-length input
+ * Vec3 vec3_lerp(Vec3 a, Vec3 b, float t);
+ *
+ * Mat4
+ * Mat4 mat4_identity(void);
+ * Mat4 mat4_mul(Mat4 a, Mat4 b); result = a * b (b is applied first)
+ * Mat4 mat4_translate(Vec3 t);
+ * Mat4 mat4_scale(Vec3 s);
+ * Mat4 mat4_rotate_y(float angle); rotates +Z toward +X, i.e.
+ * (0,0,1) -> (sin a, 0, cos a)
+ * Mat4 mat4_perspective(float fovy_rad, float aspect, float near, float far);
+ * standard OpenGL (gluPerspective) form
+ * Mat4 mat4_look_at(Vec3 eye, Vec3 target, Vec3 up);
+ * standard OpenGL (gluLookAt) form
+ *
+ * CONVENTIONS: Right-handed, Y up. Radians everywhere. Keep each function a
+ * few lines with a short comment; this is a learning resource.
+ * Include guard: MATH3D_H.
+ *
+ * NOT IN SCOPE: Quaternions, matrix inverse, SIMD, Vec4, generic N-dim math.
+ * Add a function only when a caller needs it.
+ *
+ * DONE WHEN: All functions above compile cleanly under -std=c99 -Wall
+ * -Wextra, and mat4_perspective * mat4_look_at produces a
+ * correct view of the ground grid in render.c.
+ * ============================================================
+ */
+#ifndef MATH3D_H
+#define MATH3D_H
+
+#endif /* MATH3D_H */
diff --git a/platformer/src/physics.c b/platformer/src/physics.c
new file mode 100644
index 0000000..3608c48
--- /dev/null
+++ b/platformer/src/physics.c
@@ -0,0 +1,40 @@
+/*
+ * ============================================================
+ * FILE: physics.c
+ *
+ * PURPOSE: Moves a Body forward one fixed tick: gravity, integration,
+ * landing on the ground, and staying inside the world.
+ *
+ * FITS IN: Implements physics.h. Called by player.c inside player_update(),
+ * AFTER the player has chosen its velocity for this tick. Uses
+ * world_ground_height() and world_clamp_to_bounds() from world.h.
+ *
+ * IMPLEMENT physics_step(b, dt), in this order:
+ * 1. Gravity: if !b->on_ground, vel.y -= GRAVITY * dt, then clamp vel.y to
+ * no lower than -TERMINAL_VELOCITY.
+ * (When on the ground, vel.y is left alone. A jump sets it positive
+ * before this call, and that's what lifts the body off the ground.)
+ * 2. Integrate (semi-implicit Euler: velocity was updated first, then position):
+ * pos += vel * dt
+ * Add a comment explaining why this order is stable enough for a
+ * fixed timestep.
+ * 3. Ground: ground = world_ground_height(pos.x, pos.z).
+ * if pos.y <= ground: pos.y = ground; if vel.y < 0, vel.y = 0;
+ * on_ground = true
+ * else: on_ground = false
+ * Note: on_ground must become false the moment a jump lifts the body,
+ * and walking off a ledge will also set it false once terrain exists.
+ * 4. Bounds: pos = world_clamp_to_bounds(pos). If x or z got clamped,
+ * zero that velocity component so the body doesn't "stick" against
+ * the edge while pushing into it.
+ *
+ * CONVENTIONS: dt is always TICK_DT in practice, but use the parameter rather
+ * than the constant so the function stays general.
+ *
+ * NOT IN SCOPE: Friction/acceleration (that's player movement *intent*, in
+ * player.c), wall/ceiling collision, slopes, sub-stepping.
+ *
+ * DONE WHEN: A body placed at y = 10 falls, speeds up, lands exactly on
+ * y = 0 with on_ground = true, and stays there.
+ * ============================================================
+ */
diff --git a/platformer/src/physics.h b/platformer/src/physics.h
new file mode 100644
index 0000000..dfbfebb
--- /dev/null
+++ b/platformer/src/physics.h
@@ -0,0 +1,36 @@
+/*
+ * ============================================================
+ * FILE: physics.h
+ *
+ * PURPOSE: Public interface for generic physical motion: a `Body` that
+ * falls, moves and lands on the ground. It knows nothing about
+ * players or controllers, so enemies and objects can reuse it later.
+ *
+ * FITS IN: player.c owns a Body, sets its horizontal velocity from input,
+ * then calls physics_step() once per tick. physics.c asks world.h
+ * about the ground and the bounds.
+ *
+ * INTERFACE: Use these exact names:
+ *
+ * typedef struct Body {
+ * Vec3 pos; position of the body's FEET (bottom center), meters
+ * Vec3 vel; velocity, meters/second
+ * bool on_ground; true if the body ended the last step standing on ground
+ * } Body;
+ *
+ * void physics_step(Body *b, float dt);
+ *
+ * Include <stdbool.h> and "math3d.h".
+ *
+ * CONVENTIONS: Include guard: PHYSICS_H.
+ *
+ * NOT IN SCOPE: Rigid bodies, rotation, mass, forces/impulses API, collision
+ * between bodies.
+ *
+ * DONE WHEN: player.c can move and land using only Body + physics_step.
+ * ============================================================
+ */
+#ifndef PHYSICS_H
+#define PHYSICS_H
+
+#endif /* PHYSICS_H */
diff --git a/platformer/src/player.c b/platformer/src/player.c
new file mode 100644
index 0000000..1f1b94c
--- /dev/null
+++ b/platformer/src/player.c
@@ -0,0 +1,73 @@
+/*
+ * ============================================================
+ * FILE: player.c
+ *
+ * PURPOSE: The heart of the current milestone: how the character runs,
+ * turns and jumps. Modeled on SM64's approach: an explicit state
+ * machine, speed that follows the analog stick, and a facing
+ * direction that turns toward the stick instead of snapping.
+ *
+ * FITS IN: Implements player.h. Reads Input (controls.h). Writes the
+ * Body's velocity, then calls physics_step() (physics.h) to do the
+ * actual motion. Tunables all come from config.h.
+ *
+ * IMPLEMENT:
+ * - player_init / player_reset: body.pos = spawn, vel = 0, on_ground = true,
+ * facing_yaw = 0, forward_speed = 0, state = PLAYER_IDLE.
+ *
+ * - player_update(p, in, camera_yaw, dt). Use one static helper per state
+ * (update_idle / update_run / update_jump / update_fall), dispatched by a
+ * `switch (p->state)`. Keep each helper short. Shared steps:
+ *
+ * A. Stick -> world direction (camera-relative). Using camera.h's convention:
+ * fwd = (-sin(camera_yaw), 0, -cos(camera_yaw))
+ * right = ( cos(camera_yaw), 0, -sin(camera_yaw))
+ * wish = fwd * in->move.y + right * in->move.x
+ * mag = vec2_length(in->move) (0..1, already deadzoned)
+ * wish_yaw = atan2f(wish.x, wish.z) (only meaningful if mag > 0)
+ *
+ * B. Ground movement (IDLE / RUN):
+ * - If mag > 0: facing_yaw = approach_angle(facing_yaw, wish_yaw,
+ * PLAYER_TURN_RATE * dt); forward_speed = approachf(forward_speed,
+ * PLAYER_MAX_SPEED * mag, PLAYER_GROUND_ACCEL * dt)
+ * - Else: forward_speed = approachf(forward_speed, 0,
+ * PLAYER_GROUND_FRICTION * dt)
+ * - State: forward_speed > 0 -> RUN, otherwise IDLE.
+ *
+ * C. Jump (from IDLE / RUN): if in->jump_pressed and body.on_ground:
+ * body.vel.y = PLAYER_JUMP_VELOCITY; on_ground = false; state = JUMP.
+ *
+ * D. Air movement (JUMP / FALL): the same as B, but turn rate and accel are
+ * multiplied by PLAYER_AIR_CONTROL, and there's NO friction when the
+ * stick is released (you keep your momentum, like SM64).
+ * - Variable jump height: in JUMP, if !in->jump_held and vel.y > 0,
+ * multiply vel.y by PLAYER_JUMP_CUT ONCE (don't repeat it every tick;
+ * either switch to FALL right away or keep a flag). Comment WHY: tapping A
+ * gives a hop, holding it gives a full jump.
+ * - JUMP -> FALL when vel.y <= 0.
+ * - FALL -> IDLE/RUN when body.on_ground (landing).
+ * - If the player is on the ground state-wise but body.on_ground is false
+ * (walked off an edge, once edges exist) -> FALL.
+ *
+ * E. Apply: body.vel.x = sin(facing_yaw) * forward_speed
+ * body.vel.z = cos(facing_yaw) * forward_speed
+ * then physics_step(&p->body, dt).
+ *
+ * - player_state_name: a switch that returns string literals.
+ *
+ * CONVENTIONS: Facing vector = (sin(yaw), 0, cos(yaw)). Speeds are in m/s,
+ * accelerations in m/s^2, and every one of them multiplies by dt.
+ * No magic numbers; everything comes from config.h.
+ *
+ * NOT IN SCOPE: Double/triple jump, long jump, wall kick, ground pound,
+ * skidding/turnaround, slopes, coyote time, jump buffering.
+ * Leave a short comment at the state enum pointing to the
+ * README roadmap as the place to grow.
+ *
+ * DONE WHEN: Small stick tilts walk slowly and full tilt runs at
+ * PLAYER_MAX_SPEED. Turning is quick but not instant, and letting go
+ * of the stick brings the player to a short, smooth stop. A tap of A
+ * gives a short hop and holding A gives a full ~2.4 m jump. The
+ * player lands cleanly back in IDLE/RUN.
+ * ============================================================
+ */
diff --git a/platformer/src/player.h b/platformer/src/player.h
new file mode 100644
index 0000000..bedfaf4
--- /dev/null
+++ b/platformer/src/player.h
@@ -0,0 +1,48 @@
+/*
+ * ============================================================
+ * FILE: player.h
+ *
+ * PURPOSE: Public interface for the player character: its state and the
+ * one function that advances it each tick.
+ *
+ * FITS IN: main.c owns one Player, calls player_update() each tick, and
+ * calls player_reset() on Input.reset_pressed. render.c reads it
+ * to draw it.
+ *
+ * INTERFACE: Use these exact names:
+ *
+ * typedef enum PlayerState {
+ * PLAYER_IDLE, on ground, not moving
+ * PLAYER_RUN, on ground, moving (walk vs run is just speed)
+ * PLAYER_JUMP, in air, going up after a jump
+ * PLAYER_FALL in air, going down (or walked off something)
+ * } PlayerState;
+ *
+ * typedef struct Player {
+ * Body body; position / velocity / on_ground (physics.h)
+ * float facing_yaw; direction the player faces, radians.
+ * Facing vector = (sin(yaw), 0, cos(yaw)),
+ * which matches mat4_rotate_y in math3d.h.
+ * float forward_speed; ground speed along facing_yaw, m/s (>= 0)
+ * PlayerState state;
+ * } Player;
+ *
+ * void player_init(Player *p, Vec3 spawn);
+ * void player_reset(Player *p, Vec3 spawn);
+ * void player_update(Player *p, const Input *in, float camera_yaw, float dt);
+ * camera_yaw is a plain float so player.c doesn't depend on camera.h.
+ * const char *player_state_name(PlayerState s); "IDLE", "RUN", ... for debug
+ *
+ * Include "math3d.h", "physics.h", "controls.h".
+ *
+ * CONVENTIONS: Include guard: PLAYER_H.
+ *
+ * NOT IN SCOPE: Health, animation, extra moves (see README roadmap).
+ *
+ * DONE WHEN: main.c and render.c compile against this header alone.
+ * ============================================================
+ */
+#ifndef PLAYER_H
+#define PLAYER_H
+
+#endif /* PLAYER_H */
diff --git a/platformer/src/render.c b/platformer/src/render.c
new file mode 100644
index 0000000..a326b15
--- /dev/null
+++ b/platformer/src/render.c
@@ -0,0 +1,65 @@
+/*
+ * ============================================================
+ * FILE: render.c
+ *
+ * PURPOSE: Draws the whole scene with modern OpenGL 3.3 core and as little
+ * code as possible: a ground grid, the player as a box, and the
+ * player's drop shadow.
+ *
+ * FITS IN: Implements render.h. Reads Camera (camera.h), Player (player.h)
+ * and world_half_extent()/world_ground_height() (world.h). Uses the
+ * GL functions that window.c loaded through GLEW.
+ *
+ * IMPLEMENT:
+ * - ONE shader program, source written as string literals in this file
+ * (no shader files to load):
+ * vertex: in vec3 a_pos; uniform mat4 u_mvp; gl_Position = u_mvp * vec4(a_pos,1)
+ * fragment: uniform vec4 u_color; out vec4 frag; frag = u_color
+ * Add a static helper that compiles a shader and prints the info log
+ * on failure. Look up the uniform locations once in render_init.
+ *
+ * - Three meshes, each a VAO + VBO built once in render_init:
+ * 1. Ground grid: GL_LINES in the XZ plane at y = 0, one line every
+ * GRID_SPACING from -world_half_extent() to +world_half_extent(), in
+ * both directions. Put "major" lines (every GRID_MAJOR_EVERY-th) in a
+ * SEPARATE draw range so they can get a brighter color. The grid is
+ * what makes motion readable in a blank world, so explain that in a comment.
+ * 2. Unit cube: 36 vertices (GL_TRIANGLES), spanning x,z in [-0.5, 0.5]
+ * and y in [0, 1] so its origin is at the BOTTOM center, matching
+ * Body.pos being the feet.
+ * 3. Shadow disc: a GL_TRIANGLE_FAN circle of radius 1 in the XZ plane
+ * (~24 segments).
+ *
+ * - render_frame(cam, player, aspect):
+ * 1. glClearColor(SKY_COLOR_R/G/B), clear color + depth.
+ * 2. vp = camera_projection(cam, aspect) * camera_view(cam).
+ * 3. Grid: u_mvp = vp. Draw minor lines in a dim color, major lines brighter.
+ * 4. Shadow (drawn BEFORE the player):
+ * model = translate(player x, ground_y + 0.01, player z) * scale(r, 1, r)
+ * with r around PLAYER_HALF_WIDTH * 1.2. Dark color. The +0.01 lift
+ * stops z-fighting with the ground. Comment WHY the shadow exists:
+ * in SM64 the blob under Mario is the main cue for where you'll land.
+ * Without it, jumps in 3D are very hard to judge.
+ * ground_y = world_ground_height(player x, player z).
+ * 5. Player box:
+ * model = translate(body.pos) * rotate_y(facing_yaw)
+ * * scale(2*PLAYER_HALF_WIDTH, PLAYER_HEIGHT, 2*PLAYER_HALF_WIDTH)
+ * Bright color (e.g. red). Also draw a small second box as a "nose" on
+ * the front face (+Z in model space) so the facing direction is visible.
+ * That makes the turn rate tunable by eye.
+ * Everything uses the one shader, changing only u_mvp and u_color.
+ *
+ * - render_shutdown: delete the VAOs, VBOs and the program.
+ *
+ * CONVENTIONS: `s_` statics for GL handles. Model matrices built from
+ * math3d.h helpers. There's no lighting, so flat colors are fine.
+ *
+ * NOT IN SCOPE: Lighting, textures, models, text/HUD, anti-aliasing,
+ * interpolating between ticks (a README roadmap item).
+ *
+ * DONE WHEN: The scene shows a sky-colored background, a grid ground plane
+ * stretching to the world edge, a box with a visible nose that faces
+ * where it runs, and a shadow that stays on the ground under the
+ * box during a jump.
+ * ============================================================
+ */
diff --git a/platformer/src/render.h b/platformer/src/render.h
new file mode 100644
index 0000000..33e518d
--- /dev/null
+++ b/platformer/src/render.h
@@ -0,0 +1,31 @@
+/*
+ * ============================================================
+ * FILE: render.h
+ *
+ * PURPOSE: Public interface for drawing a frame. Rendering only READS game
+ * state; it never changes the player, the camera or the world.
+ *
+ * FITS IN: main.c calls render_init() after window_init(), render_frame()
+ * once per display frame, and render_shutdown() before
+ * window_shutdown().
+ *
+ * INTERFACE: Use these exact signatures:
+ *
+ * bool render_init(void); compiles shaders, builds meshes. Returns
+ * false (after printing why) on failure.
+ * void render_frame(const Camera *cam, const Player *player, float aspect);
+ * void render_shutdown(void); frees GL objects
+ *
+ * Include <stdbool.h>, "camera.h", "player.h".
+ *
+ * CONVENTIONS: Include guard: RENDER_H.
+ *
+ * NOT IN SCOPE: A general renderer / scene graph, materials, textures, text.
+ *
+ * DONE WHEN: main.c can draw everything with these three calls.
+ * ============================================================
+ */
+#ifndef RENDER_H
+#define RENDER_H
+
+#endif /* RENDER_H */
diff --git a/platformer/src/window.c b/platformer/src/window.c
new file mode 100644
index 0000000..455b249
--- /dev/null
+++ b/platformer/src/window.c
@@ -0,0 +1,44 @@
+/*
+ * ============================================================
+ * FILE: window.c
+ *
+ * PURPOSE: Creates and owns the single game window and its OpenGL context.
+ * This is the ONLY file that calls GLFW window/context functions
+ * and glewInit. (controls.c calls GLFW input functions.)
+ *
+ * FITS IN: main.c calls window_init() first and window_shutdown() last.
+ * Every frame main.c calls window_poll_events() and window_swap().
+ * Implements the interface in window.h.
+ *
+ * IMPLEMENT:
+ * - Private state: `static GLFWwindow *s_window;`
+ * - Include order matters: <GL/glew.h> BEFORE <GLFW/glfw3.h>.
+ * - window_init():
+ * 1. glfwSetErrorCallback -> print GLFW errors to stderr.
+ * 2. glfwInit(). Note that this also initializes GLFW's joystick/gamepad
+ * support, which controls.c depends on.
+ * 3. Hints: GL 3.3, GLFW_OPENGL_CORE_PROFILE, GLFW_OPENGL_FORWARD_COMPAT.
+ * 4. Create a WINDOW_WIDTH x WINDOW_HEIGHT window titled WINDOW_TITLE
+ * (config.h), make its context current.
+ * 5. glewExperimental = GL_TRUE; glewInit(). With a core profile, glewInit
+ * can leave a harmless GL_INVALID_ENUM behind, so call glGetError()
+ * once to clear it and add a comment explaining why.
+ * 6. glfwSwapInterval(1) for vsync.
+ * 7. Framebuffer-size callback -> glViewport(0, 0, w, h).
+ * 8. Enable GL_DEPTH_TEST here (it's global GL state set once).
+ * On any failure: print a clear message, clean up, return false.
+ * - window_framebuffer_size / window_aspect: use glfwGetFramebufferSize
+ * (NOT the window size, because they differ on HiDPI displays). Guard against
+ * height == 0 (minimized window) so the aspect never divides by zero.
+ * - Everything else is a thin wrapper over the matching glfw* call.
+ *
+ * CONVENTIONS: `s_` prefix for file-private statics. Messages go to stderr.
+ *
+ * NOT IN SCOPE: Input handling (that's controls.c), drawing (render.c),
+ * fullscreen, window icons, resizable-minimum-size logic.
+ *
+ * DONE WHEN: A window opens at the configured size and title with a
+ * 3.3 core context, closes cleanly, and resizing it keeps the
+ * viewport correct.
+ * ============================================================
+ */
diff --git a/platformer/src/window.h b/platformer/src/window.h
new file mode 100644
index 0000000..c40dc9e
--- /dev/null
+++ b/platformer/src/window.h
@@ -0,0 +1,43 @@
+/*
+ * ============================================================
+ * FILE: window.h
+ *
+ * PURPOSE: Public interface for the OS window, the OpenGL context and the
+ * clock. Hides GLFW/GLEW setup from the rest of the game.
+ *
+ * FITS IN: Called by main.c (lifecycle, loop), render.c (aspect ratio /
+ * framebuffer size), and controls.c (window handle, only for
+ * the keyboard fallback).
+ *
+ * INTERFACE: Use these exact signatures:
+ *
+ * bool window_init(void);
+ * Creates the window + GL 3.3 core context, loads GL via GLEW.
+ * Returns false (after printing why to stderr) on failure.
+ * void window_shutdown(void);
+ * bool window_should_close(void);
+ * void window_request_close(void); e.g. when Start/Esc is pressed
+ * void window_poll_events(void); once per display frame
+ * void window_swap(void); present the finished frame
+ * double window_time(void); seconds since start (double for
+ * precision over long sessions)
+ * void window_framebuffer_size(int *w, int *h); in PIXELS (for glViewport)
+ * float window_aspect(void); framebuffer width / height
+ * void window_set_title(const char *title); used for a debug readout
+ * struct GLFWwindow *window_handle(void); ONLY controls.c may use this
+ *
+ * Include <stdbool.h>. Forward-declare `struct GLFWwindow;` rather than
+ * including GLFW here, so files that include window.h don't pull in GLFW.
+ *
+ * CONVENTIONS: Include guard: WINDOW_H.
+ *
+ * NOT IN SCOPE: Fullscreen toggle, multiple windows, mouse capture.
+ *
+ * DONE WHEN: The header compiles on its own and main.c can drive the whole
+ * window lifecycle through it.
+ * ============================================================
+ */
+#ifndef WINDOW_H
+#define WINDOW_H
+
+#endif /* WINDOW_H */
diff --git a/platformer/src/world.c b/platformer/src/world.c
new file mode 100644
index 0000000..2dffb72
--- /dev/null
+++ b/platformer/src/world.c
@@ -0,0 +1,29 @@
+/*
+ * ============================================================
+ * FILE: world.c
+ *
+ * PURPOSE: The blank test world: an empty, flat square of ground where we
+ * tune movement. It stays empty on purpose, like the test space
+ * SM64's team used before building real levels.
+ *
+ * FITS IN: Implements world.h. Has no dependencies besides config.h and
+ * math3d.h. physics.c is its main caller.
+ *
+ * IMPLEMENT:
+ * - world_init(): nothing to do yet. Leave a comment saying this is where
+ * level data would be loaded.
+ * - world_ground_height(x, z): return 0.0f. Mark the unused parameters with
+ * (void)x; (void)z; so -Wextra stays quiet, and add a comment saying this
+ * is where a heightmap/platform lookup will go.
+ * - world_clamp_to_bounds(p): clamp p.x and p.z with clampf from math3d.h.
+ * - world_spawn_point(): return vec3_make(0, 0, 0).
+ * - world_half_extent(): return WORLD_HALF_EXTENT.
+ *
+ * CONVENTIONS: Y up. The ground surface is the plane y = world_ground_height.
+ *
+ * NOT IN SCOPE: Anything that isn't flat ground. Don't build a collision
+ * system "for later"; add it when the first platform shows up.
+ *
+ * DONE WHEN: It compiles warning-free, and the player can't leave the square.
+ * ============================================================
+ */
diff --git a/platformer/src/world.h b/platformer/src/world.h
new file mode 100644
index 0000000..9553938
--- /dev/null
+++ b/platformer/src/world.h
@@ -0,0 +1,40 @@
+/*
+ * ============================================================
+ * FILE: world.h
+ *
+ * PURPOSE: Public interface for "the level". Today the level is a blank,
+ * flat square of ground, and this API is how other modules ask
+ * questions about it.
+ *
+ * FITS IN: physics.c asks for the ground height and bounds. main.c asks
+ * for the spawn point. render.c asks for the extent so it knows
+ * how big a grid to draw.
+ *
+ * INTERFACE: Use these exact signatures:
+ *
+ * void world_init(void);
+ * float world_ground_height(float x, float z);
+ * Height of the ground at (x, z). Returns 0.0f for now. This is
+ * the one hook where terrain/platforms will plug in later.
+ * Vec3 world_clamp_to_bounds(Vec3 p);
+ * Returns p with x and z clamped to [-WORLD_HALF_EXTENT,
+ * +WORLD_HALF_EXTENT]. y is untouched.
+ * Vec3 world_spawn_point(void);
+ * Where the player starts / resets to: (0, 0, 0) for now.
+ * float world_half_extent(void);
+ * Returns WORLD_HALF_EXTENT (so render.c doesn't need config
+ * knowledge of the world's shape).
+ *
+ * Include "math3d.h".
+ *
+ * CONVENTIONS: Include guard: WORLD_H.
+ *
+ * NOT IN SCOPE: Level files, platforms, walls, slopes, objects.
+ *
+ * DONE WHEN: physics.c and render.c can be written using only this header.
+ * ============================================================
+ */
+#ifndef WORLD_H
+#define WORLD_H
+
+#endif /* WORLD_H */