@homie-rocks/studio 0.46.2 → 0.46.3

package/CHANGELOG.md

@@ -17,6 +17,67 @@ To bring a studio up to date, tell Claude: "Upgrade my studio to the newest Homi
 `npx -y @homie-rocks/studio@latest upgrade`, which shows what's new since the version your studio pins (from this
 file) and what the upgrade would change, and changes nothing until you agree.
 
+## [0.46.3] - 2026-10-11
+
+**Plugin 0.46.3**
+
+A guest who signs in keeps both histories; a rival's sounds reach the players who can hear them; a shooter's own
+actions answer at once; a tap moves as far as it was held; a client cannot stretch its own lag compensation.
+
+### Added
+
+Every item here is opt-in: a game that declares none of them plays, costs and saves exactly as on 0.46.2.
+
+- `mergeSaves({ '<game>': { saves: { '<key or prefix*>': rule }, stats: { … } } })` from
+  `@homie-rocks/studio/worker`: how a guest's saves combine with an account's when the guest signs in to an account
+  that already has the same key. Rules: `'account'`, `'guest'`, `'newer'`, `'larger'`, `'smaller'`, `'sum'`,
+  `'union'` (a list joined by id), or the game's own function, run on the server. It happens once, in the sign-in's
+  own transaction, guarded against a room writing a result at the same moment. The sign-in response says what
+  was merged, moved and kept (`adopted`), and a key no rule could combine reaches the game's `onConflict` with the
+  guest's value (saves/SAVES.md, "When a guest signs in to their account").
+- Effects with an audience: `world.emit(effect, at, data, { within: metres, to: id | [ids] })` sends an effect only
+  to the players whose own body is in range or who are named; a watcher receives the ones with a range. For a sound a rival
+  could hear or a number only the shooter may see, in place of drawing it from state the rival should not have.
+  An effect with no audience is public and is sent as before.
+- `f.held()`, an input type: the browser sends the average of the control over each tick, so a key held for part
+  of a tick moves the body for that part. Short taps no longer travel a whole tick or two by where the tick's
+  edges fell. An entry that reaches the server after its tick is settled on the next ticks, not counted twice.
+- `openRoom({ predict: { <kind>(me, input, ctx) { … } } })`: the player's own actions predicted like their own
+  movement (run each predicted tick and between ticks, put right by every snapshot and re-run). `ctx.ghost` shows a
+  provisional entity and `ctx.effect` a provisional effect that the server's own then confirms (`confirms: true`)
+  or the room retracts (`room.on('retract', …)`). A valued pulse (`f.pulse()`) now names the tick it was pressed
+  on and the server acts on it in that tick; the control row says the newest pulse acted on, so a prediction
+  holds when the pulse's own message is late (as it can be through a Gate).
+- `world.unitsLeft`: the budget units the running handler may still spend, so a handler that plans can stop early.
+- `room.rewindSeconds` in rules: the game's hard cap on how far a person's ray is rewound for latency (from 0 to
+  `historySeconds`). Without it the cap is `historySeconds`, as before; `0.25` is a sensible value for a shooter.
+
+### Fixed
+
+Each of these changes what happened before; none needs a change to a game.
+
+- A guest with verified results who signed in to an account that also had some kept only the account's: the
+  guest's `server:` record was dropped, and nothing could combine the two afterwards because a browser cannot
+  write a `server:` key. Two server records are now joined by id when the guest signs in, with no rule declared.
+- A result a room wrote for the guest a moment after they signed in was written under a player that no longer
+  existed. It now follows the guest to the account (`appendServerRecord`, at the same one read and one write).
+- Lag compensation could be stretched by a client: the round trip was timed on a separate answer the client could
+  hold back, and only the smallest value ever seen was kept. It is now timed on the input frames themselves (each
+  names the newest snapshot its browser had), as a low percentile over the last ten seconds, and the allowance
+  counts the whole ticks an input waited after it arrived instead of a fixed one. A client still cannot look
+  faster than it is; one that pretends to be slower is bounded by `room.rewindSeconds`.
+
+### Upgrade notes
+
+- Nothing to do for a studio that declares none of the above. To use `mergeSaves`, add it to
+  `site/src/worker.mjs` beside `hostRules`.
+- A page from before this version that is still open against the new Worker is timed the old way until it
+  reloads. Its rewind is bounded by the same cap.
+- All of the above works the same through Gates (a room of more than 64 seats) as in a small room; each has a
+  seeded test both ways. Through a Gate a held input that misses its tick can be drawn a few centimetres short for
+  a tick or two before it settles.
+- Version 0.46.3 is provisional. No deploy or merge is part of this PR.
+
 ## [0.46.2] - 2026-10-11
 
 **Plugin 0.46.2** · Big rooms: the room runs the rules, its Gates do the rest.

package/guides/game/RULES.md

@@ -207,6 +207,7 @@ State belongs only in `fields`, `motion`, or `shared`; never a changing module v
 | `f.fix()` | Multiples of 1/4096, ±2147483648; `fuel: f.fix({ init: 1 })` |
 | `f.bit()` | Boolean; `alive: f.bit({ init: true })` |
 | `f.press()` | Input-only one-shot boolean button; `fire: f.press()` |
+| `f.held()` | Input-only number averaged over the tick (0.46.3); `ax: f.held()` |
 | `f.tick()` | Absolute tick, 0–4294967295; `until: f.tick()` |
 | `f.ticks()` | Tick duration, same range; `cooldown: f.ticks()` |
 | `f.vec3()` | Float32 vector `{x,y,z}`; `target: f.vec3()` |
@@ -220,7 +221,7 @@ State belongs only in `fields`, `motion`, or `shared`; never a changing module v
 Vector writes may omit z (it becomes zero); reads contain all three coordinates.
 Integer writes round and clamp, not wrap. Guard against underflow explicitly:
 `self.hp = Math.max(0, self.hp - damage)`. Inputs may contain only integer types,
-fix, bit and press. Each field may hold at most 16,384 cells and a kind 65,536.
+fix, held, bit and press. Each field may hold at most 16,384 cells and a kind 65,536.
 A scalar is one cell; a vector four; a text is `1 + ceil(max/64)`;
 a list is `1 + max * itemCells`; a map is `1 + max * (1 + itemCells)`;
 a struct is one plus the cells of its fields. Map keys are at most 32 characters.
