@homie-rocks/studio 0.46.2 → 0.46.5

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;
@@ -2547,6 +2547,8 @@ export function createNetplay<S = unknown, A = unknown, C = unknown>(opts: Netpl
         // An AI alone in a room (nobody seated): it knocks again only after a while (section 17).
         if (code === 'agents-alone') aloneUntil = wall() + AGENTS_ALONE_WAIT_MS;
         if (code === 'host-fault') { rulesNotice(String(m.message)); return; }
+        // A result the server could not keep for this player (0.46.5): said on their screen, not dropped in silence.
+        if (code === 'unsaved') { rulesNotice(String(m.message)); return; }
         if (code === 'vote') { warnOnce('vote', m['message']); return; }
         if (code === 'rate' || code === 'state-full') { warnOnce(`${code}:${String(m['of'] ?? '')}`, m['message']); return; }
         // The room still runs another build of the game (section 23): not final. Its players were told to reload; this

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@homie-rocks/studio",
-  "version": "0.46.2",
+  "version": "0.46.5",
   "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,27 @@ 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 historyTicks = Math.ceil((c.historySeconds ?? 0) * tickHz);
+  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 +438,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 +496,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 +591,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.
@@ -586,7 +629,9 @@ export function createHost(o: HostOptions): Host {
   /* ---------------------------------------------------------------- frames out */
 
   const hasHands = (seat: number, driver: Driver): boolean => driver === 'person' || (driver === 'ai' && [...peers.values()].some((p) => p.seat === seat && p.agent?.hands === 'self'));
-  const nameOf = (seat: number, driver: Driver): string => (driver === 'bot' || (driver === 'ai' && (core.bodies().find((b) => b.seat === seat)?.owner === 'reserved' || !names.has(seat))) ? BOT_NAMES[seat % BOT_NAMES.length] : names.get(seat) || `Player ${seat + 1}`);
+  // The game's own names for its bots (room.bots.names, 0.46.5), else the toolkit's.
+  const botNames = c.botNames?.length ? c.botNames : BOT_NAMES;
+  const nameOf = (seat: number, driver: Driver): string => (driver === 'bot' || (driver === 'ai' && (core.bodies().find((b) => b.seat === seat)?.owner === 'reserved' || !names.has(seat))) ? botNames[seat % botNames.length] : names.get(seat) || `Player ${seat + 1}`);
   function sendRoster(): void {
     const guides = new Map(agentSlots().map((s) => [s.slot, s.agent]));
     const slots = core.bodies().sort((a, b) => a.seat - b.seat).map((b) => ({ slot: b.seat, seat: b.driver === 'bot' ? null : b.seat, name: nameOf(b.seat, b.driver), bot: b.driver === 'bot', ...(guides.has(b.seat) ? { agent: guides.get(b.seat) } : {}) }));
@@ -616,10 +661,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 +701,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 +750,14 @@ 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);
+      const row = [b.seat, b.r, q ? q.ack : 0, q && q.lead !== 127 ? q.lead : -128];
+      // A sixth number only in a game that rewinds (room.historySeconds, 0.46.5): how many ticks back this seat's own
+      // ray may look right now, so its browser can predict against the pose the server will judge, not a guess at it.
+      if (historyTicks) row.push(taken ?? 0, Math.min(historyTicks, rewindTicks(b.seat)));
+      else if (taken !== undefined) row.push(taken);
+      rows.push(row);
       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);

package/rules/rules.ts

@@ -54,7 +54,7 @@ export const QUEUE_MAX = 16_384;
 
 /* ------------------------------------------------------------------ field types */
 
-export type FieldKind = 'u8' | 'u16' | 'u32' | 'i8' | 'i16' | 'i32' | 'bit' | 'fix' | 'vec3' | 'dir' | 'tick' | 'ticks' | 'ref' | 'text' | 'list' | 'map' | 'struct' | 'press' | 'pulse';
+export type FieldKind = 'u8' | 'u16' | 'u32' | 'i8' | 'i16' | 'i32' | 'bit' | 'fix' | 'vec3' | 'dir' | 'tick' | 'ticks' | 'ref' | 'text' | 'list' | 'map' | 'struct' | 'press' | 'pulse' | 'held';
 export interface Field {
   readonly t: FieldKind;
   /** The value a new entity starts with. */
@@ -82,7 +82,8 @@ const plain = (t: FieldKind) => (o?: FieldOptions): Field => made(t, o);
  * false; `fix` is a fixed-point number in steps of 1/4096; `vec3` is a position or a velocity in metres; `dir` is a
  * unit vector in the declared dimensions; `tick` is a moment and `ticks` a length on the room's clock; `ref` is the id of an
  * entity or a player; `text`, `list` and `map` name their largest size. `press` (in `input` only) is a button that
- * fires once.
+ * fires once; `held` (in `input` only) is a number the browser averages over each tick, so a tap shorter than a tick
+ * moves for the part of the tick it was down.
  */
 export const f = brand(Object.freeze({
   u8: plain('u8'), u16: plain('u16'), u32: plain('u32'), i8: plain('i8'), i16: plain('i16'), i32: plain('i32'),
@@ -93,6 +94,8 @@ export const f = brand(Object.freeze({
   struct: (fields: Fields, o?: FieldOptions): Field => made('struct', o, { fields: Object.freeze({ ...fields }) }),
   press: (): Field => made('press', undefined),
   pulse: (): Field => made('pulse', undefined),
+  /** Input only (0.46.3): a number averaged over the tick. A key down for a third of a tick reads a third; a stick reads its mean. */
+  held: (): Field => made('held', undefined),
 }));
 
 /**
@@ -164,9 +167,12 @@ export interface RulesDef {
   shared?: Fields;
   room?: {
     rounds?: { seconds: number; breakSeconds: number };
-    bots?: { keep: number };
+    /** `names` (0.46.5): what the game's bots are called, by seat; the toolkit's own list without it. */
+    bots?: { keep: number; names?: readonly string[] };
     records?: RoundRecords;
     historySeconds?: number;
+  /** The furthest a person's ray may be rewound, in seconds (0.46.3): a hard cap under `historySeconds`, whatever their connection measures. */
+  rewindSeconds?: number;
     start?: RoomHandler;
     join?: (ctx: any, player: { seat: number; driver: 'person' | 'bot' | 'ai'; owner: string; character?: Character | null }) => { kind: string; at: Vec3; heading?: Vec3; fields?: Record<string, unknown>; motion?: Record<string, unknown> };
     on?: Record<string, RoomHandler>;
@@ -387,8 +393,11 @@ export interface Compiled {
   view: FieldList;
   records?: RoundRecords;
   historySeconds?: number;
+  /** The furthest a person's ray may be rewound, in seconds (0.46.3): a hard cap under `historySeconds`, whatever their connection measures. */
+  rewindSeconds?: number;
   rounds: { seconds: number; breakSeconds: number } | null;
   bots: number;
+  botNames?: readonly string[];
   start: RoomHandler | null;
   join: NonNullable<RulesDef['room']>['join'] | null;
   roomOn: Record<string, RoomHandler>;
@@ -409,7 +418,7 @@ export const BUILT_IN_FIELDS = Object.freeze(['id', 'kind', 'pos', 'vel', 'headi
 
 const NAME = /^[a-z][A-Za-z0-9_]{0,31}$/;
 const INTS = new Set(['u8', 'u16', 'u32', 'i8', 'i16', 'i32']);
-const TYPES = new Set(['u8', 'u16', 'u32', 'i8', 'i16', 'i32', 'bit', 'fix', 'vec3', 'dir', 'tick', 'ticks', 'ref', 'text', 'list', 'map', 'struct', 'press', 'pulse']);
+const TYPES = new Set(['u8', 'u16', 'u32', 'i8', 'i16', 'i32', 'bit', 'fix', 'vec3', 'dir', 'tick', 'ticks', 'ref', 'text', 'list', 'map', 'struct', 'press', 'pulse', 'held']);
 
 /**
  * One declared field, checked, and made again as the runtime's own: a frozen record of its type, its sizes and its
@@ -436,7 +445,8 @@ function checkField(fd: unknown, where: string, inInput: boolean): void {
   const x = fd as Field;
   if (!x || typeof x !== 'object' || typeof x.t !== 'string' || !TYPES.has(x.t)) throw new Error(`${where} is not a field type: declare it with f (f.u16(), f.vec3(), f.list(f.ref(), 8)…)`);
   if ((x.t === 'press' || x.t === 'pulse') && !inInput) throw new Error(`${where}: f.press() is for input only (a button that fires once)`);
-  if (inInput && !(INTS.has(x.t) || x.t === 'bit' || x.t === 'press' || x.t === 'pulse' || x.t === 'fix')) throw new Error(`${where}: an input field is a whole number, f.fix(), f.bit() or f.press()`);
+  if (x.t === 'held' && !inInput) throw new Error(`${where}: f.held() is for input only (a control averaged over the tick it was held in)`);
+  if (inInput && !(INTS.has(x.t) || x.t === 'bit' || x.t === 'press' || x.t === 'pulse' || x.t === 'held' || x.t === 'fix')) throw new Error(`${where}: an input field is a whole number, f.fix(), f.held(), f.bit() or f.press()`);
   if (x.durable !== undefined && (typeof x.durable !== 'boolean' || inInput || !/^(entities\.[^.]+\.fields|shared)\.[^.]+$/.test(where))) throw new Error(`${where}: durable belongs on a top-level state field`);
   if (x.visibility !== undefined && !/^entities\.[^.]+\.fields\.[^.]+$/.test(where)) throw new Error(`${where}: visibility belongs on a top-level entity field`);
   if (x.visibility !== undefined && (!['owner','server','results'].includes(x.visibility) || inInput)) throw new Error(`${where}: visibility is owner, server or results on state fields only`);
@@ -628,6 +638,8 @@ export function compileRules(def: RulesDef, env: CompileEnv = {}): Compiled {
   }
   const keep = room.bots === undefined ? 0 : typeof room.bots?.keep === 'number' ? Math.floor(room.bots.keep) : NaN;
   if (!(keep >= 0 && keep <= SEATS_MAX)) throw new Error(`room.bots is { keep: n }, 0 to ${SEATS_MAX}`);
+  const botNames = (room.bots as { names?: unknown } | undefined)?.names;
+  if (botNames !== undefined && !(Array.isArray(botNames) && botNames.length >= 1 && botNames.length <= 64 && botNames.every((n) => typeof n === 'string' && n.trim().length >= 1 && n.length <= 24 && !/[\u0000-\u001f\u007f\u200b-\u200f\u202a-\u202e\u2066-\u2069]/.test(n)))) throw new Error('room.bots.names is a list of 1 to 64 names, each 1 to 24 characters on one line');
   if (room.start !== undefined && typeof room.start !== 'function') throw new Error('room.start is a function');
   if (room.join !== undefined && typeof room.join !== 'function') throw new Error('room.join is a function');
   const players = kinds.filter((k) => k.player);
@@ -646,13 +658,14 @@ export function compileRules(def: RulesDef, env: CompileEnv = {}): Compiled {
     }
   }
   if (room.historySeconds !== undefined && (typeof room.historySeconds !== 'number' || !Number.isFinite(room.historySeconds) || room.historySeconds < 0 || room.historySeconds > 2)) throw new Error('room.historySeconds is from 0 to 2');
+  if (room.rewindSeconds !== undefined && (typeof room.rewindSeconds !== 'number' || !Number.isFinite(room.rewindSeconds) || room.rewindSeconds < 0 || room.rewindSeconds > (room.historySeconds ?? 0))) throw new Error('room.rewindSeconds is the most a shot is rewound for a slow connection: a number from 0 to room.historySeconds');
   const seats = Math.max(1, Math.min(Number.MAX_SAFE_INTEGER, Math.floor(Number(env.seats)) || 8));
   const navigation:Record<string,readonly RouteNode[]> = Object.create(null);let graphNodes=0;
   if(d.navigation){const entries=Object.entries(d.navigation);if(entries.length>8)throw new Error('navigation declares at most 8 graphs');for(const [name,graph] of entries){if(!/^[A-Za-z][A-Za-z0-9_]{0,47}$/.test(name))throw new Error('navigation graph names are identifiers up to 48 characters');navigation[name]=prepareGraph(graph);graphNodes+=navigation[name].length;if(graphNodes>8192)throw new Error('navigation declares at most 8192 nodes in total');}}
   Object.freeze(navigation);
   return {
     navigation, contract: RULES_CONTRACT, save: SAVE_REVISION, dims, kinds, kindOf, events, commands, effects, effectNames: Object.keys(effects),
-    shared: fieldList(d.shared, 'shared'), view, ...(room.records?{records:room.records}:{}), ...(room.historySeconds ? {historySeconds:room.historySeconds}:{}), rounds, bots: Math.min(keep, seats), start: room.start ?? null, join: room.join ?? null, roomOn, asks,
+    shared: fieldList(d.shared, 'shared'), view, ...(room.records?{records:room.records}:{}), ...(room.historySeconds ? {historySeconds:room.historySeconds}:{}), ...(room.rewindSeconds !== undefined ? {rewindSeconds:room.rewindSeconds}:{}), rounds, ...(botNames ? { botNames: Object.freeze([...(botNames as string[])]) } : {}), bots: Math.min(keep, seats), start: room.start ?? null, join: room.join ?? null, roomOn, asks,
     tune, publicTune, map, settings, seats,
   };
 }
@@ -665,6 +678,8 @@ export function compileRules(def: RulesDef, env: CompileEnv = {}): Compiled {
  */
 export interface Schema {
   records?: true;
+  /** A game that rewinds (0.46.5): its window and its cap, for a browser predicting its own shots. */
+  rewind?: { historySeconds: number; capSeconds?: number };
   contract: 2;
   dims: 2 | 3;
   seats: number;
@@ -674,6 +689,8 @@ export interface Schema {
   commands: Record<string, FieldList>;
   shared: FieldList;
   historySeconds?: number;
+  /** The furthest a person's ray may be rewound, in seconds (0.46.3): a hard cap under `historySeconds`, whatever their connection measures. */
+  rewindSeconds?: number;
   rounds: { seconds: number; breakSeconds: number } | null;
   settings: RoomSettings;
 }
@@ -687,7 +704,7 @@ function publicField(field: Field, hidden=false): Field {
 }
 export function schemaOf(c: Compiled): Schema {
   return {
-    contract: RULES_CONTRACT, dims: c.dims, seats: c.seats, ...(c.records?{records:true as const}:{}),
+    contract: RULES_CONTRACT, dims: c.dims, seats: c.seats, ...(c.records?{records:true as const}:{}), ...(c.historySeconds ? { rewind: { historySeconds: c.historySeconds, ...(c.rewindSeconds !== undefined ? { capSeconds: c.rewindSeconds } : {}) } } : {}),
     kinds: c.kinds.map((k) => ({ ...(k.query?{query:k.query}:{}), ...(k.collider?{collider:k.collider}:{}), ...(k.body?.terrain ? {terrain:k.body.terrain} : {}), name: k.name, player: Boolean(k.player), ...(k.player?.control ? {control:k.player.control}:{}), owner: Boolean(k.body?.owner), radius: k.body?.radius ?? 0, ...(c.dims === 3 && k.body ? { shape: k.body.shape, height: k.body.height || 2 * k.body.radius } : {}), maxSpeed: k.body?.maxSpeed ?? 0, score: k.score, fields: k.fields.map(([name,field])=>[name,publicField(field)]), motion: k.motion, input: k.input })),
     effects: c.effects, effectNames: c.effectNames, commands: c.commands, shared: c.shared, rounds: c.rounds, settings: c.settings,
   };

package/rules/types.ts

@@ -22,6 +22,7 @@ export interface RayOptions {
 export type RayHit = Hit & { readonly dist: number };
 export interface RaySnapshot {sweep(body:{pos:Point;grounded?:boolean},delta:Point,options?:{ground?:boolean}):Hit|undefined;support(body:{pos:Point},distance?:number):(Hit&{dist:number})|undefined;ray(from:Point,direction:Point,max:number):RayHit|undefined;rayAll(from:Point,direction:Point,max:number):readonly RayHit[]}
 export interface RayQueries { rays(options?:RayOptions):RaySnapshot; ray(from: Point, direction: Point, max: number, options?: RayOptions): RayHit | undefined; rayAll(from: Point, direction: Point, max: number, options?: RayOptions): readonly RayHit[] }
+export interface EffectAudience { readonly to?: string | readonly string[]; readonly within?: number }
 export type Area = { sphere: { at: Point; r: number } } | { box: { min: Point; max: Point } } | { cone: { at: Point; dir: Point; r: number; angle: number } };
 export interface MapView { readonly name: string; spot(name: string): Vec3 | undefined; spots(name: string): readonly Vec3[] }
 export interface Clock { readonly tick: number; readonly dt: number; ticks(seconds: number): number; readonly math: typeof math }
@@ -30,6 +31,8 @@ export type World<E, F, S, V, C, A, T, Room extends boolean = false> = Clock & {
   readonly tune: ReadonlyState<T>; readonly map: MapView; readonly stage: string; readonly level: number; readonly levelMax: number; readonly guideLevel: number; readonly guideSeats: readonly number[]; readonly kids: boolean; readonly levelSet: boolean;
   readonly shared: Room extends true ? S : ReadonlyState<S>;
   readonly round: Round & (Room extends true ? { end(): void; restart(): void } : {});
+  /** Budget units the running handler may still spend (0.46.3). */
+  readonly unitsLeft: number;
   random(): number;
   label(player:string):string;
   send<K extends keyof E>(target: string, event: K, ...data: Payload<E[K]>): void;
@@ -38,6 +41,8 @@ export type World<E, F, S, V, C, A, T, Room extends boolean = false> = Clock & {
   sendArea<K extends keyof E>(area: Area, event: K, ...data: Payload<E[K]>): void;
   after<K extends keyof E>(ticks: number, event: K, ...data: Payload<E[K]>): void;
   emit<K extends keyof F>(effect: K, at: Point | string, ...data: Payload<F[K]>): void;
+  /** With an audience (0.46.3): only the people driving the entities named in `to`, and those whose own body is within `within` metres, receive it. A watcher receives the ones with a range, never one addressed only `to` somebody. */
+  emit<K extends keyof F>(effect: K, at: Point | string, data: WriteState<F[K]>, audience: EffectAudience): void;
   spawn<K extends keyof C>(kind: K, at: Point, fields?: Partial<WriteState<C[K]>>): string;
   near<K extends keyof V>(at: Point, radius: number, kind: K): readonly Query<V[K]>[];
   near(at: Point, radius: number): readonly Query<V[keyof V]>[];