@irtio/schema 4.0.0 → 4.2.0

package/README.md

@@ -0,0 +1,56 @@
+# @irtio/schema
+
+Define shared multiplayer state, typed RPCs, and messages. The same schema supplies TypeScript
+types and binary encoding for your room and its clients.
+
+```bash
+npm install @irtio/schema
+```
+
+## Define state and an RPC
+
+Create `irtio/schema.ts`:
+
+```ts
+import { defineSchema, entity, f32, server, singleton, u32 } from '@irtio/schema';
+
+export const schema = defineSchema(
+  {
+    players: entity({ x: f32, y: f32 }),
+    match: singleton({ round: u32 }),
+  },
+  {
+    roles: ['player'] as const,
+    rpc: {
+      nextRound: server({}),
+    },
+  },
+);
+```
+
+`players` contains records addressed by id. `match` is one server-owned object. `nextRound`
+declares a client-to-server call; implement it with `defineRoom` from `@irtio/server`.
+For a deployed project, use the project id generated by `irtio init` in the schema options.
+
+## Choose a schema primitive
+
+| Export | Use |
+| --- | --- |
+| `entity(fields, options?)` | Records with ids, ownership, and optional visibility rules |
+| `singleton(fields, options?)` | One object, written by the server |
+| `bool`, `u8`, `u16`, `u32`, `i32`, `f32`, `f64` | Boolean and numeric fields |
+| `str(maxBytes)` | A UTF-8 string with a byte limit |
+| `enumOf(...)`, `struct(...)`, `list(...)`, `ref(...)` | Enums, nested values, bounded lists, and references |
+| `server(spec)`, `client(spec)` | RPC declarations in either direction |
+| `State<typeof schema>` | The inferred server state type |
+
+A schema validates shape and bounds. Authorize actions and validate gameplay in room handlers.
+Append new RPCs and messages to their declaration maps to preserve existing wire ids.
+
+For codec and tooling integrations, the package also exports state creation, snapshot and delta
+codecs, change tracking, canonical schema reconstruction, and schema diffing. Use the client SDK
+and room API to manage these during normal gameplay.
+
+See the [schema reference](https://irt.io/docs/reference/schema) for field signatures, collection
+options, defaults, and migration rules, or start with the
+[quickstart](https://irt.io/docs/getting-started).

package/dist/index.d.ts

@@ -123,6 +123,11 @@ declare function normalizeValue(d: TypeDesc, v: unknown, path?: string): unknown
  * physics entity is client-writable, so a client's write history for one of these entities is
  * exactly its intent frames — which is what week 10's client-side re-stepping replays.
  *
+ * That makes `intents` the owner-write list rather than a force list, which surprises people: a
+ * field the owner writes and the step never reads — a cosmetic `yaw`, a held emote — still goes
+ * in `intents`, because that is the only way to make a field of a body-backed collection writable
+ * at all. Listing a non-force there is correct, not a misuse.
+ *
  * Unlike week 8's `interpolate` (a client-side rendering choice, deliberately outside the schema
  * hash), physics options are **server shape**: a room and a client that disagree about which
  * fields the simulation owns disagree about the world. They go in the canonical form and
@@ -143,7 +148,12 @@ type PhysicsBodyMap = {
 interface EntityPhysics {
     /** Fields the simulation owns: translation (`x`/`y`/`z`), rotation quaternion (`q*`), velocities (`v*`/`w*`). */
     readonly body: PhysicsBodyMap;
-    /** Owner-written input fields the step consumes. Declaration order is the canonical order. */
+    /**
+     * The owner-write list: every field the owning client may write. Usually inputs the step
+     * consumes, but not only — a purely cosmetic owned field (a `yaw` nothing simulates, a chosen
+     * colour) belongs here too, because this list *is* how a field on a body-backed collection
+     * becomes writable. Declaration order is the canonical order.
+     */
     readonly intents?: readonly string[];
 }
 /** Compiled form on `CollectionDesc.physics`. */
@@ -282,10 +292,22 @@ declare function ownershipFromCanonical(at: string, raw: unknown): OwnershipOpti
 
 /**
  * `'server'` is the room's own private state: no client role sees it, no client may write it, and
- * it never reaches the wire. It is the first-class spelling of what `visibility: 'role'` with an
- * empty `roles` list has always done by accident, and it takes no `roles`.
+ * its rows are never encoded into a snapshot or a delta. The collection's definition — its name
+ * and field names — is still part of the schema the server and every client share, so the names
+ * are public and only the values are private. It is the first-class spelling of what
+ * `visibility: 'role'` with an empty `roles` list has always done by accident, and it takes no
+ * `roles`.
+ */
+/**
+ * `'owner'` is per-record, not per-role: an entity record is visible to the one client that owns
+ * it — the first-class ownership every entity record already carries, the thing `perPlayer`,
+ * `requestOwnership` and `ctx.owner` all speak about — and to the server. Its adds and removes are
+ * scoped the same way, so a client never learns another client's record exists, and a transfer of
+ * ownership reaches the old owner as a `remove` and the new one as an `add`. A record left
+ * server-owned (`SERVER_OWNER`, the empty string) is owned by no client and is therefore visible
+ * to none. It is entity-only — a singleton has no owner — and takes no `roles` and no `grid`.
  */
-type Visibility = 'all' | 'role' | 'spatial-grid' | 'server';
+type Visibility = 'all' | 'role' | 'spatial-grid' | 'server' | 'owner';
 interface GridOptions<K extends string = string> {
     /** Numeric fields containing the entity's world position. */
     readonly x: K;
@@ -304,7 +326,8 @@ interface EntityOptions {
     readonly serverOwned?: boolean;
     /**
      * `'all'` (default) | `'role'` (per-role views, needs `roles`) | `'spatial-grid'` (per-client
-     * AOI) | `'server'` (room-private: no client sees or writes it).
+     * AOI) | `'server'` (room-private: no client sees or writes it) | `'owner'` (per-record: the
+     * client that owns the record, and the server).
      */
     readonly visibility?: Visibility;
     /** With `visibility: 'role'`: the roles that see this collection. */
@@ -398,8 +421,10 @@ interface EntityOptions {
      * only when declared, so every schema written before this keeps the hash it had.
      *
      * Entity-only, and meaningless on a `serverOwned` collection (where every field already is);
-     * both are refused. On a `physics` collection the intent list already answers the question, so a
-     * field named by both is refused too.
+     * both are refused. Refused on a `physics` collection too, and for the same reason: the owner
+     * writes only the fields in `physics.intents`, so every other field is already server-only.
+     * (`physics.intents` is the owner-write list, not a force list — an owned field the step never
+     * reads, a cosmetic `yaw` say, goes in `intents` too. That is how it becomes writable.)
      *
      * There is deliberately no dynamic form. A per-field *owner id* would have to ride the wire per
      * field per record, and the case that needs one is served by a second collection.
@@ -824,12 +849,30 @@ type State<S> = {
 type RolesOf<O extends EntityOptions> = O extends {
     roles: readonly (infer R)[];
 } ? R : never;
-/** Is collection with options `O` visible to `Role`? */
+/**
+ * Is a collection with options `O` visible to `Role`?
+ *
+ * `server` is never visible. A `role` collection is visible when `Role` **overlaps** its roles,
+ * not when `Role` is wholly contained in them — and that distinction is the whole point.
+ *
+ * The default `Role` on {@link ClientState} is the union of every role the schema declares. Under
+ * containment, `['host' | 'guest'] extends ['host']` is false, so a bare `ClientState<S>` dropped
+ * *every* role-visible collection and reading one needed a cast — even though a hidden collection
+ * is present at runtime (the wire has a slot for every collection; a client without the role just
+ * receives it empty or default-valued). Overlap gives the bare default all of them, which is what
+ * the runtime hands you, while `ClientState<S, 'hunter'>` still excludes anything scoped only to
+ * other roles, which is what a role-narrowed view is for.
+ *
+ * `spatial-grid` and `owner` are `true` for every role, for the same reason: they scope *entities*,
+ * not collections. The collection is present in every client's state — empty, or holding only the
+ * ids that client's AOI or ownership entitles it to — and the filtering happens at runtime, which
+ * no role-indexed type can express.
+ */
 type VisibleTo<O extends EntityOptions, Role extends string> = O extends {
     visibility: 'server';
 } ? false : O extends {
     visibility: 'role';
-} ? [Role] extends [RolesOf<O>] ? true : false : true;
+} ? [Extract<Role, RolesOf<O>>] extends [never] ? false : true : true;
 type VisibleKeys<S, Role extends string> = {
     [K in keyof SchemaDefs<S>]: VisibleTo<DefOptions<SchemaDefs<S>[K]>, Role> extends true ? K : never;
 }[keyof SchemaDefs<S>];

package/dist/index.js

@@ -699,7 +699,7 @@ function compileServerFields(name, kind, fields, o) {
   }
   if (o.physics) {
     throw new Error(
-      `${name}: serverFields says nothing on a physics collection \u2014 the owner of a body-backed record writes its declared intents and nothing else. Take the field out of physics.intents instead`
+      `${name}: serverFields is redundant on a physics collection \u2014 the owner writes only the fields in physics.intents, so every other field is already server-only. Remove serverFields`
     );
   }
   return new Set([...out].sort());
@@ -1165,6 +1165,26 @@ function validateForDeploy(schema) {
         message: `${c.name}: grid is only valid with visibility 'spatial-grid'`
       });
     }
+    if (c.visibility === "owner") {
+      if (c.kind !== "entity") {
+        issues.push({
+          level: "error",
+          message: `${c.name}: owner visibility is entity-only \u2014 a singleton has no owner`
+        });
+      }
+      if (c.roles && c.roles.length > 0) {
+        issues.push({
+          level: "error",
+          message: `${c.name}: visibility 'owner' takes no roles \u2014 it is scoped by record ownership, not by role`
+        });
+      }
+      if (c.serverOwned) {
+        issues.push({
+          level: "warning",
+          message: `${c.name}: visibility 'owner' on a serverOwned collection \u2014 every record stays server-owned, so no client ever sees one`
+        });
+      }
+    }
     if (c.visibility === "server" && c.roles && c.roles.length > 0) {
       issues.push({
         level: "error",
@@ -1326,7 +1346,7 @@ function typeOf(t, at) {
 }
 function entityOptions(e, name) {
   const visibility = stringAt(e, "visibility");
-  if (visibility !== "all" && visibility !== "role" && visibility !== "spatial-grid" && visibility !== "server") {
+  if (visibility !== "all" && visibility !== "role" && visibility !== "spatial-grid" && visibility !== "server" && visibility !== "owner") {
     throw new Error(
       `schemaFromCanonical: ${name}: unknown visibility ${JSON.stringify(visibility)}`
     );

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@irtio/schema",
-  "version": "4.0.0",
+  "version": "4.2.0",
   "description": "irtio schema DSL, type inference, canonical hash, codec, change tracking, and schema diff",
   "license": "MIT",
   "repository": {