summaryrefslogtreecommitdiff
path: root/platformer/game_feel.md
blob: 6fc4a2e226aa546514ec7fb121ed0fbd4b51a227 (plain) (blame)
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
# 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 32 ticks
  (0.53 s, 1.54 m, `PLAYER_GROUND_FRICTION` 11.3 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.
- **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 120°
  (`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` and `retreating_movement` are named player states on purpose.** They're
  fields on `Player`, separate from the IDLE/RUN/SKID/JUMP/FALL 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 also shows as `SKID` 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.
- **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. 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.
- **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 m/s² (0.23 → 0.45 → 0.53 s stop; the last step kept 0.53 s at 6 m/s) | 11.3 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 |
| 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.