@irtio/schema 0.5.2 → 0.6.0

package/dist/index.d.ts

@@ -159,6 +159,46 @@ declare function compilePhysics(at: string, kind: 'entity' | 'singleton', fields
 declare function canonicalPhysics(p: PhysicsDesc): Record<string, unknown>;
 /** Reads a canonical physics fragment back (`schemaFromCanonical`). */
 declare function physicsFromCanonical(at: string, raw: unknown): EntityPhysics;
+/**
+ * One planar body's state, in the vocabulary a 2D engine speaks. This is the only place the
+ * mapping from two dimensions onto the thirteen 3D channels is written down, and it lives in the
+ * schema package precisely because two sides have to agree about it: the room's server-side world
+ * writes through it, and anything reading those channels back (a renderer deriving the angle, a
+ * client-side world) reverses it. A second copy of these six lines somewhere else would be a
+ * silent way for the two to disagree by a sign.
+ *
+ * `angle` rides the quaternion about Z, which is what a rotation in the xy plane *is*:
+ * `qz = sin(a/2)`, `qw = cos(a/2)`, and back out with `2 * atan2(qz, qw)`. Channels a plane has no
+ * use for (`z`, `qx`, `qy`, `vz`, `wx`, `wy`) read as constant zero rather than being omitted, so a
+ * schema written for one engine still decodes under the other.
+ */
+interface Body2dState {
+    readonly x: number;
+    readonly y: number;
+    /** Radians, counter-clockwise. */
+    readonly angle: number;
+    readonly vx: number;
+    readonly vy: number;
+    /** Radians per second about Z. */
+    readonly angularVelocity: number;
+}
+/** The value a planar body puts on one 3D channel. */
+declare function channelOf2d(channel: PhysicsBodyChannel, b: Body2dState): number;
+/** Reads the angle back out of the two quaternion channels a plane uses. */
+declare function angleFrom2d(qz: number, qw: number): number;
+/**
+ * The reverse of {@link channelOf2d}: folds one channel's value into a mutable planar state.
+ * `qz`/`qw` are accumulated and the angle recomputed, so either order of arrival works.
+ */
+declare function applyChannel2d(channel: PhysicsBodyChannel, value: number, target: {
+    x: number;
+    y: number;
+    qz: number;
+    qw: number;
+    vx: number;
+    vy: number;
+    wz: number;
+}): void;
 
 /**
  * `entity`, `singleton`, `server`, `client`, `defineSchema`, and the compiled schema
@@ -774,6 +814,59 @@ declare function applyDelta(schema: AnySchema, state: PlainState, delta: Delta):
 /** Field-level diff between two plain states: what would have to be sent to turn `from` into `to`. */
 declare function computeDirty(schema: AnySchema, from: PlainState, to: PlainState): DirtySet;
 
+/**
+ * The measurement walker: a reader's-eye pass over *encoded* delta and snapshot bytes that
+ * reports where each byte went, keyed by collection and field.
+ *
+ * This is deliberately a second reader of the wire format rather than an instrumented writer.
+ * The encoders and `ValueSink` are untouched, so the hot path stays byte-identical and
+ * cost-identical whether or not anything is profiling; and because the walker reads exactly what
+ * `decodeDeltaFrom`/`decodeSnapshot` read, it works on the server after an encode and on the
+ * client before a decode, from the same code.
+ *
+ * The copy is kept honest by conservation: the spans it reports partition the bytes it consumed,
+ * with nothing counted twice and nothing left over (`walk.test.ts` proves it against
+ * `encodeDelta(...).length` over random schemas). If the format changes here without changing
+ * `codec.ts`, or the other way round, that property test fails.
+ *
+ * Nothing here allocates a decoded value: it skips values by width, so a profiled room pays for
+ * a second pass over the bytes and not for a second decode.
+ */
+
+/**
+ * Where the bytes went. Every callback reports a byte count, and for one walk the counts sum to
+ * the number of bytes the walk consumed.
+ */
+interface WalkEvents {
+    /**
+     * Framing that belongs to no single field: `tick`, `hash8`, the dirty-collection count, and
+     * each collection's index and op count (snapshot: the header and each entity count).
+     */
+    header(bytes: number): void;
+    /**
+     * One op's own framing: the tag byte, the id string, the owner string (add), the dirty mask
+     * and the owner string when the owner bit is set (update). Always called before that op's
+     * fields, so a consumer can route a whole op somewhere else by latching on this call.
+     *
+     * A snapshot's records report as `add` ops whose framing is the id and owner strings; a
+     * snapshot singleton has no op framing at all, only fields.
+     */
+    op(collection: CollectionDesc, kind: 'add' | 'update' | 'remove', id: string, bytes: number): void;
+    /** One field value, nested struct masks and presence bytes included. */
+    field(collection: CollectionDesc, field: FieldDesc, bytes: number): void;
+}
+/**
+ * Walks one delta body, reporting spans through `events`. Accepts raw bytes or a positioned
+ * reader, which it leaves at the first byte after the body exactly as `decodeDeltaFrom` does
+ * (the `CORRECT` frame's tick suffix is the caller's). Returns the number of bytes consumed.
+ */
+declare function walkDelta(schema: AnySchema, bytes: Uint8Array | ByteReader, events: WalkEvents): number;
+/**
+ * Walks one snapshot body, reporting spans through `events`. Entity records report as `add` ops;
+ * a singleton reports only its fields. Returns the number of bytes consumed.
+ */
+declare function walkSnapshot(schema: AnySchema, bytes: Uint8Array | ByteReader, events: WalkEvents): number;
+
 /**
  * `track()` — a proxy tree over a plain state that records every write into a `DirtySet`.
  *
@@ -824,4 +917,4 @@ interface SchemaChange {
 /** Compares two compiled schemas and returns every classified change, sorted by path then code. */
 declare function diffSchemas(oldSchema: AnySchema, newSchema: AnySchema): SchemaChange[];
 
-export { type AddOptions, type AnyDef, type AnyRpc, type AnySchema, type AnyType, type BodyFieldsOf, type BroadcastProxy, ByteReader, ByteWriter, CANONICAL_VERSION, type ClientCallProxy, type ClientImplementations, type ClientRpcs, type ClientState, type Collection, type CollectionDesc, type CollectionDirty, type DecodedSnapshot, type DeepReadonly, type DeepWritable, type DefMap, type Delta, type DeltaCollection, type DeltaOp, type DirtySet, EntityCollection, type EntityDef, type EntityOptions, type EntityPhysics, type FieldDesc, type FieldMask, type Fields, type FromCanonicalOptions, type GridDesc, type GridOptions, type Header, ID_MAX_BYTES, type Implementations, type Infer, type InferFields, type InitFields, type InitOf, type InstanceOf, type Kind, type OwnableKeys, type Owned, PHYSICS_BODY_CHANNELS, type PhysicsBodyChannel, type PhysicsBodyMap, type PhysicsDesc, type PhysicsKeys, type PlainState, RESERVED_COLLECTION_NAMES, RESERVED_RPC_NAMES, type ReadonlyBodyFields, type ReadonlyCollection, type RecordDirty, type RoleOf, type RpcDef, type RpcDesc, type RpcDirection, type RpcMap, type RpcParams, type RpcReturns, type RpcSpec, SERVER_OWNER, SINGLETON_ID, type Schema, type SchemaChange, type SchemaDefs, type SchemaIssue, type SchemaOptions, type SchemaRoles, type SchemaRpc, type ServerCallProxy, type ServerOwnedKeys, type ServerRpcs, type SingletonDef, type SnapshotOptions, type State, type Tracked, type Type, type TypeDesc, type ValueSink, type Visibility, type VisibleKeys, applyDelta, bool, bytesEqual, canonicalPhysics, canonicalType, client, cloneValue, collectionDirty, compilePhysics, computeDirty, createDirtySet, createFieldMask, createState, decodeDelta, decodeDeltaFrom, decodeFields, decodeSnapshot, defaultRecord, defaultValue, defineSchema, describeType, diffSchemas, encodeDelta, encodeFields, encodeSnapshot, entity, enumOf, estimateSize, f32, f64, filterDirty, frozenProxy, i32, isDirtyEmpty, isWhole, list, markAdd, markField, markOwner, markPath, markRemove, mergeDirty, mergeMask, normalizeRecord, normalizeValue, physicsFromCanonical, readValue, ref, schemaFromCanonical, server, sha256, sha256Hex, singleton, stableStringify, str, struct, toHex, track, u16, u32, u8, validateForDeploy, validateValue, writeValue };
+export { type AddOptions, type AnyDef, type AnyRpc, type AnySchema, type AnyType, type Body2dState, type BodyFieldsOf, type BroadcastProxy, ByteReader, ByteWriter, CANONICAL_VERSION, type ClientCallProxy, type ClientImplementations, type ClientRpcs, type ClientState, type Collection, type CollectionDesc, type CollectionDirty, type DecodedSnapshot, type DeepReadonly, type DeepWritable, type DefMap, type Delta, type DeltaCollection, type DeltaOp, type DirtySet, EntityCollection, type EntityDef, type EntityOptions, type EntityPhysics, type FieldDesc, type FieldMask, type Fields, type FromCanonicalOptions, type GridDesc, type GridOptions, type Header, ID_MAX_BYTES, type Implementations, type Infer, type InferFields, type InitFields, type InitOf, type InstanceOf, type Kind, type OwnableKeys, type Owned, PHYSICS_BODY_CHANNELS, type PhysicsBodyChannel, type PhysicsBodyMap, type PhysicsDesc, type PhysicsKeys, type PlainState, RESERVED_COLLECTION_NAMES, RESERVED_RPC_NAMES, type ReadonlyBodyFields, type ReadonlyCollection, type RecordDirty, type RoleOf, type RpcDef, type RpcDesc, type RpcDirection, type RpcMap, type RpcParams, type RpcReturns, type RpcSpec, SERVER_OWNER, SINGLETON_ID, type Schema, type SchemaChange, type SchemaDefs, type SchemaIssue, type SchemaOptions, type SchemaRoles, type SchemaRpc, type ServerCallProxy, type ServerOwnedKeys, type ServerRpcs, type SingletonDef, type SnapshotOptions, type State, type Tracked, type Type, type TypeDesc, type ValueSink, type Visibility, type VisibleKeys, type WalkEvents, angleFrom2d, applyChannel2d, applyDelta, bool, bytesEqual, canonicalPhysics, canonicalType, channelOf2d, client, cloneValue, collectionDirty, compilePhysics, computeDirty, createDirtySet, createFieldMask, createState, decodeDelta, decodeDeltaFrom, decodeFields, decodeSnapshot, defaultRecord, defaultValue, defineSchema, describeType, diffSchemas, encodeDelta, encodeFields, encodeSnapshot, entity, enumOf, estimateSize, f32, f64, filterDirty, frozenProxy, i32, isDirtyEmpty, isWhole, list, markAdd, markField, markOwner, markPath, markRemove, mergeDirty, mergeMask, normalizeRecord, normalizeValue, physicsFromCanonical, readValue, ref, schemaFromCanonical, server, sha256, sha256Hex, singleton, stableStringify, str, struct, toHex, track, u16, u32, u8, validateForDeploy, validateValue, walkDelta, walkSnapshot, writeValue };

package/dist/index.js

@@ -318,6 +318,56 @@ function physicsFromCanonical(at, raw) {
   }
   return { body, intents };
 }
