lecodes-sdk 2.0.3 → 2.0.4

package/package.json

@@ -20,6 +20,7 @@
     "./bridges/*": "./src/bridges/*.d.ts",
     "./ui/tree": "./src/ui/tree.ts",
     "./tween/easing": "./src/animate/tween/easing.ts",
+    "./tween/read": "./src/animate/tween/read.ts",
     "./testing": "./tests/helpers/index.ts",
     "./testing/preload": "./tests/helpers/preload.ts",
     "./version": "./src/version.ts"
@@ -42,7 +43,7 @@
     "typescript": "~5.8.3",
     "gl-matrix": "^3.4.4"
   },
-  "version": "2.0.3",
+  "version": "2.0.4",
   "files": [
     "src",
     "dist",

package/src/animate/tween/read.ts

@@ -0,0 +1,146 @@
+// The READER of the tween blob: `buildBlob`'s layout (./spec.ts) back into tracks and keys. For a
+// host that plays an animation with no creator-tween in it (Web Lite hands the tracks to the
+// browser's animations) — creator-tween reads the same layout in C (blob.h).
+//
+// The reader is the builder's twin and lives beside it: tests/animate/blob.test.ts builds a spec,
+// reads it back and holds the two against each other, so a change of the layout that reaches one
+// side only fails there.
+
+import { EASE_TABLE, EASE_TABLE_SIZE, evalEasing, type EasingSpec } from "./easing"
+
+/** The version of the layout this reader knows (./spec.ts BLOB_VERSION). */
+const VERSION = 1
+// The kinds whose one lane is an index into the string table (./spec.ts KIND_*).
+const KIND_TRANSFORM_MATRIX = 4, KIND_DISCRETE = 8, KIND_STRING = 9
+
+export type BlobKey = {
+  /** 0..1 within the track. */
+  t: number
+  easing: EasingSpec
+  /** Absent = the target's value when the animation first plays. */
+  value?: { lanes: number[] } | { str: string }
+}
+
+export type BlobTrack = {
+  domain: number
+  /** An index into the `targets` handed over next to the blob (a role, in a transition's blob). */
+  target: number
+  prop: string
+  kind: number
+  lanes: number
+  /** The unit of a FLOAT_UNIT, the function list of a TRANSFORM. */
+  sig?: string
+  atMs: number
+  durMs: number
+  commit: boolean
+  keys: BlobKey[]
+}
+
+export type ReadBlob = {
+  clock: number
+  /** One iteration, ms. */
+  durationMs: number
+  delayMs: number
+  /** -1 = forever. */
+  iterations: number
+  pingPong: boolean
+  rate: number
+  /** Time-callbacks, ms; the index is what the host reports. */
+  calls: number[]
+  tracks: BlobTrack[]
+}
+
+/** The blob as tracks, or null for data that is not a blob of this version (or is cut short). */
+export const readBlob = (data: ArrayLike<number>, strings: readonly string[]): ReadBlob | null => {
+  if (data.length < 10 || data[0] !== VERSION) return null
+  const nTracks = data[7]!, nCalls = data[8]!, nTables = data[9]!
+  let at = 10
+  if (at + nCalls + nTables * EASE_TABLE_SIZE > data.length) return null
+  const calls: number[] = []
+  for (let i = 0; i < nCalls; i++) calls.push(data[at++]!)
+  const tables: Float32Array[] = []
+  for (let i = 0; i < nTables; i++) {
+    const table = new Float32Array(EASE_TABLE_SIZE)
+    for (let k = 0; k < EASE_TABLE_SIZE; k++) table[k] = data[at++]!
+    tables.push(table)
+  }
+  const str = (index: number): string | undefined => (index >= 0 ? strings[index] : undefined)
+
+  const tracks: BlobTrack[] = []
+  for (let t = 0; t < nTracks; t++) {
+    if (at + 10 > data.length) return null
+    const kind = data[at + 3]!, lanes = data[at + 4]!, nKeys = data[at + 8]!
+    const track: BlobTrack = {
+      domain: data[at]!, target: data[at + 1]!, prop: str(data[at + 2]!) ?? "", kind, lanes,
+      sig: str(data[at + 9]!), atMs: data[at + 5]!, durMs: data[at + 6]!, commit: data[at + 7]! !== 0, keys: [],
+    }
+    at += 10
+    if (at + nKeys * (7 + lanes) > data.length) return null
+    const stringLane = kind === KIND_TRANSFORM_MATRIX || kind === KIND_DISCRETE || kind === KIND_STRING
+    for (let k = 0; k < nKeys; k++) {
+      const easeKind = data[at + 1]!
+      const p: [number, number, number, number] = [data[at + 2]!, data[at + 3]!, data[at + 4]!, data[at + 5]!]
+      const easing: EasingSpec = easeKind === EASE_TABLE ? { kind: easeKind, p, table: tables[p[0]] } : { kind: easeKind, p }
+      const key: BlobKey = { t: data[at]!, easing }
+      if (data[at + 6]! !== 0) {
+        if (stringLane) key.value = { str: str(data[at + 7]!) ?? "" }
+        else {
+          const values: number[] = []
+          for (let l = 0; l < lanes; l++) values.push(data[at + 7 + l]!)
+          key.value = { lanes: values }
+        }
+      }
+      at += 7 + lanes
+      track.keys.push(key)
+    }
+    tracks.push(track)
+  }
+  if (at !== data.length) return null
+  return { clock: data[1]!, durationMs: data[2]!, delayMs: data[3]!, iterations: data[4]!, pingPong: data[5]! !== 0, rate: data[6]!, calls, tracks }
+}
+
+// ---- a track's value at a time -------------------------------------------------------------------
+
+const KIND_QUAT = 6, KIND_MAT4 = 11
+
+const slerp = (out: number[], o: number, a: number[], b: number[], s: number): void => {
+  let bx = b[o] ?? 0, by = b[o + 1] ?? 0, bz = b[o + 2] ?? 0, bw = b[o + 3] ?? 1
+  const ax = a[o] ?? 0, ay = a[o + 1] ?? 0, az = a[o + 2] ?? 0, aw = a[o + 3] ?? 1
+  let cosom = ax * bx + ay * by + az * bz + aw * bw
+  if (cosom < 0) { cosom = -cosom; bx = -bx; by = -by; bz = -bz; bw = -bw }
+  let k0 = 1 - s, k1 = s
+  if (1 - cosom > 1e-6) {
+    const omega = Math.acos(Math.min(1, cosom)), sinom = Math.sin(omega)
+    k0 = Math.sin((1 - s) * omega) / sinom
+    k1 = Math.sin(s * omega) / sinom
+  }
+  out[o] = k0 * ax + k1 * bx; out[o + 1] = k0 * ay + k1 * by; out[o + 2] = k0 * az + k1 * bz; out[o + 3] = k0 * aw + k1 * bw
+}
+
+/** The two keys around the local time `ms` of a track and how far between them the track is,
+ *  eased: the first key holds before the track, the last one after it. */
+export const segmentAt = (track: BlobTrack, ms: number): { from: BlobKey, to: BlobKey, s: number } | null => {
+  const keys = track.keys
+  if (keys.length === 0) return null
+  const u = track.durMs <= 0 ? (ms >= track.atMs ? 1 : 0) : Math.min(1, Math.max(0, (ms - track.atMs) / track.durMs))
+  const first = keys[0]!, last = keys[keys.length - 1]!
+  if (keys.length === 1 || u <= first.t) return { from: first, to: first, s: 0 }
+  if (u >= last.t) return { from: last, to: last, s: 0 }
+  let i = 0
+  while (i + 1 < keys.length && keys[i + 1]!.t <= u) i++
+  const from = keys[i]!, to = keys[i + 1]!
+  const span = to.t - from.t
+  return { from, to, s: evalEasing(from.easing, span > 0 ? (u - from.t) / span : 1) }
+}
+
+/** The lanes of a numeric track at the local time `ms`, into `out` (a key with no value reads as zeros). */
+export const sampleTrack = (track: BlobTrack, ms: number, out: number[]): void => {
+  const at = segmentAt(track, ms)
+  if (!at) return
+  const lanesOf = (key: BlobKey): number[] => (key.value && "lanes" in key.value ? key.value.lanes : [])
+  const a = lanesOf(at.from), b = lanesOf(at.to), s = at.s
+  const lerp = (from: number, to: number) => { for (let k = from; k < to; k++) out[k] = (a[k] ?? 0) + ((b[k] ?? 0) - (a[k] ?? 0)) * s }
+  if (track.kind === KIND_QUAT) { slerp(out, 0, a, b, s); return }
+  if (track.kind === KIND_MAT4) { lerp(0, 3); slerp(out, 3, a, b, s); lerp(7, 10); return }
+  lerp(0, track.lanes)
+}

package/src/canvas/gen/cssColor.ts

@@ -1,4 +1,4 @@
-// GENERATED by scripts/vendor-canvas.ts from engines/canvas/recorders/ts/src/cssColor.ts @ ae6bc30b952b — do not edit here.
+// GENERATED by scripts/vendor-canvas.ts from engines/canvas/recorders/ts/src/cssColor.ts @ 72e545dab1f5 — do not edit here.
 // Bump the submodule and run `bun run vendor:canvas`; `bun run check:canvas-ops` fails when this copy is stale.
 // The CSS color parser — the TypeScript twin of core/include/anycanvas/css_color.h: the same grammar,
 // the same name table, float32 emulated op for op (Math.fround, in the header's order), so both give

package/src/canvas/gen/recorder.ts

@@ -1,4 +1,4 @@
-// GENERATED by scripts/vendor-canvas.ts from engines/canvas/recorders/ts/src/recorder.ts @ ae6bc30b952b — do not edit here.
+// GENERATED by scripts/vendor-canvas.ts from engines/canvas/recorders/ts/src/recorder.ts @ 72e545dab1f5 — do not edit here.
 // Bump the submodule and run `bun run vendor:canvas`; `bun run check:canvas-ops` fails when this copy is stale.
 // The TypeScript recorder: a Canvas2D-shaped API whose calls WRITE the opcode stream of spec/ops.h.
 // Nothing is drawn here — the stream goes to the core interpreter (native, or wasm on the web), which

package/src/canvas/gen/spec.ts

@@ -1,4 +1,4 @@
-// GENERATED by scripts/vendor-canvas.ts from engines/canvas/spec/gen/spec.ts @ ae6bc30b952b — do not edit here.
+// GENERATED by scripts/vendor-canvas.ts from engines/canvas/spec/gen/spec.ts @ 72e545dab1f5 — do not edit here.
 // Bump the submodule and run `bun run vendor:canvas`; `bun run check:canvas-ops` fails when this copy is stale.
 // GENERATED by spec/generate.ts from spec/*.h — do not edit.
 

package/src/inject.ts

@@ -39,7 +39,7 @@ export { device, type HapticStyle, type MotionOptions } from "./runtime/device"
 export { Input, InputChannel, type InputKeyEvent, type InputGamepadEvent, type InputEventName, type GamepadState, type GamepadAxisName } from "./runtime/input"
 export { WebSocket } from "./runtime/net"
 // Multiplayer (docs/multiplayer-plan.md): roles, players, JSON messages over the _creatorNet transport.
-export { Net, NetPlayer, Replicated, NetEntity, type NetMessage, type NetRole, type NetStatus, type NetEvents, type NetLaunch, type NetInput, type NetKind, type NetTransform } from "./net"
+export { Net, NetPlayer, Replicated, NetEntity, type NetMessage, type NetRole, type NetStatus, type NetEvents, type NetLaunch, type NetInput, type NetKind, type NetTransform, type NetCorrection } from "./net"
 // App-backend transport: the compiler-generated stubs of `*.server.ts` modules call these; user code
 // only ever imports its server functions (docs/backend-plan.md §4).
 export { __rpc, __channel, __serverOnly, RpcError, type ClientChannel } from "./runtime/rpc"

package/src/net/codec.ts

@@ -6,23 +6,31 @@
 // Nothing else: no strings, no nesting, no optionals — snapshot fields are flat and fixed-size by
 // design. Both sides run the same bundle, so the layout is derived, never transmitted; the `sig`
 // feeds the schema hash the handshake compares.
+//
+// A numeric field is INTERPOLATED between two snapshots unless the kind names it `discrete` (an
+// index, a count, an id): a discrete field takes the later snapshot's value whole, as a boolean does.
+// That is a rule of the reader — the wire is the same f32.
 
 export type FieldKind = 0 | 1 | 2   // f32 · bool · f32[]
-export type Field = { key: string; kind: FieldKind; len: number }
+export type Field = { key: string; kind: FieldKind; len: number; step: boolean }
 export type Layout = { fields: Field[]; floats: number; bools: number; bytes: number; sig: string }
 
 const describe = (v: unknown): string => Array.isArray(v) ? `array of ${v.length}` : v === null ? "null" : typeof v
 
-export const makeLayout = (defaults: Record<string, unknown>, what: string): Layout => {
+export const makeLayout = (defaults: Record<string, unknown>, what: string, discrete: readonly string[] = []): Layout => {
   const fields: Field[] = []
   let floats = 0
   let bools = 0
+  for (const key of discrete) {
+    if (!(key in defaults)) throw new Error(`${what}: discrete field '${key}' is not in the defaults`)
+  }
   for (const key of Object.keys(defaults)) {
     const v = defaults[key]
-    if (typeof v === "number") { fields.push({ key, kind: 0, len: 1 }); floats++ }
-    else if (typeof v === "boolean") { fields.push({ key, kind: 1, len: 1 }); bools++ }
+    const step = discrete.includes(key)
+    if (typeof v === "number") { fields.push({ key, kind: 0, len: 1, step }); floats++ }
+    else if (typeof v === "boolean") { fields.push({ key, kind: 1, len: 1, step: true }); bools++ }
     else if (Array.isArray(v) && v.length > 0 && v.length <= 64 && v.every((n) => typeof n === "number")) {
-      fields.push({ key, kind: 2, len: v.length }); floats += v.length
+      fields.push({ key, kind: 2, len: v.length, step }); floats += v.length
     } else {
       throw new Error(`${what}: field '${key}' must be a number, a boolean or a fixed-length number[] (got ${describe(v)})`)
     }
@@ -97,14 +105,15 @@ export const unpackFrom = (view: DataView, offset: number, layout: Layout, into:
   return o
 }
 
-/** `out = a + (b − a) · t` for the numeric fields; booleans take `b`'s. */
+/** `out = a + (b − a) · t` for the numeric fields; booleans and the discrete ones take `b`'s. */
 export const lerpState = (layout: Layout, a: any, b: any, t: number, out: any): void => {
   for (const f of layout.fields) {
-    if (f.kind === 0) out[f.key] = a[f.key] + (b[f.key] - a[f.key]) * t
-    else if (f.kind === 2) {
+    if (f.kind === 2) {
       const pa = a[f.key] as number[], pb = b[f.key] as number[], po = out[f.key] as number[]
-      for (let i = 0; i < f.len; i++) po[i] = pa[i] + (pb[i] - pa[i]) * t
-    } else out[f.key] = b[f.key]
+      const k = f.step ? 1 : t
+      for (let i = 0; i < f.len; i++) po[i] = pa[i] + (pb[i] - pa[i]) * k
+    } else if (f.step) out[f.key] = b[f.key]
+    else out[f.key] = a[f.key] + (b[f.key] - a[f.key]) * t
   }
 }
 

package/src/net/core.ts

@@ -48,7 +48,7 @@ export type NetStats = { rtt: number; loss: number; sentKbps: number; receivedKb
 
 export const CH_RELIABLE = 0
 export const CH_UNRELIABLE = 1
-export const PROTO = 2
+export const PROTO = 3
 export const LOCAL_SLOT = -1
 
 // Record kinds from creator-net (creator-net.h CNET_RECORD_*).
@@ -67,6 +67,9 @@ export class NetPlayer {
   /** A local bag for game facts (score, team, ready). NOT replicated — anything a client must see
    *  goes through a message or replicated state. */
   data: any = {}
+  /** Server: what this player's `Net.connect(…, { hello })` carried (the game's own: a build, a
+   *  token) — the value `Net.listen({ accept })` was asked about. Undefined everywhere else. */
+  hello: unknown = undefined
   /** @internal transport slot on the server; LOCAL_SLOT for the in-process player */
   _slot: number
   /** @internal server side: this player's input ring (replication.ts) */
@@ -129,6 +132,10 @@ export const state = {
   connectResolve: null as null | (() => void),
   connectReject: null as null | ((e: Error) => void),
   myName: "Player",
+  /** client: the game's own part of the `$hello` (`Net.connect(…, { hello })`), opaque to the SDK */
+  hello: undefined as unknown,
+  /** server: the game's say in the handshake (`Net.listen({ accept })`) — a reason refuses */
+  accept: null as null | ((hello: unknown, who: { name: string }) => string | null | void),
 }
 
 // Replication's seams into the roster / pump (set by replication.ts when a session starts — from a
@@ -255,6 +262,8 @@ export const resetToOffline = (): void => {
   state.nextId = 1
   state.connectResolve = null
   state.connectReject = null
+  state.hello = undefined
+  state.accept = null
 }
 
 // ---- server side ------------------------------------------------------------------------------------
@@ -283,13 +292,17 @@ const onServerRecord = (kind: number, slot: number, arg: number, payload: unknow
   const [name, data] = parsed
   if (name === "$hello") {
     if (playerBySlot(slot)) return
-    const reason = !data || data.proto !== PROTO ? "version" : hooks.helloCheck?.(data) ?? null
+    const name = String(data?.name ?? `Player ${state.nextId}`)
+    // the SDK's own checks first, then the game's say (it never sees a client of another protocol)
+    const reason = !data || data.proto !== PROTO ? "version"
+      : hooks.helloCheck?.(data) ?? state.accept?.(data.hello, { name }) ?? null
     if (reason) {
-      sendRaw(slot, CH_RELIABLE, JSON.stringify(["$reject", { reason }]))
+      sendRaw(slot, CH_RELIABLE, JSON.stringify(["$reject", { reason: String(reason) }]))
       b.kick(slot)
       return
     }
-    const p = addPlayer(state.nextId++, String(data.name ?? `Player ${state.nextId - 1}`), slot)
+    const p = addPlayer(state.nextId++, name, slot)
+    p.hello = data.hello
     sendRaw(slot, CH_RELIABLE, JSON.stringify(["$welcome", {
       id: p.id,
       players: state.players.filter((q) => q !== p).map((q) => ({ id: q.id, name: q.name })),
@@ -310,7 +323,7 @@ const onServerRecord = (kind: number, slot: number, arg: number, payload: unknow
 const onClientRecord = (kind: number, slot: number, arg: number, payload: unknown): void => {
   const b = bridge()!
   if (kind === REC_CONNECTED) {
-    sendRaw(0, CH_RELIABLE, JSON.stringify(["$hello", { proto: PROTO, name: state.myName, ...(hooks.helloExtra?.() ?? {}) }]))
+    sendRaw(0, CH_RELIABLE, JSON.stringify(["$hello", { proto: PROTO, name: state.myName, hello: state.hello, ...(hooks.helloExtra?.() ?? {}) }]))
     return
   }
   if (kind === REC_CONNECT_FAILED || kind === REC_DISCONNECTED) {

package/src/net/index.ts

@@ -10,12 +10,12 @@ import {
   type Listener, type NetEvents, type NetLaunch, type NetMessage, type NetRole, type NetStatus,
 } from "./core"
 import {
-  NetEntity, Replicated, allEntities, currentTick, declareInput, declareKind, entityById, installReplication, setInput, stats,
-  type NetInput, type NetKind, type NetTransform,
+  NetEntity, Replicated, allEntities, currentTick, declareInput, declareKind, entityById, installReplication, setInput, stats, viewTick,
+  type NetCorrection, type NetInput, type NetKind, type NetTransform,
 } from "./replication"
 
 export { NetPlayer, NetEntity, Replicated }
-export type { NetEvents, NetLaunch, NetMessage, NetRole, NetStatus, NetInput, NetKind, NetTransform }
+export type { NetEvents, NetLaunch, NetMessage, NetRole, NetStatus, NetInput, NetKind, NetTransform, NetCorrection }
 
 class NetImpl {
   get role(): NetRole { return state.role }
@@ -34,12 +34,21 @@ class NetImpl {
   /** The simulation tick — one per fixed step (`updateFixed`). The server's is THE tick; a client
    *  runs a few ticks ahead so its inputs arrive in time. */
   get tick(): number { return currentTick() }
+  /** The server tick this machine is SHOWING the others at: on a client, its estimate of the server's
+   *  clock less the interpolation delay (fractional); `tick` everywhere else, where nothing is
+   *  interpolated. What a client names when it tells the server "as I saw it". */
+  get viewTick(): number { return viewTick() }
   /** Live counters: snapshots, input lead / `ahead`, corrections, missed inputs, bytes out. */
   get stats(): typeof stats { return stats }
 
   /** Start serving on `port`. From offline this makes us the host (a player who is also the
-   *  server); on the dedicated exe (`Net.launch.role === "server"`) there is no local player. */
-  listen(opts: { port?: number; maxClients?: number; name?: string; dedicated?: boolean } = {}): boolean {
+   *  server); on the dedicated exe (`Net.launch.role === "server"`) there is no local player.
+   *  `accept` is the game's say in the handshake: it is given what the client's `connect` passed as
+   *  `hello` and returns a reason to refuse (the client's `reject` event carries it), nothing to accept. */
+  listen(opts: {
+    port?: number; maxClients?: number; name?: string; dedicated?: boolean
+    accept?: (hello: unknown, who: { name: string }) => string | null | void
+  } = {}): boolean {
     const b = bridge()
     if (!b) { emit("error", "multiplayer is not supported on this host"); return false }
     if (state.role !== "offline") this.disconnect()
@@ -56,6 +65,7 @@ class NetImpl {
     state.isServer = true
     state.isClient = !dedicated
     state.status = "online"
+    state.accept = opts.accept ?? null
     if (!dedicated) ensureMe()
     installReplication()
     startPhases()
@@ -63,12 +73,15 @@ class NetImpl {
     return true
   }
 
-  /** Connect to a host/server (`address` = "ip:port"). Resolves once the server welcomed us. */
-  connect(target: { address: string }, opts: { name?: string } = {}): Promise<void> {
+  /** Connect to a host/server (`address` = "ip:port"). Resolves once the server welcomed us.
+   *  `hello` = anything JSON the game wants the server to see before it lets us in (its
+   *  `Net.listen({ accept })`, then `player.hello`); the SDK only carries it. */
+  connect(target: { address: string }, opts: { name?: string; hello?: unknown } = {}): Promise<void> {
     const b = bridge()
     if (!b) return Promise.reject(new Error("multiplayer is not supported on this host"))
     if (state.role !== "offline") this.disconnect()
     if (opts.name) state.myName = opts.name
+    state.hello = opts.hello
     return new Promise<void>((resolve, reject) => {
       if (!b.connect(target.address)) { reject(new Error(`bad address '${target.address}'`)); return }
       state.role = "client"
@@ -163,8 +176,16 @@ class NetImpl {
 
   /** A replicated entity type: the defaults are the snapshot layout (same field rules as `input`),
    *  `transform` tells the SDK which fields mirror the node's pose, `client` births the proxy on a
-   *  client when the server spawns one (`new Node().aspect(Replicated, { kind, owner })`). */
-  kind<S extends object>(name: string, defaults: S, opts: { transform?: NetTransform; client?: (rep: NetEntity<S>, scene: any) => any } = {}): NetKind<S> {
+   *  client when the server spawns one (`new Node().aspect(Replicated, { kind, owner })`) — it may
+   *  be set later, `Kind.client = …`, where the client's code lives. `discrete` names the numeric
+   *  fields that are never interpolated (an index, a count); `correction` tunes how the owner's
+   *  prediction is brought back to the server's state (all in the game's own units). */
+  kind<S extends object>(name: string, defaults: S, opts: {
+    transform?: NetTransform
+    client?: (rep: NetEntity<S>, scene: any) => any
+    discrete?: readonly (keyof S & string)[]
+    correction?: Partial<NetCorrection>
+  } = {}): NetKind<S> {
     return declareKind(name, defaults, opts as any)
   }
 

package/src/net/replication.ts

@@ -16,9 +16,10 @@
 // offset `rep.correction` absorbs the jump and decays.
 //
 // Wire (channel 1, unreliable, binary; a leading type byte):
-//   1 inputs    C→S  u8 1 · u32 firstTick · u8 count · count × input record        (last 3 ticks)
+//   1 inputs    C→S  u8 1 · u32 firstTick · u8 count · count × input record        (the ticks since the
+//                    last send + 2 older ones, 3 at least; sent when the tick moved)
 //   2 snapshot  S→C  u8 2 · u32 tick · u32 lastInputTick · u8 missed · u16 count ·
-//                    count × { u16 netId · u8 kind · state record }                (every 3rd tick)
+//                    count × { u32 netId · u8 kind · state record }                (every 3rd tick)
 // Channel 0 (reliable JSON): `$spawn {netId, kind, owner, state}` · `$despawn {netId}`.
 
 import { Aspect } from "../core/Aspect"
@@ -31,6 +32,19 @@ import { CH_UNRELIABLE, CH_RELIABLE, LOCAL_SLOT, NetPlayer, bridge, broadcastRaw
 
 export type NetTransform = "pos" | "pos+rot" | "none"
 
+/** How an owner's prediction is brought back to the server's state. The SDK knows nothing of what
+ *  the entity is, so the defaults are neutral: every disagreement counts, none is a teleport. */
+export type NetCorrection = {
+  /** A vertical disagreement below this is ignored (world units). 0 = none ignored. A body that
+   *  snaps to a floor differs by a little between two machines, and lifting it by that feeds itself. */
+  deadbandY: number
+  /** A disagreement of this much or more is a teleport: the body jumps and `correction` stays zero
+   *  (world units). Infinity = always smoothed. */
+  snap: number
+  /** The decay time constant of the visual offset `correction` (seconds). 0 = no smoothing. */
+  tau: number
+}
+
 /** The per-tick input layout: `const PlayerInput = Net.input({ moveX: 0, moveY: 0, jump: false })`. */
 export type NetInput<T extends object = any> = { readonly layout: Layout; readonly defaults: T; readonly __t?: T }
 
@@ -44,8 +58,10 @@ export type NetKind<S extends object = any> = {
   /** Which state fields the SDK samples on the server and applies to a client proxy: `pos` (a
    *  `pos: [x,y,z]` field), `pos+rot` (+ a `rot: [x,y,z,w]` quaternion field), or `none`. */
   readonly transform: NetTransform
-  /** Births the client-side proxy on spawn; the SDK attaches `Replicated` to what it returns. */
-  readonly client?: (rep: NetEntity<S>, scene: Scene | null) => Node | void
+  readonly correction: NetCorrection
+  /** Births the client-side proxy on spawn; the SDK attaches `Replicated` to what it returns.
+   *  Assignable: a declaration both ends share may leave it to the client's own module. */
+  client?: (rep: NetEntity<S>, scene: Scene | null) => Node | void
   readonly __t?: S
   /** @internal scratch state for snapshot decoding */
   readonly _scratch: S
@@ -56,10 +72,10 @@ const SNAPSHOT_EVERY = 3        // 20 Hz
 const INTERP_DELAY = 6          // ticks behind the estimated server tick (100 ms)
 const LEAD_MIN = 2, LEAD_MAX = 8
 const SNAPSHOT_BUDGET = 1000    // bytes — one unreliable datagram (creator-net caps messages at 1024)
-const CORRECTION_TAU = 0.1      // seconds — the visual offset's decay time constant
-const SNAP_DISTANCE = 2         // metres — a bigger disagreement is a teleport: no smoothing
+const CORRECTION_TAU = 0.1      // seconds — the visual offset's decay time constant, unless the kind says
 const NO_INPUT = 0xffffffff
-const VERTICAL_DEADBAND = 0.12  // metres — owner height disagreements below this are floor-snap noise
+const INPUT_MAX = 8             // input records in one packet (the ring keeps as many ticks)
+const REC_HEAD = 5              // u32 netId · u8 kind
 
 // ---- registries ---------------------------------------------------------------------------------------
 
@@ -72,6 +88,8 @@ let nextNetId = 1
 
 let tick = 0
 let localInput: any = null                // what Net.setInput set this tick (every role but `server`)
+let localSet = false                      // Net.setInput was called at all this session
+let sentTick = -1                         // client: the tick of the newest input sent
 const inputRing = new Map<number, any>()  // client: tick → values, resent with the next 2 sends
 let estimate = -1                         // client: the server's tick, fractional, advanced per frame
 let leadCooldown = 0
@@ -147,6 +165,12 @@ export class NetEntity<S extends object = any> {
     const p = this.owner
     return (p?._in?.cur ?? inp.defaults) as T
   }
+  /** `input()` is an input the owner gave — false until the first one exists (the server before
+   *  the owner's first packet, the owner before its first `Net.setInput`), when it is the defaults. */
+  get hasInput(): boolean {
+    if (!state.isServer || this.isMine) return localSet
+    return !!this.owner?._in?.cur
+  }
 
   /** Client: `state` was refreshed (a snapshot landed / the interpolation moved). */
   on(event: "state", cb: (s: S) => void): this { if (!this._listeners.includes(cb)) this._listeners.push(cb); return this }
@@ -157,10 +181,13 @@ export class NetEntity<S extends object = any> {
 
 // ---- declarations (Net.kind / Net.input) --------------------------------------------------------------
 
-export const declareKind = <S extends object>(name: string, defaults: S, opts: { transform?: NetTransform; client?: NetKind<S>["client"] } = {}): NetKind<S> => {
+export const declareKind = <S extends object>(name: string, defaults: S, opts: {
+  transform?: NetTransform; client?: NetKind<S>["client"]; discrete?: readonly string[]; correction?: Partial<NetCorrection>
+} = {}): NetKind<S> => {
   if (kinds.has(name)) throw new Error(`Net.kind('${name}') is already declared`)
   if (kindList.length >= 255) throw new Error("Net.kind: at most 255 kinds")
-  const layout = makeLayout(defaults as Record<string, unknown>, `Net.kind('${name}')`)
+  const layout = makeLayout(defaults as Record<string, unknown>, `Net.kind('${name}')`, opts.discrete)
+  const correction: NetCorrection = { deadbandY: 0, snap: Infinity, tau: CORRECTION_TAU, ...opts.correction }
   const transform = opts.transform ?? "none"
   const need = transform === "pos" ? ["pos"] : transform === "pos+rot" ? ["pos", "rot"] : []
   for (const key of need) {
@@ -168,7 +195,7 @@ export const declareKind = <S extends object>(name: string, defaults: S, opts: {
     const len = key === "pos" ? 3 : 4
     if (!f || f.kind !== 2 || f.len !== len) throw new Error(`Net.kind('${name}'): transform '${transform}' needs a '${key}' field of ${len} numbers`)
   }
-  const kind: NetKind<S> = { name, id: kindList.length, layout, defaults: cloneDefaults(defaults), transform, client: opts.client, _scratch: cloneDefaults(defaults) }
+  const kind: NetKind<S> = { name, id: kindList.length, layout, defaults: cloneDefaults(defaults), transform, correction, client: opts.client, _scratch: cloneDefaults(defaults) }
   kinds.set(name, kind)
   kindList.push(kind)
   return kind
@@ -187,6 +214,7 @@ export const setInput = <T extends object>(inp: NetInput<T>, values: Partial<T>)
   const v = cloneDefaults(inp.defaults)
   assignState(inp.layout, v, values)
   localInput = v
+  localSet = true
   if (state.role === "client") {
     inputRing.set(tick, v)
     for (const t of inputRing.keys()) if (t < tick - 8) inputRing.delete(t)
@@ -194,6 +222,7 @@ export const setInput = <T extends object>(inp: NetInput<T>, values: Partial<T>)
 }
 
 export const currentTick = (): number => tick
+export const viewTick = (): number => (state.role === "client" && estimate >= 0 ? estimate - INTERP_DELAY : tick)
 export const allEntities = (): NetEntity[] => [...entities.values()]
 export const entityById = (netId: number): NetEntity | undefined => entities.get(netId)
 
@@ -314,6 +343,7 @@ export class Replicated extends Aspect<"replicated", Node> {
   get correction(): Vec3 { return this._rec?.correction ?? ZERO }
   /** The owner's input for the tick being simulated (see `NetEntity.input`). */
   input<T extends object>(inp: NetInput<T>): T { return this._rec ? this._rec.input(inp) : (localInput ?? inp.defaults) }
+  get hasInput(): boolean { return this._rec ? this._rec.hasInput : localSet }
   // state-change listeners live on the entity: `node.replicated.entity.on('state', cb)` (the aspect's
   // own on/off are its aspect events)
 }
@@ -358,7 +388,7 @@ const buildSnapshot = (forTick: number): void => {
   const list = [...entities.values()]
   if (list.length === 0) { pendingSnapshot = null; return }
   let size = 0
-  for (const e of list) size += 3 + e.kind.layout.bytes
+  for (const e of list) size += REC_HEAD + e.kind.layout.bytes
   const buf = new ArrayBuffer(Math.min(size, SNAPSHOT_BUDGET))
   const view = new DataView(buf)
   let o = 0
@@ -370,10 +400,10 @@ const buildSnapshot = (forTick: number): void => {
   }
   for (let i = 0; i < n; i++) {
     const e = list[(snapshotStart + i) % n]
-    const rec = 3 + e.kind.layout.bytes
+    const rec = REC_HEAD + e.kind.layout.bytes
     if (o + rec > buf.byteLength) break
     samplePose(e)
-    view.setUint16(o, e.netId, true); o += 2
+    view.setUint32(o, e.netId, true); o += 4
     view.setUint8(o, e.kind.id); o += 1
     o = packInto(view, o, e.kind.layout, e.state)
     written++
@@ -439,10 +469,10 @@ const onClientBinary = (channel: number, data: ArrayBuffer): void => {
 
   let o = 12
   for (let i = 0; i < count; i++) {
-    if (o + 3 > data.byteLength) break
-    const netId = view.getUint16(o, true)
-    const kind = clientKinds[view.getUint8(o + 2)]
-    o += 3
+    if (o + REC_HEAD > data.byteLength) break
+    const netId = view.getUint32(o, true)
+    const kind = clientKinds[view.getUint8(o + 4)]
+    o += REC_HEAD
     if (!kind) {
       if (!warnedKind) { warnedKind = true; console.warn("Net: snapshot with an unknown kind id — dropped") }
       return
@@ -478,11 +508,9 @@ const reconcileOwner = (e: NetEntity, T: number): void => {
   if (!pred) return
   const s = e.state as any
   const dx = s.pos[0] - pred[0], dz = s.pos[2] - pred[2]
-  // Vertical deadband: a grounded character's height differs by a few cm between two machines
-  // (landing phase, floor snap) and lifting the body by that much only makes it fall again — an
-  // oscillation the correction itself feeds. Only a real height difference (a ledge, a jump) counts.
+  // the kind's vertical deadband (NetCorrection.deadbandY): what it calls noise is not corrected
   let dy = s.pos[1] - pred[1]
-  if (Math.abs(dy) < VERTICAL_DEADBAND) dy = 0
+  if (Math.abs(dy) < e.kind.correction.deadbandY) dy = 0
   const d = Math.hypot(dx, dy, dz)
   if (d < 0.005) return
   stats.corrections++
@@ -491,7 +519,7 @@ const reconcileOwner = (e: NetEntity, T: number): void => {
   for (const q of e._pred.values()) { q[0] += dx; q[1] += dy; q[2] += dz }
   const sh = e._shift ?? (e._shift = [0, 0, 0])
   sh[0] += dx; sh[1] += dy; sh[2] += dz
-  if (d >= SNAP_DISTANCE) e.correction.set(0, 0, 0)
+  if (d >= e.kind.correction.snap) e.correction.set(0, 0, 0)
 }
 
 const applyOwnerShift = (e: NetEntity): void => {
@@ -502,7 +530,7 @@ const applyOwnerShift = (e: NetEntity): void => {
   e.node.position = [p.x + sh[0], p.y + sh[1], p.z + sh[2]]
   const rec = e._pred.get(tick - 1)
   if (rec) { rec[0] += sh[0]; rec[1] += sh[1]; rec[2] += sh[2] }
-  if (Math.hypot(sh[0], sh[1], sh[2]) < SNAP_DISTANCE) { e.correction.x -= sh[0]; e.correction.y -= sh[1]; e.correction.z -= sh[2] }
+  if (Math.hypot(sh[0], sh[1], sh[2]) < e.kind.correction.snap) { e.correction.x -= sh[0]; e.correction.y -= sh[1]; e.correction.z -= sh[2] }
 }
 
 const clientFrame = (): void => {
@@ -510,11 +538,12 @@ const clientFrame = (): void => {
   if (estimate >= 0) estimate += dt * 60
   stats.lead = estimate >= 0 ? tick - estimate : 0
   const rt = estimate - INTERP_DELAY
-  const k = Math.exp(-dt / CORRECTION_TAU)
   for (const e of entities.values()) {
     if (e.isMine) {
       const c = e.correction
       if (c.x !== 0 || c.y !== 0 || c.z !== 0) {
+        const tau = e.kind.correction.tau
+        const k = tau > 0 ? Math.exp(-dt / tau) : 0
         c.x *= k; c.y *= k; c.z *= k
         if (Math.hypot(c.x, c.y, c.z) < 1e-3) c.set(0, 0, 0)
       }
@@ -538,13 +567,17 @@ const clientFrame = (): void => {
 }
 
 const sendInputs = (): void => {
-  if (!inputDef || inputRing.size === 0) return
-  const first = tick - 2
-  const buf = new ArrayBuffer(6 + 3 * inputDef.layout.bytes)
+  // nothing new since the last send: a frame without a fixed step
+  if (!inputDef || inputRing.size === 0 || tick === sentTick) return
+  // every tick since the last send (a long frame steps more than once) + 2 older ones against loss
+  const count = Math.min(INPUT_MAX, Math.max(3, tick - sentTick + 2))
+  sentTick = tick
+  const first = tick - count + 1
+  const buf = new ArrayBuffer(6 + count * inputDef.layout.bytes)
   const view = new DataView(buf)
   view.setUint8(0, 1)
   view.setUint32(1, first, true)
-  view.setUint8(5, 3)
+  view.setUint8(5, count)
   let o = 6
   let last: any = localInput ?? inputDef.defaults
   for (let t = first; t <= tick; t++) {
@@ -615,6 +648,8 @@ export const installReplication = (): void => {
       estimate = -1
     }
     inputRing.clear()
+    localSet = false
+    sentTick = -1
     pendingSnapshot = null
     leadCooldown = 0
     for (const p of state.players) p._in = null