@homie-rocks/studio 0.45.2 → 0.46.0

package/CHANGELOG.md

@@ -17,6 +17,93 @@ 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.0] - 2026-10-10
+
+**Plugin 0.46.0**
+
+Keep a world and its account characters across restarts.
+
+### Added
+
+- Opt-in lasting single-area worlds: `room.lifetime: "persistent"` retains a room
+  across empty periods, restarts and compatible builds. State fields declared
+  `{ durable: true }` are written the moment they change, as one small journal
+  record committed before that tick is published, exactly once across a crash.
+  The rest of the room is checkpointed every `room.durability.movementSeconds`
+  (30 by default for a lasting world) and on pause or an orderly stop; a restore
+  is the last checkpoint plus the journal, so value is never lost or repeated
+  though positions may rewind a moment. A room where nothing changes writes
+  nothing. Storage failures stop play and retain committed state.
+- Optional `room.characters: true` keeps one character per game on the existing
+  signed-in player account. Rules read `player.character` on join and write its
+  inventory through declared entity fields. A durable lease and return outbox
+  prevent two rooms holding the character at once. Explicit `world.finish()`
+  resets retain the latest account character instead of replaying its old inventory.
+  No manual provisioning.
+
+### Changed
+
+- Only opted-in worlds use a stable public room instead of allocating fresh match
+  copies. Full worlds wait for seats; named room links select other worlds.
+- Lasting worlds default to `offline: false` so practice cannot look like a
+  durable session. An explicit `offline: true` still allows unsaved local practice.
+- Only character games require studio account sign-in before playing and return
+  the character on disconnect/recall instead of leaving it as a bot.
+- `room.durability.movementSeconds` defaults to 30 when `lifetime` is
+  `"persistent"`; it is still 1 for every other room. In a lasting world an
+  undeclared field, a position or an undeclared non-player entity can come back
+  up to that many seconds old after a crash: declare what must not.
+- Only lasting worlds retain incompatible saves instead of
+  resetting and stop on write failure. Their save envelopes do
+  not use the match path's 16 MB cap. Existing simulation and Cloudflare constraints
+  still apply. Ordinary rules games and browser-hosted games keep their APIs,
+  save costs and lifecycle.
+
+### Fixed
+
+- Refund-event SQL triggers no longer try to parse plain-text settings as JSON,
+  which could prevent account room tickets being signed. The automatic
+  `0020_function_meta.sql` migration preserves refund IDs and delivery behavior.
+
+### Upgrade notes
+
+- First milestone-3 slice. Compatible deployments still restart the Worker and
+  reload old views; uninterrupted rule swaps, migrations, durable command retries,
+  atomic trades and restore points remain later slices. Commands should be
+  idempotent; a command lost before commitment has not happened. Queued events are
+  not atomic transfers when a recipient leaves. Existing cloud saves, shop orders
+  and grants, and app records retain their existing behavior.
+- Version 0.46.0 is provisional. No deploy or merge is part of this PR.
+
+## [0.45.3] - 2026-10-10
+
+**Plugin 0.45.3**
+
+Run richer server-authoritative combat, admission and bots with shared collision queries.
+
+### Added
+
+- Opt-in ray options, ordered `rayAll` hits, named hit regions, projectile profiles, immutable query scenes and scratch movement queries.
+- `f.pulse()` carries a nonzero byte action once over the reliable input-event channel. Use it for weapon selection; ordinary sampled fields must not carry one-frame actions.
+- Entity field visibility: `owner`, `server` and `results`. Per-recipient projections also apply to welcome, watching and reconnect snapshots. Private-delivery deltas refer to a keyframe so packet loss cannot leave moving actors at stale poses.
+- Authenticated room round records, with a durable retry outbox and idempotent player-history append. Browser saves cannot overwrite server records.
+- Budgeted routes over baked walking graphs, ordered same-tick dispatch, player labels, ranked takeover and result-free retries. Named `navigation` graphs validate once at compilation, avoiding repeated graph-validation charges in bot handlers while retaining live obstacle checks and full searches.
+
+### Fixed
+
+- **Ray compatibility:** the earlier PR revision changed all rays to hit inside solids and charged more. Three-argument calls now retain their existing results and cost. Supplying the new options explicitly opts into inside-solid hits and the new query cost.
+- **Collider delivery:** the earlier PR revision copied every primitive field. Collider rows now carry only explicitly declared public `collider.fields`, and geometry revisions are sent only when changed relative to the snapshot baseline.
+- **Build compatibility:** `label`, `dispatch`, `rayAll`, `rays` and `restart` remain legal ordinary property and destructuring names. Guarding capability calls does not reserve these data names.
+- **Terrain compatibility:** the earlier PR revision changed terrain casting globally. Existing casts retain the 0.45.0 implementation; `body.terrain: 'exact'` and ray option `terrain: 'exact'` opt into the new algorithm and cost. Seeded compatibility tests pin old results and costs.
+- Client-requested actor rewind is bounded by server-measured round-trip latency plus presentation and scheduling margins, within the declared history limit. A client cannot simply choose any point in the history window.
+- Optional `sweep(body, delta, {ground:false})` skips redundant support work when the mover explicitly computes grounding. Default sweep behavior is unchanged. Exact terrain casts reject irrelevant support features early, reuse face-entry calculations and cache identical immutable queries within a handler. Ten thousand seeded exact casts pin zero result drift through the face optimization. Near-first tile traversal cuts charged work by 30% across 2,000 seeded dense-terrain casts; its maximum contact-component drift is 2.6e-14. These opt-in savings do not enlarge handler budgets.
+
+### Upgrade notes
+
+- New ray and terrain policies are opt-in. Query filters and locally predicted feedback do not grant damage authority.
+- `server:` save keys are reserved for declared room records; player-owned saves use other keys. Records retain at most 100 completed rounds.
+- This capability work does not itself constitute a Stormbreak gameplay parity claim.
+
 ## [0.45.2] - 2026-10-10
 
 **Plugin 0.45.2** · [#76](https://github.com/homie-rocks/homie/pull/76)

package/guides/game/RULES.md

@@ -137,6 +137,58 @@ for an app. A wall/TV watches without taking a seat. Each interactive phone
 takes one of the room's declared seats; shared state is replicated, public and transient. An app's
 lasting, authorized business data belongs in `createAppRecords`, not in room fields.
 
+## Lasting worlds and account characters
+
+For a world that should still exist tomorrow, set game.json:
+
+```json
+{"room":{"host":"server","lifetime":"persistent","characters":true}}
+```
+
+Lasting worlds default to `offline: false`: wait for the durable server. A studio
+may explicitly set `offline: true` for separate local practice, whose progress
+is not saved to the world or account. Never count that as proof of persistence.
+
+`characters` is optional: `lifetime` alone keeps the world. Account characters
+require the existing studio sign-in/passkey. Play redirects to the account page
+when needed. In `room.join(ctx, player)`, return
+`player.character ?? { kind: 'runner', at: spawn }`. Keep inventory in that player
+kind's declared fields and change it only in rules. Mark inventory/currency and
+collectible-ID sets with `{durable: true, visibility: 'owner'}`; use `durable: true`
+for world changes and public progress too, omitting visibility only when public.
+Durability and recipient visibility are separate declarations. The runtime returns its kind,
+position, heading, fields and motion to the account when it leaves. Use
+`player: true` or `leave: 'despawn'`; a returned character cannot also become a bot.
+Do not reset inventory in `arrive`, round-start handlers or `world.finish`.
+
+The public world has a stable room name; `?room=<name>` chooses another world.
+Every durable change commits before publishing its results. An empty world sleeps and
+retains state. A failed write stops play with the last good save intact. Another
+room waits for the current holder to return the character; no timeout grants a
+stale copy. No database or IDs are set up by hand. Ordinary games keep their
+existing save frequency and behavior.
+
+Write idempotent pickups using a saved collectible ID/set; duplicate commands
+must not mint again. Events arrive later and can become `undeliverable` when a
+recipient leaves; do not treat sending one as an atomic inventory transfer.
+Trading and shop-grant consumption need the later economy slice. Browser saves
+remain player-owned and are not an authoritative inventory.
+
+Durable fields, entity lifecycle, pending events and character leases use an
+atomic incremental journal. The rest is checkpointed every 30 seconds by default
+(`room.durability.movementSeconds`, 1–60), and on pause/shutdown. Unchanged rooms
+write nothing. A crash can rewind movement, but committed value and consumed
+inputs replay together exactly once. Declare every fact needed to prevent a
+repeat reward durable, including pickup IDs and cooldowns that protect value.
+Compatible deploys still restart/reload and then restore the world.
+A state-schema change is refused on restore with data retained; keep the previous
+compatible build until migrations ship. Offline play has no account authority.
+
+For proof, build normally, then sign two players in and test movement, pickup,
+restart mid-pickup, a compatible rebuild, and a fresh profile signing in as the
+same player. Verify actual inventory and world state. A lasting world need not
+finish a round: its browser proof replaces the match check's round requirement.
+
 ## State and field types
 
 `f` declares state, event/command/effect payloads, ask state and guide views.
@@ -683,10 +735,10 @@ for a minute with delay. Movement should respond before the authoritative respon
 score and other shared outcomes still arrive with the network. The studio chooses `players.max`; neither frame rate nor feel is guaranteed by a passing build.
 
 Room state is saved automatically (default movementSeconds: 1, plus round end,
-pause and finish). After 60 seconds with no person the room ends even if screens or
+pause and finish; a lasting world instead journals its durable fields at once and
+checkpoints the rest every 30 seconds). After 60 seconds with no person the room ends even if screens or
 AI remain. Use browser createSaves for player-owned character progress; it is not
