lecodes-sdk 2.0.2 → 2.0.4

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

package/src/ui/UIScreen.ts

@@ -37,6 +37,23 @@ export interface UIScreen extends UIContainerBase<UIScreenStyle, DrawableStyle &
    */
   keepAlive(enabled?: boolean): this
 
+  /**
+   * The screen's ADDRESS on the web: while the screen is the one shown, the browser's address
+   * bar shows it, and a link copied from there opens the app with it (`app.launchUrl`). A route,
+   * not a page's address: `"/product/42"`, `"/search?q=shoes"` — the app never sees where the
+   * page is served from. Call it again to change the address of a screen that is shown (a
+   * filter, a search): the entry of the browser's history is replaced, not added to. `null`
+   * takes the address away; a screen with none keeps the address of the one under it.
+   *
+   * The way in is the app's: read `app.launchUrl` at start and listen to the `"url"` event, as
+   * for a deep link on a phone. No-op on hosts without an address bar.
+   *
+   * ```ts
+   * const ProductScreen = (id: string) => UIScreen(...).url(`/product/${id}`)
+   * ```
+   */
+  url(route: string | null): this
+
   /** Touch began on the screen; `ev.track(...)` takes over the rest of the gesture. */
   onTouchStart(callback: (ev: TouchStartEvent<UIScreen>) => void): this,
   /** @internal The destination tuple (Presentable). */
@@ -80,6 +97,12 @@ export class ScreenElement extends ContainerElement<"screen"> {
     return this
   }
 
+  url(route: string | null): this {
+    // an optional method of the bridge: a host without an address bar has none
+    if (this._h.id !== 0) tree().setDestUrl?.(TREE_DEST_SCREEN, this._h.id, route)
+    return this
+  }
+
   readonly touchStartListeners: any[] = []
   onTouchStart (callback: any): this {
     this.touchStartListeners.push(callback)

package/src/version.ts

@@ -4,7 +4,7 @@
 // same manifest). Its MAJOR is the bundle ↔ runtime contract: a bundle's `// sdk:` header line
 // and a host's embedded version must agree on the major for the host to run the bundle; minor
 // and patch never gate anything (features are detected, never versioned).
-export const SDK_VERSION = "2.0.2"
+export const SDK_VERSION = "2.0.4"
 
 /** The major of a semver string, or null when it is not one. */
 export const sdkMajor = (version: string | null | undefined): number | null => {

package/tests/helpers/fakeTree.ts

@@ -192,6 +192,8 @@ export class FakeTree {
   }
   routerHide = (transition: number): void => { this.rec("routerHide", transition); this.closeCurrent() }
   routerRestore = (transition: number): void => { this.rec("routerRestore", transition); const top = this.stack[this.stack.length - 1]; if (top) this.present(top, transition) }
+  /** A host with an address bar has it (Web Lite); a test of a host without one deletes it. */
+  setDestUrl?: (kind: number, id: number, url: string | null) => void = (kind, id, url) => { this.rec("setDestUrl", kind, id, url) }
   isViewSupported = (name: string): boolean => { this.rec("isViewSupported", name); return this.supportedViews.has(name) }
   supportedViews = new Set<string>()
   /** The contract version of a supported view (1 unless a test says otherwise). */