+function channelOf2d(channel, b) {
+  switch (channel) {
+    case "x":
+      return b.x;
+    case "y":
+      return b.y;
+    case "qz":
+      return Math.sin(b.angle / 2);
+    case "qw":
+      return Math.cos(b.angle / 2);
+    case "vx":
+      return b.vx;
+    case "vy":
+      return b.vy;
+    case "wz":
+      return b.angularVelocity;
+    default:
+      return 0;
+  }
+}
+function angleFrom2d(qz, qw) {
+  return 2 * Math.atan2(qz, qw);
+}
+function applyChannel2d(channel, value, target) {
+  switch (channel) {
+    case "x":
+      target.x = value;
+      return;
+    case "y":
+      target.y = value;
+      return;
+    case "qz":
+      target.qz = value;
+      return;
+    case "qw":
+      target.qw = value;
+      return;
+    case "vx":
+      target.vx = value;
+      return;
+    case "vy":
+      target.vy = value;
+      return;
+    case "wz":
+      target.wz = value;
+      return;
+    default:
+      return;
+  }
+}
 
 // src/sha256.ts
 var K = new Uint32Array([
@@ -1901,6 +1951,147 @@ function computeDirty(schema, from, to) {
   return dirty;
 }
 
+// src/walk.ts
+function skip(r, n) {
+  if (n < 0 || r.remaining < n) throw new Error("unexpected end of buffer");
+  r.pos += n;
+}
+function structNames2(d) {
+  return Object.keys(d.fields);
+}
+function skipValue(r, desc) {
+  if (desc.opt && r.u8() === 0) return;
+  switch (desc.kind) {
+    case "bool":
+    case "u8":
+    case "enum":
+      skip(r, 1);
+      return;
+    case "u16":
+      skip(r, 2);
+      return;
+    case "u32":
+    case "i32":
+    case "f32":
+      skip(r, 4);
+      return;
+    case "f64":
+      skip(r, 8);
+      return;
+    case "str":
+    case "ref":
+      skip(r, r.varint());
+      return;
+    case "list": {
+      const n = r.varint();
+      for (let i = 0; i < n; i++) skipValue(r, desc.item);
+      return;
+    }
+    case "struct": {
+      for (const fd of Object.values(desc.fields)) skipValue(r, fd);
+      return;
+    }
+  }
+}
+function readBit2(mask, i) {
+  return ((mask[i >> 3] ?? 0) & 1 << (i & 7)) !== 0;
+}
+function skipDirtyField(r, desc) {
+  if (desc.kind !== "struct") {
+    skipValue(r, desc);
+    return;
+  }
+  if (desc.opt && r.u8() === 0) return;
+  const names = structNames2(desc);
+  const maskBytes = r.bytes(names.length + 7 >> 3);
+  for (let i = 0; i < names.length; i++) {
+    if (!readBit2(maskBytes, i)) continue;
+    skipDirtyField(r, desc.fields[names[i]]);
+  }
+}
+function readerFor(bytes) {
+  return bytes instanceof ByteReader ? bytes : new ByteReader(bytes);
+}
+function walkDelta(schema, bytes, events) {
+  const r = readerFor(bytes);
+  const from = r.pos;
+  let at = r.pos;
+  skip(r, 12);
+  const count = r.varint();
+  events.header(r.pos - at);
+  for (let ci = 0; ci < count; ci++) {
+    at = r.pos;
+    const index = r.varint();
+    const c = schema.collections[index];
+    if (!c) throw new Error(`delta references unknown collection index ${index}`);
+    const opCount = r.varint();
+    events.header(r.pos - at);
+    for (let oi = 0; oi < opCount; oi++) {
+      at = r.pos;
+      const tag = r.u8();
+      const id = r.str();
+      if (tag === 2) {
+        events.op(c, "remove", id, r.pos - at);
+        continue;
+      }
+      if (tag === 0) {
+        skip(r, r.varint());
+        events.op(c, "add", id, r.pos - at);
+        for (const f of c.fields) {
+          const start = r.pos;
+          skipValue(r, f.type);
+          events.field(c, f, r.pos - start);
+        }
+        continue;
+      }
+      if (tag !== 1) throw new Error(`unknown delta op byte ${tag} in ${c.name}`);
+      const n = c.fields.length;
+      const maskBytes = r.bytes(n + 1 + 7 >> 3).slice();
+      if (readBit2(maskBytes, n)) skip(r, r.varint());
+      events.op(c, "update", id, r.pos - at);
+      for (let i = 0; i < n; i++) {
+        if (!readBit2(maskBytes, i)) continue;
+        const f = c.fields[i];
+        const start = r.pos;
+        skipDirtyField(r, f.type);
+        events.field(c, f, r.pos - start);
+      }
+    }
+  }
+  return r.pos - from;
+}
+function walkSnapshot(schema, bytes, events) {
+  const r = readerFor(bytes);
+  const from = r.pos;
+  skip(r, 12);
+  events.header(12);
+  for (const c of schema.collections) {
+    if (c.kind === "entity") {
+      let at = r.pos;
+      const n = r.varint();
+      events.header(r.pos - at);
+      for (let i = 0; i < n; i++) {
+        at = r.pos;
+        const id = r.str();
+        skip(r, r.varint());
+        events.op(c, "add", id, r.pos - at);
+        for (const f of c.fields) {
+          const start = r.pos;
+          skipValue(r, f.type);
+          events.field(c, f, r.pos - start);
+        }
+      }
+    } else {
+      for (const f of c.fields) {
+        const start = r.pos;
+        skipValue(r, f.type);
+        events.field(c, f, r.pos - start);
+      }
+    }
+  }
+  return r.pos - from;
+}
+
 // src/track.ts
 var fieldTables = /* @__PURE__ */ new WeakMap();
 function structFields(d) {
@@ -2388,6 +2579,14 @@ function diffCollections(oldCollections, newCollections, changes) {
         message: `${oldC.name}: visible roles changed from [${(oldC.roles ?? []).join(", ")}] to [${(newC.roles ?? []).join(", ")}] \u2014 changes who sees this collection`
       });
     }
+    if (oldC.index !== newC.index) {
+      changes.push({
+        kind: "breaking",
+        code: `${oldC.kind}.reordered`,
+        path: oldC.name,
+        message: `${oldC.name}: wire index changed (${oldC.index} -> ${newC.index}) \u2014 collections are addressed positionally, so every delta and snapshot for this collection would be misread (breaking)`
+      });
+    }
     if (stableStringify(oldC.grid) !== stableStringify(newC.grid)) {
       changes.push({
         kind: "breaking",
@@ -2422,9 +2621,25 @@ function diffRpcs(oldRpcs, newRpcs, changes) {
       });
     }
   }
+  if (oldRpcs.length !== newRpcs.length) {
+    changes.push({
+      kind: "breaking",
+      code: "rpc.builtin_reordered",
+      path: "rpc",
+      message: `rpc: the number of RPCs changed from ${oldRpcs.length} to ${newRpcs.length}, which shifts the ids of irtio's built-in RPCs (they are numbered after yours) \u2014 connected clients would call the wrong one (breaking)`
+    });
+  }
   for (const oldR of oldRpcs) {
     const newR = newByName.get(oldR.name);
     if (!newR) continue;
+    if (oldR.index !== newR.index) {
+      changes.push({
+        kind: "breaking",
+        code: "rpc.reordered",
+        path: `rpc.${oldR.name}`,
+        message: `rpc ${oldR.name}: wire id changed (${oldR.index} -> ${newR.index}) \u2014 RPCs are addressed by a positional id, so calls would reach the wrong handler (breaking)`
+      });
+    }
     if (oldR.direction !== newR.direction) {
       changes.push({
         kind: "breaking",
@@ -2682,11 +2897,14 @@ export {
   RESERVED_RPC_NAMES,
   SERVER_OWNER,
   SINGLETON_ID,
+  angleFrom2d,
+  applyChannel2d,
   applyDelta,
   bool,
   bytesEqual,
   canonicalPhysics,
   canonicalType,
+  channelOf2d,
   client,
   cloneValue,
   collectionDirty,
@@ -2745,5 +2963,7 @@ export {
   u8,
   validateForDeploy,
   validateValue,
+  walkDelta,
+  walkSnapshot,
   writeValue
 };

package/package.json

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