-server-verified money. All replicated fields are public, including disguised roles.
-Use a separate authorized records service for private or lasting app records.
+server-verified money. Entity fields default to public. Declare visibility explicitly for private information (below); shared state and motion remain public. Use declared server round records for verified match history.
 
 
 ## Spatial delivery (0.45.0; milestone 2 slice 2)
@@ -772,3 +824,224 @@ known geometry beyond received ticks: a client cannot predict an unseen remote
 build/destruction. Once that update arrives, replay uses its geometry immediately.
 Moving platforms use world.place in their handlers; sweep/support see each tick's
 position. Passenger carrying is explicit movement logic, not automatic physics.
+
+## Filtered combat and camera queries
+
+`world.ray(from, direction, metres, options?)` returns the nearest hit or undefined.
+`world.rayAll` returns all entry hits in distance order (one per shape or named
+part, not exit faces). Static geometry wins equal-distance ties; entity and part
+insertion order break remaining ties. Both queries charge their scans, geometry,
+filtering and output to the normal handler budget. The maximum ray distance is 10,000 metres; radius queries keep their 64 m bound; no query raises the game's budget.
+
+```ts
+runner: {
+  // Movement remains a capsule; these boxes apply only to ray queries.
+  body: {shape: 'capsule', radius: .42, height: 1.8, maxSpeed: 22},
+  query: {layer: 'fighters', tags: ['damageable'], parts: {
+    body: {shape: 'box', radius: .42, height: 1.5},
+    head: {shape: 'box', radius: .24, height: .4, offset: {x: 0, y: 0, z: 1.5}},
+  }},
+  fields: {hp: f.fix({init: 100})},
+  // ...player, inputs, movement and handlers...
+}
+```
+
+Parts are axis-aligned, feet-relative shapes, at most 16 per kind. `hit.part`
+is their declared name. A kind without parts uses its normal body or enabled
+collider. Parts do not resize movement bodies. Optional `query.profiles` holds up to eight named part sets; `profile` in ray options selects one, falling back to the default parts when that kind has no matching profile. For example, projectile travel may use a full-height box while bullets use separate body/head boxes. Geometry-only rays always use collision shapes. Query layers and tags are static
+kind declarations. A live collider's `enabled` and `size` fields still control
+its presence and dimensions.
+
+Options are plain data, never callbacks:
+
+- `kind`, `tag`, `layer`: exact entity-kind, declared-tag and layer matches.
+  Undeclared layers default to `geometry` for live colliders and `body` otherwise.
+  Static map shapes use `geometry` and are not subject to kind/tag/field filters.
+- `where: {hp: {gt: 0}}`: filter declared entity fields. Values may be exact
+  numbers, strings or booleans; numeric tests are `gt`, `gte`, `lt`, `lte`, plus
+  `eq`. All tests must match. Missing fields do not match. At most 16 fields.
+- `ignore: [ref]`: at most 16 opaque entity refs. Entity-handler and movement rays ignore their own entity
+  by default; `ignoreSelf: false` includes it. This also applies when a moving
+  non-player entity is itself a live collider. Local view rays use the own player
+  as caller; room-handler rays have no implicit caller. Rocket travel can ignore its owner explicitly; blast damage
+  may include the owner.
+- `geometryOnly: true`: map plus enabled live colliders, using their collision
+  shape rather than hit parts. Fighters do not shield other fighters. Use an
+  exclusion when testing the visibility of the cover being damaged. Evaluate
+  every visibility ray before sending damage events to preserve pre-blast cover.
+- `entitiesOnly: true`: omit the static map. Combine with the filters above.
+- `radius` and `shape`: cast a sphere (default) or axis-aligned box with this
+  half-size around the ray centre, useful for camera clearance. Radius defaults
+  to zero and is at most 100 metres. A point ray beginning inside a solid reports
+  an immediate hit; movement sweeps continue to allow escape from overlap.
+
+`room.ray` and `room.rayAll` use the same implementation for local aiming and
+cosmetic feedback. They use the drawn entity poses and latest known live geometry;
+only server results award damage. Spatially absent non-collider entities cannot
+be targeted by the view. Unknown remote edits are not predicted.
+
+Movement's `ctx.world.ray/rayAll` (also on `ctx.map`) query its tick's frozen static
+and live collision geometry with these same options. Collider kind, layer, tags
+and scalar fields accompany collision revisions, including outside visual
+interest, so a predicted geometry filter has the same data as authority.
+Movement cannot query fighters or award damage. These APIs do not implement lag
+compensation: they query the current authoritative or presented world.
+
+### Consent before driving an inherited bot
+
+A player's declaration may set `control: 'accepted'`, naming a declared bit in
+`motion`. When false, authority calls `think` even for a present person, and the
+view draws the authoritative body without predicting that person's movement.
+Commands remain available: validate an explicit consent command and set the bit
+true. Initialize it on arrival and reset it in `on.takeover` when appropriate.
+The server still owns driver/seat identity; this flag only controls input.
+
+Set `takeover: 'fitness'` to name a numeric field used when selecting a fill bot.
+The highest value wins (equal values use the highest seat). Update it in rules
+from health, position or whatever makes a body suitable. Reserved companions
+never yield. The selected entity keeps its ID, inventory and all state; only its
+seat and driver change. A displaced bot retains its own state at the donor's old
+seat. Without this declaration, existing seat-based selection is unchanged.
+
+Movement queries reject distant live colliders by swept bounds before detailed
+intersection, just as static map queries do. Bounds include capsule radius and
+height, vertical columns and the full sweep, preserving fast travel and support.
+
+### Ordered same-tick interactions
+
+`world.dispatch(id, event, payload)` delivers a declared event immediately and
+returns whether a live receiver had a handler. The receiver changes only its own
+state; after it returns, later queries see those changes. Use it for ordered
+pellets, where destroying a wall or killing a fighter changes the next ray.
+Ordinary `send` retains next-tick delivery. For a blast, collect every visibility
+decision before dispatching damage so one broken wall still shields that blast.
+
+Dispatch consumes the caller's remaining handler budget, including receiver work,
+and permits at most eight nested deliveries. It does not grant writes to another
+entity or shared state. It is not a transaction: mutations before an error remain
+subject to ordinary field coercion. Missing targets return false; there is no
+queued undeliverable event for immediate delivery. Movement cannot dispatch.
+
+Solid-terrain capsule distance queries reject triangle faces whose bounds cannot
+beat the closest feature already found. This preserves exact sampled geometry,
+including both source triangles and the solid sides and underside.
+
+### Bounded actor-pose rewind
+
+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.
+A placement or new round prevents rewinding through a teleport or reset.
+
+Rewind changes actor poses only. Eligibility filters use current fields, so a
+corpse or a fighter killed by an earlier pellet cannot absorb later pellets.
+Static terrain and live cover stay current: new cover blocks an old shot, and
+destroyed cover no longer blocks. This conservative cover policy is explicit;
+it is not a historical replay of world destruction. Rewind does not move actors,
+change movement prediction, roll back damage or rewind projectiles. Choose the
+window in game rules and validate actions normally; the client's tick is a claim.
+
+Vertical capsule sweeps against solid terrain use an exact swept sphere against
+the prism extended by the capsule centreline. Face, edge and vertex contacts
+replace iterative grazing convergence; geometry and handler budgets stay intact.
+
+For many related visibility or navigation queries in one handler, use
+`const scene = world.rays(options)`, then `scene.ray(from, direction, metres)`
+or `scene.rayAll(...)`. It captures actor poses, live geometry and filter fields
+once; later damage or placement does not change that scene. Each ray is still
+budgeted. Keep it local to the handler. Use ordinary `world.ray` when subsequent
+hits must see mutations, such as sequential pellets. Predicted movement exposes
+`ctx.world.rays` for its current geometry, too.
+
+`world.label(playerRef)` reads the relay's current display name (including bot
+names), at most 40 characters, or an empty string for a missing/non-player ref.
+Copy it into a declared field when a historical message must survive departures
+or seat exchanges. Names are presentation text, never proof of player identity;
+use the existing owner/ref for identity. The host restores labels with its save.
+
+For a body's planned route, capture `world.rays({geometryOnly:true,
+shape:'capsule', radius:.4, height:1.8})`. A capsule ray starts at its centre;
+`scene.sweep(scratchBody, delta)` and `scene.support(scratchBody, distance)` use
+its foot position instead, like shared movement. A scratch body has plain `pos`
+and `grounded` fields. These bounded queries change only that local copy, never
+a player or the captured scene. Use the same movement helper to evaluate a
+jump or dive without granting an action to the real body. Height is at least
+twice the radius, at most 200 metres; spherical casts retain their diameter.
+
+`world.round.restart()` is room-only. It abandons the current attempt and starts the
+next round on the next tick, keeping seats and entities and running the normal
+`roundStart` handlers. It publishes no completed results or `roundOver` event and
+skips the intermission. Use it for an authorized retry; validate eligibility in
+your room handler. Pending restart intent survives save/restore.
+
+
+### Discrete actions with a value
+
+Use `select: f.pulse()` for a weapon slot or other byte-valued action. Call
+`room.input({select: 2})` on the press and return to zero on release. A nonzero
+value is queued once, including a pulse shorter than a simulation tick; held
+samples do not create repeated actions. Zero is neutral. The reliable event
+channel carries these actions, with at most 16 pending per seat and one consumed
+per tick. Epoch changes discard old-round actions. `f.press()` remains the
+boolean equivalent; `f.u8()` is sampled state and can miss a one-frame pulse.
+
+### Private entity fields and verified round history
+
+Declare an entity field with `{visibility: 'server'}` for bot brains or secrets,
+`{visibility: 'owner'}` for private inventory, or `{visibility: 'results'}` for
+statistics revealed during intermission. Nested contents follow their top-level
+field. Hidden values become neutral on the client; never depend on them in shared
+movement. Server rules still read full state. Watchers receive public fields and
+results only. Entity positions, driver information, shared state and motion are
+public. This is field visibility, not fog-of-war entity hiding.
+
+A collider transmits only geometry plus explicitly named public scalar fields:
+`collider: {size: 'size', enabled: 'solid', fields: ['material']}`. Do not put
+private fields in that list. Unchanged collision rows are inherited from the
+snapshot baseline; keyframes and reconnects remain complete.
+
+For verified history declare
+`room.records: {key: 'server:career-v1', identity: 'matchKey', eligible: 'ready',
+fields: {kills: 'earnedKills', damage: 'earnedDamage'}}`. The identity names a
+shared text field that rules make unique for each round. The optional eligibility
+names a player boolean field; result fields name numeric player fields. The
+Worker associates the participant with its authenticated player ID and stores
+`id`, `endedAt`, `place`, `won` and the declared totals when the round completes.
+A durable outbox retries failed writes; duplicate round IDs are ignored. Read
+with `createSaves().get(key)`. Browser writes, deletes and save resets cannot
+change `server:` records. Keep guest/authentication setup active before playing.
+
+### Opt-in exact terrain and baked navigation
+
+Legacy three-argument rays keep their historical result and cost. Supplying ray
+options enables the richer query policy, including hits at distance zero when
+starting inside solids. Terrain changes are separate: set `terrain: 'exact'` in
+ray options or the entity body declaration to use exact face/edge/vertex terrain
+casts. Existing terrain behavior is retained when omitted. Test your map's
+slopes, ledges and movement when opting in.
+
+Declare static graphs once with `navigation: {walk: graph}` in `defineRules`, then
+call `world.route('walk', from, to, {radius, height})`. Compilation validates and
+copies the graph once; handlers pay for the live search, not graph validation.
+At most eight named graphs with 8192 nodes total are accepted. Unknown names fail.
+The array form remains available for occasional dynamic graphs.
+
+`world.route(graph, from, to, {radius, height})` searches an immutable authored
+walking graph. Nodes are `[x, y, z, neighbourIndices]`; endpoints are node indices.
+The graph has at most 8192 nodes and 16 neighbours per node. Edges must already
+encode static terrain walkability. The runtime checks live colliders, returns
+all node indices of a route or an empty list, and charges the search to the
+handler budget. It never substitutes a partial route at an expansion cap.
+Replan when the goal changes and when live geometry changes. Bake invalid or
+occupied terrain nodes out of the graph, and choose reachable endpoints.
+`@homie-rocks/nav` is the richer mesh/crowd API for applications that own that
+runtime; rules graphs avoid importing mutable navigation state into handlers.
+
+`room.predict.idleHold: true` holds small visual reconciliation offsets while
+input and body are stationary. Movement resumes smoothing. Large invalid poses
+still snap to authority. Opt in only after measuring stop/reversal and delayed
+collision behavior for the game's mover.
+
+For multi-cast movement or scratch trajectory checks, `ctx.world.sweep(body, delta, {ground:false})` (also captured-scene `sweep`) moves and returns the same collision but leaves `body.grounded` unchanged. Use it only when your mover computes support explicitly. Omitting the option retains the existing support query and grounding behavior. This avoids paying for identical support checks after horizontal and upward probes.

package/guides/game/SKILL.md

@@ -179,11 +179,55 @@ edits, build, act on the diagnostics and test the actual play before declaring i
   Never turn typing off to make room: place the strip instead (`chat/CHAT.md` has every field).
 - Update `game.json` `name` and `blurb`, and the `<title>`.
 
+## Lasting worlds and account characters
+
+For a world that should still exist tomorrow, set game.json:
+
+```json
+{"room":{"host":"server","lifetime":"persistent","characters":true}}
+```
+
+Lasting worlds default to `offline: false`: wait for the durable server. A studio
+may explicitly set `offline: true` for separate local practice, whose progress
+is not saved to the world or account. Never count that as proof of persistence.
+
+`characters` is optional: `lifetime` alone keeps the world. Account characters
+require the existing studio sign-in/passkey. Play redirects to the account page
+when needed. In `room.join(ctx, player)`, return
+`player.character ?? { kind: 'runner', at: spawn }`. Keep inventory in that player
+kind's declared fields and change it only in rules. The runtime returns its kind,
+position, heading, fields and motion to the account when it leaves. Use
+`player: true` or `leave: 'despawn'`; a returned character cannot also become a bot.
+Do not reset inventory in `arrive`, round-start handlers or `world.finish`.
+
+The public world has a stable room name; `?room=<name>` chooses another world.
+Every tick commits before publishing its results. An empty world sleeps and
+retains state. A failed write stops play with the last good save intact. Another
+room waits for the current holder to return the character; no timeout grants a
+stale copy. No database or IDs are set up by hand. Ordinary games keep their
+existing save frequency and behavior.
+
+Write idempotent pickups using a saved collectible ID/set; duplicate commands
+must not mint again. Events arrive later and can become `undeliverable` when a
+recipient leaves; do not treat sending one as an atomic inventory transfer.
+Trading and shop-grant consumption need the later economy slice. Browser saves
+remain player-owned and are not an authoritative inventory.
+
+This first slice saves the whole world every tick, so opted-in games pay for
+more writes. Compatible deploys still restart/reload and then restore the world.
+A state-schema change is refused on restore with data retained; keep the previous
+compatible build until migrations ship. Offline play has no account authority.
+
+For proof, build normally, then sign two players in and test movement, pickup,
+restart mid-pickup, a compatible rebuild, and a fresh profile signing in as the
+same player. Verify actual inventory and world state. A lasting world need not
+finish a round: its browser proof replaces the match check's round requirement.
+
 ## Progress that lasts: cloud saves
 
 When the plan says progress persists across sessions or devices (the codex's "Progress that lasts", or the person
-asks for a character, levels, unlocks, a collection, hardcore), wire in saves. Never keep it in the room: a room
-forgets everything 60 s after its last player leaves.
+asks for a character, levels, unlocks, a collection, hardcore), wire in saves. For player-owned browser progress use the existing saves API below. For a server-authoritative
+world or inventory, use Lasting worlds above. Ordinary match rooms expire after their last player leaves.
 
 - `game.json`: `"saves": true`. A new game of that kind can start from the starter:
   `npx --no-install homie-studio game new <id> --from ember-vale --name "<Name>"` (a hero that lasts, lifetime

package/lib/build.mjs

@@ -602,7 +602,7 @@ async function buildInto(dist, { esbuild, studio, shop, live, games, before, typ
   // studio.json site.order: the catalogue's order is every listing's order.
   const shown = orderGames(all.filter((g) => existsSync(join(dist, 'games', g.id, 'index.html'))), s.order, log);
   // Server-hosted games: what this build made, and for a one-game build what the catalogue before it said of the others.
-  const rulesOf = new Map(ruled.map((r) => [r.id, { host: r.settings.host, offline: r.settings.offline, tickHz: r.settings.tickHz, inputHz: r.settings.inputHz, contract: r.schema.contract, build: r.build, stateHash: r.stateHash, rounds: r.rounds }]));
+  const rulesOf = new Map(ruled.map((r) => [r.id, { ...(r.settings.lifetime ? { lifetime: r.settings.lifetime } : {}), ...(r.settings.characters ? { characters: true } : {}), host: r.settings.host, offline: r.settings.offline, tickHz: r.settings.tickHz, inputHz: r.settings.inputHz, contract: r.schema.contract, build: r.build, stateHash: r.stateHash, rounds: r.rounds, ...(r.schema.records?{records:true}:{}) }]));
   if (only) for (const row of readJson(join(dist, 'games.json'))?.games ?? []) if (row?.room?.contract && row.id !== only && !rulesOf.has(row.id)) rulesOf.set(row.id, row.room);
   // What each game's build is (its landing's own pictures are not part of it): the digest the manifest names.
   const builds = {};

package/lib/rules-check-worker.mjs

@@ -184,7 +184,7 @@ function play(c, companions, allow) {
   const bots = (mode) => { policy = { ...(policy ?? {}), bots: mode }; frames.push({ t: 'policy', policy }); };
 
   const movesToCheck = [];
-  const moved = (...args) => movesToCheck.push(args);
+  const moved = (...args) => { movesToCheck.push(args); if (fault && fault.includes(`${args[0]}.move:`) && !fault.includes('Movement input:')) fault += ` Movement input: ${JSON.stringify(args[2])}; before: ${JSON.stringify(args[3])}.`; };
   let A = open({ observe, noted, moved, send });
   for (const m of told()) A.frame(m);
   /** The room stops and starts again as a deploy restarts it: a new epoch, everybody away until they are back. */
@@ -236,8 +236,9 @@ function play(c, companions, allow) {
   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 steering = new Map();
   let moveTick = 0;
+  let moveSelf;
   let moveGeometry = c.map;
-  const moveCtx = new Map(c.kinds.filter((k) => k.move && k.body).map((k) => [k.name, L.M.moveContext({ tick: () => moveTick, tickHz, tune: c.publicTune, map: c.map, geometry: () => moveGeometry, name: c.map.name, spots: c.map.spots, radius: () => k.body.radius, shape: () => k.body, dims: c.dims })]));
+  const moveCtx = new Map(c.kinds.filter((k) => k.move && k.body).map((k) => [k.name, L.M.moveContext({ tick: () => moveTick, tickHz, tune: c.publicTune, map: c.map, geometry: () => moveGeometry, self: () => moveSelf, name: c.map.name, spots: c.map.spots, radius: () => k.body.radius, shape: () => k.body, dims: c.dims })]));
   /**
    * An owner-moved body's own browser, for one tick: the game's `move` from where the last snapshot has the body, by
    * the step a browser takes (pack.ts `stepMove`), and the claim of where that leaves it. Its units are the play's.
@@ -249,7 +250,7 @@ function play(c, companions, allow) {
     const e = w && L.P.unpackEntity(c.kinds, w, c.dims);
     if (!e) return null;
     G.note = (what, at, written) => noted(k.name, 'move', what, at, written);
-    moveTick = t;
+    moveTick = t; moveSelf = b.id;
     const body = L.P.stepMove(k.move, { pos: e.pos, vel: e.vel, heading: e.heading, grounded: e.grounded, motion: L.P.thawFields(k.motion, e.motion) }, Object.freeze(values), moveCtx.get(k.name), Math.max(1, Math.floor(budget / 4)), k.motion, c.dims,
       (error) => { fault ??= `${G.file}:${G.line} ${k.name}.move: ${fix(diagnostic(String(error?.message ?? error)))} A player's own browser runs this move for its body.${when()}`; });
     G.note = null;
