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
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
|
# 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` 6 m/s at full tilt).
The top run speed is kept modest **on purpose**: future moves will be how players go faster, and a
slower base run makes precise movement easier.
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.
- **The character is heavy.** Starts build up and stops skid: the player should feel like a real,
tangible object, but never like they're on ice. From rest, full tilt reaches top speed in 43 ticks
(0.72 s, `PLAYER_GROUND_ACCEL` 8.4 m/s²). Releasing the stick at full speed skids to a stop in 31 ticks
(0.52 s, 1.45 m, `PLAYER_GROUND_FRICTION` 12.0 m/s²). Heaviness is felt as *time*, so if you change
`PLAYER_MAX_SPEED`, rescale accel and friction to keep these times (at a lower top speed, the same
accel reaches it sooner and feels snappier).
- **Turning is quick but not instant while moving** (`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.
- **Turning on a dime from a standstill.** On the ground at speed 0, a stick push more than 90°
(`PLAYER_SNAP_TURN_DEG`) away from the facing direction faces it on the very first tick. Pushes of
90° or less use the normal quick turn rate (a 90° turn takes 8 ticks, 0.13 s), so small aim
adjustments stay smooth. This applies only on the ground; in the air the reduced turn rate always
applies.
- **Air keeps momentum.** In the air the turn rate is 30% of the ground rate (`PLAYER_AIR_CONTROL`), and
acceleration has its own constant (`PLAYER_AIR_ACCEL` 9 m/s², the old 30% of the ground accel, kept when
the ground got heavier so jumps steer the same). There's 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.
- **Jump buffer: an early press still counts.** An A press is remembered for `PLAYER_JUMP_BUFFER`
(0.1 s), and the first moment within that time a jump is possible, it happens. On the ground
that's instant. Pressed while still falling, it fires on the landing tick: presses up to 6 ticks
(0.10 s) early give the second jump, and 7 or more give nothing. Pressed just before grabbing a
wall, it fires as an early wall jump the moment you grab. Holding A still decides hop vs. full
jump. **Why:** players pressed a hair early while falling and lost the second jump.
- **A normal jump rewards a full run with a little extra speed.** In a normal jump the top speed is
`PLAYER_JUMP_MAX_SPEED` (7 m/s). Up to run speed (6 m/s × stick) the air accelerates as usual; past
it, only at `PLAYER_JUMP_BOOST_ACCEL` (1.5 m/s²), so a full jump from a full run builds evenly:
6.25 / 6.50 / 6.75 / 7.00 m/s at 0.17 / 0.33 / 0.50 / 0.67 s, landing at 6.97. A short hop lands at
about 6.5, and a standing jump only reaches 6. After landing with the stick held, the extra fades at
`PLAYER_OVERSPEED_DECEL` (2 m/s²): back to 6 m/s in 29 ticks (0.48 s), **never in one step**.
Releasing the stick still uses normal friction (7 → 0 in 0.62 s). Knock-on effects: a skid right
after landing starts from ~7 m/s (a longer slide), and a second jump bleeds 7 → 5 in 0.57 s.
Hopping again just after the 0.2 s window closes keeps you at about 6.5–7 m/s indefinitely (a
bunny hop). That's a speed tech we haven't decided on yet.
- **The second jump (SM64's double jump).** Landing any first jump (hop or full) or a retreat jump
turns on `heightened_movement` for `PLAYER_SECOND_JUMP_WINDOW` (0.2 s, 12 ticks counting the landing tick).
Pressing A while it's on launches at `PLAYER_SECOND_JUMP_VELOCITY` (18.41 m/s): a full second jump
reaches **4.08 m** (1.75× the first, measured at 60 Hz, 54 ticks of airtime), and tapping A gives
about 1.4 m. `heightened_movement` stays on for the whole second jump, whatever its length, and turns
off when it lands, so the second jump can't chain into another.
- **The second jump trades speed for height.** Until it lands, the top speed is
`PLAYER_SECOND_JUMP_MAX_SPEED` (5 m/s) instead of 6. Taking off at a full run bleeds the extra
speed off gradually at `PLAYER_SECOND_JUMP_SLOWDOWN` (3.5 m/s²), reaching 5 m/s after 19 ticks (0.32 s)
of the 0.90 s jump. While the player is over the cap, the stick only turns them; the bleed happens
whatever the stick does. A full-speed second jump covers about 4.8 m (it was 5.4 m uncapped).
**Don't bleed at `PLAYER_AIR_ACCEL`:** the first version did (6 → 4 m/s in 0.25 s), and it felt like
hitting a wall of syrup right at takeoff. After landing, normal ground accel brings 6 m/s back in about 0.23 s. There's
no extra state for this: `jump_number == 2` already means "in the second jump", and `top_speed()`
in `player.c` reads it. Walking off an edge and landing
also turns it off. A press on the landing tick already counts.
- **The skid (SM64's turnaround skid).** At full run and above (at least 95% of `PLAYER_MAX_SPEED`,
`PLAYER_SKID_SPEED_FRACTION`, so faster future moves count too), pulling the stick more than 130°
(`PLAYER_SKID_ANGLE_DEG`) off the run direction enters the `SKID` state. The player **faces the stick at once**
(and keeps tracking it) while still sliding the old way (`skid_yaw`), so they're turned around and
sliding backward. There's no steering. The skid always lasts `PLAYER_SKID_DURATION` (0.5 s, 30 ticks)
and ends stopped, with speed following `start × (1 − (t / 0.5)^PLAYER_SKID_GLIDE_POWER)`. At power 2
(**glide, then plant**), braking starts near zero and builds: from 6 m/s the speed is 5.76 / 5.04 /
3.84 / 2.16 m/s at 0.1 / 0.2 / 0.3 / 0.4 s, the slide covers 1.95 m, and braking peaks at about 24 m/s²
right at the end. A higher power glides longer and plants harder, and 1 is even braking.
`retreating_movement` is on for the whole skid. Pushing sideways (90°) never skids. Sliding off an
edge ends the skid and keeps the slide's direction in the air.
**History:** the first skid braked evenly at 18 m/s² (0.33 s) and turned only at the end. The user
wanted it longer, gentler at first ("a short slide rather than a fast turnaround"), and facing the
stick immediately.
- **The retreat jump (like SM64's side flip).** Pressing A at any point during the skid launches the player
the way they already face (toward the stick, or where it last pointed if it was let go) at `PLAYER_RETREAT_JUMP_SPEED` (4 m/s)
in that direction, which is also its top speed until landing. It uses `PLAYER_RETREAT_JUMP_VELOCITY`
(19.66 m/s): a full retreat jump reaches **4.67 m** (2.00× the first jump, the highest jump), with
59 ticks of airtime and about 3.9 m of travel; a tap gives about 1.4 m. `retreating_movement` stays
on through the jump and turns off on landing. Landing it **does** open the second-jump window
(`heightened_movement`, 0.2 s), so skid → retreat jump → second jump chains. `heightened_movement` is
also on for the whole retreat jump, so it can grab a wall.
- **`heightened_movement` rules, all in one place.** It's on during the second jump, retreat jump,
every wall jump and every wall hang, and for a 0.2 s window after landing a normal or retreat jump
(the window only counts down while not in a jump). It is **not** on during a plain first jump, so a
single jump can't grab a wall. **We tried it the other way:** players expected to wall hang off one
jump, but it made wall hangs too strong, so it was reverted. It turns off when the window runs out,
when landing a second jump or plain fall, or when a wall hang runs out. On the ground it means "A
gives the second jump"; in the air it means "can wall hang".
- **The wall hang (`WALL_HANG`).** Grabbing a wall needs all of these: `heightened_movement` is on,
the player is in the air (JUMP or FALL), they hit the side of a box with `allows_wall_hang`, and
they came in within 45° of head-on (`PLAYER_WALL_HANG_ANGLE_DEG`), **and** their jump wouldn't
carry their feet over the wall's top anyway (apex = y + vy²/2g below the top). A 50° hit slides
along the wall as usual. The **clear-the-top rule** means hopping onto a ledge from just below its
lip with a heightened jump lands on top instead of grabbing the face. It was added when every jump
could grab and kept after the revert, since it also stops second jumps snagging on lips. Measured
with a heightened jump: 1.2 m under the cliff's lip lands on top, while 10 m lower grabs the face. On grabbing, the player **turns to face where the wall jump will launch** (the
mirrored direction below, so the nose previews the jump), stops, and slides down with gravity off:
`vel.y = −min(3 m/s² × t, 2 m/s)` (`PLAYER_WALL_SLIDE_ACCEL`, `PLAYER_WALL_SLIDE_MAX_SPEED`). That's
0.45 / 0.90 / 1.35 / 1.50 m/s at 0.15 / 0.30 / 0.45 / 0.50 s, and about 0.4 m of slide over the
whole hang. (The 2 m/s cap is only reached if the hang lasts past 0.67 s.) After
`PLAYER_WALL_HANG_DURATION` (0.5 s, 30 ticks) the player lets go: they drop
straight down at normal gravity, with `heightened_movement` off so they can't grab again before
landing. Sliding onto a floor is an ordinary landing, and sliding past the wall's bottom or end
lets go early.
- **The wall jump.** A during the hang jumps along the approach direction **mirrored off the wall**:
the part along the wall is kept and the part into it flips, so coming in 5° from the left leaves 5°
to the right (measured: 175° in → 5° out, 210° in → −30° out). In the first 0.1 s of the hang
(`PLAYER_WALL_JUMP_EARLY_TIME`, 6 ticks) it's a **second jump**: 4.08 m up, launched at 5 m/s.
After that it's a **normal jump**: 2.33 m up, launched at 6 m/s, and landing it opens the usual
0.2 s window. **Both keep `heightened_movement` on for the whole jump**, so any wall jump can grab
the next wall. (At first the late one turned it off, and players found wall jumps that
wouldn't grab the next wall.) Each
takes on everything about its jump kind (top speed in the air, the variable-height cut, what
landing does). **One wall can't be grabbed twice in a row:** the wall *surface* you jumped off (same
facing, same face position) is locked out until you land, so holding toward it can't climb it
forever. Comparing surfaces rather than boxes matters on the cliff, which is built from side-by-side
strips: zigzagging along one face can't climb it. Two walls facing each
other can still be chained: in the chimney, each early wall jump gains 3.3 m and crosses in 39 ticks.
- **`heightened_movement` and `retreating_movement` are named player states on purpose.** They're
fields on `Player`, separate from the IDLE/RUN/SKID/JUMP/FALL/WALL_HANG action, because later moves are meant
to key off them. Which jump the player is in is `jump_kind` (`JUMP_NORMAL`, `JUMP_SECOND`,
`JUMP_RETREAT`); the jumps share the `JUMP` action. The title bar
shows `| heightened` / `| retreating` while they're on (the title refreshes every 0.25 s, so the
0.2 s window may blink briefly or not show at all; the jumps themselves always show
it). The skid and wall hang also show as `SKID` / `WALL_HANG` in the state slot.
- **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 12 m radius, 24 m across, at 6 m/s). 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.
- **Locked-pan zones** (`ZONE_LOCKED_PAN`, non-solid boxes from `level_build_zones`, drawn as sparse
black dashes on see-through faces). While the middle of the player's body is inside one, the camera
**doesn't swing behind them** on its own. The stick, recenter, framing/lead room and auto-tilt all
still work. **One box** covers the whole cliff and its climb band (out about 20 m past the south and east
faces, taking in some of the river too) from the ground to exactly the 55 m top, so on the summit
the swing resumes. Crossing platforms one tier below the top (53.5 m) are still inside it. Measured: a 3 s sideways run
swings the camera 1.05 rad normally, and 0.00 inside a zone.
- **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
> **Platform size rule: platforms are ~5 m across at minimum.** Only the most extreme challenges
> (or secrets) go smaller. **Why:** the player is heavy. Starts build up, stops skid for half a
> second, and a normal jump lands with momentum. At this size or larger, the player feels they have
> **space**: room to land, skid and line up the next jump, without a small ledge turning every
> landing into a fall. Apply it to anything new, hand-placed or generated. A smaller platform is a
> deliberate choice that should read as a special challenge, never a default.
> (Right now the cliff course generator uses 4–6 m, `ROUTE_MIN_SIZE` / `ROUTE_MAX_SIZE` in
> `level.c`; its minimum should move up to ~5 m to follow this rule. The random test platforms
> around spawn, 2–6 m, predate the rule.)
- **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).
- **Wall hanging is opt-in per box.** `Box.allows_wall_hang` is false by default. The level marks
**big terrain surfaces** (cliffs, rock pillars, the wall course's walls) and never small platforms, so
ordinary platforming never gets sticky. Hangable walls are drawn **violet** (`COLOR_WALL_HANG`), and
hangable rock is **violet-tinted rock** (`COLOR_CLIFF_HANG`), so you can tell at a glance.
- **Level content lives in `level.c`; `world.c` only stores it, moves it, and answers queries.**
- **The wall course** (`WALL_COURSE` in `level.c`) is straight ahead of the starting camera, 33–48 m
toward −Z and clear of the random platforms. It has a 12 × 8 m main wall (hangable, facing spawn), a
chimney (two 10 m hangable walls with a 4 m gap, entered from the end facing spawn), a 1.5 m step
block in front of the main wall, a ledge on the main wall at 4–4.5 m (x −2..1), a slab at 5.5–6 m
off the wall's left end, and an 8 m terracotta pillar that is *not* hangable, for comparison. The
layout is a first guess for tuning. Note the ledge: jumping into the main wall right under it hits
the ledge's side first, which isn't hangable.
- **The cliff course** (`level.c`, seeded from `CLIFF_COURSE_SEED`) is **behind** spawn (+Z, so turn
around). It's meant for **expression, not a skill check**: a scatter of platforms you read and
choose a way through, some moving, some leading nowhere, some that look possible and aren't.
- **The cliff** is a right triangle, 55 m tall. The south face (z = 40, facing spawn, x −30..20) and
the east face (x = 20, z 40..90) meet at the south-east corner. The third side faces north-west,
built as 10 strips stepping down the diagonal. **The cliff is hangable** (violet-tinted rock), and
so are 7 tall rock pillars 4–6 m out from the faces, which form random chimneys with it. The pillars
are placed after the route and never block one of its hops. The rule is that big terrain surfaces
are hangable and small platforms aren't.
- **Height tiers:** every still platform's top sits on a **1.5 m grid** measured down from the cliff
top (`TIER_HEIGHT`). One tier up is a single jump and two tiers up is a double (second) jump, so
which one a gap needs reads at a glance.
- **How it's generated:** a band wraps the cliff (along the south face, around the corner, up the
east face). Each row out from the face turns the corner at its own spot, so distance along the
band is continuous. On it:
1. One hidden **route** from the ground to one tier below the top, made of **big platforms (4–6
m)**, because the player's weight makes small ledges skid-offs. The platforms sit **1.5–13 m out
from the face** (not hugging it; only the last few come in, for the hop onto the top). Steps
are **mostly singles (+1.5 m)**, with doubles (+3.0 m) mixed in as needed and **never two
doubles in a row**. Measured on the current seed: 19 singles, 8 doubles, 1 level step, 0
back-to-back doubles. The path between each pair is checked clear. A step either goes along
the band or **switches rows** (out a row, or back in, at the same spot along the face). It
switches more when it's ahead of schedule, so it arrives (`ROUTE_ARRIVE_BY`) without running
off the face. Hops in toward the face are singles. When stuck, it tries easier hops, then a
scan of nearby spots.
2. A **scatter** of 6 platforms, each a **single hop beside a route platform**, level with it or
one tier up or down. They're branches, shortcuts and dead ends, mostly reachable with one jump.
3. **The crossing:** a tiered route (mostly up or level, never two doubles in a row) from the
top's north-west corner over the river to the **far cliff, 58 m** (two tiers above the top,
hangable, the finish), plus 2 extras beside it.
In total that's **39 platforms** (the user asked for 30–40), 7 of them moving. Climb platforms
average 6.2 m from the cliff face.
- **Moving platforms:** each slides back and forth along the band, bobs up and down, or loops a
flat or upright circle, with its own 3.5–7 s period and phase (`BoxMotion` in `level.h`). Every
motion passes through its placed position each cycle, and no two moving route platforms are in a
row, so waiting always works. They keep 1.0 m from rock (more than the player is wide, so they
can't pin you) and stay 1 m above the ground. The finish **needs** at least one of them.
- **Placement rules:** nothing overlaps. Platforms nearly over one another (within 0.3 m sideways)
are 4.3 m apart vertically, so none blocks a jump from another.
- **Verified by a headless course test** (outside the repo). It builds a reachability graph with a
conservative jump model, sampling the moving platforms over 60 s. The bot then plays every
plausible upward hop between still platforms and drops the ones that fail (30 played, 0 failed).
The top and the finish are reachable. With one route and ~39 platforms, most route platforms are
the only way past their spot in the graph. The graph doesn't count wall hangs, though, and the
hangable cliff and pillar chimneys offer other ways up. **The user asked for ambiguity:** jumps
that fail or dead ends are fine, as long as the course as a whole can be finished. Don't tighten
it into a clean, obvious path.
- **Topping out:** the route's last hop is a single jump (no wall grab). With a second jump, the
clear-the-top rule lands you on top instead of grabbing the face. The generator's hops in toward
the face are singles, so they can't grab the face on an overshoot.
- **The river** is 13 overlapping water tiles (`BOX_STYLE_WATER`, a solid 5 cm sheet, no swimming)
along the diagonal, parallel to the third side.
- **Known rough edges:** there's no camera collision, so the camera passes into the cliff and
through platforms (it's even more noticeable here). A fall from the top is a 55 m drop with no
damage, and Back resets. Jumping off a moving platform doesn't keep its momentum (SM64 mostly
doesn't either). Changing the seed gives a new climb; re-run the course test if you do, or after
changing movement numbers.
- **Box styles** (`Box.style`: `BOX_STYLE_PLATFORM` by default, `CLIFF`, `WATER`) only change color
in `render.c`; collision ignores them. Every box literal spells out all four fields, since the
build warns on missing initializers.
- **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. The 4.08 m second jump can reach 14 of
the 16 slabs straight from the ground; the two with tops at 4.11 m and 4.17 m still need a block. Only 9 of 16 floating slabs have a block close
enough to jump from; reachability isn't guaranteed yet. That count was made at a 9 m/s run. At 6 m/s a
full running jump covers only about 4.0 m horizontally (it was about 6 m), so fewer slabs may be
reachable now.
- **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.
- Every push out of a box's side sets `Body.hit_wall`, the side's `wall_normal` and its `wall` box.
That's how the wall hang knows what it touched. `Body.gravity_scale` (normally 1) lets the
player switch gravity off while it drives its own wall slide.
- **Moving platforms carry you.** `main.c` calls `world_update` before the player each tick. Physics
first moves a body by however far its `ground_box` moved (so you ride up, down, sideways and round
loops: 0 fall-offs and 4 cm of drift over 16 s on every moving platform). Then it steps the body out
of any box that moved into it, along the shortest way. Still boxes never trigger the step-out.
- **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. The 4.08 m second jump makes this 1.75× as
noticeable.
- **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.
- **Reversals below full run are still light.** At full run, pulling back skids (see the skid
section). Below 95% of top speed, pulling back still swings around in a tight 0.26 s U-turn with all
the speed kept, since velocity always points along the facing direction. Extending the skid to
slower runs is listed under `NOT IN SCOPE` in `player.c`.
- **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 6 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° |
| Top run speed | 9 → 7 → 5 → 6 m/s (slower on purpose; later moves add speed) | 6 m/s |
| Ground accel | 30 → 12 → 7 → 8.4 m/s² (0.30 → 0.60 → 0.72 s to top speed; the last step kept 0.72 s at 6 m/s) | 8.4 m/s² |
| Ground friction | 40 → 16 → 9.5 → 11.3 → 12.0 m/s² (0.23 → 0.45 → 0.53 → 0.52 s stop; 11.3 kept 0.53 s at 6 m/s, then a hair quicker) | 12.0 m/s² |
| Air accel | 30% of ground accel → its own constant, value kept | 9 m/s² |
| Second jump height | 2× (19.66 m/s) → 1.75× (18.41 m/s), sets `heightened_movement` | 18.41 m/s |
| Second jump window | 0.5 s → 0.3 s → 0.2 s after landing | 0.2 s |
| Second jump from | normal jump landings → also retreat jump landings | both |
| Normal jump top speed | 6 m/s (run speed) → 7 m/s, built at 1.5 m/s², eased back at 2 m/s² after landing | 7 m/s |
| Retreat jump | + `heightened_movement` for the whole jump (it can wall hang) | on |
| Wall hang | added: 45° grab, 0.75 s, slide 3 m/s² capped at 2 m/s, mirrored wall jump (second-jump-like for 0.1 s, then normal) | — |
| Wall hang duration | 0.75 s → 0.5 s (early wall jump window kept at 0.1 s) | 0.5 s |
| Cliff course | hand-placed single path → generated (2 routes + ~135 platforms) → 1 route + extras, ~37 big platforms (3–4.5 m), hangable rock, moving platforms | seed 20260930 |
| Wall lockout | per box → per wall surface (the cliff is several boxes) | surface |
| Late wall jump heightened | off → on (late wall jumps couldn't grab the next wall) | on |
| Facing while wall hanging | into the wall → the wall jump's launch direction (a visual preview) | launch dir |
| Jump buffer | none → 0.1 s (early presses fire on landing / grab) | 0.1 s |
| First jump heightened | off → on (a single jump can wall hang), plus the clear-the-top rule | (reverted below) |
| Skid pull-back angle | 120° → 130° (must pull more squarely back) | 130° |
| First jump heightened (revert) | on → off again (wall hangs off one jump were too strong); clear-the-top rule kept | off |
| Cliff course platforms | 3–4.5 m → 4–6 m, 1.5–13 m out from the face, heights on a 1.5 m tier grid, no back-to-back doubles, far cliff 60 → 58 m | 39 |
| Second jump top speed | 6 m/s (same as running) → 4 → 5 m/s until it lands (4 felt a tad harsh) | 5 m/s |
| Second jump slowdown | air accel 9 m/s² (0.25 s, "wall of syrup") → own rate 3.5 m/s² (0.60 s) | 3.5 m/s² |
| Skid | none (full-speed U-turn) → 18 m/s² even braking, turn at the end (0.33 s) → face the stick at once, glide-then-plant curve (power 2) | 0.5 s |
| Retreat jump | added: 2× height, launched at 4 m/s toward the stick, sets `retreating_movement` | 19.66 m/s |
| Standstill turn | turn rate → instant at speed 0 → instant only past 90° (ground only) | > 90° instant |
---
## 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), the FPS counter in the top-right corner (vsync caps it at the display rate), 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.
|