@@ -344,6 +345,7 @@ These costs bound work, not elapsed wall time.
 | `sendArea(area,event,data?)` | Entity/room; 20 + 2N + 6C; 64 areas/tick, reach 64m | `world.sendArea({sphere:{at:self.pos,r:2}}, 'hit', {damage:1})` |
 | `after(ticks,event,data?)` | Entity/room; 16 + 6C; wait clamped 1–2147483647; targets caller | `world.after(20, 'ready', {})` |
 | `emit(effect,at,data?)` | Declared effect; 10 + 6C; at is position or ID; 256 effects a tick, and the next one throws | `world.emit('spark', self.pos, {})` |
+| `emit(effect,at,data,audience)` | The same, plus 8, for who may perceive it (0.46.3): `{within: metres}`, `{to: id}` or `{to: [ids]}` (32 at most), or both | `world.emit('grunt', self.id, {}, {within: 45})` |
 | `spawn(kind,at,fields?)` | Entity/room; 10 + copy cost; 2048 entities, non-player kinds only | `world.spawn('coin', self.pos, { value: 2 })` |
 | `despawn(self)` | Own non-player entity; constant guard cost | `world.despawn(self)` |
 | `place(self,at,options?)` | Own entity; 82; options vel/heading; clamps to bounds, changes movement revision | `world.place(self, world.map.spots('start')[0])` |
@@ -369,7 +371,8 @@ Queries return readonly views; send events to make recipients change themselves.
 Math vectors are readonly too: replace `d.x += n` with
 `d = { ...d, x: d.x + n }`, or use `world.math.add`/`scale`.
 
-World properties: `tick`, `dt`, `tune`, `shared`, `map`, `math`, `stage`, `level`,
+World properties: `tick`, `dt`, `unitsLeft` (0.46.3: budget units the running
+handler may still spend, so a planner can stop early), `tune`, `shared`, `map`, `math`, `stage`, `level`,
 `levelMax`, `round: {n,phase,endsAt}`. Phase is `live` or `over`.
 `rounds.seconds: 0` means no automatic deadline: your room must call round.end.
 A positive duration ends automatically. Round results arrive two ticks after the
@@ -941,7 +944,22 @@ Declare `room.historySeconds: 1` (maximum two seconds). The server retains and
 saves non-collider body positions and placement revisions on its virtual clock.
 The view's `room.viewTick` is the tick used to interpolate remote bodies. Send it
 with an action, then use `world.ray(..., {atTick, ...filters})`. Fractional ticks
-interpolate saved poses. Player requests clamp to the smaller of the configured window and the server-measured round-trip latency plus 150 ms presentation delay and one simulation tick. Without a measurement only that small margin is allowed. The relay measures a nonce challenge; client-supplied latency figures are ignored.
+interpolate saved poses. A player's request is clamped to: the relay's own
+measurement of that connection's round trip, plus 150 ms of presentation delay,
+plus the whole ticks the input waited between arriving and running (at least one,
+at most a quarter of a second). Without a measurement only that margin is allowed.
+
+The measurement (0.46.3) is a low percentile of the last ten seconds of round
+trips timed on the input frames themselves: each frame names the newest snapshot
+its browser had, and the relay knows when that snapshot left. A client cannot
+make it shorter than its real latency, and holding back a separate answer no
+longer raises it. A modified client can still pretend to be further away than it
+is, as it could by really being so; what that buys is bounded by the game's cap.
+Set `room.rewindSeconds` (from 0 to `historySeconds`): the most any shot is
+rewound, whatever the connection reports. `0.25` suits a shooter: a round trip
+up to about 100 ms is compensated in full and a slower player leads the target a
+little. Without it the cap is `historySeconds`, as before. Client-supplied
+latency figures are ignored.
 A placement or new round prevents rewinding through a teleport or reset.
 
 Rewind changes actor poses only. Eligibility filters use current fields, so a
@@ -986,6 +1004,89 @@ skips the intermission. Use it for an authorized retry; validate eligibility in
 your room handler. Pending restart intent survives save/restore.
 
 