@@ -345,9 +346,9 @@ function play(c, companions, allow) {
     const stats = A.core.stats; const cut = stats.ticksCut; const held = stats.held;
     A.tickNow();
     units += A.core.stats.tickUnits;
-    for (const [name, tick, input, before, after, geometry] of movesToCheck.splice(0)) {
+    for (const [name, tick, input, before, after, geometry, id] of movesToCheck.splice(0)) {
       const kind = c.kinds.find(k => k.name === name);
-      moveTick = tick; moveGeometry = geometry ?? c.map;
+      moveTick = tick; moveGeometry = geometry ?? c.map; moveSelf = id;
       const result = L.P.stepMove(kind.move, before, input, moveCtx.get(name), Math.max(1, Math.floor(budget / 4)), kind.motion, c.dims,
         error => { fault ??= `${siteOf(name, 'move')} ${name}.move: prediction failed: ${error.message}.${when()}`; });
       units += result.used;

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 } = c;
+  const { kinds, events, commands, effects, shared, rounds, bots, roomOn, asks, map: geometry, dims, contract, seats, save, historySeconds } = 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, 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}:{}), tickHz: c.settings.tickHz, save }, (k, v) => typeof v === 'function' ? true : v)).digest('hex').slice(0, 32);
 }
 
 /**

package/lib/rules-guard.mjs

@@ -66,10 +66,11 @@ export const REFUSED_NAMES = ['constructor', 'prototype', '__proto__', 'stack',
 /** The names JavaScript calls by itself to turn an object into a number or a text: no function may sit under one. */
 export const HOOK_NAMES = ['valueOf', 'toString', 'toJSON'];
 /** What the host runtime's own objects offer: `world`, `ctx`, the round, the map (rules/core.ts) and `world.math` (rules/math.ts). */
