lecodes-sdk 0.19.0

package/src/math/vec.ts

@@ -0,0 +1,255 @@
+// Fluent 2D / 3D vectors — the SDK's user-facing vector math (no gl-matrix, no out-params, no imports).
+//
+// Design (see PLAN.md): a vector is a *mutable little struct* — `v.x = 3`, `v.set(x, y, z)` mutate in
+// place — but every *method* is PURE: `a.add(b)` returns a NEW vector and never touches `a`. So chains
+// (`dir.normalize().scale(s)`) can't clobber their source, and the immutable-method style is the most
+// amenable to a future escape-analysis / scalar-replacement compiler pass. Backing is plain number
+// fields (not a Float32Array), which the optimizer can trivially scalar-replace.
+//
+// "Never wrap away the metal": vectors expose `.x/.y/.z`, are iterable (`const [x, y] = v`, `[...v]`),
+// and every method / constructor accepts a raw tuple just as well as a wrapper. Reads off a `*Like`
+// input go through the `cx/cy/cz` helpers below, which work uniformly on a wrapper (`.x`) or an
+// array-like (`[0]`), so callers can always pass `[0, 1, 0]` where a vector is expected.
+
+export type Vec2Like = Vec2 | readonly [number, number] | number[] | Float32Array
+export type Vec3Like = Vec3 | readonly [number, number, number] | number[] | Float32Array
+
+/** Read the x / first component of any vector-like (wrapper, tuple, or typed array). `?? ` is safe on
+ *  0 and NaN — it only falls through on `undefined` (i.e. a non-wrapper that has no `.x`). */
+export const cx = (v: { x?: number } | ArrayLike<number>): number => (v as { x?: number }).x ?? (v as ArrayLike<number>)[0]
+export const cy = (v: { y?: number } | ArrayLike<number>): number => (v as { y?: number }).y ?? (v as ArrayLike<number>)[1]
+export const cz = (v: { z?: number } | ArrayLike<number>): number => (v as { z?: number }).z ?? (v as ArrayLike<number>)[2]
+
+/** Relative-epsilon compare (matches gl-matrix's `equals`), so the oracle tests agree to the bit. */
+const approx = (a: number, b: number, eps: number): boolean => Math.abs(a - b) <= eps * Math.max(1, Math.abs(a), Math.abs(b))
+
+// ---------------------------------------------------------------------------------------------------
+// Vec2
+// ---------------------------------------------------------------------------------------------------
+
+export class Vec2 {
+  x: number
+  y: number
+
+  constructor(x: number | Vec2Like = 0, y = 0) {
+    if (typeof x === "number") { this.x = x; this.y = y }
+    else { this.x = cx(x); this.y = cy(x) }
+  }
+
+  // --- mutation (the only methods that change `this`) ---
+  /** Mutate the components in place. Returns `this`. */
+  set(x: number, y: number): this { this.x = x; this.y = y; return this }
+  /** Copy another vector's components into this one. Returns `this`. */
+  copy(v: Vec2Like): this { this.x = cx(v); this.y = cy(v); return this }
+
+  // --- pure arithmetic (each returns a NEW Vec2) ---
+  add(v: Vec2Like): Vec2 { return new Vec2(this.x + cx(v), this.y + cy(v)) }
+  sub(v: Vec2Like): Vec2 { return new Vec2(this.x - cx(v), this.y - cy(v)) }
+  mul(v: Vec2Like): Vec2 { return new Vec2(this.x * cx(v), this.y * cy(v)) }
+  div(v: Vec2Like): Vec2 { return new Vec2(this.x / cx(v), this.y / cy(v)) }
+  scale(s: number): Vec2 { return new Vec2(this.x * s, this.y * s) }
+  /** `this + v * s` (fused multiply-add). */
+  scaleAndAdd(v: Vec2Like, s: number): Vec2 { return new Vec2(this.x + cx(v) * s, this.y + cy(v) * s) }
+  negate(): Vec2 { return new Vec2(-this.x, -this.y) }
+
+  // --- products / measures ---
+  dot(v: Vec2Like): number { return this.x * cx(v) + this.y * cy(v) }
+  /** 2D cross product → the scalar z of the 3D cross (signed parallelogram area). */
+  cross(v: Vec2Like): number { return this.x * cy(v) - this.y * cx(v) }
+  length(): number { return Math.hypot(this.x, this.y) }
+  lengthSq(): number { return this.x * this.x + this.y * this.y }
+  distanceTo(v: Vec2Like): number { return Math.hypot(this.x - cx(v), this.y - cy(v)) }
+  distanceSqTo(v: Vec2Like): number { const dx = this.x - cx(v), dy = this.y - cy(v); return dx * dx + dy * dy }
+
+  normalize(): Vec2 {
+    const l = Math.hypot(this.x, this.y)
+    return l === 0 ? new Vec2(0, 0) : new Vec2(this.x / l, this.y / l)
+  }
+  lerp(v: Vec2Like, t: number): Vec2 { return new Vec2(this.x + (cx(v) - this.x) * t, this.y + (cy(v) - this.y) * t) }
+  clamp(min: Vec2Like, max: Vec2Like): Vec2 {
+    return new Vec2(clampN(this.x, cx(min), cx(max)), clampN(this.y, cy(min), cy(max)))
+  }
+  min(v: Vec2Like): Vec2 { return new Vec2(Math.min(this.x, cx(v)), Math.min(this.y, cy(v))) }
+  max(v: Vec2Like): Vec2 { return new Vec2(Math.max(this.x, cx(v)), Math.max(this.y, cy(v))) }
+  /** Left-hand perpendicular: (-y, x), a 90° CCW turn. */
+  perp(): Vec2 { return new Vec2(-this.y, this.x) }
+  /** Rotate by `rad` (CCW) around `origin` (default 0). */
+  rotate(rad: number, origin: Vec2Like = ZERO2): Vec2 {
+    const ox = cx(origin), oy = cy(origin)
+    const c = Math.cos(rad), s = Math.sin(rad)
+    const dx = this.x - ox, dy = this.y - oy
+    return new Vec2(ox + dx * c - dy * s, oy + dx * s + dy * c)
+  }
+  /** The vector's heading in radians: `atan2(y, x)`. */
+  heading(): number { return Math.atan2(this.y, this.x) }
+  /** Angle (radians) between this and `v`. */
+  angle(v: Vec2Like): number {
+    const mag = Math.sqrt(this.lengthSq() * (cx(v) * cx(v) + cy(v) * cy(v)))
+    return mag === 0 ? 0 : Math.acos(clampN(this.dot(v) / mag, -1, 1))
+  }
+
+  withX(x: number): Vec2 { return new Vec2(x, this.y) }
+  withY(y: number): Vec2 { return new Vec2(this.x, y) }
+
+  // --- interop ---
+  equals(v: Vec2Like, eps = 1e-6): boolean { return approx(this.x, cx(v), eps) && approx(this.y, cy(v), eps) }
+  clone(): Vec2 { return new Vec2(this.x, this.y) }
+  toArray(): [number, number] { return [ this.x, this.y ] }
+  *[Symbol.iterator](): Iterator<number> { yield this.x; yield this.y }
+
+  static from(v: Vec2Like): Vec2 { return new Vec2(cx(v), cy(v)) }
+  static get zero(): Vec2 { return new Vec2(0, 0) }
+  static get one(): Vec2 { return new Vec2(1, 1) }
+  static get up(): Vec2 { return new Vec2(0, 1) }
+  static get down(): Vec2 { return new Vec2(0, -1) }
+  static get left(): Vec2 { return new Vec2(-1, 0) }
+  static get right(): Vec2 { return new Vec2(1, 0) }
+}
+
+// ---------------------------------------------------------------------------------------------------
+// Vec3
+// ---------------------------------------------------------------------------------------------------
+
+export class Vec3 {
+  x: number
+  y: number
+  z: number
+
+  constructor(x: number | Vec3Like = 0, y = 0, z = 0) {
+    if (typeof x === "number") { this.x = x; this.y = y; this.z = z }
+    else { this.x = cx(x); this.y = cy(x); this.z = cz(x) }
+  }
+
+  // --- mutation ---
+  set(x: number, y: number, z: number): this { this.x = x; this.y = y; this.z = z; return this }
+  copy(v: Vec3Like): this { this.x = cx(v); this.y = cy(v); this.z = cz(v); return this }
+
+  // --- pure arithmetic ---
+  add(v: Vec3Like): Vec3 { return new Vec3(this.x + cx(v), this.y + cy(v), this.z + cz(v)) }
+  sub(v: Vec3Like): Vec3 { return new Vec3(this.x - cx(v), this.y - cy(v), this.z - cz(v)) }
+  mul(v: Vec3Like): Vec3 { return new Vec3(this.x * cx(v), this.y * cy(v), this.z * cz(v)) }
+  div(v: Vec3Like): Vec3 { return new Vec3(this.x / cx(v), this.y / cy(v), this.z / cz(v)) }
+  scale(s: number): Vec3 { return new Vec3(this.x * s, this.y * s, this.z * s) }
+  /** `this + v * s` (fused multiply-add). */
+  scaleAndAdd(v: Vec3Like, s: number): Vec3 { return new Vec3(this.x + cx(v) * s, this.y + cy(v) * s, this.z + cz(v) * s) }
+  negate(): Vec3 { return new Vec3(-this.x, -this.y, -this.z) }
+
+  // --- products / measures ---
+  dot(v: Vec3Like): number { return this.x * cx(v) + this.y * cy(v) + this.z * cz(v) }
+  cross(v: Vec3Like): Vec3 {
+    const bx = cx(v), by = cy(v), bz = cz(v)
+    return new Vec3(this.y * bz - this.z * by, this.z * bx - this.x * bz, this.x * by - this.y * bx)
+  }
+  length(): number { return Math.hypot(this.x, this.y, this.z) }
+  lengthSq(): number { return this.x * this.x + this.y * this.y + this.z * this.z }
+  distanceTo(v: Vec3Like): number { return Math.hypot(this.x - cx(v), this.y - cy(v), this.z - cz(v)) }
+  distanceSqTo(v: Vec3Like): number {
+    const dx = this.x - cx(v), dy = this.y - cy(v), dz = this.z - cz(v)
+    return dx * dx + dy * dy + dz * dz
+  }
+
+  normalize(): Vec3 {
+    const l = Math.hypot(this.x, this.y, this.z)
+    return l === 0 ? new Vec3(0, 0, 0) : new Vec3(this.x / l, this.y / l, this.z / l)
+  }
+  lerp(v: Vec3Like, t: number): Vec3 {
+    return new Vec3(this.x + (cx(v) - this.x) * t, this.y + (cy(v) - this.y) * t, this.z + (cz(v) - this.z) * t)
+  }
+  clamp(min: Vec3Like, max: Vec3Like): Vec3 {
+    return new Vec3(clampN(this.x, cx(min), cx(max)), clampN(this.y, cy(min), cy(max)), clampN(this.z, cz(min), cz(max)))
+  }
+  min(v: Vec3Like): Vec3 { return new Vec3(Math.min(this.x, cx(v)), Math.min(this.y, cy(v)), Math.min(this.z, cz(v))) }
+  max(v: Vec3Like): Vec3 { return new Vec3(Math.max(this.x, cx(v)), Math.max(this.y, cy(v)), Math.max(this.z, cz(v))) }
+  /** Reflect this vector about a (unit) `normal`: `v - 2·(v·n)·n`. */
+  reflect(normal: Vec3Like): Vec3 {
+    const d = 2 * this.dot(normal)
+    return new Vec3(this.x - d * cx(normal), this.y - d * cy(normal), this.z - d * cz(normal))
+  }
+  /** Vector projection of this onto `onto`. */
+  project(onto: Vec3Like): Vec3 {
+    const ox = cx(onto), oy = cy(onto), oz = cz(onto)
+    const denom = ox * ox + oy * oy + oz * oz
+    if (denom === 0) return new Vec3(0, 0, 0)
+    const k = this.dot(onto) / denom
+    return new Vec3(ox * k, oy * k, oz * k)
+  }
+  /** Angle (radians) between this and `v`. */
+  angle(v: Vec3Like): number {
+    const bx = cx(v), by = cy(v), bz = cz(v)
+    const mag = Math.sqrt(this.lengthSq() * (bx * bx + by * by + bz * bz))
+    return mag === 0 ? 0 : Math.acos(clampN(this.dot(v) / mag, -1, 1))
+  }
+
+  // --- rotation ---
+  /** Rotate this point around the X axis through `origin` (default 0) by `rad`. */
+  rotateX(rad: number, origin: Vec3Like = ZERO3): Vec3 {
+    const ox = cx(origin), oy = cy(origin), oz = cz(origin)
+    const py = this.y - oy, pz = this.z - oz, c = Math.cos(rad), s = Math.sin(rad)
+    return new Vec3(this.x, oy + py * c - pz * s, oz + py * s + pz * c)
+  }
+  rotateY(rad: number, origin: Vec3Like = ZERO3): Vec3 {
+    const ox = cx(origin), oy = cy(origin), oz = cz(origin)
+    const px = this.x - ox, pz = this.z - oz, c = Math.cos(rad), s = Math.sin(rad)
+    return new Vec3(ox + pz * s + px * c, this.y, oz + pz * c - px * s)
+  }
+  rotateZ(rad: number, origin: Vec3Like = ZERO3): Vec3 {
+    const ox = cx(origin), oy = cy(origin), oz = cz(origin)
+    const px = this.x - ox, py = this.y - oy, c = Math.cos(rad), s = Math.sin(rad)
+    return new Vec3(ox + px * c - py * s, oy + px * s + py * c, this.z)
+  }
+  /** Rotate this vector by a quaternion (x, y, z, w). Accepts a `Quat` or a raw `[x,y,z,w]`. */
+  rotate(q: ArrayLike<number> | { x: number, y: number, z: number, w: number }): Vec3 {
+    const qx = cx(q as Vec3Like), qy = cy(q as Vec3Like), qz = cz(q as Vec3Like)
+    const qw = (q as { w?: number }).w ?? (q as ArrayLike<number>)[3]
+    const vx = this.x, vy = this.y, vz = this.z
+    // t = 2 * (q.xyz × v)
+    let tx = qy * vz - qz * vy, ty = qz * vx - qx * vz, tz = qx * vy - qy * vx
+    tx += tx; ty += ty; tz += tz
+    // v + w·t + q.xyz × t
+    return new Vec3(
+      vx + qw * tx + qy * tz - qz * ty,
+      vy + qw * ty + qz * tx - qx * tz,
+      vz + qw * tz + qx * ty - qy * tx,
+    )
+  }
+  /** Transform this point by a column-major mat4 (a `Mat4`, its `.m`, or a raw length-16 array),
+   *  applying translation and the perspective divide. */
+  transform(m: ArrayLike<number> | { m: ArrayLike<number> }): Vec3 {
+    const a = (m as { m?: ArrayLike<number> }).m ?? (m as ArrayLike<number>)
+    const x = this.x, y = this.y, z = this.z
+    let w = a[3] * x + a[7] * y + a[11] * z + a[15]
+    w = w || 1
+    return new Vec3(
+      (a[0] * x + a[4] * y + a[8] * z + a[12]) / w,
+      (a[1] * x + a[5] * y + a[9] * z + a[13]) / w,
+      (a[2] * x + a[6] * y + a[10] * z + a[14]) / w,
+    )
+  }
+
+  withX(x: number): Vec3 { return new Vec3(x, this.y, this.z) }
+  withY(y: number): Vec3 { return new Vec3(this.x, y, this.z) }
+  withZ(z: number): Vec3 { return new Vec3(this.x, this.y, z) }
+
+  // --- interop ---
+  equals(v: Vec3Like, eps = 1e-6): boolean {
+    return approx(this.x, cx(v), eps) && approx(this.y, cy(v), eps) && approx(this.z, cz(v), eps)
+  }
+  clone(): Vec3 { return new Vec3(this.x, this.y, this.z) }
+  toArray(): [number, number, number] { return [ this.x, this.y, this.z ] }
+  *[Symbol.iterator](): Iterator<number> { yield this.x; yield this.y; yield this.z }
+
+  static from(v: Vec3Like): Vec3 { return new Vec3(cx(v), cy(v), cz(v)) }
+  static get zero(): Vec3 { return new Vec3(0, 0, 0) }
+  static get one(): Vec3 { return new Vec3(1, 1, 1) }
+  static get up(): Vec3 { return new Vec3(0, 1, 0) }
+  static get down(): Vec3 { return new Vec3(0, -1, 0) }
+  static get left(): Vec3 { return new Vec3(-1, 0, 0) }
+  static get right(): Vec3 { return new Vec3(1, 0, 0) }
+  /** Forward is −Z (the engine's cameras look down −Z; `node.forward` is −Z at identity). */
+  static get forward(): Vec3 { return new Vec3(0, 0, -1) }
+  static get back(): Vec3 { return new Vec3(0, 0, 1) }
+}
+
+const clampN = (v: number, lo: number, hi: number): number => (v < lo ? lo : v > hi ? hi : v)
+const ZERO2 = new Vec2(0, 0)
+const ZERO3 = new Vec3(0, 0, 0)

