lecodes-cli 0.18.2 → 0.19.0

package/runtime/sdk/net/core.ts

@@ -0,0 +1,384 @@
+// Net core — the transport half of LeCodes multiplayer (docs/multiplayer-plan.md §4–5): roles,
+// connect / listen, players + roster, JSON messages, the poll pump. Replication (inputs, snapshots,
+// `Replicated`) lives in ./replication.ts and plugs into this file through `hooks`; the public `Net`
+// object is ./index.ts.
+//
+// Roles (`Net.role`):
+//   offline  the default — both sides run in this process, `Net.send` delivers in-process
+//   host     offline + `Net.listen()`: a player who is also the server (listen server)
+//   server   the dedicated exe (`--server`): `isServer` true, `isClient` false, no local player
+//   client   connected to a host or a server
+// Game code is written once: `Net.isServer` guards the rules, `Net.isClient` the presentation,
+// and offline satisfies both.
+//
+// Transport: the `_creatorNet` bridge (creator-pkg over creator-net / yojimbo) — a byte pipe with
+// two channels (0 reliable-ordered, 1 unreliable) that knows nothing about players. Everything on
+// the reliable channel here is JSON text: the roster protocol (`$`-prefixed, reserved) and the
+// game's own `Net.message`s (`[name, data]`). Binary payloads (inputs, snapshots) go to
+// ./replication.ts. Pumped from the aspect dispatcher's phase hooks (core/Aspect.ts) — poll FIRST in
+// the early phase, flush LAST in the late one — claimed on the first listen/connect, never at
+// module scope (chisel drops top-level side effects, and a host without the bridge has no loop).
+
+import { _ensureNetDispatch, _phaseHooks } from "../core/Aspect"
+
+export type Listener = (...args: any[]) => void
+
+export type NetRole = "offline" | "host" | "client" | "server"
+export type NetStatus = "idle" | "connecting" | "online" | "error"
+
+/** A typed message key: `const Fire = Net.message<{ dir: number[] }>("fire")`. The type lives in
+ *  TypeScript only; the payload is JSON. */
+export type NetMessage<T = unknown> = { readonly name: string; readonly unreliable: boolean; readonly __t?: T }
+
+export type NetEvents = {
+  /** Client: welcomed by the server. Host/server: listening. */
+  connect: () => void
+  /** The connection ended (`reason` from the transport, e.g. "timed out", "kicked"). */
+  disconnect: (reason: string) => void
+  /** The server refused us (`reason`: "full" | "version" | "schema" | a kick reason). */
+  reject: (reason: string) => void
+  join: (player: NetPlayer) => void
+  leave: (player: NetPlayer, reason: string) => void
+  error: (message: string) => void
+}
+
+export type NetLaunch = { role: "server" | "client"; address: string; port: number; maxClients: number }
+
+export const CH_RELIABLE = 0
+export const CH_UNRELIABLE = 1
+export const PROTO = 2
+export const LOCAL_SLOT = -1
+
+// Record kinds from creator-net (creator-net.h CNET_RECORD_*).
+const REC_CONNECTED = 1
+const REC_DISCONNECTED = 2
+const REC_MESSAGE = 3
+const REC_CONNECT_FAILED = 4
+
+export const bridge = (): typeof _creatorNet | null => (typeof _creatorNet !== "undefined" ? _creatorNet : null)
+
+export class NetPlayer {
+  /** Session-unique id assigned by the server (1 = the host's own player when hosting). */
+  readonly id: number
+  name: string
+  readonly connectedAt: number
+  /** 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 = {}
+  /** @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) */
+  _in: any = null
+  private _leave: Listener[] = []
+
+  constructor(id: number, name: string, slot: number) {
+    this.id = id
+    this.name = name
+    this._slot = slot
+    this.connectedAt = Date.now()
+  }
+
+  get isMe(): boolean { return state.me === this }
+  /** Round trip to this player in ms (server side) or to the server (our own player on a client). */
+  get rtt(): number { return infoOf(this)[1] }
+  get loss(): number { return infoOf(this)[2] }
+
+  /** Server → this player. */
+  send<T>(msg: NetMessage<T>, data: T): void {
+    if (!state.isServer) throw new Error("player.send is server-side; a client uses Net.send")
+    deliverTo(this, msg, data)
+  }
+
+  kick(reason = "kicked"): void {
+    if (!state.isServer || this._slot === LOCAL_SLOT) return
+    sendRaw(this._slot, CH_RELIABLE, JSON.stringify(["$reject", { reason }]))
+    bridge()?.kick(this._slot)
+  }
+
+  on(event: "leave", cb: (player: NetPlayer, reason: string) => void): this {
+    if (!this._leave.includes(cb)) this._leave.push(cb)
+    return this
+  }
+  off(event: "leave", cb: (player: NetPlayer, reason: string) => void): this {
+    const i = this._leave.indexOf(cb)
+    if (i >= 0) this._leave.splice(i, 1)
+    return this
+  }
+  /** @internal */
+  _left(reason: string): void {
+    for (const fn of this._leave.slice()) fn(this, reason)
+  }
+}
+
+// ---- state ---------------------------------------------------------------------------------------
+
+export const state = {
+  role: "offline" as NetRole,
+  status: "idle" as NetStatus,
+  isServer: true,
+  isClient: true,
+  me: null as NetPlayer | null,
+  players: [] as NetPlayer[],
+  nextId: 1,
+  /** a session is up: the phase hooks are installed and pump every frame */
+  active: false,
+  events: new Map<string, Listener[]>(),
+  handlers: new Map<string, Listener[]>(),
+  connectResolve: null as null | (() => void),
+  connectReject: null as null | ((e: Error) => void),
+  myName: "Player",
+}
+
+// Replication's seams into the roster / pump (set by replication.ts when a session starts — from a
+// function, never at module scope). Each is optional so the core runs alone.
+export const hooks = {
+  frameEarly: null as null | ((dt: number) => void),
+  frameFixed: null as null | ((dt: number) => void),
+  frameLate: null as null | ((dt: number) => void),
+  /** client: extra `$hello` fields (schema hash) */
+  helloExtra: null as null | (() => Record<string, unknown>),
+  /** server: a reject reason for this `$hello`, or null to accept */
+  helloCheck: null as null | ((data: any) => string | null),
+  /** server: extra `$welcome` fields (tick, kind table) */
+  welcomeExtra: null as null | (() => Record<string, unknown>),
+  /** server: right after `$welcome` + `$join` went out — send the live entities to the newcomer */
+  afterWelcome: null as null | ((p: NetPlayer) => void),
+  /** client: the `$welcome` arrived (before the connect event) */
+  onWelcome: null as null | ((data: any) => void),
+  /** client: a reserved `$` message the roster does not know (spawn / despawn) */
+  clientReserved: null as null | ((name: string, data: any) => void),
+  /** binary payloads (channel 1): inputs on the server, snapshots on the client */
+  serverBinary: null as null | ((p: NetPlayer, channel: number, data: ArrayBuffer) => void),
+  clientBinary: null as null | ((channel: number, data: ArrayBuffer) => void),
+  /** server: a player is gone (after the leave event) */
+  playerLeft: null as null | ((p: NetPlayer) => void),
+  /** the session ends (before the state resets); `role` = the role we are leaving */
+  reset: null as null | ((role: NetRole) => void),
+}
+
+export const emit = (event: keyof NetEvents, ...args: any[]): void => {
+  const list = state.events.get(event)
+  if (!list) return
+  for (const fn of list.slice()) fn(...args)
+}
+
+const EMPTY_INFO = new Float32Array(5)
+const infoOf = (p: NetPlayer): Float32Array => {
+  const b = bridge()
+  if (!b || p._slot === LOCAL_SLOT && state.role !== "client") return EMPTY_INFO
+  return b.clientInfo(p._slot)
+}
+
+export const playerBySlot = (slot: number): NetPlayer | undefined => state.players.find((p) => p._slot === slot)
+
+export const addPlayer = (id: number, name: string, slot: number): NetPlayer => {
+  const p = new NetPlayer(id, name, slot)
+  state.players.push(p)
+  return p
+}
+
+export const removePlayer = (p: NetPlayer, reason: string): void => {
+  const i = state.players.indexOf(p)
+  if (i >= 0) state.players.splice(i, 1)
+  p._left(reason)
+  emit("leave", p, reason)
+  if (state.isServer) hooks.playerLeft?.(p)
+}
+
+// The local player exists in every role but `server`.
+export const ensureMe = (): NetPlayer => {
+  if (state.me) return state.me
+  state.me = addPlayer(state.nextId++, state.myName, LOCAL_SLOT)
+  return state.me
+}
+
+// ---- transport --------------------------------------------------------------------------------------
+
+export const sendRaw = (slot: number, channel: number, payload: string | ArrayBuffer): boolean => {
+  const b = bridge()
+  return b ? b.send(slot, channel, payload) : false
+}
+
+// Handler dispatch is in-process for the local player (offline / host's own), async so a message
+// sent from inside a handler behaves like one that crossed the wire (ordered, never re-entrant).
+export const queueLocal = (fn: () => void): void => { Promise.resolve().then(fn) }
+
+export const dispatchMessage = (name: string, data: unknown, from: NetPlayer | null): void => {
+  const list = state.handlers.get(name)
+  if (!list) return
+  for (const fn of list.slice()) fn(data, from)
+}
+
+export const deliverTo = (p: NetPlayer, msg: NetMessage<any>, data: unknown): void => {
+  if (p._slot === LOCAL_SLOT) {
+    queueLocal(() => dispatchMessage(msg.name, data, null))
+    return
+  }
+  sendRaw(p._slot, msg.unreliable ? CH_UNRELIABLE : CH_RELIABLE, JSON.stringify([msg.name, data]))
+}
+
+export const broadcastRaw = (payload: string | ArrayBuffer, except: NetPlayer | null, channel = CH_RELIABLE): void => {
+  for (const p of state.players) {
+    if (p === except || p._slot === LOCAL_SLOT) continue
+    sendRaw(p._slot, channel, payload)
+  }
+}
+
+// The session's frame plumbing: poll first thing in the early phase, replication's own work around
+// it, sends flushed at the end of the late phase. The dispatcher (and its fixed phase — Net.tick is
+// a fixed-step count) is forced on, so an app with no aspects at all still pumps.
+export const startPhases = (): void => {
+  if (state.active) return
+  state.active = true
+  _ensureNetDispatch()
+  _phaseHooks.early = (dt) => { pump(); if (state.active) hooks.frameEarly?.(dt) }
+  _phaseHooks.fixed = (dt) => { if (state.active) hooks.frameFixed?.(dt) }
+  _phaseHooks.late = (dt) => { if (state.active) hooks.frameLate?.(dt) }
+}
+
+export const stopPhases = (): void => {
+  if (!state.active) return
+  state.active = false
+  _phaseHooks.early = _phaseHooks.fixed = _phaseHooks.late = null
+}
+
+export const resetToOffline = (): void => {
+  hooks.reset?.(state.role)
+  stopPhases()
+  state.role = "offline"
+  state.status = "idle"
+  state.isServer = true
+  state.isClient = true
+  state.players = []
+  state.me = null
+  state.nextId = 1
+  state.connectResolve = null
+  state.connectReject = null
+}
+
+// ---- server side ------------------------------------------------------------------------------------
+
+const onServerRecord = (kind: number, slot: number, arg: number, payload: unknown): void => {
+  const b = bridge()!
+  if (kind === REC_CONNECTED) return   // the roster starts with the client's $hello
+  if (kind === REC_DISCONNECTED) {
+    const p = playerBySlot(slot)
+    if (!p) return
+    const reason = b.reasonString(arg, true)
+    removePlayer(p, reason)
+    broadcastRaw(JSON.stringify(["$leave", { id: p.id, reason }]), null)
+    return
+  }
+  if (kind !== REC_MESSAGE) return
+  if (payload instanceof ArrayBuffer) {
+    const from = playerBySlot(slot)
+    if (from) hooks.serverBinary?.(from, arg, payload)
+    return
+  }
+  if (typeof payload !== "string") return
+  let parsed: any
+  try { parsed = JSON.parse(payload) } catch { return }
+  if (!Array.isArray(parsed) || typeof parsed[0] !== "string") return
+  const [name, data] = parsed
+  if (name === "$hello") {
+    if (playerBySlot(slot)) return
+    const reason = !data || data.proto !== PROTO ? "version" : hooks.helloCheck?.(data) ?? null
+    if (reason) {
+      sendRaw(slot, CH_RELIABLE, JSON.stringify(["$reject", { reason }]))
+      b.kick(slot)
+      return
+    }
+    const p = addPlayer(state.nextId++, String(data.name ?? `Player ${state.nextId - 1}`), slot)
+    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 })),
+      ...(hooks.welcomeExtra?.() ?? {}),
+    }]))
+    broadcastRaw(JSON.stringify(["$join", { id: p.id, name: p.name }]), p)
+    hooks.afterWelcome?.(p)
+    emit("join", p)
+    return
+  }
+  if (name.startsWith("$")) return
+  const from = playerBySlot(slot)
+  if (from) dispatchMessage(name, data, from)
+}
+
+// ---- client side ------------------------------------------------------------------------------------
+
+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?.() ?? {}) }]))
+    return
+  }
+  if (kind === REC_CONNECT_FAILED || kind === REC_DISCONNECTED) {
+    const reason = b.reasonString(arg, false)
+    const wasOnline = state.status === "online"
+    const reject = state.connectReject
+    resetToOffline()
+    if (kind === REC_CONNECT_FAILED) {
+      state.status = "error"
+      reject?.(new Error(reason))
+      emit("error", reason)
+    } else {
+      reject?.(new Error(reason))
+      if (wasOnline) emit("disconnect", reason)
+    }
+    return
+  }
+  if (kind !== REC_MESSAGE) return
+  if (payload instanceof ArrayBuffer) { hooks.clientBinary?.(arg, payload); return }
+  if (typeof payload !== "string") return
+  let parsed: any
+  try { parsed = JSON.parse(payload) } catch { return }
+  if (!Array.isArray(parsed) || typeof parsed[0] !== "string") return
+  const [name, data] = parsed
+  switch (name) {
+    case "$welcome": {
+      state.me = addPlayer(data.id, state.myName, LOCAL_SLOT)
+      for (const q of data.players ?? []) addPlayer(q.id, q.name, 0)
+      state.status = "online"
+      hooks.onWelcome?.(data)
+      const resolve = state.connectResolve
+      state.connectResolve = null
+      state.connectReject = null
+      resolve?.()
+      emit("connect")
+      return
+    }
+    case "$reject": {
+      const reason = String(data?.reason ?? "rejected")
+      const reject = state.connectReject
+      state.connectReject = null
+      state.connectResolve = null
+      reject?.(new Error(reason))
+      emit("reject", reason)
+      return
+    }
+    case "$join": {
+      const p = addPlayer(data.id, data.name, 0)
+      emit("join", p)
+      return
+    }
+    case "$leave": {
+      const p = state.players.find((q) => q.id === data.id)
+      if (p) removePlayer(p, String(data.reason ?? ""))
+      return
+    }
+  }
+  if (name.startsWith("$")) { hooks.clientReserved?.(name, data); return }
+  dispatchMessage(name, data, null)
+}
+
+export const pump = (): void => {
+  const b = bridge()
+  if (!b) return
+  const batch = b.poll()
+  if (!batch) return
+  const onRecord = state.isServer ? onServerRecord : onClientRecord
+  for (let i = 0; i + 3 < batch.length; i += 4) {
+    onRecord(batch[i], batch[i + 1], batch[i + 2], batch[i + 3])
+    if (!state.active) return   // a record tore the session down
+  }
+}

