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
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
|
# Game feel guide
This is a handoff for anyone (agent or person) changing movement, the camera, or the level. The
README covers *how the code is organized*; this file covers *how the game should feel*, which
decisions got us there, and which traps we've already stepped in. Read the README's guiding
principles first; everything here builds on them.
Every number below is current as of this writing. The source of truth is `src/config.h`.
---
## The feel, in one paragraph
An SM64-inspired platformer with a **responsive, analog character** and a **patient, cinematic
camera**. The character does exactly what the stick says. The camera behaves like a calm camera
operator: it holds still whenever it can, lets the player sit off-center, and makes its own
adjustments **slowly and smoothly**. Slowness is the signature. Playtesters singled out the slow
automatic panning as what "really nails the feel", and every tuning pass since has moved automatic
camera motion slower and softer, never faster. When in doubt, make automatic camera motion slower
and eased, not snappier.
---
## Non-negotiables
1. **Fixed 60 Hz simulation.** All game logic runs in fixed `TICK_DT` steps (see `main.c`). Every rate
multiplies by `dt`. This makes jump heights and speeds identical on every machine, which is the
only way tuning by feel can work.
2. **All tuning lives in `src/config.h`**, one constant per concept, each with a comment that says
what it changes about the *feel* ("lower = softer start and stop"). No magic numbers elsewhere for
anything a designer would tune. Names ending in `_DEG` are in degrees (easier to tune by eye);
everything else is radians, meters, and seconds.
3. **The prompt block at the top of each source file is its documentation.** When you change
behavior or an interface, update that file's prompt, every other prompt that mentions it, and the
README. Future work is generated from those prompts, so letting them go stale breaks the next pass.
4. **README principles still hold:** minimal files, minimal dependencies (GLFW + GLEW + OpenGL + libc),
minimal scope, readable C99.
---
## Character movement
- **Speed follows the stick.** Tilt amount sets target speed (`PLAYER_MAX_SPEED` 9 m/s at full tilt).
The left stick uses a **radial** deadzone so diagonals and slow walking stay smooth. Never snap
the left stick to axes; movement must stay free in every direction.
- **Camera-relative controls.** Stick up = away from the camera.
- **Turning is quick but not instant** (`PLAYER_TURN_RATE` 12 rad/s, about 0.26 s for 180°). The nose on
the player box exists so the turn rate can be judged by eye.
- **Stops are short and smooth:** from full speed, friction stops the player in about 14 ticks (0.23 s).
- **Air keeps momentum.** Air control is 30% of ground accel and turn rate, with no friction when the
stick is released (SM64-style).
- **Variable jump height.** Holding A gives a full jump; releasing early multiplies upward speed
by `PLAYER_JUMP_CUT` once. Measured at 60 Hz: a full jump reaches **2.33 m** (the "~2.4 m" in comments
is the continuous-physics figure) and a tap gives about 0.72 m. Level geometry is sized against 2.33 m.
- **A jump pressed on the landing tick is never lost.** The FALL state hands off to the ground
logic on the same tick it detects landing.
- **SM64-style circling is intentional.** Controls stay purely camera-relative even while the camera
swings on its own, so holding the stick sideways during a camera swing makes the player run a
wide arc (about 18 m radius, 36 m across). The user explicitly chose this over locking the stick direction.
**Don't "fix" it without asking.**
---
## The camera (the heart of the feel)
### How it's modeled
The camera stores **where the player sits on screen** (`framing`, in NDC), **how far away** they are
(`depth`), and yaw/pitch. The eye position is derived from those every tick. This is what keeps
the rules simple (zone rules are clamps on `framing`), and it's why orbiting keeps the player at
the same spot on screen (the camera orbits the *player*, not empty space). If you rework the camera,
keep this model or you'll lose several properties below at once.
### The rules that define the feel
- **A still player means a still camera.** A player standing inside the resting zone never moves
the camera. Every ease snaps the last hair to its goal so "settled" means truly motionless, and
the distance lag only catches up *while the player is moving*. The only deliberate exception is
the auto-tilt (below).
- **Off-center is a feature, not a bug.** The player is allowed, even encouraged, to sit away from
the middle of the screen. Don't add automatic re-centering.
- **Screen zones** (window fractions; 0 = left/bottom, 1 = right/top):
| | Horizontal | Vertical |
|---|---|---|
| Resting zone (a stopped player here = no camera motion) | 0.383 – 0.617 | 0.383 – **0.50** |
| Running bound (hard limit; the camera is pushed past it) | 0.333 – 0.667 (thirds) | 0.333 – **0.55** |
The top is lower than the thirds on purpose: when running away from the camera, it keeps the
view **ahead** of the player open so upcoming obstacles stay visible. The running bound is always
`CAMERA_ZONE_INSET` (5% of the window) beyond the resting zone.
- **Runs toward or away from the camera:** the player drifts out to the running bound, and the camera
gets pushed along from there. When they stop, the camera eases (`CAMERA_SETTLE_RATE`) until they
sit exactly on the resting zone's edge.
- **Sideways runs get lead room.** The camera works *ahead* of the player, carrying them to the
**trailing** thirds line (running right → they sit on the left third), so open screen lies in the
direction they're heading. Horizontally, the camera keeps pace; raw sideways drift is
deliberately **not** turned into screen motion. (An earlier blend let half the drift through, and
it pushed the player to the *leading* side after a camera swing: the opposite of the intent.)
- **Back-quarter swing.** On sideways runs the camera slowly turns toward **~30° off directly behind**
the player's motion, on whichever side it's already on (`CAMERA_SWING_SPEED` 0.5 rad/s, scaled by how
sideways the run is). It never snaps fully behind the player on its own; only the recenter button
does that.
- **Auto-tilt.** After **2 s** with no manual camera input (right stick, or a recenter click), pitch
eases to **15°**. The motion speeds up gently, cruises at a slow cap, and brakes along the curve
`sqrt(2 * accel * remaining)` so it settles exactly on target without overshoot. A pitch set by
hand is respected until the countdown runs out again; touching the stick stops the tilt
immediately. It only changes pitch, so it runs at the same time as the yaw swing.
- **Recenter (right stick click / `C`)** is a one-shot glide to "behind the player, centered". During
the glide the camera rides along rigidly with the player, so the glide **always finishes, even
mid-run**, and then the zone rules take over again. (The first version chased the player
exponentially, never finished while they ran, and felt like the zone had been deleted.) The right
stick still works mid-glide; it steers the glide's goal instead of fighting it.
- **Reset (Back) also resets the camera.** The camera tracks per-tick movement, so a teleport would
otherwise look like a 100 m sprint.
- **Floor guard:** the eye never drops below `CAMERA_MIN_HEIGHT` (0.5 m) above the player's feet, so it
stays out of the floor at low pitch.
### Manual camera control
- Yaw `CAMERA_YAW_SPEED` 2.5 rad/s (testers like it). Pitch `CAMERA_PITCH_SPEED` **1.125** rad/s, 25%
lower than the original after feedback that up/down was too quick.
- **Right-stick axis snap (`LOOK_AXIS_SNAP_DEG` 15°).** Thumbs never push perfectly straight; with a
radial deadzone a 5° lean became 12.5°/s of unwanted yaw while looking up/down. Pushes within 15°
of an axis become exactly that axis, and the rest of each 45° octant is *stretched* so there is no
jump at the snap edge and true diagonals stay diagonal. We tried 10° and 5°; the user settled on 15°.
The camera code itself has no yaw/pitch crossover: pure up/down input changes yaw by exactly 0.
### How automatic camera motion should move
| Motion | Style | Why |
|---|---|---|
| Framing settle, lead room, recenter, distance lag | exponential ease that snaps at the end | smooth arrival, and truly still afterward |
| Back-quarter swing | constant slow rate | even, predictable, cinematic |
| Auto-tilt | accelerate, cap, brake to target | the user asked for non-linear speed-up and slow-down |
New automatic camera behaviors should follow the same approach: slow, eased, and never snapping.
---
## Level and collision
- **The level is a test space**, like SM64's pre-level sandbox: flat ground plus 40 seeded-random box
platforms (`WORLD_SEED`, so every run is the same layout). Spawn is kept clear (4 m).
- **Heights are sized to the jump:** ground blocks top out at 2.0 m (below the 2.33 m jump); floating
slabs sit at 2.6–4.2 m, reached by jumping from a block. Only 9 of 16 floating slabs have a block close
enough to jump from; reachability isn't guaranteed yet.
- **Collision behaviors worth preserving:**
- Gravity *always* pulls and the floor pushes back, so walking off a ledge falls without special cases.
- Movement is resolved one axis at a time, so running diagonally into a wall **slides** along it.
- The floor check uses the height *before* the move, so even a terminal-velocity fall can't tunnel
through a 0.5 m slab.
- Jumping into an underside bonks.
- **Readability is part of feel.** With no lighting, a one-color box is a flat silhouette and jumps
become guesswork. Platforms use a **fixed brightness per face** (tops brightest). The **drop shadow**
sits on whatever surface you'd land on and is the main depth cue, as in SM64. Keep both if you
touch rendering.
---
## Known tensions and open threads
- **The camera tracks every full jump vertically.** The running bound's vertical span (0.22 of the
window) is smaller than a full jump on screen (about 0.38), so the camera rises and falls with each
jump. SM64's approach, framing vertically against the ground under the player rather than their
airborne height, was offered but not yet decided.
- **Holding sideways never reaches the back quarter.** With circling, the player's "right" turns
with the camera, so the swing chases forever. It only settles when the player steers to hold a line.
- **The starting pitch (20°) differs from the auto-tilt target (15°),** so every session begins with a
small upward tilt. Setting `CAMERA_PITCH_DEFAULT` to 0.26 rad would skip it.
- **High-angle auto-tilt resets are long** (60° → 15° takes about 15.7 s of motion). For big tilts the
top speed (`CAMERA_AUTO_PITCH_SPEED`) sets the time; for small ones, the acceleration does.
- **No camera collision:** the camera can pass through tall platforms (it's on the roadmap).
- **Rough edges not yet addressed:** there's no step-up (even a 0.6 m block needs a jump);
`forward_speed` isn't reduced by walls (the title shows 9 m/s while pushing into one); the drawn
box rotates but the collision box doesn't (up to about 17 cm visual overlap with walls at
diagonals).
---
## Tuning history (so it isn't undone by accident)
| Setting | Path | Current |
|---|---|---|
| Resting zone top | thirds line → half height | 0.50 |
| Running bound top | thirds line → 5% above half | 0.55 |
| Sideways framing | drift to leading side → lead to trailing thirds line | lead room |
| Recenter button | left stick click → right stick click | right stick |
| Auto-tilt delay | 5 s → 4 s → 3 s → 2 s | 2.0 s |
| Auto-tilt angle | 33° → 25° → 15° | 15° |
| Auto-tilt motion | linear 0.15 rad/s → eased, much slower → accel slightly quicker → all 10% slower | 0.054 rad/s cap, 0.045 rad/s² |
| Manual pitch speed | 1.5 → 1.125 rad/s | 1.125 |
| Right-stick snap | none → 15° → 10° → 5° → back to 15° | 15° |
---
## Verifying a feel change
- **Build:** `make` must produce zero warnings. `touch src/config.h && make` rebuilds everything that
uses it.
- **Headless tests are the fastest proof.** `player.c`, `physics.c`, `world.c`, and `camera.c` need no
window or GL, so a scratch `main()` can drive `Input` structs tick by tick. To check framing,
project the player through `camera_projection() * camera_view()` and convert to window fractions;
that measures what the player actually sees. To test `static` helpers in `controls.c`, `#include
"controls.c"` in the test, stub `window_handle()`, and link GLFW.
- **Keep tests out of the repo, and don't copy headers next to them.** `#include "..."` searches the
test's own directory first, so a stale header copy silently wins (this happened once).
- **Report numbers, not impressions:** before and after timings, peak screen positions, settle
times. The user tunes with both numbers and feel.
- **Say what you couldn't test.** Agents can't press the gamepad. Live checks are limited to
launching (`timeout 2.5 ./platformer`), reading the title-bar readout (state, speed, height,
pad/keyboard), and screenshots (e.g. `ffmpeg -f x11grab`).
- **The development pad** is an Xbox Elite Series 2 over USB. GLFW's built-in database lacks its exact
GUID, so an embedded mapping line lives in `controls.c` (`EXTRA_GAMEPAD_MAPPINGS`). Unmapped pads are
printed at startup with their GUID.
---
## Working on this project
- Requests are often small and relative ("a tad", "the slightest bit"). Treat those as roughly
10–25%, **say which constant you changed and by how much**, and show before/after measurements.
- If a request is ambiguous (e.g. "make *it* slower" with several candidates), state your
reading explicitly and offer to switch. We've guessed wrong before.
- Don't commit or push unless asked; the user handles git. When reconciling branches, prefer
merges that keep local commit hashes.
- `platformer/Makefile` is **untracked**: the parent repo's `.gitignore` ignores `Makefile`. Changes to
it won't be committed unless that rule changes.
|