summaryrefslogtreecommitdiff
path: root/platformer/game_feel.md
diff options
context:
space:
mode:
authorSchark <jordan@schark.online>2026-09-29 18:02:03 -0400
committerSchark <jordan@schark.online>2026-09-29 18:02:03 -0400
commit87486b2f6c11791d1e192bba8a583a994f273201 (patch)
treed81dcddc1dc3da66b2ba7f7a20a6b737db3a7cd2 /platformer/game_feel.md
parent438831b93e409719900c629ef1c1acddc3632645 (diff)
downloadgamedev-87486b2f6c11791d1e192bba8a583a994f273201.tar.gz
gamedev-87486b2f6c11791d1e192bba8a583a994f273201.zip
Add game_feel for agentic work
Diffstat (limited to 'platformer/game_feel.md')
-rw-r--r--platformer/game_feel.md228
1 files changed, 228 insertions, 0 deletions
diff --git a/platformer/game_feel.md b/platformer/game_feel.md
new file mode 100644
index 0000000..2d96731
--- /dev/null
+++ b/platformer/game_feel.md
@@ -0,0 +1,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.