-export const WORLD_METHODS = ['ticks', 'random', 'send', 'sendRoom', 'announce', 'sendArea', 'after', 'emit', 'spawn', 'despawn', 'place', 'near', 'inBox', 'ray', 'sweep', 'ask', 'goalDone', 'finish', 'end', 'spot', 'spots'];
+export const WORLD_METHODS = ['ticks', 'random', 'route', 'label', 'send', 'dispatch', 'sendRoom', 'announce', 'sendArea', 'after', 'emit', 'spawn', 'despawn', 'place', 'near', 'inBox', 'ray', 'rayAll', 'rays', 'sweep', 'ask', 'goalDone', 'finish', 'end', 'restart', 'spot', 'spots'];
 export const MATH_METHODS = ['sin', 'cos', 'tan', 'atan', 'atan2', 'asin', 'acos', 'exp', 'log', 'pow', 'hypot', 'rad', 'deg', 'clamp', 'lerp', 'vec', 'add', 'sub', 'scale', 'dot', 'cross', 'len', 'dist', 'norm', 'clampLen', 'lerpVec', 'dir', 'angle'];
 const VALUE_METHODS = new Set([...ARRAY_METHODS, ...STRING_METHODS, ...MAPSET_METHODS]);
 export const MOVE_METHODS = ['support', 'overlaps'];
