incanto 0.74.0 → 0.76.0

package/skills/incanto-hud.md

@@ -179,6 +179,22 @@ reveals the line then advances; choice lines render buttons and wait for
 `choose(i)`. Buttons opt into pointer events — the rest of the HUD stays
 click-through.
 
+**A line that moves on by itself** — `autoAdvanceSeconds` (default `0` = wait
+for the click) keeps a fully-shown line up that long and then advances it. A
+cutscene has nobody clicking: the camera is on a rail and the controller is
+off. A line with choices always waits.
+
+```json
+{ "name": "Talk", "type": "UiDialogue", "props": { "autoAdvanceSeconds": 2.6 } }
+```
+
+**Cinematic bars** are a property of the LAYER, not two panels: `HudLayer`'s
+`letterbox` (0..0.5) is the fraction of the layer's height each bar covers,
+drawn full-bleed at the top and bottom edges over every widget, and animated
+by whatever writes it (`hud.letterbox = 0.11` on a cutscene's first frame,
+`0` on its last). Two `UiPanel`s sat in their anchor slots — inside the layer's
+padding, above the dialogue box — and never reached the edge.
+
 **Driving them with no screen** — a HUD widget is DOM, so a headless harness
 cannot click one. Both take the gesture directly:
 
@@ -279,6 +295,67 @@ or moving a widget to another corner all work from a behavior — and from the
 editor's inspector, which is the same code path. They used to be baked in when
 the widget was built and could never be changed afterwards.
 
