@homie-rocks/studio 0.43.0 → 0.44.0

package/CHANGELOG.md

@@ -17,9 +17,25 @@ 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.44.0] - 2026-10-10
+
+**Plugin 0.44.0** · [#83](https://github.com/homie-rocks/homie/pull/83)
+
+Send each player the part of the room near their character.
+
+### Added
+
+- Server-hosted rules games can choose `room.view.radiusM` in game.json. Views receive nearby entities and their own body, with compact state updates and fresh state on reconnect. Omit it to keep the whole-room view.
+- Seeded tests cover spatial visibility, delta recovery and 300 simulated clients through the host and relay. The longer capacity workload runs in the extended suite.
+
+### Upgrade notes
+
+- `room.each`, `enter` and `leave` describe visible entities when a radius is set. Dispose of departed meshes and recreate them when they return. Rules and movement need no changes; existing starters keep their whole-room views.
+- This is the first bigger-rooms slice. The public build/join path still has 32 seats until Gates ship in the next slice. The 300-client proof is local, not a Cloudflare capacity measurement. Interest filtering does not hide secrets; private fields and tells follow later.
+
 ## [0.43.0] - 2026-10-09
 
-**Plugin 0.43.0**
+**Plugin 0.43.0** · [release-2026-10-10-studio-0.43.0](https://github.com/homie-rocks/homie/releases/tag/release-2026-10-10-studio-0.43.0)
 
 Ask for a game and its rules run on your server.
 

package/README.md

@@ -1259,3 +1259,17 @@ Homie as a short note you see and send yourself (`homie_feedback`, above).
 ## License
 
 Apache-2.0. See `LICENSE` and `NOTICE`.
+
+
+### Spatial state delivery
+
+Server-hosted rules games may set `room.view.radiusM` in game.json to send each
+player nearby entities and its own body. Omitted or null sends the whole room.
+Rules and movement stay the same; the view's `each`, `enter` and `leave` describe
+the visible set. Dispose of meshes on leave and recreate them on enter.
+Watchers, shared state, effects and rosters remain public. This is bandwidth
+filtering, not private state. Browser-hosted rooms send the whole room.
+
+0.44.0 delivers this first part of bigger rooms. Public admission above 32 seats
+arrives with Gates in the next slice. See [the milestone 2 notes](../../docs/rooms-milestone-2-notes.md)
+for the remaining slices and the local 300-client proof.

package/lib/template-history.json

@@ -2385,6 +2385,47 @@
      }
     }
    }
+  },
+  "0.44.0": {
+   "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": "34444a6ca4b14437"
+   },
+   "sections": {
+    "AGENTS.md": {
+     "(intro)": "214aa46eb3a895d5",
+     "## Layout": "f3a280b8c96cd068",
+     "## Apps: one screen, roles and parts": "8596f2b25edda3e2",
+     "## Commands (all through the pinned CLI in node_modules)": "159151b8861fc051",
+     "## The site": "0cb8dd9a6f8a0096",
+     "## Making games": "9e44559de535d842",
+     "## The Game Codex and progress": "0738ef719cef3a4c",
+     "## Art direction and models": "a48fff7bf0a5f2fc",
+     "## Running live games (the back office)": "51ebf2ab756f6e4d",
+     "## Servers and AI seats": "d0028361fe567add",
+     "## Selling things (the shop)": "9e020d69dd6a954e",
+     "## Continuing a build from the Claude app": "0d68081e924ca419",
+     "## Rules": "2e6b29afb85dcf7e",
+     "## Telling Homie": "80b46fdd9e578db8",
+     "## Beta": "9d02638207a26e73"
+    }
+   },
+   "named": {
+    "Homie Arcade": {
+     "sections": {
+      "AGENTS.md": {
+       "## Commands (all through the pinned CLI in node_modules)": "2cdd530e48170bfd"
+      }
+     }
+    }
+   }
   }
  }
 }

package/netplay/netplay.ts

@@ -2628,6 +2628,9 @@ export function createNetplay<S = unknown, A = unknown, C = unknown>(opts: Netpl
       setRole(next, wasOffline && roleKnown ? 'reconnected' : String(m['why'] ?? 'welcome'), { ckpt, snap, round: roundInfo, roster: slots });
       if (next === 'host' && snap) tick = Math.max(tick, snap.k);
     }