package/src/net/codec.ts

@@ -0,0 +1,119 @@
+// Defaults → wire layout (docs/multiplayer-plan.md §4 "input: defaults object = layout"). The hot
+// stream — inputs and snapshot states — is binary and its shape comes from a plain defaults object:
+//   number    → f32
+//   boolean   → 1 bit (packed after the floats)
+//   number[]  → f32 × length, fixed
+// 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.
+
+export type FieldKind = 0 | 1 | 2   // f32 · bool · f32[]
+export type Field = { key: string; kind: FieldKind; len: number }
+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 => {
+  const fields: Field[] = []
+  let floats = 0
+  let bools = 0
+  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++ }
+    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
+    } else {
+      throw new Error(`${what}: field '${key}' must be a number, a boolean or a fixed-length number[] (got ${describe(v)})`)
+    }
+  }
+  const sig = fields.map((f) => `${f.key}:${f.kind}${f.len > 1 ? f.len : ""}`).join(",")
+  return { fields, floats, bools, bytes: floats * 4 + Math.ceil(bools / 8), sig }
+}
+
+/** A fresh state object shaped like the defaults (arrays copied, never shared). */
+export const cloneDefaults = <T extends object>(defaults: T): T => {
+  const out: Record<string, unknown> = {}
+  for (const key of Object.keys(defaults)) {
+    const v = (defaults as Record<string, unknown>)[key]
+    out[key] = Array.isArray(v) ? v.slice() : v
+  }
+  return out as T
+}
+
+/** Copy the layout's fields from `from` into `into` (array elements copied in place; unknown keys
+ *  ignored — a JSON spawn state or a partial `setInput`). */
+export const assignState = (layout: Layout, into: any, from: any): void => {
+  if (!from) return
+  for (const f of layout.fields) {
+    const v = from[f.key]
+    if (v === undefined) continue
+    if (f.kind === 2) {
+      const a = into[f.key] as number[]
+      for (let i = 0; i < f.len; i++) a[i] = +(v[i] ?? 0)
+    } else if (f.kind === 1) into[f.key] = !!v
+    else into[f.key] = +v
+  }
+}
+
+export const packInto = (view: DataView, offset: number, layout: Layout, s: any): number => {
+  let o = offset
+  for (const f of layout.fields) {
+    if (f.kind === 0) { view.setFloat32(o, s[f.key], true); o += 4 }
+    else if (f.kind === 2) {
+      const a = s[f.key] as number[]
+      for (let i = 0; i < f.len; i++) { view.setFloat32(o, a[i] ?? 0, true); o += 4 }
+    }
+  }
+  let bits = 0
+  let n = 0
+  for (const f of layout.fields) {
+    if (f.kind !== 1) continue
+    if (s[f.key]) bits |= 1 << (n & 7)
+    n++
+    if ((n & 7) === 0) { view.setUint8(o++, bits); bits = 0 }
+  }
+  if (n & 7) view.setUint8(o++, bits)
+  return o
+}
+
+export const unpackFrom = (view: DataView, offset: number, layout: Layout, into: any): number => {
+  let o = offset
+  for (const f of layout.fields) {
+    if (f.kind === 0) { into[f.key] = view.getFloat32(o, true); o += 4 }
+    else if (f.kind === 2) {
+      const a = into[f.key] as number[]
+      for (let i = 0; i < f.len; i++) { a[i] = view.getFloat32(o, true); o += 4 }
+    }
+  }
+  let bits = 0
+  let n = 0
+  for (const f of layout.fields) {
+    if (f.kind !== 1) continue
+    if ((n & 7) === 0) bits = view.getUint8(o++)
+    into[f.key] = (bits & (1 << (n & 7))) !== 0
+    n++
+  }
+  return o
+}
+
+/** `out = a + (b − a) · t` for the numeric fields; booleans 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) {
+      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]
+  }
+}
+
+/** FNV-1a over a string → 8 hex chars. Enough to tell two bundles' schemas apart. */
+export const hashString = (s: string): string => {
+  let h = 0x811c9dc5
+  for (let i = 0; i < s.length; i++) {
+    h ^= s.charCodeAt(i)
+    h = Math.imul(h, 0x01000193)
+  }
+  return (h >>> 0).toString(16).padStart(8, "0")
+}