+## A minimap (UiMinimap)
+
+Every open world, every stealth game, every wave shooter wants one, and the
+HUD had text, bars, banners, images and buttons — no map:
+
+```json
+{ "name": "Map", "type": "UiMinimap",
+  "props": { "anchor": "topRight", "size": 160, "radius": 40,
+             "dots": { "enemy": "#ff5050", "pickup": "#ffd54f", "goal": "#3aa0ff" },
+             "heading": "%Skin" } }
+```
+
+| prop | default | what it does |
+|---|---|---|
+| `size` | `160` | diameter, px |
+| `radius` | `40` | world units from the centre to the rim (m in 3D, px in 2D) |
+| `follow` | `""` | the node at the centre; `""` = the first node in the `player` group |
+| `dots` | `{}` | group → colour: every node in a listed group is a dot (not `groups` — that is the node's own membership) |
+| `heading` | `""` | a node whose yaw turns the map so its "ahead" is up (+Z-forward — the skin the controller turns); `""` = north (−z) up |
+| `self` / `dotSize` / `background` / `shape` | `#ffffff` / `6` / dark / `circle` | the look |
+
+- The plane is x/z in 3D and x/y in 2D; things beyond `radius` are not drawn;
+  a group you do not list is not drawn. It follows moving parents (an enemy
+  under a spawner's group node is where it is drawn).
+- **`markers()` is the same list headless** — `{x, y, color, group, node}`
+  in canvas px — so a harness can ask what the map shows (`examples/survivor-3d`
+  asserts the husks that reached you are on it), and `centre()` is the node
+  it is following. Draws on a `<canvas>` in the browser; nothing in a test.
+- A dot's colour that is not a string is a load error: the keys of `dots`
+  are your group names (any is right), the values must be colours.
+
+## A waypoint — the objective marker (UiWaypoint)
+
+Every open world puts a marker over the objective; every example here told
+the player where to go in a sentence at the top of the screen. One widget:
+
+```json
+{ "name": "Mark", "type": "UiWaypoint",
+  "props": { "target": "/root/Shop1", "label": "bakery", "hideWithin": 4, "arriveWithin": 3 } }
+```
+
+| prop | default | what it does |
+|---|---|---|
+| `target` | `''` | the node the marker floats over — change it from a behavior as the objective moves on |
+| `label` / `color` / `size` | `''` / `#ffd54f` / `22` | the text under the diamond, its colour, its size in px |
+| `distance` | `true` | show the metres left under it |
+| `clamp` / `margin` | `true` / `40` | off screen or behind the camera, slide to a rectangle `margin` px in from the edge and turn the arrow that way (behind: mirrored through the centre first, so it points the way to turn) |
+| `hideWithin` | `0` | hide when you are this close (m); 0 = never |
+| `arriveWithin` | `0` | `arrived` fires once when `from` comes this close, and again after leaving and coming back; 0 = never |
+| `from` | `''` | who the distance is measured from — the first node in the `player` group by default |
+
+- It floats over its target through the renderer's own projection
+  (`engine.toScreen`), so `anchor` means nothing here and it never sits in a
+  HUD column.
+- **`screen()` is the same answer headless** — `{x, y, angle, behind,
+  onScreen, clamped, distance, visible}` in canvas px — from whatever
+  `toScreen` a test installs (`engine.toScreen = (w) => ({ x, y, behind })`),
+  so a harness can ask where the marker is and which way it points
+  (`examples/errands-3d` asks that the marker moves from shop to shop);
+  `distanceNow()` is the metres alone, projection or not.
+
 ## Playable on a controller (focus navigation)
 
 A menu you can only click is not playable on a gamepad, and "add controller
@@ -310,6 +387,12 @@ What activation MEANS is per widget: a button presses, a toggle flips (left/righ
 sets it explicitly, which reads better on a pad), a select walks its list, a
 slider nudges by one `step`.
 
+**A `disabled` widget is out of the ring** — a title screen's CONTINUE before
+there is a save is the ordinary case, and stopping on it gave a pad player a
+button where `A` does nothing and nothing on screen said why. Enable it and it
+is back in the ring on the same frame; `hud.focus()` will not move onto one
+either.
+
 **A `GameFlow` pause panel arms it for you** — that screen IS a menu, it knows
 exactly when it opens and closes, and it puts the layer's own value back on
 resume. Every game with a pause menu was otherwise writing the same two lines,
@@ -381,6 +464,39 @@ the pointer path — a non-`draggable` source does nothing, a target that is not
 
 
 
+## The shell every shipped game has
+
+A title screen, a pause menu, options that persist, a minimap and an objective
+marker are all HudLayer widgets in scene JSON — `examples/shell-3d` composes the
+lot in one game, and it is the shortest thing to copy:
+
+- **One panel per screen** (`Title`, `PauseMenu`, `Options`), and ONE place in
+  your behaviour that writes their `visible`. A screen two places can show is a
+  screen that gets stuck.
+- **`GameFlow` owns every screen**, and none of it is TypeScript: `pauseAction`
+  toggles the pause and shows `pausePanelPath`, `titlePanelPath` holds the world
+  at boot, `screen(path)` pushes options over whichever menu asked and `back()`
+  returns to it. Wire the buttons with `connections` — `pressed → resume`,
+  `pressed → screen ["…/Options"]`, `pressed → back`, `pressed → restart` — and
+  author every panel that is not up at boot `"visible": false`. See "The whole
+  shell, without a script" in `incanto-gameplay-behaviors.md`.
+- **The options are the engine's own widgets** — `UiVolumeSlider`,
+  `UiMuteToggle`, `UiQualitySelect`, `UiFrameCapSelect`, `UiRenderScaleSelect`
+  read and write `engine.settings` and persist themselves. Anything you ADD
+  (look sensitivity, difficulty) is two lines: set the widget's `value` from
+  `settings` at ready, and `settings.set` on `changed`.
+- **`focusNavigation` goes ON for a menu and OFF for play**, or the arrow keys
+  belong to the menu while the player is trying to walk.
+- **`UiWaypoint.screen()`** answers where the marker is — `onScreen`, `behind`,
+  `clamped` — and a headless run can ask it, so "does my objective marker stay
+  on screen when the objective is behind me" is a check and not a hope.
+- **Give the start button a name a machine can read** — PLAY, START, RESUME.
+  A title screen holds the world at `timeScale` 0, and `incanto-feel` and the
+  facing check press their way past it before measuring (`HudLayer.focusables()`
+  in that order, then everything else); a button they cannot start reports
+  `the clock never ran` instead of numbers. `incanto-playtest`'s bot presses
+  widgets on its own.
+
 ## More than one language
 
 Any text prop here can name a translation key instead of a literal:

package/skills/incanto-multiplayer.md

@@ -45,6 +45,9 @@ Authority rules:
   > `incanto-multiplay` prints its verdict instead of exiting 13 with nothing.
   > Take one lock, do the whole read-modify-write inside it, and release.
 - physics/AI run client-side; one-simulator needs (NPC waves) use the host-client pattern
+- a SHARED physics object (a ball, a crate, a door) → **owner-handoff**: one
+  client simulates it at a time and the server decides which — the recipe is
+  "A shared physics object" below, and `examples/soccer-mp-3d` is the composition
 
 ## Scene JSON
 
@@ -95,7 +98,13 @@ a half-finished edit that behaves exactly like a broken one.
   after two seconds, by name. `source: "users"` spawns one
   instance of the registered scene per OTHER account (self skipped); the flat `sync` patch
   applies onto the spawned scene's root; `position` lerps when `interpolate: true`
-  (remote entities render slightly in the past — that's correct). Emits
+  (remote entities render slightly in the past — that's correct). **A remote is
+  made from its FIRST patch, where that patch says it is** — not at the join,
+  at the origin, sliding to its place: the kernel lists an account the moment it
+  joins with nothing in it, and an instance built then stood on the kick-off
+  spot for a few frames (with a body on the remote scene it kicked the ball
+  into the player beside it). So a remote scene with a `CharacterBody3D` root is
+  fine, and is how the ball bounces off the OTHER player in `soccer-mp-3d`. Emits
   `spawned(node, key)` / `despawned(node, key)`. `source: "collection:<id>"` mirrors a
   room collection by `__id` — a collection ENTITY applies as your server wrote it
   (`addCollectionItem('coins', { position: [x, y] })` lands on the spawned node;
@@ -344,6 +353,109 @@ Runnable reference: `examples/arena-preview` (Coin Dash — server-authoritative
 `$lock`'d coin claim + `$roomTick` match clock, two clients split-screen). Going
 live is the one-line transport swap below.
 
+## A shared physics object (a ball two players kick)
+
+The replication above is per PLAYER: one owner node, its own state. A 1v1
+soccer game has one thing both players act on — the ball — and a ball is a
+physics body no data-authoritative server can integrate at 60 Hz (`$roomTick`
+runs every 100–1000 ms; a ball at 10 m/s moves a metre or ten between ticks).
+The shape that works, measured in `examples/soccer-mp-3d`:
+
+- **Every client runs its own Rapier ball.** It bounces off boards and off
+  the other player's body locally; nothing is a ghost.
+- **One client at a time is the ball's OWNER**, and the server says which
+  (`room.ballOwner`). The owner publishes position + velocity at the owner
+  throttle (a custom server function that DROPS a publish from anyone else —
+  that is the authority) into a room collection entity; the others MIRROR it:
+  set the local ball's velocity to the published one plus a position-error
+  gain (`6/s`), so it chases the truth while still colliding, and teleport
+  when the gap is wide (`2.5 m`).
+- **Touching the ball takes it over** (`claimBall`, `$lock`'d) — the kick
+  applies its impulse to the local ball AT ONCE and the claim makes that
+  simulation the room's; a player WALKING at the ball (the move stick, not a
+  shove) claims it too, which is what makes dribbling possible. A player the
+  ball hits does not claim it, so a shot off a standing opponent bounces as the
+  shooter's simulation says, and two players standing on the ball do not hand
+  it back and forth every window.
+- **A `seq` on the entity says "snap, do not chase".** The server bumps it on
+  every reset and every handoff, and writes the entity itself when it puts the
+  ball on the spot — every client snaps to a new seq, except the client that
+  wrote it.
+- **The server is the referee** in `$roomTick`: sides, the clock, a GOAL read
+  from the replicated ball (it is caught in the net, so a slow tick cannot miss
+  it), the reset, and who kicks off. Clients paint the score from room state
+  and never call a goal.
+
+What it is NOT: fair under latency. The kicker's client is right by
+definition, so a laggy opponent's tackle lands late — the "casual sync" the
+model is built for, stated on purpose. Two things the engine changed for it:
+an impulse now composes with a velocity written in the same frame (the
+mirror's write used to erase the kick a step later), and a remote spawns
+where its first patch says it is.
+
+## An online race: one physics body PER owner
+
+The ball above is one body two players fight over. A race is the other shape —
+a body EACH, nothing to hand off — and `examples/race-mp-3d` ("Apex Duel") is
+the composition:
+
+```json
+{ "name": "Car", "type": "RigidBody3D",
+  "props": { "mass": 900, "linearDamping": 0.3, "angularDamping": 1.5,
+             "collider": { "shape": "box", "size": [1.9, 0.7, 4.2] } },
+  "groups": ["car", "player"],
+  "network": { "mode": "owner",
+               "sync": ["position", "rotation", "Wheel0.rotation", "Wheel1.rotation"],
+               "throttleMs": 50 },
+  "script": { "name": "Racer" },
+  "children": [
+    { "name": "Drive", "type": "Vehicle3D",
+      "props": { "enabled": false, "engineForce": 4200, "wheels": [
+        { "position": [-0.85, -0.15,  1.45], "radius": 0.38, "steer": true },
+        { "position": [ 0.85, -0.15,  1.45], "radius": 0.38, "steer": true },
+        { "position": [-0.85, -0.15, -1.45], "radius": 0.38, "drive": true },
+        { "position": [ 0.85, -0.15, -1.45], "radius": 0.38, "drive": true } ] } }
+  ] }
+```
+
+- **The other car is a kinematic box**, not a vehicle: `remote-car.scene.json`
+  is a `CharacterBody3D` root with the same meshes and `Wheel<i>` nodes (so the
+  synced `Wheel0.rotation` path resolves on the copy). The spawner poses it
+  from the wire — position interpolated, rotation applied outright — and the
+  local car BUMPS it, because a kinematic body pushes a dynamic one.
+- **The lights hold the car, not the input.** `Vehicle3D.enabled` is false
+  until the room says `race`; parked, the car still settles on its springs and
+  still reads its actions, so green is a real launch. Offline (no
+  NetworkManager) the behaviour enables it at once.
+- **The server counts gates, IN ORDER.** `passGate(i)` is `$lock`'d and
+  accepted only for the gate that car is due (`next[account]`); gate 0 after
+  the last one is a lap; the lap that reaches `LAPS` sets `phase: 'done'` and
+  `winner`. The client never counts online — it reads `laps`/`next` off the
+  room state and turns a change into its `gate`/`lap` signals. A cut across
+  the infield therefore counts nothing, on the server, where cutting is decided.
+- **Gates are `Area3D` sensors driven THROUGH** (the wheel rays ignore them),
+  routed by `connections` with `"filter": { "group": "player" }` so the remote
+  car — group `remote`, never `player` — cannot trip a gate on this client.
+- **Who is ahead** is laps, then gates this lap, then distance to the next
+  gate — computable on every client from the room state plus the two car
+  positions, so the HUD's `1st`/`2nd` needs no server field.
+- **No frame before the manager.** `createGame3D` starts the loop at once —
+  and ticks two warm-up frames before it even returns — while
+  `NetworkManager.create` takes a moment to join; every frame in between runs
+  the game OFFLINE. The race's `Racer` grids itself to slot 0 when it finds no
+  manager (the right thing for `incanto verify` and the editor's ▶ play), and
+  in the browser that offline pose went out as the client's FIRST replicated
+  state, on top of the other player's car, which the kinematic copy then lifted
+  off the ground. Boot with `autoStart: false` and call `game.engine.start()`
+  once the manager exists (`examples/race-mp-3d/src/main.ts`):
+
+  ```ts
+  const game = await createGame3D({ canvas, scene, behaviors, autoStart: false });
+  const manager = await NetworkManager.create(game.engine, { transport });
+  manager.registerScene('remote-car', remoteCarJson);
+  game.engine.start(); // the first frame is a networked one
+  ```
+
 ## Going live on agent8 (gameserver-sdk v2)
 
 The agent8 platform exposes NOTHING client-callable by default — every function
@@ -451,7 +563,14 @@ kernel with no remote functions, so `roomState` came back `{}` instead of
 changed nothing — a ✓ that could not have been a ✗.
 
 If your server cannot be loaded the run REFUSES rather than quietly measuring a
-game without its own rules.
+game without its own rules. It is looked for one and two directories above the
+scene (`src/game.scene.json` and `src/scenes/game.scene.json` both put the
+project root there) and in the working directory; the report's first line
+names the one it loaded — `· server: …/server/src/server.ts (Server)` — or
+says `no server loaded`, and the `--json` report carries `server` and
+`serverNote`. Before this it looked two levels up only, found nothing for a
+scene at `src/`, said nothing, and ran every online example's `agrees` rung on
+the bare kernel with an empty room state.
 
 **Pass `--behaviors src/behaviors.ts` too.** A sync key is very often written by
 game TypeScript (`player.firing = input.isPressed('fire')`), and without the
@@ -472,3 +591,23 @@ every client agreed perfectly about a value nobody ever sent.
 cannot see them — a bullet has no account — so a spawner that took a hundred
 entities off the wire and materialised none of them used to be entirely silent.
 Now it says which spawner, and how many entities it dropped.
+
+**A body still moving is allowed one send window.** The rung quiesces for
+sixty frames — the driver's held inputs are dropped first — and then compares
+the owner's truth with what the copies last RECEIVED. A character stops; a car
+does not (released, a raycast vehicle coasts at constant speed), so its copies
+are honestly `speed × (throttleMs + the server's turn)` behind. That much slack
+is granted on `position` and `rotation` keys, scaled by the owner's own
+`linearVelocity` / `angularVelocity` — a dead sync still fails, its gap grows
+with the match — and the report names who was still moving:
+
+```
+· p1, p2 still moving when compared — a copy may trail by one send window, and that is not a disagreement
+```
+
+`rotation` is compared as an ORIENTATION (the angle between the two), because
+Euler XYZ writes one attitude two ways near the gimbal lock and wraps at ±180°
+— `[177, 88, -177]` and `[-180, 88, 180]` are a degree apart, not 357°. And
+`incanto multiplay` drives a physics owner (one with a `linearVelocity`) along
+its own forward at 3 m/s rather than teleporting it — a car thrown through the
+kerbs every frame is the instrument's doing, not the game's.