package/runtime/sdk/net/index.ts

@@ -0,0 +1,181 @@
+// Net — LeCodes multiplayer, the public object (docs/multiplayer-plan.md §4). The transport, roster
+// and JSON messages are ./core.ts; kinds, inputs, snapshots and the `Replicated` aspect are
+// ./replication.ts. Principles: the schema object is the key and the verbs live on the addressee
+// (`Net.send(Msg, d)` / `player.send(Msg, d)` / `Net.broadcast(Msg, d)` / `Net.on(Msg, cb)`); the
+// player is the unit of addressing; offline / host / client / server run the same game code.
+
+import {
+  CH_RELIABLE, CH_UNRELIABLE, LOCAL_SLOT, NetPlayer, bridge, dispatchMessage, emit, ensureMe, queueLocal,
+  removePlayer, resetToOffline, sendRaw, startPhases, state,
+  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,
+} from "./replication"
+
+export { NetPlayer, NetEntity, Replicated }
+export type { NetEvents, NetLaunch, NetMessage, NetRole, NetStatus, NetInput, NetKind, NetTransform }
+
+class NetImpl {
+  get role(): NetRole { return state.role }
+  get status(): NetStatus { return state.status }
+  get isServer(): boolean { return state.isServer }
+  get isClient(): boolean { return state.isClient }
+  /** True on hosts that ship the transport (desktop, the 3d/full Android variants, iOS). Web: false. */
+  get supported(): boolean { return bridge() !== null }
+  /** What the exe was launched as (`--server --port N` / `--connect ADDR`), or null. */
+  get launch(): NetLaunch | null { return (bridge()?.launch() as NetLaunch | null) ?? null }
+  get me(): NetPlayer { return state.role === "server" ? (null as unknown as NetPlayer) : ensureMe() }
+  get players(): readonly NetPlayer[] { if (state.role !== "server") ensureMe(); return state.players }
+  player(id: number): NetPlayer | undefined { return state.players.find((p) => p.id === id) }
+  /** Our round trip to the server (client), 0 otherwise. */
+  get rtt(): number { return state.role === "client" ? (bridge()?.clientInfo(0)[1] ?? 0) : 0 }
+  /** 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() }
+  /** 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 {
+    const b = bridge()
+    if (!b) { emit("error", "multiplayer is not supported on this host"); return false }
+    if (state.role !== "offline") this.disconnect()
+    if (opts.name) state.myName = opts.name
+    // `dedicated` (no local player) defaults to how the exe was launched; a windowed --server that
+    // still wants its own player passes `dedicated: false`.
+    const dedicated = opts.dedicated ?? this.launch?.role === "server"
+    if (!b.listen(opts.port ?? 40000, opts.maxClients ?? 16)) {
+      state.status = "error"
+      emit("error", `could not listen on port ${opts.port ?? 40000}`)
+      return false
+    }
+    state.role = dedicated ? "server" : "host"
+    state.isServer = true
+    state.isClient = !dedicated
+    state.status = "online"
+    if (!dedicated) ensureMe()
+    installReplication()
+    startPhases()
+    emit("connect")
+    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> {
+    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
+    return new Promise<void>((resolve, reject) => {
+      if (!b.connect(target.address)) { reject(new Error(`bad address '${target.address}'`)); return }
+      state.role = "client"
+      state.isServer = false
+      state.isClient = true
+      state.status = "connecting"
+      state.connectResolve = resolve
+      state.connectReject = reject
+      installReplication()
+      startPhases()
+    })
+  }
+
+  /** Client → offline. Host/server → everyone is dropped, back to offline. */
+  disconnect(): void {
+    const b = bridge()
+    if (state.role === "offline") return
+    const wasClient = state.role === "client"
+    const players = state.players.slice()
+    b?.disconnect()
+    resetToOffline()
+    if (wasClient) emit("disconnect", "disconnected")
+    else for (const p of players) if (p._slot !== LOCAL_SLOT) removePlayer(p, "server closed")
+  }
+
+  // ---- messages: JSON, typed in TS only -------------------------------------------------------------
+
+  /** Declare a message type once; the name is the wire id. `unreliable` = channel 1 (fire-and-forget). */
+  message<T = void>(name: string, opts: { unreliable?: boolean } = {}): NetMessage<T> {
+    if (name.startsWith("$")) throw new Error("message names starting with '$' are reserved")
+    return { name, unreliable: !!opts.unreliable }
+  }
+
+  /** Client → server (offline / host: delivered in-process, `from` = our own player). */
+  send<T>(msg: NetMessage<T>, data: T): void {
+    if (state.role === "client") {
+      sendRaw(0, msg.unreliable ? CH_UNRELIABLE : CH_RELIABLE, JSON.stringify([msg.name, data]))
+      return
+    }
+    if (state.role === "server") throw new Error("Net.send is client-side; the server uses player.send / Net.broadcast")
+    const me = ensureMe()
+    queueLocal(() => dispatchMessage(msg.name, data, me))
+  }
+
+  /** Server → every player (incl. the host's own), minus `except`. */
+  broadcast<T>(msg: NetMessage<T>, data: T, opts: { except?: NetPlayer | null } = {}): void {
+    if (!state.isServer) throw new Error("Net.broadcast is server-side")
+    const payload = JSON.stringify([msg.name, data])
+    const channel = msg.unreliable ? CH_UNRELIABLE : CH_RELIABLE
+    for (const p of state.players) {
+      if (p === opts.except) continue
+      if (p._slot === LOCAL_SLOT) queueLocal(() => dispatchMessage(msg.name, data, null))
+      else sendRaw(p._slot, channel, payload)
+    }
+  }
+
+  /** Subscribe to a built-in event or to a message (`from` = the sending player on the server,
+   *  null on a client — the server sent it). Returns `Net` for chaining. */
+  on<K extends keyof NetEvents>(event: K, cb: NetEvents[K]): this
+  on<T>(msg: NetMessage<T>, cb: (data: T, from: NetPlayer | null) => void): this
+  on(key: any, cb: Listener): this {
+    const map = typeof key === "string" ? state.events : state.handlers
+    const name = typeof key === "string" ? key : key.name
+    const list = map.get(name) ?? []
+    if (!list.includes(cb)) list.push(cb)
+    map.set(name, list)
+    return this
+  }
+
+  off<K extends keyof NetEvents>(event: K, cb: NetEvents[K]): this
+  off<T>(msg: NetMessage<T>, cb: (data: T, from: NetPlayer | null) => void): this
+  off(key: any, cb: Listener): this {
+    const map = typeof key === "string" ? state.events : state.handlers
+    const name = typeof key === "string" ? key : key.name
+    const list = map.get(name)
+    if (!list) return this
+    const i = list.indexOf(cb)
+    if (i >= 0) list.splice(i, 1)
+    return this
+  }
+
+  // ---- replication: defaults object = layout --------------------------------------------------------
+
+  /** The per-tick input layout (one per game): `const PlayerInput = Net.input({ moveX: 0, moveY: 0, jump: false })`.
+   *  Fields: number → f32, boolean → 1 bit, number[] → f32 × length. */
+  input<T extends object>(defaults: T): NetInput<T> { return declareInput(defaults) }
+
+  /** Set this tick's input — from `updateFixed`, once per tick, on the machine that owns the player
+   *  (client / host / offline). The owner's sim reads it back through `rep.input(PlayerInput)`; a
+   *  client also ships it to the server for the same tick. */
+  setInput<T extends object>(inp: NetInput<T>, values: Partial<T>): void { setInput(inp, values) }
+
+  /** 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> {
+    return declareKind(name, defaults, opts as any)
+  }
+
+  /** Every replicated entity this machine knows. */
+  get entities(): readonly NetEntity[] { return allEntities() }
+  entity(netId: number): NetEntity | undefined { return entityById(netId) }
+
+  /** Dev only: yojimbo's network simulator on our side of the wire (latency/jitter in ms, loss in %). */
+  simulate(opts: { latency?: number; jitter?: number; loss?: number }): void {
+    bridge()?.simulate(opts.latency ?? 0, opts.jitter ?? 0, opts.loss ?? 0)
+  }
+}
+
+export const Net = new NetImpl()