From 87486b2f6c11791d1e192bba8a583a994f273201 Mon Sep 17 00:00:00 2001 From: Schark Date: Tue, 29 Sep 2026 18:02:03 -0400 Subject: Add game_feel for agentic work --- platformer/game_feel.md | 228 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 228 insertions(+) create mode 100644 platformer/game_feel.md 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. -- cgit v1.2.3-18-g5258