+const NEW_METHODS = new Set(['route','label','dispatch','rayAll','rays','restart']);
 const CALLABLE = new Set([...VALUE_METHODS, ...WORLD_METHODS, ...MOVE_METHODS, ...MATH_METHODS]);
 const refusedName = (k) => REFUSED_NAMES.includes(k) || k.startsWith('toLocale');
 /** Operators that turn each operand into a number or a text. (`+` is handled beside them; `==` and `!=` are refused.) */
@@ -398,7 +399,7 @@ export function guardSource(code, { file = 'rules.js', map = null, linked = fals
       const decl = path.parentPath.isVariableDeclarator() && path.parentPath.parentPath.isVariableDeclaration() && statementsOf(path.parentPath.parentPath);
       for (const p of path.node.properties) {
         if (t.isRestElement(p)) continue;
-        const risky = p.computed || CALLABLE.has(p.key.name ?? p.key.value);
+        const risky = p.computed || (CALLABLE.has(p.key.name ?? p.key.value) && !NEW_METHODS.has(p.key.name ?? p.key.value));
         if (risky && !(decl && t.isIdentifier(p.value))) bad(p, `take "${p.computed ? 'a computed key' : p.key.name ?? p.key.value}" out with a plain \`const { … } = value\` declaration, or read it with a dot: a pattern here could take a method out of a value`);
       }
     },
@@ -457,7 +458,7 @@ export function guardSource(code, { file = 'rules.js', map = null, linked = fals
         const checks = [];
         for (const d of path.node.declarations) {
           if (!t.isObjectPattern(d.id)) continue;
-          for (const p of d.id.properties) if (!t.isRestElement(p) && t.isIdentifier(p.value) && (p.computed || CALLABLE.has(p.key.name ?? p.key.value))) checks.push(t.expressionStatement(call('nf', [t.identifier(p.value.name), line(p)])));
+          for (const p of d.id.properties) if (!t.isRestElement(p) && t.isIdentifier(p.value) && (p.computed || (CALLABLE.has(p.key.name ?? p.key.value) && !NEW_METHODS.has(p.key.name ?? p.key.value)))) checks.push(t.expressionStatement(call('nf', [t.identifier(p.value.name), line(p)])));
         }
         if (checks.length) path.insertAfter(checks);
       },

package/lib/rules-types.mjs

@@ -78,9 +78,9 @@ type W = World<${parameters}>;
 type RW = World<${parameters}, true>;
 type Definition = Omit<RulesDef, 'entities' | 'room' | 'move' | 'asks'> & {
   entities: ${entities}; move?: Moves;
-  room?: { rounds?: { seconds: number; breakSeconds: number }; bots?: { keep: number };
+  room?: { records?: {key:string;identity:string;eligible?:string;fields:Readonly<Record<string,string>>}; rounds?: { seconds: number; breakSeconds: number }; bots?: { keep: number }; historySeconds?: number;
     start?: (world: RW) => void;
-    join?: (ctx: Pick<W, 'map' | 'shared' | 'tune' | 'math' | 'round'>, player: { seat: number; driver: 'person' | 'bot' | 'ai'; owner: string }) => ${joins};
+    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 };
   };
   asks?: ${record(Object.entries(d.asks).map(([n, a]) => [n, `{ state: Fields; questions: ${value(a.questions)}; floor: (state: ReadonlyState<${fields(a.state)}>) => ${picks(a.questions)} }`]))};

package/lib/scaffold.mjs

@@ -1,4 +1,4 @@
-import { FUNCTIONS_MIGRATION, FUNCTIONS_MIGRATION_FILE, FUNCTIONS_CURSOR_MIGRATION, FUNCTIONS_CURSOR_MIGRATION_FILE } from '../worker/functions-schema.mjs';
+import { FUNCTIONS_META_MIGRATION, FUNCTIONS_META_MIGRATION_FILE, FUNCTIONS_MIGRATION, FUNCTIONS_MIGRATION_FILE, FUNCTIONS_CURSOR_MIGRATION, FUNCTIONS_CURSOR_MIGRATION_FILE } from '../worker/functions-schema.mjs';
 import { MCP_MIGRATION, MCP_MIGRATION_FILE } from '../worker/mcp-store.mjs';
 import { APPS_MIGRATION, APPS_MIGRATION_FILE } from '../worker/app-records.mjs';
 import { PURCHASE_MIGRATION, PURCHASE_MIGRATION_FILE, PURCHASE_STATE, PURCHASE_STATE_FILE } from '../worker/purchase-schema.mjs';
@@ -802,6 +802,7 @@ export { default, Table, Lobby, Gate, Concentrator } from '@homie-rocks/studio/w
     [`site/migrations/${MCP_MIGRATION_FILE}`]: MCP_MIGRATION,
     [`site/migrations/${FUNCTIONS_MIGRATION_FILE}`]: FUNCTIONS_MIGRATION,
     [`site/migrations/${FUNCTIONS_CURSOR_MIGRATION_FILE}`]: FUNCTIONS_CURSOR_MIGRATION,
+    [`site/migrations/${FUNCTIONS_META_MIGRATION_FILE}`]: FUNCTIONS_META_MIGRATION,
     [`site/migrations/${LOUNGE_MIGRATION_FILE}`]: LOUNGE_MIGRATION,
     'wrangler.jsonc': wranglerConfig({ worker, name, d1: studio.cloudflare.d1, r2: studio.cloudflare.r2, layout: 'root' }),
     '.claude/skills/.gitkeep': '',
@@ -973,6 +974,11 @@ function ensurePartsStateMigration(root) {
   return `site/migrations/${PURCHASE_STATE_FILE}`;
 }
 
+function ensureFunctionMeta(root) {
+  const file=join(root,'site','migrations',FUNCTIONS_META_MIGRATION_FILE);
+  if(existsSync(file))return null;
+  mkdirSync(dirname(file),{recursive:true});writeFileSync(file,FUNCTIONS_META_MIGRATION);return `site/migrations/${FUNCTIONS_META_MIGRATION_FILE}`;
+}
 function ensureFunctionCursors(root) {
   const file=join(root,'site','migrations',FUNCTIONS_CURSOR_MIGRATION_FILE);
   if(existsSync(file))return null;
@@ -989,12 +995,12 @@ function ensureMcpMigration(root) {
   mkdirSync(dirname(file),{recursive:true});writeFileSync(file,MCP_MIGRATION);return `site/migrations/${MCP_MIGRATION_FILE}`;
 }
 export function ensureMigrations(root) {
-  return [ensureStatsMigration(root), ensurePlayersMigration(root), ensureOfficeMigration(root), ensureServersMigration(root), ensureChatMigration(root), ensureShopMigration(root), ensureLoungeMigration(root), ensureShopReservations(root), ensureShopStatements(root), ensureShopLines(root), ensureAppsMigration(root), ensurePartsMigration(root), ensurePartsStateMigration(root), ensureMcpMigration(root), ensureFunctionsMigration(root), ensureFunctionCursors(root)].filter(Boolean);
+  return [ensureStatsMigration(root), ensurePlayersMigration(root), ensureOfficeMigration(root), ensureServersMigration(root), ensureChatMigration(root), ensureShopMigration(root), ensureLoungeMigration(root), ensureShopReservations(root), ensureShopStatements(root), ensureShopLines(root), ensureAppsMigration(root), ensurePartsMigration(root), ensurePartsStateMigration(root), ensureMcpMigration(root), ensureFunctionsMigration(root), ensureFunctionCursors(root), ensureFunctionMeta(root)].filter(Boolean);
 }
 
 /** What a migration file the template added is for, in a few words (deploy and dev say it). */
 export function migrationWord(file) {
-  return /studio_mcp/.test(file) ? 'AI connections and tool call history' : /studio_apps/.test(file) ? 'apps: lasting records and signed-in role grants' : /lounge/.test(file) ? 'the Lounge and kept chat: play nights, moderators, and what was said only where an owner turns history on' : /shop/.test(file) ? 'the shop: orders, what players own, refunds and referral books (paid sales wait until shop.json and the studio\'s Stripe connection are ready)' : /players/.test(file) ? 'player accounts and cloud saves' : /chat/.test(file) ? 'room chat: the owner\'s chat rules and players\' reports (never the chat itself)' : /servers/.test(file) ? 'servers and agent seats: room pools with their own rules, AI passes' : /office/.test(file) ? 'the back office: launch states, invites, the owner\'s controls' : 'the studio\'s own stats: counts, never tracks';
+  return /function_meta/.test(file) ? 'refund events alongside plain-text studio settings' : /studio_mcp/.test(file) ? 'AI connections and tool call history' : /studio_apps/.test(file) ? 'apps: lasting records and signed-in role grants' : /lounge/.test(file) ? 'the Lounge and kept chat: play nights, moderators, and what was said only where an owner turns history on' : /shop/.test(file) ? 'the shop: orders, what players own, refunds and referral books (paid sales wait until shop.json and the studio\'s Stripe connection are ready)' : /players/.test(file) ? 'player accounts and cloud saves' : /chat/.test(file) ? 'room chat: the owner\'s chat rules and players\' reports (never the chat itself)' : /servers/.test(file) ? 'servers and agent seats: room pools with their own rules, AI passes' : /office/.test(file) ? 'the back office: launch states, invites, the owner\'s controls' : 'the studio\'s own stats: counts, never tracks';
 }
 
 /**