+### Held input: a tap moves for the time it was down (0.46.3)
+
+An ordinary input field is read once a tick, at the tick's edge. A key held for
+60 ms of a 50 ms tick therefore moves the body for one tick or for two, by where
+the edges happened to fall: short taps travel too far and vary. Declare a
+movement axis `ax: f.held()` instead. The browser then sends the average of what
+the control read over each tick (a key down for a third of the tick reads a
+third of its value; an analogue stick reads its mean), prediction uses the same
+number, and `move` multiplies speed by it as before, so the body moves for the
+part of the tick the key was down. `room.input({ax: 1})` is called as usual,
+every frame or on change; a boolean counts as 1. `think` returns a plain number.
+Use it for movement axes, not for buttons: a button is `f.press()` or `f.pulse()`.
+Keep its values in -1 to 1. An entry that reaches the server after its tick is
+not counted twice: the tick it missed ran on the value before it, and the server
+settles the difference on the next ticks, so the body ends where the browser
+predicted.
+
+### Effects with an audience: what a player may perceive (0.46.3)
+
+Everything in a snapshot's public fields and every plain `world.emit` reaches
+every player. A sound or a flash must not be drawn from state a rival should not
+have (another player's exact health), and need not be sent to someone who could
+not perceive it. Emit the event instead, and say who perceives it:
+
+```ts
+world.emit('grunt', self.id, {}, { within: 45 });            // earshot of where self stands
+world.emit('hitConfirm', target.id, { damage }, { to: shooter.id }); // the shooter alone
+world.emit('alarm', self.pos, {}, { within: 30, to: allies }); // either is enough
+```
+
+`within` is metres from the effect's place (the named entity's position at that
+moment) to the listener's own body; `to` names entities, and the people driving
+them receive it. A watcher, and a seat with no body yet, perceive the room: they
+receive every effect with a `within`, and never one addressed only `to` somebody.
+An effect with no audience is public, exactly as before. Delivery costs one
+frame a listener on ticks that have such effects and nothing on ticks that do
+not. Send what is perceivable (a hit landed, roughly how hard); send exact
+numbers only `to` the player entitled to them.
+
+### Predicting the player's own actions (0.46.3)
+
+The own position is predicted by `move`. Other own actions (a weapon swap, a
+build, a reload, a hit marker) otherwise wait for the server's round trip. Give
+the view a predictor for the kind:
+
+```ts
+const room = openRoom<typeof rules>({ predict: { runner(me, input, ctx) {
+  if (input.select) swap(me, input.select, ctx.tick * ctx.dt);        // the rules' own pure helper
+  if (input.build && me.builds > 0) { me.builds--; ctx.ghost('cover', spot(me), { size }); }
+  if (input.fire && aimHits(ctx, me)) ctx.effect('hit', me.id, {});
+} } });
+```
+
+The room runs it for the own body once a predicted tick, after `move`, with that
+tick's input, and on a copy between ticks, so a press answers on the next drawn
+frame. `me` holds the body's declared fields (and readonly `id`, `pos`, `vel`,
+`heading`, `grounded`, `motion`); what it writes is held to the declared types
+and read back through `room.me`. Every snapshot puts the server's values back
+and runs the still-pending inputs again, exactly as it does for the position, so
+a wrong guess corrects itself. Share pure helpers with the rules (no `world`):
+the server's handler remains the authority and the only place a result counts.
+
+`ctx.ghost(kind, at, fields?, {match?, seconds?})` draws a provisional entity:
+`room.each` yields it with `provisional: true` until an entity of that kind that
+`match(entity)` accepts (default: within a metre) arrives, and then until that
+one is drawn, so there is never a gap or a double. `ctx.effect(name, at, data?,
+{match?})` fires the effect's listeners now with `predicted: true`; the server's
+own effect of that name then arrives with `confirms: true` (use its exact data,
+do not replay the sound). If the server ran the tick without confirming, the
+room emits `retract` (`{ghost, kind}` or `{effect, ...data}`) and the ghost
+leaves: take the marker down quietly. `ctx.ray/rays/rayAll` query what the
+player sees (`ctx.viewTick`); `ctx.preview` says the run is between ticks. A
+predictor runs often: keep it cheap, and keep per-entity state in `me`.
+
+A tick's prediction runs more than once (between ticks, again when the input
+changes, then the tick itself) and shows each thing once. Things are told apart
+by their name and `key`: give two effects of one name that mean different things
+(`ctx.effect('audio', me.id, {name: 'jump'}, {key: 'jump'})` beside a `reload`)
+a `key` each, and the same for two ghosts of a kind. Read `me.id` into a constant
+before using it in a `match` closure: `me` is reused. A valued pulse
+(`f.pulse()`) carries the tick it was predicted on, and the server acts on it in
+that tick, so a predicted swap is in the snapshot of the tick it was drawn for.
+
 ### Discrete actions with a value
 
 Use `select: f.pulse()` for a weapon slot or other byte-valued action. Call

package/guides/game/SKILL.md

@@ -243,6 +243,11 @@ world or inventory, use Lasting worlds above. Ordinary match rooms expire after
   handle. Draw the character's name over its body and in the ranking (a declared command requests it; rules validate and keep it in the player entity), except on a kids server, where the others stay handles. Ember Vale does it.
 - Show who is playing (`saves.player.name`, guest or signed in) and a small "Keep my progress" button that calls
   `saves.signIn()`; the play page shows its passkey sheet. Pressing Play never needs an account.
+- A guest who signs in to an account that already has the same key: say how the two combine, once, in
+  `site/src/worker.mjs`: `mergeSaves({ '<id>': { saves: { coins: 'sum', 'best-level': 'larger', settings: 'newer' },
+  stats: { kills: 'sum' } } })` from `@homie-rocks/studio/worker` (or a function for an inventory). Server records
+  are joined without a rule; any other key with no rule reaches the game's `onConflict` (SAVES.md, "When a guest
+  signs in to their account").
 - Prove it: build, `npm run dev`, open `http://localhost:8787/<id>/play` (passkeys need `localhost`, not
   `127.0.0.1`), play, reload: the progress is still there. The whole guide is
   `node_modules/@homie-rocks/studio/saves/SAVES.md` (the limits, offline and conflicts, what is stored, privacy).

package/lib/rules-check-worker.mjs

@@ -233,7 +233,7 @@ function play(c, companions, allow) {
   }
 
   /* ---- what the people press. Each plays one of three ways, changing every 20 s; seat 1 never sends anything. */
-  const ends = (fd) => (fd.t === 'bit' || fd.t === 'press' ? [false, true] : fd.t === 'fix' ? [-1, 1] : [L.P.coerce(fd, -Infinity, c.dims), L.P.coerce(fd, Infinity, c.dims)]);
+  const ends = (fd) => (fd.t === 'bit' || fd.t === 'press' ? [false, true] : fd.t === 'fix' || fd.t === 'held' ? [-1, 1] : [L.P.coerce(fd, -Infinity, c.dims), L.P.coerce(fd, Infinity, c.dims)]);
   const steering = new Map();
   let moveTick = 0;
   let moveSelf;

package/lib/rules-check.mjs

