@maccesar/titools 5.1.1 → 5.2.0

package/skills/ti-game/references/physics.md

@@ -0,0 +1,502 @@
+# Physical models and equations
+
+Use this reference to choose movement by its intended feel, derive parameters,
+or explain frame-rate-dependent behavior. A camera angle is not a physics
+model: a top-down character, car, spaceship and billiard ball use different
+rules. The [34-demo catalog](examples.md) covers action, platforms, ball games,
+adventures, board interactions and visual demonstrations.
+
+Verified on 2026-10-12 against upstream
+[`3bea2f4007d4aa515e432ec2a016dd14c5c0f2ba`](https://github.com/m1ga/ti.game/tree/3bea2f4007d4aa515e432ec2a016dd14c5c0f2ba).
+Upstream HEAD still has that commit. Local forks and installed binaries can
+contain additional changes; do not silently treat them as this snapshot.
+
+Each equation is labeled **Engine** (native implementation), **Demo**
+(application rule) or **Analytical** (a mathematical model for tuning).
+An analytical equation does not imply a matching public property exists.
+JS selects controls and reacts to events; frame-by-frame integration stays native.
+
+<!-- TOC-START -->
+## Contents
+
+- [Units and conventions](#units-and-conventions)
+- [Model selection across the demos](#model-selection-across-the-demos)
+- [Sprite integration and constant acceleration](#sprite-integration-and-constant-acceleration)
+- [Thrust, inertia and linear damping](#thrust-inertia-and-linear-damping)
+- [Projectiles and additive impulses](#projectiles-and-additive-impulses)
+- [Arcade car equations](#arcade-car-equations)
+- [Direct character control](#direct-character-control)
+- [Jumps, flaps and scrolling runners](#jumps-flaps-and-scrolling-runners)
+- [Landing and impact measurements](#landing-and-impact-measurements)
+- [Static reflection and arcade ball sports](#static-reflection-and-arcade-ball-sports)
+- [Equal-mass billiards and circular containment](#equal-mass-billiards-and-circular-containment)
+- [Slopes and contact friction](#slopes-and-contact-friction)
+- [Verlet ropes and tethers](#verlet-ropes-and-tethers)
+- [Swept movement and periodic worlds](#swept-movement-and-periodic-worlds)
+- [Paths, tweens and navigation](#paths-tweens-and-navigation)
+- [Rhythm timing](#rhythm-timing)
+- [Particle integration](#particle-integration)
+- [Time step and frame rate](#time-step-and-frame-rate)
+- [What needs a different model](#what-needs-a-different-model)
+
+<!-- TOC-END -->
+
+## Units and conventions
+
+| Quantity | Units |
+| --- | --- |
+| Position, width, height, path distance | Surface pixels, from guarded GameView `resize` |
+| `velocityX/Y`, `maxSpeed` | px/s |
+| `gravity`, `gravityX`, `thrust`, `enginePower` | px/s² |
+| Native `dt` | Seconds |
+| JS `duration`, `after`, `every`, particle lifetime | Milliseconds |
+| `rotation` | Clockwise degrees; 0 points up |
+| `angularVelocity`, `turnRate` | degrees/s |
+| `linearDamping`, car `drag`, car `grip` | 1/s coefficients, not percentage strings |
+| Rope `damping` | Retained displacement fraction per update |
+| `restitution` | Dimensionless, 0..1 |
+
+Origin is top-left; y increases downwards. Position is the sprite anchor.
+For `θ = rotation·π/180`, forward `f=(sin θ,−cos θ)` and right
+`r=(cos θ,sin θ)`. `n` below is a unit contact normal.
+
+## Model selection across the demos
+
+| Model | Examples | What determines movement |
+| --- | --- | --- |
+| Inertial ship | Asteroids | Thrust adds velocity along heading; rotation does not redirect existing momentum |
+| Gravity and replacement jump/flap | Platformer, Flappy, Skate, Flip | Vertical acceleration plus a chosen takeoff velocity |
+| Direct character control | Topdown | Velocity follows input immediately, including diagonal normalization |
+| Arcade car | Racing | Forward/lateral velocity, throttle, steering, drag and grip |
+| Ball with static-surface reflection | Volley, Plinko, Circles, Slopes | Gravity, geometry normals and restitution |
+| Equal-mass circle bodies | Pool, Plinko, Drum, Circles | Bilateral normal impulse and separation |
+| Circular containment | Drum | Keep ball centers inside radius `R−r` |
+| Position constraints | Rope | Verlet displacement and link-distance relaxation |
+| Fast body or instant query | Swept, Raycast, Worldwrap | Swept movement versus a discrete ray query |
+| Prescribed route | Path, Maze, Pointclick, Tilemap, Demoscene | Distance traveled along a path; A* chooses waypoints |
+| Prescribed interpolation | Cards, Puzzle, Basic | Tween destination and easing; drag/snap rules |
+| Timing window | Rhythm | Constant velocity and distance-to-pad acceptance |
+| Ballistic effects | Particles | Native emitter rate, gravity and lifetime; no Sprite solid response |
+| Cross-cutting systems | Camera, Blend, Text, Hitbox, Zones, Timescale | Presentation, geometry, events or clock; not separate locomotion models |
+
+Names map to `example/<name>.js`, with lowercase spelling. These groups cover
+all 34 launcher entries; Lunar Lander in the action recipes is a curated
+composition, not an extra upstream demo. Use [examples.md](examples.md) for
+the exact filenames and [api.md](api.md) for public properties.
+
+## Sprite integration and constant acceleration
+
+**Engine**, without contacts or position overrides:
+
+```text
+vNext = v + a·dt
+pNext = p + vNext·dt
+```
+
+This is semi-implicit Euler: acceleration before position. In Sprite, the
+order is car integration, angular velocity, thrust and its speed cap,
+gravity, linear damping, position, scroll wrap, path, animation, tween and
+idle wobble. Scene collision/attachment passes can change that result again.
+Do not combine several position writers expecting their displacements to add.
+
+**Analytical**, constant acceleration with no cap/contact:
+
+```text
+v(t) = v0 + a·t
+p(t) = p0 + v0·t + 0.5·a·t²
+```
+
+That position is the continuous solution, not the exact discrete output.
+At constant step, `t=N·dt`, Euler gives
+`pN=p0+v0·t+0.5·a·(t²+t·dt)`. Multiplying by dt is necessary but does
+not eliminate integration error.
+
+**Demo Wind**: gravityX values −900..900 px/s², leaves with vertical gravity
+260 and a puck with gravity 0. Constant sideways acceleration is an arcade
+wind field; it is not drag calculated from relative air velocity.
+
+Sources: [Android Sprite.update](https://github.com/m1ga/ti.game/blob/3bea2f4/android/src/ti/game/engine/Sprite.java),
+[iOS TGSprite.update](https://github.com/m1ga/ti.game/blob/3bea2f4/ios/Classes/TGSprite.m).
+
+## Thrust, inertia and linear damping
+
+**Engine**:
+
+```text
+rotation += angularVelocity·dt
+f = (sin θ,−cos θ)                 # updated heading
+v += f·thrust·dt
+if |v| > maxSpeed: v *= maxSpeed/|v|
+v += (gravityX,gravity)·dt
+if linearDamping > 0:
+    v *= max(0,1−linearDamping·dt)
+    if |v| < 4 px/s: v = (0,0)
+p += v·dt
+```
+
+The thrust cap runs only in its active branch; direct velocity writes are
+not capped. Asteroids uses 220 degrees/s turning and both thrust and speed
+cap `0.9·min(W,H)`, with no ship damping. Turning changes the nose, not the
+velocity already accumulated. Assisted flight can deliberately add damping,
+but it is resistance everywhere, not contact-only friction.
+
+**Analytical** damping: `dv/dt=−cv`, hence `v(t)=v0·exp(−ct)` and speed
+half-life `ln(2)/c`. With constant aligned acceleration, `dv/dt=a−cv`
+tends to `a/c`. The engine approximates damping using `1−c·dt`, then
+applies its rest threshold. Box2D documents the same continuous decay but
+uses `1/(1+c·dt)`; do not substitute that for ti.game's implemented formula.
+[Box2D damping reference](https://box2d.org/documentation/md_simulation.html).
+
+### Powered launch below the rest threshold
+
+At rest, thrust220 and damping 1.2 at a 1/60 s step give
+`220/60·(1−1.2/60)=3.593` px/s. The threshold erases it before position
+integration, every step. At120 FPS the problem also occurs; thrust100 can
+be erased even at 30 FPS. This follows from the same formula on both platforms.
+
+For an application that should brake only while coasting, set damping 0
+while thrust is active and restore its chosen coefficient without thrust.
+This changes powered-flight drag. If resistance must remain during thrust,
+the intended correction belongs in the native rest policy, with tests of
+accelerating bodies and resting bodies on both platforms. Do not invent a
+per-frame JS position loop, give an artificial initial velocity, or increase
+thrust solely to escape the cutoff.
+
+Acceleration and resistance together are physically valid. The cutoff is
+the problematic numerical condition. A flame animation proves a visual
+state, not nonzero motion; different device behavior still requires FPS,
+surface, input and installed-build evidence.
+
+### Coasting brake feel reference
+
+**Application profile**, Titanium Asteroids autopilot, recorded 2026-10-12:
+set `linearDamping: 0` while thrust is active and `linearDamping: 1.2` s⁻¹
+when thrust stops. Native braking then multiplies velocity by
+`max(0, 1-1.2*dt)`, with the installed engine's rest cutoff.
+
+César liked the speed of this braking as a reference for other games,
+especially arcade racing, although he did not choose it as the preferred
+feel for Asteroids. Keep the coefficient and activation condition together
+when comparing the feel. This is an optional tuning example, not a default
+for all games or an upstream demo preset. In a racer, evaluate longitudinal
+braking and lateral grip separately before adopting it.
+
+## Projectiles and additive impulses
+
+**Demo Asteroids**, nose launch:
+
+```text
+pBullet = pShip + f·0.55·SHIP_SIZE
+vBullet = vShip + f·BULLET_SPEED
+BULLET_SPEED = 1.2·min(W,H)
+```
+
+Inherited ship velocity is a deliberate application choice. A fixed
+world-speed projectile instead assigns only `f·speed`.
+
+**Analytical** impulse: `Δv=J/m`. The demos add a chosen velocity change
+directly; Sprite has no configurable rigid-body mass. `v+=Δv` bends existing
+motion, whereas `v=vNew` replaces it. Pool strikes are additive, Flappy's
+vertical flap is a replacement, and Drum's SHAKE replaces velocities while
+its contact-driven TUMBLE adds increments.
+
+## Arcade car equations
+
+**Engine carMode**, forward/right axes from the old heading:
+
+```text
+vForward = v·f; vLateral = v·r
+steerFactor = clamp(vForward/(0.25·maxSpeed),−1,1)
+rotation += steering·turnRate·steerFactor·dt
+vForward += throttle·enginePower·dt
+vForward *= max(0,1−drag·dt)
+vLateral *= max(0,1−grip·dt)
+vForward = clamp(vForward,−0.4·maxSpeed,maxSpeed)
+v = fNew·vForward + rNew·vLateral
+```
+
+Recomposition uses the updated heading. A stopped car with zero forward
+speed does not steer; reverse forward speed reverses steering direction.
+Lower grip retains more lateral drift; drag reduces forward speed.
+Negative throttle can brake and then reverse. It is an arcade model,
+without wheelbase geometry, individual tires or weight transfer.
+
+**Demo Racing** uses `maxSpeed=0.8·min(W,TH)`, where TH is track height,
+`enginePower=1.1·maxSpeed`, turnRate 210, grip 3.2 and drag 0.8. These numeric
+values have the units in the table above, not an interchangeable percentage.
+No JS loop should rotate the velocity to reproduce this native model.
+
+Sources: Android Sprite.updateCar and iOS TGSprite.updateCar, at the same
+links as [Sprite integration](#sprite-integration-and-constant-acceleration).
+
+## Direct character control
+
+**Demo Topdown** uses speed `S=3.5·TILE`. For cardinal input it assigns
+`v=(moveX,moveY)·S`; for diagonal input each axis uses `S/sqrt(2)` so
+the combined magnitude remains S. Releasing input writes zero velocity:
+there is no ship-like inertia. For a general nonzero input vector d, the
+application formula is `v=S·d/|d|`; distinguish this from analog magnitude
+control, which may intentionally retain the stick's partial travel.
+
+The demo dog normalizes its target direction at `1.1S` on a decision timer.
+The timer chooses direction; native velocity integrates movement between
+decisions. [Top-down recipe](recipes-action.md#top-down--zelda).
+
+## Jumps, flaps and scrolling runners
+
+**Demo** Platformer assigns `vx=direction·RUN_SPEED` and, on permitted
+grounded input, `vy=−JUMP`. Flappy assigns `vy=−0.6H` per tap; it does not
+accumulate upward impulses. Its tilt tween is visual, not aerodynamic lift.
+Skate keeps player x fixed and moves terrain/obstacles at `vx=−0.5W`.
+
+**Analytical**, gravity `g>0`, takeoff speed magnitude `J`:
+
+```text
+timeToApex = J/g
+height = J²/(2g)
+sameLevelFlightTime = 2J/g
+J for desired height h = sqrt(2gh)
+g for height h and apex time T = 2h/T²; J = 2h/T
+```
+
+| Demo | g | J | Continuous prediction |
+| --- | --- | --- | --- |
+| Platformer | 2.2H | 0.95H | Apex 0.432 s; rise 0.205H |
+| Skate | 2.4H | 0.9H | Apex 0.375 s; same-level flight 0.75 s |
+| Flappy | 1.9H | 0.6H | Isolated flap apex0.316 s; rise 0.095H |
+| Volley players | 2.2H | 0.85H | Apex 0.386 s; rise 0.164H |
+
+Contact geometry, ceilings and discrete integration change actual results.
+`oneWay` allows top landings through otherwise passable platforms; exact
+conditions differ by resolver. Moving solids carry grounded riders using
+their frame delta. Skate's raised scrolling road disables `carryRiders` so
+the player is not dragged off screen. [Action recipes](recipes-action.md).
+
+## Landing and impact measurements
+
+**Engine** `land` reports a grounding transition after solid response.
+Its payload does not include the original velocity. Live `velocityY` can
+already be zero or reflected, and JS event delivery can be later still.
+Do not classify a hard touchdown as gentle by reading that zero value.
+
+For sprite solids, `solidimpact.speed` snapshots relative closing normal
+speed before response, compensated for the frame's own acceleration.
+Set `impactThreshold:0` to include gentle positive impacts and check the
+contact normal/group. It is not full vector speed or an exact post-gravity
+pre-contact sample. A rule involving tangential velocity needs separate
+evidence; solid TileLayer cells do not emit `solidimpact`.
+
+The [Lunar Lander recipe](recipes-action.md#lunar-lander) uses a static sprite
+pad and this normal-impact contract. A resting body with no positive impact
+does not receive an invented impact merely because its threshold is0.
+
+Sources: Android `Scene.resolveSolids`, `dispatchSolidImpact`, `finishContacts`;
+iOS `TGScene.resolveSolids`, `dispatchSolidImpactFor`, `finishContactsFor`;
+see [event payload](api.md#sprite-events).
+
+## Static reflection and arcade ball sports
+
+**Engine**, circle against a static solid, outward normal:
+
+```text
+e = max(eMover,eSolid)
+vn = v·n
+if vn < 0:
+    if e > 0 and −e·vn > 40 px/s: v -= (1+e)·vn·n
+    else: v -= vn·n
+```
+
+This preserves tangential velocity. The small-rebound cutoff belongs to
+this response, not the equal-mass bilateral impulse below. No contact
+friction or collision-generated spin is implied.
+
+**Demo Volley** replaces the ball's velocity on player contact:
+`u=normalize(pBall−pPlayer)`, `S=0.85H`,
+`vx=u.x·S`, `vy=min(u.y·S,−0.45S)`. It guarantees an upward component
+instead of simulating two masses. Scenario walls use native restitution;
+player hits use an arcade rule. Plinko uses gravity 1100, restitution 0.42,
+circle pegs and `push` chips.
+
+Sources: [Android Scene.resolveCircleSolids](https://github.com/m1ga/ti.game/blob/3bea2f4/android/src/ti/game/engine/Scene.java),
+[iOS TGScene.resolveCircleSolids](https://github.com/m1ga/ti.game/blob/3bea2f4/ios/Classes/TGScene.m).
+
+## Equal-mass billiards and circular containment
+
+**Engine**, two visible circles, both `push`, each listing the other's group:
+
+```text
+n = normalize(centerA−centerB)
+penetration = radiusA+radiusB−distance
+if penetration > slop: pA+=n·penetration/2; pB−=n·penetration/2
+vn = (vA−vB)·n
+e = max(eA,eB)
+if vn < 0:
+    j = −(1+e)·vn/2
+    vA += j·n; vB -= j·n
+```
+
+Each pair resolves once. Restitution1 exchanges normal components; tangent
+components remain unchanged. Even differently sized circles are equal-mass
+bodies. Without mutual groups the response falls back to a one-sided solid.
+
+Pool uses restitution 0.96, damping 0.62, and a cue velocity increment
+`2600·min(1,tapDistance/(0.55W))` along the tap direction. That limits the
+strike increment, not total speed when a moving cue is hit again. Pockets
+are triggers, not 3D drops.
+
+**Analytical**, unequal masses would require
+`j=−(1+e)·vn/(1/mA+1/mB)`, then `vA+=j·n/mA`, `vB−=j·n/mB`.
+That is not the current `push` implementation.
+
+**Engine contain**: a ball of radius r inside a container of radius R has
+allowed center distance `R−r`. If exceeded, the correcting normal points
+toward the container center and penetration is `distance−(R−r)`.
+The ball must fit. Drum uses gravity 1400, restitution 0.55, damping 0.35 and
+mutual `push` balls. It mixes impulses/contact response, not a spinning
+rigid drum or fluid simulation. [Shaped-solid patterns](patterns.md#shaped-solids-ramps-round-posts-and-bodies-that-push-back--slopesjs-circlesjs-pooljs-drumjs).
+
+## Slopes and contact friction
+
+Rotated ramps require `rotatedRect` geometry for the real face normal.
+The normal component is cancelled/reflected while tangent velocity remains.
+**Analytical**, on a fixed frictionless slope at angle α from horizontal,
+downslope acceleration magnitude is `g·abs(sin α)`.
+
+Slopes uses gravity 1100, crate restitution 0, ball0.1 and floor/walls0.5.
+Its ball slides; a circle shape does not add rolling torque. Sprite damping
+acts off the slope too and cannot substitute contact-only tangent friction.
+Smooth uphill walking, connected terrain, mass and torque remain outside
+this model. [Limitations](roadmap.md).
+
+## Verlet ropes and tethers
+
+**Engine**, a free node:
+
+```text
+displacement = (pCurrent−pPrevious)·damping
+pPrevious = pCurrent
+pCurrent += displacement + (0,gravity·dt²)
+```
+
+For adjacent nodes, `Δ=pB−pA`, `d=|Δ|`, target length L, correction
+`Δ·(d−L)/d` is split between free nodes, or applied fully to the free node
+when the other is pinned. Division has an epsilon guard. `iterations` repeats
+relaxation: more passes stiffen the result at a CPU cost.
+
+The first Rope demo uses 14 links of length 0.04H, gravity 1.6H,
+damping 0.985 and 3 constraint passes. Nodes do not automatically receive
+Sprite solid collisions. `tail` plus positive `maxLength` additionally
+clamps head-to-tail distance and removes outward radial velocity. With two
+free sprite ends the correction is split; dragging an end makes the other
+yield. It is a positional tether, not a mass/stiffness Hooke spring.
+
+Rope damping is **per update**, not1/s. Before forces and constraints, the
+retained displacement factor over one second at 0.985 would be about 0.635
+at 30 updates,0.404 at 60 and 0.163 at 120. These are not predictions of the
+whole rope's amplitude. An analytical time-normalized alternative would be
+`exp(−c·dt)` or `dRef^(dt/dtRef)`; the engine uses the fixed supplied factor.
+
+At the pinned source, Rope.update has no zero-delta early return. Existing
+Verlet displacement and constraints still run at dt 0; `timeScale=0` is not
+a guarantee that rope nodes freeze. This differs from merely setting the
+gravity term to zero. Scene/hardware acceptance is still needed for a
+pause design; stopping the render loop with `pause()` is a different action
+because it also stops rendering. Do not silently change the global pause
+UX to avoid this boundary.
+
+Sources: [Android Rope.update](https://github.com/m1ga/ti.game/blob/3bea2f4/android/src/ti/game/engine/Rope.java),
+[iOS TGRope.update](https://github.com/m1ga/ti.game/blob/3bea2f4/ios/Classes/TGRope.m).
+
+## Swept movement and periodic worlds
+
+**Analytical** per-step movement is `Δp=v·dt`:9600 px/s travels160 px
+at 60 FPS. A final-position overlap can skip a thin wall.
+Swept tests examine the traveled segment; circle pairs have circular sweeps,
+other shape pairs use their respective geometry/approximations. The solid
+sweep skips `contain`/`push`; those still use discrete responses. It is not
+a general multiple-substep rigid-body simulation.
+
+Raycast is an instantaneous query, not a gravity-driven projectile.
+`wrapAround` uses screen edges; `wrapX/wrapShift` loops scrolling copies;
+`worldWrapX` defines a periodic horizontal world with participating sprites.
+**Analytical** normalization for `L=maxX−minX` is
+`x=minX+((x−minX)%L+L)%L`; nearest image displacement is
+`dx−L·round(dx/L)`. Raycast, A*, particles, ropes and skid trails do not
+repeat at the seam. [Worldwrap contract](api.md#physics).
+
+## Paths, tweens and navigation
+
+**Engine Path** accumulates `distance+=speed·dt`. Within a segment,
+`u=(distance−segmentStart)/segmentLength`,
+`p=pStart+u·(pEnd−pStart)`. Optional rotation is
+`atan2(dx,−dy)·180/π`. A* chooses the waypoints; it does not apply a force.
+Maze/Tilemap use4·TILE px/s. Path motion overrides integrated position;
+a later position tween can override the path again.
+
+**Engine Tween** uses `u=clamp(elapsed/duration,0,1)` after its delay,
+then `value=from+(to−from)·Easing(u)`. Cards, puzzles and Basic use
+prescribed destinations/gestures, not conservation of momentum.
+Camera/parallax, blend, text, flip and pixel snapping are presentation;
+they do not change those motion equations. Snapping rounds the drawn anchor,
+not physical position, and cannot eliminate every rotational raster change.
+
+Sources: [Path.advance](https://github.com/m1ga/ti.game/blob/3bea2f4/android/src/ti/game/engine/Path.java),
+[Tween.update](https://github.com/m1ga/ti.game/blob/3bea2f4/android/src/ti/game/engine/Tween.java).
+
+## Rhythm timing
+
+**Demo**, `vy=(PAD_Y+NOTE)/1.6`, starting at `y=−NOTE`, gives a 1.6 s
+trip to the pad. GOOD allows 0.08H distance and PERFECT0.03H.
+**Analytical** temporal error is `abs(y−PAD_Y)/abs(vy)`; changing fall speed
+changes the milliseconds represented by a fixed pixel window.
+
+At the demo's stated 150 BPM, quarter duration is `60000/150=400 ms`;
+an eighth is200 ms. The400 ms spawn interval and 1.6s travel are one and four
+quarters, respectively. The upstream comments call them eighths, and the
+old action recipe repeated that error. The corrected recipe preserves timing.
+
+This is a comment/recipe error, not evidence of a faulty native beat engine.
+The demo uses `setInterval(spawn,SPAWN_MS)` and independent `music.play()`;
+it has no audio-position-driven scheduling. Exact musical synchronization,
+actual asset tempo and phase would need separate measurement. A comment-only
+upstream patch should not halve SPAWN_MS or replace the motor.
+
+Source: [Rhythm demo](https://github.com/m1ga/ti.game/blob/3bea2f4/example/rhythm.js).
+
+## Particle integration
+
+**Engine** accumulates `rate·dt`, emits the integer part and keeps the
+remainder. Live particles age, receive `vy+=gravity·dt`, then position
+updates with the new velocity. At lifetime they retire. They are effects,
+not Sprite solids or automatic damage sensors. [Particle recipes](recipes-adventure-effects.md#particles).
+
+## Time step and frame rate
+
+Both renderers derive a variable real dt, cap it at 0.1s and then scale by
+`max(0,timeScale)`. They do not run a fixed-step accumulator with physics
+substeps. `maxFps` is a cap, not a guarantee of exact dt. Differences can
+come from Euler error, rest/rebound thresholds, per-update Rope damping,
+surface-based parameters, input/lifecycle or different installed binaries.
+
+GameView timers follow scene time, conventional JS timers do not. Rendering
+and touch continue under timeScale 0; the Rope exception above prevents an
+unqualified promise that every position stays unchanged.
+
+For tuning, capture the build, actual FPS, W/H, timeScale, forces and
+velocities. Check rest-to-powered motion, releases, turns, contacts and pauses
+at 30/60/120 FPS, then validate on the target hardware. Scalar equations and
+source parity are useful evidence, not certificates of identical device feel.
+[Telemetry workflow](debugging-performance.md).
+
+Sources: [Android SceneRenderer](https://github.com/m1ga/ti.game/blob/3bea2f4/android/src/ti/game/engine/SceneRenderer.java),
+[iOS TGSceneRenderer](https://github.com/m1ga/ti.game/blob/3bea2f4/ios/Classes/TGSceneRenderer.m).
+
+## What needs a different model
+
+Assisted spacecraft flight can use deliberate resistance, but it is not
+airplane aerodynamics. A fuller aircraft model needs relative airspeed,
+lift, drag, stall, altitude and bank response. Ships, tires, springs,
+variable masses and collision torque also need separate modeling choices.
+Do not claim those simulations from a sprite's artwork or camera angle.
+See [roadmap.md](roadmap.md) before naming a missing API, and retain the
+distinction between analytical tuning, application rules and native support.

package/skills/ti-game/references/project-setup.md

@@ -78,7 +78,7 @@ ti build -p ios --build-only        # macOS only → ios/dist/ti.game-iphone-<ve
 
 ## Classic projects
 
-`require('ti.game')` anywhere and add the GameView to a window. The 33 demos in the module's `example/` folder are Classic, each one a CommonJS module exporting a start function (`app.js` is the launcher, not a demo):
+`require('ti.game')` anywhere and add the GameView to a window. The 34 demos in the module's `example/` folder are Classic, each one a CommonJS module exporting a start function (`app.js` is the launcher and `backnav.js` is a helper, neither is a demo):
 
 ```javascript
 // Resources/flappy.js
@@ -332,6 +332,28 @@ function unloadLevel(level) {
 
 A single-level game with a handful of sheets should not call it at all: the textures die with the window.
 
+### Retained iOS scenes and multiple GameViews
+
+In the pinned iOS source, `TiGameGameView.didMoveToWindow` calls
+`shutdownRendering` when an attached view loses its window. That teardown
+sets a terminal shutdown flag and releases the renderer. Reattaching the
+same proxy or calling resume is not a documented reconstruction mechanism.
+If a navigation/modal presentation detaches a backdrop that must remain
+alive, keep that GameView attached or create a fresh one on return; rebuilding
+only its Sprite session is insufficient. Verify the actual UIKit presentation
+and installed module on-device.
+
+Multiple retained iOS GameViews also share each physical GCController's
+single `extendedGamepad.valueChangedHandler`. At this pin, each view's
+TGGamepadController installs its own handler and detach clears it. Another
+view can therefore replace or clear an active scene's receiver. Use explicit
+input ownership and test open/close transitions; do not assume independent
+gamepad subscriptions or treat a local fork fix as shipped upstream.
+
+Sources: upstream `ios/Classes/TiGameGameView.m` (`didMoveToWindow`,
+`shutdownRendering`) and `ios/Classes/TGGamepadController.m`
+(`attachController`, `detachController`) at `3bea2f4`.
+
 ### LiveView reloads
 
 A LiveView reload replaces Titanium's JS runtime while the native side survives, which used to leave the previous `GameView`'s render loop running — every reload added another GL thread, and the audio engine handed the new runtime sample ids the old one still owned.

package/skills/ti-game/references/recipes-action.md

@@ -2,6 +2,10 @@
 
 Production-oriented patterns distilled from the upstream action demos at `ti.game@3bea2f4`. Use [examples.md](examples.md) to locate the full runnable demo and [api.md](api.md) for exact defaults and payloads. The wall-contact API is source/README-backed because upstream has not added a wall-jump demo yet.
 
+Use [physics.md](physics.md) for the implemented equations, units, jump tuning,
+inertia versus direct control, and numerical limits. Recipes select native
+mechanisms; they do not replace that model reference.
+
 <!-- TOC-START -->
 ## Contents
 
@@ -19,7 +23,7 @@ Production-oriented patterns distilled from the upstream action demos at `ti.gam
 
 ## Tap-to-flap
 
-Gravity plus an impulse per tap. Scoring and death are collisions with invisible zones. The rotation tween is what sells the arc.
+Gravity plus a replacement vertical velocity per tap, not an accumulated impulse. Scoring and death are collisions with invisible zones. The rotation tween is what sells the arc.
 
 ```javascript
 const pig = Game.createSprite({
@@ -236,8 +240,9 @@ let lastFacing = 'down';
 let walking = false;
 
 function applyMovement() {
-	player.velocityX = moveX * SPEED;
-	player.velocityY = moveY * SPEED;
+	const speed = (moveX !== 0 && moveY !== 0) ? SPEED / Math.sqrt(2) : SPEED;
+	player.velocityX = moveX * speed;
+	player.velocityY = moveY * speed;
 	if (moveX === 0 && moveY === 0) {
 		player.stop();
 		walking = false;
@@ -418,7 +423,13 @@ Rocks are round (`hitboxShape: 'circle'`), drift on random velocities, spin on `
 
 ## Lunar lander
 
-Same flight model as Asteroids, with gravity on and a landing test. There is no "landing" event — you judge the touchdown yourself in the `land` handler, where velocities are still readable.
+Same flight model as Asteroids, with gravity and a touchdown rule. This is a
+curated recipe, not one of the 34 upstream demos. `land` reports grounding
+after the solid response: live velocity may already be zero or reflected.
+For a static sprite pad, use the snapshotted normal speed in `solidimpact`.
+It is compensated for this frame's acceleration, not the full incoming
+velocity vector. Tiles do not emit that event; use a sprite pad when the
+impact must be measured. See [landing evidence](physics.md#landing-and-impact-measurements).
 
 ```javascript
 const lander = Game.createSprite({
@@ -428,6 +439,7 @@ const lander = Game.createSprite({
 	gravity: world.gravity,                    // per-world, e.g. H * 0.35 for the Moon
 	maxSpeed: MAX_SPEED,
 	hitboxScale: 0.8,
+	impactThreshold: 0,                       // include gentle physical impacts
 	solidWith: ['terrain', 'pad'],
 	collidesWith: ['hazard']
 });
@@ -435,12 +447,12 @@ const lander = Game.createSprite({
 const MAX_LANDING_SPEED = H * 0.18;
 const MAX_LANDING_TILT = 12;                   // degrees
 
-lander.addEventListener('land', (e) => {
-	const speed = Math.abs(lander.velocityY);
+lander.addEventListener('solidimpact', (e) => {
+	const speed = e.speed;                    // immutable contact payload, not live velocity
 	const tilt = Math.abs(((lander.rotation % 360) + 540) % 360 - 180);
 	const onPad = e.group === 'pad';
 
-	if (onPad && speed <= MAX_LANDING_SPEED && tilt <= MAX_LANDING_TILT) {
+	if (onPad && e.normalY < -0.7 && speed <= MAX_LANDING_SPEED && tilt <= MAX_LANDING_TILT) {
 		succeed();
 		return;
 	}
@@ -458,12 +470,17 @@ function crash() {
 }
 ```
 
-Thrust burns fuel on the same coarse tick that reads the controls — 80 ms is fast enough to feel responsive and slow enough to stay off the bridge:
+Fuel and control decisions use a coarse game-clock tick. `BURN_RATE` is fuel
+units per game second; each nominal tick removes the rate times its interval.
+GameView timers can fire late and do not catch up after stalls, so this is a
+cadence approximation, not exact elapsed-time accounting. Store the timer ID
+and cancel it with `gameView.cancelTimer(timer)` on cleanup:
 
 ```javascript
-timer = setInterval(() => {
+const CONTROL_MS = 80;
+timer = gameView.every(CONTROL_MS, () => {
 	if (mainThrusterHeld && fuel > 0) {
-		fuel -= BURN_RATE;
+		fuel = Math.max(0, fuel - BURN_RATE * CONTROL_MS / 1000);
 		lander.thrust = THRUST;
 		exhaust.emitting = true;
 	} else {
@@ -471,10 +488,13 @@ timer = setInterval(() => {
 		exhaust.emitting = false;
 	}
 	fuelLabel.text = Math.max(0, Math.round(fuel)) + '%';
-}, 80);
+});
 ```
 
-Wind is just a horizontal acceleration you re-apply on that same tick by nudging `velocityX`; per-world gravity, drag and wind are plain numbers in a catalog object.
+Set `lander.gravityX = world.wind` in px/s² when the wind changes. Native
+integration applies it every frame; do not add velocity repeatedly from a JS
+timer. For lateral-velocity limits or exact vector touchdown tests, normal
+impact speed alone is insufficient: design a separate measurement contract.
 
 ## Endless runner
 
@@ -599,7 +619,15 @@ function hitLane(lane, pad) {
 }
 ```
 
-An invisible `misszone` trigger below the pads catches gems that got away and counts the miss. Derive the fall speed from the beat: `FALL_SPEED = (PAD_Y + NOTE) / 1.6` with a 400 ms spawn interval puts four eighth notes between spawn and pad at 150 BPM.
+An invisible `misszone` trigger below the pads catches gems that got away and
+counts the miss. `FALL_SPEED = (PAD_Y + NOTE) / 1.6` gives a 1.6 s trip from
+`-NOTE` to `PAD_Y`. At the stated 150 BPM, `60000 / 150 = 400` ms is a quarter
+note; 1.6 s is four quarter notes (eight eighths). The upstream comments say
+"eighth" but the timing constants describe quarters. Correct that wording,
+not the engine or the demo's timing without a separate design decision.
+Position windows convert to time with `windowSeconds = windowPx / FALL_SPEED`.
+The demo uses a JS interval and independent music playback, not an audio-clock
+beat scheduler; see [rhythm timing](physics.md#rhythm-timing).
 
 ## Ball sports / breakout physics
 
@@ -634,7 +662,11 @@ ball.addEventListener('collision', (e) => {
 
 Note the split: walls and the net are `solidWith` (the engine bounces the ball off them for free), while the players and the floor are `collidesWith` (you decide what happens). For breakout, bricks go in `collidesWith` and are removed with `visible = false` on hit while the paddle and walls stay solid.
 
-A `restitution: 1` ball on an invisible floor bounces forever with no JS at all — and since 2026-08-27 the bounce can live on the *floor* instead, which is what makes one springy platform in an otherwise dead level a one-property change. Round obstacles, bumpers that knock each other around and a table that brings everything to rest are all in [Shaped solids](patterns.md#shaped-solids-ramps-round-posts-and-bodies-that-push-back--slopesjs-circlesjs-pooljs-drumjs).
+A `restitution: 1` ball reflects larger impacts without restitution loss;
+the small-bounce cutoff can still settle it. Restitution can live on the
+floor, so one springy platform can bounce otherwise non-bouncy riders.
+Round obstacles, mutual push bodies and pool damping are in
+[Shaped solids](patterns.md#shaped-solids-ramps-round-posts-and-bodies-that-push-back--slopesjs-circlesjs-pooljs-drumjs).
 
 **Opponent AI** on an 80 ms timer, reading a handful of live properties per tick: