1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
|
# 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 `"<name>" (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
|