@@ -28,10 +28,10 @@ export const LONG_ALLOWANCE = Object.freeze({ ...ALLOWANCE, ticks: 8 * ALLOWANCE
 
 /** The ordered declarations a save depends on. Functions contribute their presence, never their implementation. */
 export function stateHash(c) {
-  const { kinds, events, commands, effects, shared, rounds, bots, roomOn, asks, map: geometry, dims, contract, seats, save, historySeconds } = c;
+  const { kinds, events, commands, effects, shared, rounds, bots, roomOn, asks, map: geometry, dims, contract, seats, save, historySeconds, rewindSeconds } = c;
   // Keep existing 2D save compatibility hashes when the 3D map vocabulary grows.
   const map = dims === 2 ? { name: geometry.name, bounds: geometry.bounds, boxes: geometry.boxes, circles: geometry.circles, spots: geometry.spots } : geometry;
-  return createHash('sha256').update(JSON.stringify({ kinds, events, commands, effects, shared, rounds, bots, roomOn, asks, map, dims, contract, seats, ...(historySeconds?{historySeconds}:{}), tickHz: c.settings.tickHz, save }, (k, v) => typeof v === 'function' ? true : v)).digest('hex').slice(0, 32);
+  return createHash('sha256').update(JSON.stringify({ kinds, events, commands, effects, shared, rounds, bots, roomOn, asks, map, dims, contract, seats, ...(historySeconds?{historySeconds}:{}), ...(rewindSeconds!==undefined?{rewindSeconds}:{}), tickHz: c.settings.tickHz, save }, (k, v) => typeof v === 'function' ? true : v)).digest('hex').slice(0, 32);
 }
 
 /**

package/lib/rules-types.mjs

@@ -78,7 +78,7 @@ type W = World<${parameters}>;
 type RW = World<${parameters}, true>;
 type Definition = Omit<RulesDef, 'entities' | 'room' | 'move' | 'asks'> & {
   entities: ${entities}; move?: Moves;
-  room?: { records?: {key:string;identity:string;eligible?:string;fields:Readonly<Record<string,string>>}; rounds?: { seconds: number; breakSeconds: number }; bots?: { keep: number }; historySeconds?: number;
+  room?: { records?: {key:string;identity:string;eligible?:string;fields:Readonly<Record<string,string>>}; rounds?: { seconds: number; breakSeconds: number }; bots?: { keep: number }; historySeconds?: number; rewindSeconds?: number;
     start?: (world: RW) => void;
     join?: (ctx: Pick<W, 'map' | 'shared' | 'tune' | 'math' | 'round'>, player: { seat: number; driver: 'person' | 'bot' | 'ai'; owner: string; character?: (${joins}) | null }) => ${joins};
     on?: { [K in keyof (Omit<Events, keyof GameRoomEvents> & GameRoomEvents)]?: (world: RW, event: EventData<(Omit<Events, keyof GameRoomEvents> & GameRoomEvents)[K]>) => void };

package/lib/template-history.json

@@ -2775,6 +2775,48 @@
      }
     }
    }
+  },
+  "0.46.3": {
+   "files": {
+    "CLAUDE.md": "ddf2b2a0376202f6",
+    "README.md": "684b3cca8001673c",
+    "HANDOFF.md": "29337e2ace95b2e7",
+    "games/README.md": "5ad32fe80c61f117",
+    "music/README.md": "a3dc042dadd39df8",
+    "videos/README.md": "16babc3437d5545b",
+    "posts/README.md": "37841aae476bd540",
+    "site/README.md": "732894273a32dc3f",
+    "site/src/worker.mjs": "6cc5c6131eaf6fd0"
+   },
+   "sections": {
+    "AGENTS.md": {
+     "(intro)": "394cbbe934e80722",
+     "## Version-matched authoring guides": "f6261a0e5801b96b",
+     "## Layout": "f3a280b8c96cd068",
+     "## Apps: one screen, roles and parts": "8596f2b25edda3e2",
+     "## Commands (all through the pinned CLI in node_modules)": "5222e08ca55e326e",
+     "## The site": "0cb8dd9a6f8a0096",
+     "## Making games": "bb715272fd1a615b",
+     "## The Game Codex and progress": "0738ef719cef3a4c",
+     "## Art direction and models": "a48fff7bf0a5f2fc",
+     "## Running live games (the back office)": "51ebf2ab756f6e4d",
+     "## Servers and AI seats": "1ccfd549d2369a60",
+     "## Selling things (the shop)": "9e020d69dd6a954e",
+     "## Continuing a build from the Claude app": "0d68081e924ca419",
+     "## Rules": "27881d11d3ff3803",
+     "## Telling Homie": "80b46fdd9e578db8",
+     "## Beta": "9d02638207a26e73"
+    }
+   },
+   "named": {
+    "Homie Arcade": {
+     "sections": {
+      "AGENTS.md": {
+       "## Commands (all through the pinned CLI in node_modules)": "611b437f5b3303f0"
+      }
+     }
+    }
+   }
   }
  }
 }

package/netplay/netplay.ts

@@ -1682,7 +1682,7 @@ export function createNetplay<S = unknown, A = unknown, C = unknown>(opts: Netpl
     else if (m.t === 'state' && typeof m.k === 'string') applyState(m.k, m.d);
     else if (m.t === 'round') { const incoming = m.round as RoundInfo; roundInfo = m.retime && roundInfo?.n === incoming.n ? { ...roundInfo, ...incoming } : incoming; if (!m.retime) { emit('round', roundInfo); post?.({ what: 'round', round: roundInfo }); } }
     else if (m.t === 'roster' && (offline || !connected)) { slots = m.slots as Slot[]; emit('roster', slots); post?.({ what: 'roster', slots }); }
-    else if (m.t === 'ev' && (m.to === undefined || m.to === seat || m.to === id)) emit('event', { k: String(m.k), d: m.d, from: typeof m.from === 'number' ? m.from : null });
+    else if (m.t === 'ev' && (m.to === undefined || m.to === seat || m.to === id || (m.to === -1 && seat === null))) emit('event', { k: String(m.k), d: m.d, from: typeof m.from === 'number' ? m.from : null });
   }
   let role: Role = 'replica';
   let roleKnown = false;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@homie-rocks/studio",
-  "version": "0.46.2",
+  "version": "0.46.3",
   "description": "A studio for games, music and video on its own Cloudflare: scaffold, multiplayer starters on the netplay contract, a port toolkit that makes existing single-player web games multiplayer, the site Worker with public rooms (Table/Lobby Durable Objects and D1, all on the free Workers plan, no payment method), a site with the hub's sections (Home, Games, Music, Videos, Rooms, Posts with feeds) in the studio's own look, an epic landing page for every game, big songs and videos in the studio's own R2 once it has storage (uploaded, checked by SHA-256, served at the same addresses), deploy, and the homie.rocks directory.",
   "type": "module",
   "license": "Apache-2.0",

package/rules/core.ts

@@ -69,6 +69,10 @@ export const SEND = 16;
 export const THROWN = 512;
 /** The most effects (`world.emit`) one tick takes. */
 export const FX_MAX = 256;
+/** The most entities one effect's audience names (`world.emit(effect, at, data, { to })`). */
+export const FX_TO_MAX = 32;
+/** Who may perceive an effect: within so many metres of where it happened (-1: no distance), the entities named, and where it happened. */
+export type FxAudience = [within: number, to: string[], from: [number, number, number] | null];
 /** The most area events (`world.sendArea`) one tick takes. */
 export const AREAS_MAX = 64;
 /** What the log names when a room ends because of what it holds, not because of a handler. */
@@ -85,7 +89,7 @@ export interface StepInput { values: Record<string, unknown>; claim?: { pos: Vec
 export interface ResultRow { seat: number; id: string; driver: Driver; score: number; place: number }
 export type CoreOut =
   | { t: 'round'; n: number; phase: 'live' | 'over'; endsAt: number; startedAt: number; results?: ResultRow[] }
-  | { t: 'fx'; tick: number; list: [number, unknown, unknown][] }
+  | { t: 'fx'; tick: number; list: [number, unknown, unknown, FxAudience?][] }
   | { t: 'ask'; n: string; state: unknown; questions: Record<string, unknown> }
   | { t: 'goalDone'; seat: number; ok: boolean }
   | { t: 'seats' }
@@ -162,6 +166,8 @@ export interface Core {
   /** The current round, for a host rebasing wall-clock deadlines after a pause or restore. */
   round(): Extract<CoreOut, { t: 'round' }>;
   bodies(): Body[];
+  /** Every person's body with where it stands: who an effect with an audience reaches (0.46.3). */
+  listeners(): { seat: number; id: string; pos: Vec3 }[];
   /** The body in a seat, as the host runtime needs it for the input protocol. */
   character(seat: number): import('./rules.ts').Character | null;
   bodyOf(seat: number): { id: string; kind: KindTable; r: number; away: boolean; driver: Driver } | null;
@@ -235,7 +241,7 @@ export function createCore(c: Compiled, opts: { characterForSeat?: (seat: number
   let sharedROVer = -1;
   const sharedChanged = (): void => { sharedDirty = true; sharedVer += 1; };
   let out: CoreOut[] = [];
-  let fx: [number, unknown, unknown][] = [];
+  let fx: [number, unknown, unknown, FxAudience?][] = [];
   /** What is left of the running tick's budget. A room's first `room.start` runs before any tick, with a whole one. */
   let left = c.settings.budget.tick;
   let trips = 0;
@@ -527,6 +533,8 @@ export function createCore(c: Compiled, opts: { characterForSeat?: (seat: number
   const world = brand({} as Record<string, unknown>);
   const getters: Record<string, () => unknown> = {
     tick: () => tick, dt: () => dt, round: () => roundApi, shared: sharedView, level: () => policy.level, levelMax: () => policy.levelMax, guideLevel: () => policy.guideLevel ?? policy.level, guideSeats: () => policy.guideSeats ?? EMPTY_GUIDE_SEATS, kids: () => Boolean(policy.kids), levelSet: () => Boolean(policy.levelSet),
+    // What the running handler may still spend (0.46.3): a handler that plans can stop short of its share instead of being stopped.
+    unitsLeft: () => Math.max(0, Math.min(2147483647, Math.floor(G.left))),
     stage: () => stage, tune: () => c.tune, math: () => math, map: () => mapApi,
   };
   for (const [name, get] of Object.entries(getters)) Object.defineProperty(world, name, { get, enumerable: true });
@@ -594,14 +602,30 @@ export function createCore(c: Compiled, opts: { characterForSeat?: (seat: number
       const wait = w >= 1 ? Math.min(w, 0x7fffffff) : 1;
       push({ due: tick + wait, to: cx.ent ? cx.ent.id : '', kind: cx.ent ? 'ev' : 'room', ev: ev as string, data: shapeData(c.events, ev, 'the event', data), at: tick });
     },
-    emit: (effect: unknown, at: unknown, data?: unknown): void => {
+    emit: (effect: unknown, at: unknown, data?: unknown, audience?: unknown): void => {
       charge(10);
       if (cx.scope !== 'ent' && cx.scope !== 'room') throw new Error('world.emit is for handlers');
       const i = typeof effect === 'string' ? c.effectNames.indexOf(effect) : -1;
       if (i < 0) throw new Error(`the effect "${said(effect)}" is not declared in shapes.effects`);
       if (fx.length >= FX_MAX) { G.note?.('effect', '', said(effect)); return; }
       const shape = c.effects[c.effectNames[i]];
-      fx.push([i, typeof at === 'string' ? at.slice(0, 24) : packVec(V(at), dims), packFields(shape, shapeData(c.effects, effect, 'the effect', data), dims)]);
+      const row: [number, unknown, unknown, FxAudience?] = [i, typeof at === 'string' ? at.slice(0, 24) : packVec(V(at), dims), packFields(shape, shapeData(c.effects, effect, 'the effect', data), dims)];
+      // An audience (0.46.3): who may perceive this effect. Without one it is public, as before.
+      if (audience !== undefined && audience !== null) {
+        charge(8);
+        const to = own(audience, 'to'), within = own(audience, 'within');
+        const ids: string[] = [];
+        if (typeof to === 'string') ids.push(to.slice(0, 24));
+        else if (Array.isArray(to)) { if (to.length > FX_TO_MAX) throw new Error(`an effect's audience names at most ${FX_TO_MAX} entities`); for (let n = 0; n < to.length; n++) { const id = to[n]; if (typeof id === 'string') ids.push(id.slice(0, 24)); } }
+        else if (to !== undefined) throw new Error('an effect\'s audience is { to: id | [ids], within: metres }');
+        if (within !== undefined && (typeof within !== 'number' || !Number.isFinite(within) || within < 0)) throw new Error('an effect\'s audience `within` is a distance in metres');
+        if (typeof to === 'undefined' && within === undefined) throw new Error('an effect\'s audience is { to: id | [ids], within: metres }');
+        // The place it is heard from: where it was emitted, or where the entity it names stands now.
+        const e = typeof at === 'string' ? ents.get(at.slice(0, 24)) : undefined;
+        const from = typeof at === 'string' ? (e && !e.dead ? e.pos : null) : V(at);
+        row.push([typeof within === 'number' ? within : -1, ids, from ? [from.x, from.y, from.z] : null]);
+      }
+      fx.push(row);
     },
     spawn: (kind: unknown, at: unknown, fields?: unknown): string => {
       charge(10);
@@ -1484,6 +1508,7 @@ export function createCore(c: Compiled, opts: { characterForSeat?: (seat: number
     shared: () => packFields(c.shared, shared, dims),
     character: (seat) => { const e = playerBodies().find(e => e.seat === seat); return e ? JSON.parse(JSON.stringify({ kind: e.kind.name, at: e.pos, heading: e.heading, fields: e.f, motion: e.m })) : null; },
     bodies: () => playerBodies().map((e) => ({ seat: e.seat, id: e.id, kind: e.kind.name, driver: e.driver, owner: e.owner, away: e.away, score: e.kind.score ? Number(e.f[e.kind.score]) || 0 : 0, r: e.r })),
+    listeners: () => playerBodies().filter((e) => e.driver === 'person').map((e) => ({ seat: e.seat, id: e.id, pos: e.pos })),
     bodyOf: (seat) => { const s = seats.get(seat); const e = s?.id ? ents.get(s.id) : null; return e ? { id: e.id, kind: e.kind, r: e.r, away: e.away, driver: e.driver } : null; },
     drain: () => { const o = out; out = []; return o; },
     save,

package/rules/host.ts

@@ -132,9 +132,12 @@ export interface Host {
   readonly core: Core;
 }
 
-interface Entry { at: number; values: Record<string, unknown>; presses: (string | [string, number])[]; claim: StepInput['claim'] }
+interface Entry { at: number; values: Record<string, unknown>; presses: (string | [string, number])[]; claim: StepInput['claim']; /** How many ticks before its own tick it arrived (0.46.3): the time the input itself waited here. */ early?: number }
 interface SeatIn {
-  pulses?: [string,number][];
+  /** A valued pulse, and the tick its browser predicted it on (0: none given, act at once). */
+  pulses?: [string,number,number?,number?][];
+  /** The wait of the entry now held, in ticks (see Entry.early). */
+  early?: number;
   held: Record<string, unknown>; claim: StepInput['claim']; entries: Entry[];
   /** The newest stamp this seat has sent, the stamps not yet acknowledged, and the newest acknowledged. */
   newest: number; stamps: number[]; ack: number;
@@ -254,7 +257,7 @@ export function createHost(o: HostOptions): Host {
       for (const [seat, q] of saved.inputs) {
         check(uint(seat) && seat < c.seats && q && valuesOk(seat, q.held) && claimOk(q.claim) && uint(q.newest) && uint(q.ack) && uint(q.lastFrameTick) && Number.isInteger(q.lead) && q.lead >= -127 && q.lead <= 127);
         check(Array.isArray(q.stamps) && q.stamps.length <= 256 && q.stamps.every(uint) && Array.isArray(q.entries) && q.entries.length <= c.settings.tickHz + 1);
-        if(q.pulses!==undefined)check(Array.isArray(q.pulses)&&q.pulses.length<=16&&q.pulses.every(p=>Array.isArray(p)&&p.length===2&&c.kinds.some(k=>k.input.some(([n,f])=>n===p[0]&&f.t==='pulse'))&&Number.isInteger(p[1])&&p[1]>0&&p[1]<=255));
+        if(q.pulses!==undefined)check(Array.isArray(q.pulses)&&q.pulses.length<=16&&q.pulses.every(p=>Array.isArray(p)&&(p.length===2||p.length>=3&&p.length<=4&&uint(p[2])&&(p[3]===undefined||uint(p[3])))&&c.kinds.some(k=>k.input.some(([n,f])=>n===p[0]&&f.t==='pulse'))&&Number.isInteger(p[1])&&p[1]>0&&p[1]<=255));
         for (const e of q.entries) check(uint(e.at) && valuesOk(seat, e.values) && claimOk(e.claim) && Array.isArray(e.presses) && e.presses.every((p) => c.kinds.some((k) => k.input.some(([name, fd]) => (typeof p === 'string' ? name === p && fd.t === 'press' : Array.isArray(p) && p.length === 2 && name === p[0] && fd.t === 'pulse' && Number.isInteger(p[1]) && p[1] > 0 && p[1] <= 255)))));
       }
     }
@@ -273,7 +276,26 @@ export function createHost(o: HostOptions): Host {
       }
     },
   } : {};
-  const core = createCore(c, { ...characterOptions, rewindTicks: seat => Math.ceil(((measuredRtt.get(seat) ?? 0) + 150 + period) / period), label: (seat,driver)=>nameOf(seat,driver), moved: o.moved, observe: o.observe, noted: o.noted, seed: Math.floor(random() * 4294967296) >>> 0, epoch: saved ? undefined : (Math.floor(random() * 4294967295) >>> 0) + 1, restore: saved?.core ?? null, restoreEpoch: o.restoreEpoch, stage: o.stage, decisions: !o.check });
+  /*
+   * How far back a person's ray may look (0.46.3). A shot is judged where the shooter saw the target, so the rewind is
+   * the age of that view when the input was RECEIVED, plus the time the input then waited for its tick:
+   *
+   *   the view's age   the relay's own measurement of this connection's round trip (a low percentile over a window of
+   *                    acknowledgements carried by the input frames themselves, worker/room.mjs), plus 150 ms of
+   *                    presentation delay. A client cannot bring the measurement under its real latency. It can
+   *                    pretend to be slower, by holding back what it sends, and then its input is late too.
+   *   the wait         whole ticks between an entry's arrival and the tick it was stamped for (at least one, at most a
+   *                    quarter of a second): tied to when the server received the input, not to what the client says.
+   *
+   * `room.rewindSeconds` is the game's hard cap on the sum. Without it the cap is `room.historySeconds`, as before.
+   */
+  const rewindCap = c.rewindSeconds !== undefined ? Math.ceil(c.rewindSeconds * tickHz) : null;
+  const rewindTicks = (seat: number): number => {
+    const waited = Math.max(1, Math.min(lateTicks, queues.get(seat)?.early ?? 1));
+    const need = Math.ceil(((measuredRtt.get(seat) ?? 0) + 150) / period) + waited;
+    return rewindCap === null ? need : Math.min(rewindCap, need);
+  };
+  const core = createCore(c, { ...characterOptions, rewindTicks, label: (seat,driver)=>nameOf(seat,driver), moved: o.moved, observe: o.observe, noted: o.noted, seed: Math.floor(random() * 4294967296) >>> 0, epoch: saved ? undefined : (Math.floor(random() * 4294967295) >>> 0) + 1, restore: saved?.core ?? null, restoreEpoch: o.restoreEpoch, stage: o.stage, decisions: !o.check });
   let epoch = core.epoch;
   if (saved && (o.startPaused ?? o.restoreEpoch !== undefined)) for (const body of core.bodies()) if (body.driver !== 'bot' && body.owner !== 'reserved') core.seatAway(body.seat, true);
   let lastSaveAt = o.clock.now();
@@ -415,9 +437,21 @@ export function createHost(o: HostOptions): Host {
   for (const [seat, held, claim, newest, ack] of saved?.queues ?? []) queues.set(seat, { held, claim, entries: [], newest, stamps: [], ack, lead: 127, lastFrameTick: core.tick });
   for (const [seat, q] of saved?.inputs ?? []) queues.set(seat, q);
   const neutral = (kind: KindTable): Record<string, unknown> => { const v = initFields(kind.input, c.dims); for (const [name, fd] of kind.input) if (fd.t === 'press' || fd.t === 'pulse') v[name] = fd.t === 'press' ? false : 0; return v; };
+  /*
+   * `f.held()` inputs that arrive late (0.46.3). A held value is how much of ONE tick a control was down, so the sum over
+   * a tap's ticks is the tap. When an entry misses its tick, that tick has already run on the value before it (a
+   * release that arrives late ran one more whole tick of movement), and applying the entry a tick later as well would
+   * count the tap twice over. So the difference between what the missed ticks ran on and what they were meant to run
+   * on is owed, and paid on the next ticks, inside the range the control reads in. The body then ends where the
+   * browser predicted it, however the frames fell. Kept beside the queues and not saved: a restart forgets a debt.
+   */
+  const heldNames = new Map<KindTable, string[]>();
+  const heldOf = (kind: KindTable): string[] => { let names = heldNames.get(kind); if (!names) { names = kind.input.filter(([, fd]) => fd.t === 'held').map(([name]) => name); heldNames.set(kind, names); } return names; };
+  const pulsesTaken = new Map<number, number>();
+  const heldBook = new Map<number, { ran: [number, Record<string, number>][]; debt: Record<string, number>; until: number }>();
   function queueOf(seat: number, kind: KindTable): SeatIn {
     let q = queues.get(seat);
-    if (!q) { q = { held: neutral(kind), claim: null, entries: [], newest: 0, stamps: [], ack: 0, lead: 127, lastFrameTick: core.tick }; queues.set(seat, q); }
+    if (!q) { q = { held: neutral(kind), claim: null, entries: [], newest: 0, stamps: [], ack: 0, lead: 127, lastFrameTick: core.tick }; queues.set(seat, q); pulsesTaken.delete(seat); }
     return q;
   }
   const people = (): number => { let n = 0; for (const person of present.values()) if (person) n += 1; return n; };
@@ -461,9 +495,11 @@ export function createHost(o: HostOptions): Host {
       }
       const claim = kind.body?.owner && raw.length >= i + 9 ? { pos: unpackVec([raw[i], raw[i + 1], raw[i + 2]], c.dims), vel: unpackVec([raw[i + 3], raw[i + 4], raw[i + 5]], c.dims), heading: unpackVec([raw[i + 6], raw[i + 7], raw[i + 8]], c.dims), r } : null;
       q.stamps.push(j);
-      if (j > K) { q.entries.push({ at: j, values, presses, claim }); continue; }
+      if (j > K) { q.entries.push({ at: j, values, presses, claim, early: Math.min(lateTicks, j - K) }); continue; }
       // Late: its values hold from the next tick, and its presses fire there if that is within a quarter of a second of its stamp.
       stats.lateEntries += 1;
+      const book = heldBook.get(seat as number);
+      if (book) for (const row of book.ran) if (row[0] >= j) { for (const name of heldOf(kind)) { const meant = Number(values[name]) || 0; book.debt[name] = (book.debt[name] ?? 0) + meant - (row[1][name] ?? 0); row[1][name] = meant; } book.until = K + 1 + lateTicks; }
       const at = (K + 1) >>> 0;
       const keep = at - j <= lateTicks ? presses : [];
       const same = q.entries.find((x) => x.at === at);
@@ -554,9 +590,15 @@ export function createHost(o: HostOptions): Host {
         if (agents && (kind === 'agent:do' || /^ask:/.test(kind) || (SPEECH.test(kind) && present.get(m.from as number) === false))) { if (agentInbox.length < 128) agentInbox.push(m); return; }
         if(kind === 'pulse') {
           const data=m.d,body=core.bodyOf(m.from as number);
-          if(!body || !hasHands(m.from as number,body.driver) || !Array.isArray(data) || data.length!==3 || data[0]!==epoch || typeof data[1]!=='string' || !body.kind.input.some(([name,fd])=>name===data[1]&&fd.t==='pulse'))return;
+          if(!body || !hasHands(m.from as number,body.driver) || !Array.isArray(data) || data.length<3 || data.length>5 || data[0]!==epoch || typeof data[1]!=='string' || !body.kind.input.some(([name,fd])=>name===data[1]&&fd.t==='pulse'))return;
           const value=coerce({t:'pulse'},data[2],c.dims) as number,q=queueOf(m.from as number,body.kind);q.pulses??=[];
-          if(value && q.pulses.length<16)q.pulses.push([data[1],value]);return;
+          // The browser names the tick it predicted the pulse on (0.46.3): the server acts on it in that tick, as it does for a
+          // stamped input, so what was predicted is what the tick's snapshot holds. A tick already run, or none: at once.
+          const at=Number.isInteger(data[3])&&(data[3] as number)>0?Math.min(data[3] as number,0xffffffff):0;
+          // Its number in this browser's own count (0.46.3): the control row says the newest one acted on, so a browser knows
+          // whether a pulse it predicted has happened yet, however late its message was.
+          const n=Number.isInteger(data[4])&&(data[4] as number)>0?Math.min(data[4] as number,0xffffffff):0;
+          if(value && q.pulses.length<16)q.pulses.push(n?[data[1],value,at,n]:at?[data[1],value,at]:[data[1],value]);return;
         }
         if (kind === 'cmd') { const d = m.d as unknown[]; if (Array.isArray(d) && typeof d[0] === 'string') core.command(m.from as number, d[0], d[1]); return; }
         // Speech keeps its payload, except the identity fields only the host may attach.
@@ -616,10 +658,27 @@ export function createHost(o: HostOptions): Host {
         } });
       } else if (x.t === 'ask') o.send({ t: 'decide', n: x.n, state: x.state, questions: x.questions });
       else if (x.t === 'goalDone') agents?.done(x.seat, x.ok);
-      else if (x.t === 'fx') o.send({ t: 'ev', from: null, k: 'fx', d: [x.tick, x.list] });
+      else if (x.t === 'fx') {
+        // Effects with an audience (0.46.3) go to who may perceive them: one frame a person whose body is named or in
+        // range, with the tick's public effects in the order they were emitted. A watcher (no seat) and a seat with no
+        // body perceive the room: every effect with a range, never one addressed only `to` somebody.
+        // A tick with no audience at all is one frame for everybody, as before.
+        if (!x.list.some((row) => row[3])) o.send({ t: 'ev', from: null, k: 'fx', d: [x.tick, x.list] });
+        else {
+          const all = x.list.map((row) => [row[0], row[1], row[2]]);
+          const bodies = new Map(core.listeners().map((l) => [l.seat, l]));
+          const watching = all.filter((_, n) => { const a = x.list[n][3]; return !a || a[0] >= 0; });
+          for (const seat of present.keys()) {
+            const l = bodies.get(seat);
+            const mine = !l ? watching : all.filter((_, n) => { const a = x.list[n][3]; return !a || a[1].includes(l.id) || (a[0] >= 0 && a[2] !== null && Math.hypot(a[2][0] - l.pos.x, a[2][1] - l.pos.y, a[2][2] - l.pos.z) <= a[0]); });
+            if (mine.length) o.send({ t: 'ev', from: null, k: 'fx', d: [x.tick, mine], to: seat });
+          }
+          if (watching.length) o.send({ t: 'ev', from: null, k: 'fx', d: [x.tick, watching], to: -1 });
+        }
+      }
       else if (x.t === 'seats') roster = true;
       else if (x.t === 'shared') o.send({ t: 'state', k: 'shared', d: core.shared() });
-      else if (x.t === 'epoch') { forceSave = true; epoch = x.epoch; queues.clear(); roster = true; } else if (x.t === 'fail') end('budget', { kind: x.kind, handler: x.handler });
+      else if (x.t === 'epoch') { forceSave = true; epoch = x.epoch; queues.clear(); heldBook.clear(); pulsesTaken.clear(); roster = true; } else if (x.t === 'fail') end('budget', { kind: x.kind, handler: x.handler });
     }
     if (roster || !rosterText) sendRoster();
   }
@@ -639,15 +698,26 @@ export function createHost(o: HostOptions): Host {
       const presses: (string | [string, number])[] = [];
       while (q.entries.length && q.entries[0].at <= t) {
         const e = q.entries.shift() as Entry;
-        q.held = e.values; q.claim = e.claim;
+        q.held = e.values; q.claim = e.claim; q.early = e.early ?? 1;
         if (e.at === t) for (const p of e.presses) presses.push(p);
       }
       // Silence: no frame for a second. Its input is neutral until the next entry.
       if (t - q.lastFrameTick > tickHz && !q.entries.length) { q.held = neutral(body.kind); q.claim = null; }
       while (q.stamps.length && q.stamps[0] <= t) q.ack = q.stamps.shift() as number;
       const values = { ...q.held };
+      const heldFields = heldOf(body.kind);
+      if (heldFields.length) {
+        let book = heldBook.get(seat);
+        if (!book) { book = { ran: [], debt: {}, until: 0 }; heldBook.set(seat, book); }
+        const level: Record<string, number> = {};
+        for (const name of heldFields) level[name] = Number(values[name]) || 0;
+        book.ran.push([t, level]); if (book.ran.length > lateTicks + 1) book.ran.shift();
+        if (book.until >= t) for (const name of heldFields) { const owed = book.debt[name]; if (owed) { const range = Math.max(1, Math.abs(level[name])), want = level[name] + owed, paid = Math.max(-range, Math.min(range, want)); values[name] = paid; book.debt[name] = want - paid; } }
+        else book.debt = {};
+      }
       for (const p of presses) { if (typeof p === 'string') values[p] = true; else values[p[0]] = p[1]; }
-      const pulse=q.pulses?.shift();if(pulse)values[pulse[0]]=pulse[1];
+      // One pulse a tick, in order: the head waits for its own tick when that is no more than a quarter of a second ahead.
+      const head=q.pulses?.[0];if(head&&!((head[2]??0)>t&&(head[2] as number)-t<=Math.ceil(tickHz/4))){q.pulses!.shift();values[head[0]]=head[1];if(head[3])pulsesTaken.set(seat,head[3]);}
       inputs.set(seat, { values, claim: q.claim });
     }
     if (roundRebasePending) publishRebase(now);
@@ -677,7 +747,9 @@ export function createHost(o: HostOptions): Host {
     for (const b of core.bodies()) {
       if (!hasHands(b.seat, b.driver)) continue;
       const q = queues.get(b.seat);
-      rows.push([b.seat, b.r, q ? q.ack : 0, q && q.lead !== 127 ? q.lead : -128]);
+      // A fifth number only for a seat that has sent a numbered pulse: the newest one acted on.
+      const taken = pulsesTaken.get(b.seat);
+      rows.push(taken === undefined ? [b.seat, b.r, q ? q.ack : 0, q && q.lead !== 127 ? q.lead : -128] : [b.seat, b.r, q ? q.ack : 0, q && q.lead !== 127 ? q.lead : -128, taken]);
       if (q) q.lead = 127;
     }
     // A snapshot is stamped with the moment its tick was due, so ticks run in a burst to catch up are still a tick

package/rules/pack.ts

@@ -140,6 +140,7 @@ const made = <T extends object>(fd: Field, o: T): T => { Object.freeze(o); MADE.
 export function coerce(fd: Field, v: unknown, dims: number): unknown {
   switch (fd.t) {
     case 'bit': case 'press': return v === true || v === 1;
+    case 'held':
     case 'fix': { const x = num(v); const n = Math.round(x * FIX_STEP) / FIX_STEP; return Number.isFinite(n) ? Math.max(-FIX_MAX, Math.min(FIX_MAX, n)) + 0 : zeroed(v, x); }
     case 'vec3': return vec3(v, dims);
     case 'dir': return dir(v, dims);