# 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. - **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. 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. - **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. - **Heavy stops, but not heavy reversals.** Letting go skids, yet pushing the stick the opposite way at full speed keeps all the speed and swings around in a tight 0.26 s U-turn, since velocity always points along the facing direction. SM64 solves this with a turnaround skid (brake, then turn). That's listed under `NOT IN SCOPE` in `player.c` for now, but it's the natural next step if reversals feel too light next to the stops. - **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² | | 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.