+    // A reconnect to the same role emits no role event, but its welcome is a new
+    // connection's keyframe. Rules views must adopt it before the first delta.
+    if (rulesGame && snap && next !== 'host') emit('snapshot', snap);
     if (continuing) { rulesHost?.sync(rulesPeers()); reannounce(); catchUp(had, hadSeat); }
     if (link === 'online') paintLink(); else setLink('online', 'welcome');
     // A build older than the live one, let in to its own room (section 23).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@homie-rocks/studio",
-  "version": "0.43.0",
+  "version": "0.44.0",
   "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/host.ts

@@ -99,6 +99,7 @@ export interface Host {
   readonly running: boolean;
   readonly paused: boolean;
   readonly people: number;
+  readonly viewRadiusM: number | null;
   frame(m: Record<string, unknown>): void;
   /** Start the tick loop (the first person has joined). */
   start(): void;
@@ -767,6 +768,7 @@ export function createHost(o: HostOptions): Host {
   }
 
   return {
+    get viewRadiusM() { return c.settings.view?.radiusM ?? null; },
     get tick() { return core.tick; },
     get epoch() { return epoch; },
     get running() { return running; },

package/rules/interest.mjs

@@ -0,0 +1,79 @@
+/** Per-connection state delivery. Pure data, shared by the relay and the view.
+ * Deltas name a keyframe, never an unacknowledged previous delta. Losing a delta
+ * therefore loses no baseline. A new keyframe bounds recovery to one second.
+ * No history grows with time: one keyframe per connection, no per-frame queue.
+ */
+export function interestSnapshot(snap, seat, radiusM) {
+  const [round, entities] = snap.d;
+  const own = seat === null ? null : entities.find(e => e[9] === seat && e[10] === 0);
+  const visible = own && radiusM !== null ? entities.filter(e => {
+    const p = e[3], q = own[3];
+    return e === own || (p[0] - q[0]) ** 2 + (p[1] - q[1]) ** 2 + ((p[2] ?? 0) - (q[2] ?? 0)) ** 2 <= radiusM ** 2;
+  }) : seat === null ? entities : own ? entities : [];
+  return { ...snap, d: [round, visible], c: (snap.c ?? []).filter(row => row[0] === seat) };
+}
+
+export function snapshotEncoder(keyframeTicks) {
+  let base = null;
+  let rows = new Map();
+  return {
+    reset() { base = null; rows.clear(); },
+    encode(snap) {
+      if (!base || snap.e !== base.e || snap.k <= base.k || snap.k - base.k >= keyframeTicks) {
+        base = snap;
+        rows = new Map(snap.d[1].map(e => [e[0], e.map(v => JSON.stringify(v))]));
+        return snap;
+      }
+      const present = new Set(), changed = [];
+      for (const entity of snap.d[1]) {
+        const id = entity[0]; present.add(id);
+        const before = rows.get(id);
+        if (!before) { changed.push(entity); continue; }
+        let mask = 0; const values = [];
+        for (let i = 1; i < entity.length; i++) if (JSON.stringify(entity[i]) !== before[i]) { mask |= 1 << i; values.push(entity[i]); }
+        if (mask) changed.push([id, mask, values]);
+      }
+      return { ...snap, d: { base: base.k, round: snap.d[0], changed, removed: [...rows.keys()].filter(id => !present.has(id)) } };
+    },
+  };
+}
+
+export function snapshotDecoder() {
+  let base = null;
+  let rows = new Map();
+  return {
+    reset() { base = null; rows.clear(); },
+    decode(snap) {
+      if (!snap || typeof snap !== 'object') return null;
+      if (Array.isArray(snap.d)) {
+        if (!Array.isArray(snap.d[0]) || !Array.isArray(snap.d[1]) ||
+          !snap.d[1].every(e => Array.isArray(e) && e.length >= 9 && typeof e[0] === 'string')) return null;
+        // A late duplicate keyframe must not replace the newer baseline.
+        if (!base || snap.e !== base.e || snap.k >= base.k) {
+          base = snap; rows = new Map(snap.d[1].map(e => [e[0], e]));
+        }
+        return snap;
+      }
+      const d = snap.d;
+      if (!base || !d || d.base !== base.k || snap.e !== base.e || snap.k <= base.k) return null;
+      if (!Array.isArray(d.round) || !Array.isArray(d.removed) || !Array.isArray(d.changed)) return null;
+      const next = new Map(rows);
+      for (const id of d.removed) next.delete(id);
+      for (const change of d.changed) {
+        if (!Array.isArray(change) || typeof change[0] !== 'string') return null;
+        if (change.length !== 3) {
+          if (change.length < 9) return null;
+          next.set(change[0], change); continue;
+        }
+        if (!Number.isInteger(change[1]) || change[1] < 0 || !Array.isArray(change[2])) return null;
+        const old = rows.get(change[0]);
+        if (!old) return null;
+        const entity = old.slice(); let j = 0;
+        for (let i = 1; i < entity.length; i++) if (change[1] & (1 << i)) entity[i] = change[2][j++];
+        if (j !== change[2].length) return null;
+        next.set(entity[0], entity);
+      }
+      return { ...snap, d: [d.round, [...next.values()]] };
+    },
+  };
+}

package/rules/rules.ts

@@ -37,7 +37,7 @@ export const SAVE_REVISION = 2;
 export const REACH_M = 64;
 /** The most entities one room holds. A spawn past it throws in the handler that asked. */
 export const ENTITY_MAX = 2048;
-/** The most seats one room holds (worker/seats.mjs `SEAT_MAX`). */
+/** The current bot-fill ceiling; public admission lives in worker/seats.mjs. */
 export const SEATS_MAX = 32;
 /** The most values one declared field may hold when it is full (`cellsOf`), and the most all the fields of one kind of entity may. */
 export const FIELD_CELLS_MAX = 16_384;
@@ -176,6 +176,8 @@ export interface RoomSettings {
   offline: boolean;
   tickHz: number;
   inputHz: number;
+  /** Omit the radius to send the whole room. No implicit visibility or bandwidth cap. */
+  view: { radiusM: number | null };
   durability: { movementSeconds: number };
   budget: { tick: number };
   predict: { catchM: number | null; catchUp: number; snapM: number | null; blendMs: number; interpMs: number | null };
@@ -191,7 +193,7 @@ export const BUDGET_TICK = 500_000;
 export const BUDGET_SECOND = 10_000_000;
 export const budgetFor = (tickHz: number): number => Math.min(BUDGET_TICK, Math.floor(BUDGET_SECOND / tickHz));
 export const ROOM_DEFAULTS: RoomSettings = deepFreeze({
-  host: 'server', offline: true, tickHz: 20, inputHz: 20, durability: { movementSeconds: 1 }, budget: { tick: BUDGET_TICK },
+  host: 'server', offline: true, tickHz: 20, inputHz: 20, view: { radiusM: null }, durability: { movementSeconds: 1 }, budget: { tick: BUDGET_TICK },
   predict: { catchM: null, catchUp: 1.25, snapM: null, blendMs: 100, interpMs: null },
 });
 
@@ -212,18 +214,24 @@ export function roomSettings(raw: unknown): { settings: RoomSettings; problems:
     if (!Number.isFinite(n) || n < 0) { problems.push(`"room.${name}" is a number, zero or more; using its default`); return d; }
     return n;
   };
-  const known = new Set(['host', 'offline', 'tickHz', 'inputHz', 'durability', 'budget', 'predict']);
-  for (const key of Object.keys(r)) if (!known.has(key)) problems.push(`"room.${key}" is not a setting (host, offline, tickHz, inputHz, durability, budget, predict)`);
+  const known = new Set(['host', 'offline', 'tickHz', 'inputHz', 'durability', 'budget', 'predict', 'view']);
+  for (const key of Object.keys(r)) if (!known.has(key)) problems.push(`"room.${key}" is not a setting (host, offline, tickHz, inputHz, durability, budget, predict, view)`);
   let host: 'server' | 'browser' = 'server';
   if (r.host !== undefined) { if (r.host === 'server' || r.host === 'browser') host = r.host; else problems.push('"room.host" is "server" or "browser"; using "server"'); }
   let offline = true;
   if (r.offline !== undefined) { if (typeof r.offline === 'boolean') offline = r.offline; else problems.push('"room.offline" is true or false; using true'); }
   const tickHz = whole('tickHz', r.tickHz, 1, 60, 20);
   const inputHz = whole('inputHz', r.inputHz, 1, tickHz, tickHz);
+  if (host === 'browser' && r.view?.radiusM != null) problems.push('"room.view.radiusM" needs room.host "server"; browser hosting sends the whole room');
+  if (r.view !== undefined) {
+    if (!r.view || typeof r.view !== 'object' || Array.isArray(r.view)) problems.push('"room.view" is an object with an optional radiusM');
+    else for (const key of Object.keys(r.view)) if (key !== 'radiusM') problems.push(`"room.view.${key}" is not a setting; use radiusM`);
+  }
   const p = r.predict && typeof r.predict === 'object' ? r.predict : {};
   return {
     settings: {
       host, offline, tickHz, inputHz,
+      view: { radiusM: r.view?.radiusM === null ? null : num('view.radiusM', r.view?.radiusM, null) },
       durability: { movementSeconds: whole('durability.movementSeconds', r.durability?.movementSeconds, 1, 60, 1) },
       budget: { tick: Math.max(1, Math.floor(num('budget.tick', r.budget?.tick, budgetFor(tickHz)) as number)) },
       predict: { catchM: num('predict.catchM', p.catchM, null), catchUp: num('predict.catchUp', p.catchUp, 1.25) as number, snapM: num('predict.snapM', p.snapM, null), blendMs: num('predict.blendMs', p.blendMs, 100) as number, interpMs: num('predict.interpMs', p.interpMs, null) },
@@ -540,7 +548,7 @@ export function compileRules(def: RulesDef, env: CompileEnv = {}): Compiled {
     if (!a.questions || typeof a.questions !== 'object') throw new Error(`asks.${key}.questions is required; for example { advance: { type: 'noul', instructions: 'Should the party advance?' } }`);
     asks[key] = { ...a, stateFields: fieldList(a.state, `asks.${key}.state`) };
   }
-  const seats = Math.max(1, Math.min(SEATS_MAX, Math.floor(Number(env.seats)) || 8));
+  const seats = Math.max(1, Math.min(Number.MAX_SAFE_INTEGER, Math.floor(Number(env.seats)) || 8));
   return {
     contract: RULES_CONTRACT, save: SAVE_REVISION, dims, kinds, kindOf, events, commands, effects, effectNames: Object.keys(effects),
     shared: fieldList(d.shared, 'shared'), view, rounds, bots: Math.min(keep, seats), start: room.start ?? null, join: room.join ?? null, roomOn, asks,

package/rules/view.ts

@@ -1,3 +1,4 @@
+import { snapshotDecoder } from './interest.mjs';
 import { rulesOutput } from '../netplay/rules-output.mjs';
 import { rulesCaps, rulesRates } from '../worker/limits.mjs';
 /*
@@ -162,11 +163,12 @@ export function openRoom<R = unknown>(opts: OpenRoomOptions = {}): Room<R> {
 
   /* ---------------------------------------------------------------- frames in */
 
+  const delivery = snapshotDecoder();
   function frameOf(s: Snapshot<unknown> | null): Frame | null {
     if (!s || typeof s !== 'object') return null;
     if (frames.has(s)) return frames.get(s) ?? null;
     let f: Frame | null = null;
-    const d = s.d as [unknown, unknown] | null;
+    const d = delivery.decode(s)?.d as [unknown, unknown] | null;
     if (Array.isArray(d) && Array.isArray(d[0]) && Array.isArray(d[1])) {
       const ents = new Map<string, Unpacked>();
       for (const w of d[1] as unknown[]) { const e = unpackEntity(schema.kinds, w, dims); if (e) ents.set(e.id, e); }

package/worker/room.mjs

@@ -1,3 +1,4 @@
+import { interestSnapshot, snapshotEncoder } from '../rules/interest.mjs';
 /*
  * room.mjs — the netplay v1 relay semantics, with no transport in it.
  * =============================================================================
@@ -460,7 +461,7 @@ export class NetRoom {
   hostSnap(c, m, now, text = null) {
     // The server's stamp is this relay's own clock; a browser's is its estimate of it, and is checked.
     const snap = { k: Number(m.k) || 0, st: c ? this.stamp(m.st) : Number(m.st) || now, d: m.d ?? null };
-    if (Array.isArray(m.c)) snap.c = m.c.slice(0, 64);
+    if (Array.isArray(m.c)) snap.c = m.c.slice(0, this.server ? this.seatCap : 64);
     // Revision 10: a rules game's snapshot names the room's epoch.
     if ((!c || this.rules && c.rules) && Number.isFinite(m.e)) snap.e = m.e;
     this.lastSnap = snap;
@@ -477,10 +478,19 @@ export class NetRoom {
       if (this.lite(o)) continue; // an agent with no game client draws nothing
       // A congested socket skips a snapshot rather than queueing a stale one.
       if (o.conn.buffered && o.conn.buffered() > 256 * 1024) { this.stats.drops += 1; continue; }
-      this.sendText(o.conn, out);
+      this.sendText(o.conn, this.server?.viewRadiusM != null ? JSON.stringify({ t: 'snap', from: null, ...this.playerSnapshot(o, snap) }) : out);
     }
   }
 
+  /** The same per-player delivery role will run in Gates. Keyframes belong to sockets, not saved seats. */
+  playerSnapshot(client, snap, welcome = false) {
+    if (!snap || this.server?.viewRadiusM == null) return snap;
+    const selected = interestSnapshot(snap, client.seat, this.server.viewRadiusM);
+    client.snapEncoder ??= snapshotEncoder(this.tickHz);
+    if (welcome) client.snapEncoder.reset();
+    return client.snapEncoder.encode(selected);
+  }
+
   /** One key of the slow state channel from the host. `bytes`: the frame's size, counted against the room's cap for a browser host. */
   hostState(c, m, bytes) {
     const key = typeof m.k === 'string' ? m.k.slice(0, 64) : '';
@@ -530,7 +540,7 @@ export class NetRoom {
   hostRoster(c, m) {
     if (!Array.isArray(m.slots)) return;
     // A host cannot hide an AI: a seat an agent holds is named and marked so, a slot with no seat is a bot.
-    this.lastRoster = this.labelRoster(m.slots.slice(0, 64));
+    this.lastRoster = this.labelRoster(m.slots.slice(0, this.server ? this.seatCap : 64));
     this.persistDirty = true;
     for (const o of (c && this.rules && c.rules ? this.live() : this.others(c))) this.send(o, { t: 'roster', slots: this.lastRoster });
     this.tellWatchers();
@@ -1102,7 +1112,7 @@ export class NetRoom {
       t: 'welcome', v: NET_VERSION, rev: NET_REVISION, id: c.id, room: this.code, seat: c.seat, token: c.token, name: c.name, colour: c.colour,
       ...(this.gameVer ? { ver: this.gameVer } : {}), ...(behind ? { stale: { ver: this.currentVer } } : {}), stall: this.stallMs,
       role, why, host: this.hostRef(), peers: this.peers(), ...(this.rules ? { held: this.heldPeers() } : {}), st: now, max: this.maxPlayers,
-      round: this.lastRound, roster: this.lastRoster, snap: lite ? null : this.lastSnap, state: lite ? {} : this.stateObject(),
+      round: this.lastRound, roster: this.lastRoster, snap: lite ? null : this.playerSnapshot(c, this.lastSnap, true), state: lite ? {} : this.stateObject(),
       ...(role === 'host' ? { ckpt: this.lastCkpt } : {}),
       ...(full ? { full: true } : {}),
       ...(this.liveAnnouncement() ? { announce: this.liveAnnouncement() } : {}),
@@ -1803,7 +1813,7 @@ export class NetRoom {
 
   /** A round's results, labelled the same way (`agent: true` on every AI's row). */
   labelResults(rows) {
-    return rows.slice(0, 64).map((raw) => this.labelOne(raw, true)).filter(Boolean);
+    return rows.slice(0, this.server ? this.seatCap : 64).map((raw) => this.labelOne(raw, true)).filter(Boolean);
   }
 
   labelOne(raw, result) {

package/worker/version.mjs

@@ -1,2 +1,2 @@
 /** The @homie-rocks/studio version this Worker code is (package.json's; a test keeps them equal). Cache-busts /_homie/site.js. */
-export const STUDIO_VERSION_TAG = '0.43.0';
+export const STUDIO_VERSION_TAG = '0.44.0';