lecodes-sdk 1.2.0 → 2.0.1

package/src/bridges/input.d.ts

@@ -0,0 +1,72 @@
+// The input bridge (`_creatorInput`): keyboard / mouse / gamepad behind the SDK `Input` global
+// (docs/input-plan.md) and the on-screen keyboard inset behind `app.keyboardHeight`.
+// Part of the host contract. A HOST bridge (`@host`, see ./app.d.ts): the native side is the
+// `HostInput` table of runtime/native/include/creator-pkg/host.gen.h, generated from this file.
+//
+// Design: a BUTTON is anything that goes down and up — keyboard keys, mouse buttons, gamepad
+// buttons — and they share ONE code vocabulary (KeyboardEvent.code + "MouseLeft|Right|Middle|
+// Back|Forward" + the W3C standard-gamepad "GamepadSouth|East|West|North|L1|R1|L2|R2|Select|
+// Start|L3|R3|Up|Down|Left|Right"), one held-poll and one event pair. Continuous signals (mouse
+// motion, sticks, triggers) are numbered channels behind one poll. Bindings/axes/edge detection
+// are SDK-side; hosts only report physical state. Every slot is optional: a touch-only host has
+// no buttons, no pointer, no pads, and the SDK reads "nothing held, zero motion, lock refused".
+// The push side (button events, keyboard frames) is `emitInputEvent` / `emitKeyboardEvent`:
+// update the polls BEFORE emitting, so a handler reading a poll agrees with the event.
+import type { f32, f64, i32 } from "./types"
+
+declare global {
+  /** @host input */
+  var _creatorInput: {
+    /** Is this button held right now? `gamepad` (0..3) scopes a Gamepad* code to one pad; -1 =
+     *  any connected pad. Keyboard/mouse codes ignore it. */
+    key?(code: string, gamepad: i32): boolean
+    /** Continuous input poll by channel id (SDK `InputChannel`): 0 MouseX, 1 MouseY (logical px,
+     *  last known cursor position inside the viewport), 2 MouseDX, 3 MouseDY (motion accumulated
+     *  during the PREVIOUS frame — unaccelerated/raw where the OS offers it, counts while locked),
+     *  4 WheelX, 5 WheelY (wheel notches, previous frame), 6 PointerLocked (0/1), 7 GamepadCount,
+     *  8 PointerOnUI (0/1: the primary pointer went DOWN on something the UI claimed — an
+     *  interactive node, a scrollable, an editable, a modal backdrop — and is still held; stays 1
+     *  wherever the cursor goes until the release, so a drag that started on a HUD control never
+     *  becomes camera look; always 0 while pointer-locked and for touch-only hosts without a UI claim);
+     *  gamepad p at 16 + 16·p: +0 Connected, +1 LeftX, +2 LeftY, +3 RightX, +4 RightY (−1..1,
+     *  +Y = down like the web), +5 LeftTrigger, +6 RightTrigger (0..1). Unknown channel → 0.
+     *  "Previous frame" = the host's own frame boundary (the event pump / rAF / fixed step), so
+     *  every read within one frame agrees. */
+    read?(channel: i32): f64
+    /** Request (true) / release (false) pointer lock: hide + confine the cursor, keep MouseDX/DY
+     *  flowing (FPS look). Returns whether the request was accepted now (web needs a user gesture);
+     *  the eventual state is channel 6. Hosts release on focus loss and re-acquire on focus. */
+    setPointerLock?(on: boolean): boolean
+    /** Register THE input-event listener (single slot per JS world, like `_creatorApp.registerEvent`
+     *  — the SDK fans out). kind: 0 keydown, 1 keyup, 2 gamepadconnected, 3 gamepaddisconnected.
+     *  `code` is the button code above ("" for connect events); `gamepad` the pad index for Gamepad*
+     *  codes / connect events, −1 otherwise; `repeat` 1 for an OS auto-repeat keydown. Delivered on
+     *  the JS thread no later than the end of the frame it arrived in — i.e. always before the NEXT
+     *  setLoop tick (the runtime drains its dispatch queue after the frame's timers, so a poll can
+     *  see the new state one tick before the event; web/headless deliver synchronously). @custom */
+    registerEvent?(callback: (kind: number, code: string, gamepad: number, repeat: number) => void): void
+    /** Dual-motor rumble on pad `gamepad` (0..3) — the W3C "dual-rumble" effect. `strong` = the
+     *  low-frequency (left, heavy) motor, `weak` = the high-frequency (right, light) one, both 0..1
+     *  (hosts clamp); `durationMs` > 0, hosts cap it at 5000. A new call REPLACES the running effect
+     *  on that pad; `strong = weak = 0` (any duration) stops it. The HOST owns the clock: the motors
+     *  stop by themselves after `durationMs`, on focus loss, when the pad disconnects and when the
+     *  world that started the effect is torn down — an app never has to clean up. Returns whether
+     *  the pad took the command (false: no such pad, or it has no motors). */
+    rumble?(gamepad: i32, strong: f32, weak: f32, durationMs: i32): boolean
+
+    // ---- The on-screen keyboard (docs/input-upgrades-plan.md §7) ----------------------------------
+    /** On-screen keyboard height in logical px currently overlapping the app viewport, 0 when
+     *  hidden. The RAW overlap, independent of the focused input's keyboardShrink policy (with
+     *  shrink the layout already avoids it; the main consumer is overlay mode). Surfaced as
+     *  app.keyboardHeight. Hosts without an on-screen keyboard leave it null. */
+    keyboardHeight?(): f64
+    /** Register THE keyboard listener (single slot per JS world, like registerEvent — the SDK fans
+     *  out; a separate channel because the string one can't carry two numbers). Fires on every
+     *  keyboard frame change with (height — as above, duration — the platform's animation duration
+     *  in ms, 0 where none). Surfaced as the app "keyboard" event. The host pushes with
+     *  `emitKeyboardEvent`. @custom */
+    registerKeyboardEvent?(callback: (height: number, duration: number) => void): void
+  }
+}
+
+export {}

package/src/bridges/media.d.ts

@@ -0,0 +1,55 @@
+// The media bridge (`_creatorMedia`): the SDK `AudioPlayer` / `VideoPlayer` over the host's media
+// players (the platform's decoders and network — game audio is `_creatorAudio`, the engine).
+// Part of the host contract. A HOST bridge (`@host`, see ./app.d.ts): the native side is the
+// `HostMedia` table of runtime/native/include/creator-pkg/host.gen.h, generated from this file —
+// the `var` members below plus the `interface HostMedia` slots (a slot may repeat a `@custom`
+// member's name: the JS wrapper is the runtime's, the slot is the host's).
+// OPTIONAL AS A WHOLE (`@optional`): a host without media players (desktop, headless) provides no
+// table and the global is absent — the SDK players are inert there. Only `createMediaPlayerTexture`
+// stays on `_creator` (it imports a player's frames into the 3D engine).
+//
+// Ownership (owned handles, docs/plans/hosts-unification-plan.md phase 10): a player is an OWNED
+// resource — `createAudio` / `createVideo` return a Handle; the runtime (host/media.cpp) counts a
+// PLAYING player as natively owned, so a one-shot the app fires and forgets keeps playing to its
+// end and is released then; a paused player the app dropped is released at once. The host's
+// end-of-playback callback is the runtime's trampoline: the SDK hears it by id through `setEmitter`.
+import type { f32, f64, i32 } from "./types"
+
+declare global {
+  /** @host media @optional */
+  var _creatorMedia: {
+    /** A player for `src` as an owned Handle (null = the host failed to create one). @custom */
+    createAudio(src: string): Handle | null
+    /** @custom */
+    createVideo(src: string): Handle | null
+    setVolume(id: i32, volume: f32): void
+    /** @custom (the runtime remembers the loop flag: a looping end is not a stop) */
+    setLoop(id: i32, loop: boolean): void
+    /** @custom (the runtime counts playing as ownership) */
+    setPlaying(id: i32, playing: boolean): void
+    /** Playback position in seconds. */
+    time?(id: i32): f64
+    setTime?(id: i32, time: f64): void
+    /** Media length in seconds (0 until metadata has loaded). */
+    duration?(id: i32): f64
+    /** ONE listener per world for every player's end-of-playback (`id`): the SDK turns it into
+     *  loopReached / completed. @custom */
+    setEmitter(callback: (id: number) => void): void
+  }
+}
+
+/** The host's slots behind the `@custom` members above. */
+export interface HostMedia {
+  /** A player for `src`; returns its id (-1 = failed). `onFinished` is the end-of-playback listener
+   *  (the runtime's trampoline): the host keeps the handle and calls it (`dispatchBorrowedCall`) at
+   *  every play-through end, and frees it (`jsFree`) on `remove`. */
+  createAudio(src: string, onFinished: () => void): i32
+  createVideo(src: string, onFinished: () => void): i32
+  setLoop(id: i32, loop: boolean): void
+  setPlaying(id: i32, playing: boolean): void
+  /** Release the player (decoder, network, buffers) and its `onFinished` handle. A host that leaves
+   *  it null keeps players for the process. */
+  remove?(id: i32): void
+}
+
+export {}

package/src/bridges/nav.d.ts

@@ -0,0 +1,71 @@
+// The navmesh bridge (`_creatorNav`): engines/nav (Recast/Detour).
+// Part of the host contract: every runtime implements this global (runtime/native in C++, the web
+// runtimes in TS). Types are the PRECISE ones the native side reads (see ./types.d.ts); the SDK
+// only sees numbers. The ABI checker (scripts/check-pkg-bridges.mjs) reads this folder.
+import type { bytes, f32, i32, u32, u8 } from "./types"
+
+declare global {
+  // ---- navigation meshes (creator-nav / Recast+Detour) -----------------------------------------
+  // Runtime only (docs/navmesh-plan.md §5): load a baked `.navmesh` (LNAV) from a fetch system id,
+  // query it, run a DetourCrowd of agents one fixed step at a time. Present on hosts built with
+  // CREATOR_PKG_NAV (desktop, the 3d/full Android variants, iOS) and on every web host through the
+  // wasm build; the SDK feature-detects it. Parameter blocks are fixed-order Float32Arrays
+  // (creator-nav.h CNAV_AGENT_* / CNAV_READ_*). Handles (meshId / crowdId, from 1) are the engine's
+  // own (creator-nav.h "handles"): a world swap unloads them all. Every method is one engine call.
+  /** @engine nav */
+  var _creatorNav: {
+    /** Web hosts only: loads the wasm lazily. Absent on native hosts — call it when present. @custom */
+    ready?(): Promise<void>
+    /** @c cnavLastError */
+    lastError(): string
+    /** LNAV bytes already fetched (the createGlb pattern) → meshId, 0 on failure. @c cnavLoad */
+    load(systemId: bytes): u32
+    /** @c cnavUnload */
+    unload(meshId: u32): void
+    /** The file's JSON header: agent size, cell, bounds, stats, `meta` (the CLI's provenance). @c cnavHeader */
+    header(meshId: u32): string
+    /** @c cnavPolyCount */
+    polyCount(meshId: u32): i32
+    /** @c cnavSetAreaCost */
+    setAreaCost(meshId: u32, area: u8, cost: f32): void
+    /** Straight path from → to into `out` (xyz per corner, up to out.length / 3 corners); returns the
+     *  corner count, NEGATIVE when the path is partial (the target is unreachable — it ends at the
+     *  closest polygon). `ex <= 0` = default search extents.
+     *  @c cnavPath @pack fx 3 @pack tx 3 @pack ex 3 @count outCount=out */
+    findPath(meshId: u32, fx: f32, fy: f32, fz: f32, tx: f32, ty: f32, tz: f32, ex: f32, ey: f32, ez: f32, include: u32, exclude: u32, out: Float32Array): i32
+    /** @c cnavNearestPoint @pack x 3 @pack ex 3 */
+    nearest(meshId: u32, x: f32, y: f32, z: f32, ex: f32, ey: f32, ez: f32, include: u32, exclude: u32, out: Float32Array): boolean
+    /** Walkability ray along the surface; true = BLOCKED, out = [hit xyz, wall normal xyz].
+     *  @c cnavRay @pack fx 3 @pack tx 3 */
+    raycast(meshId: u32, fx: f32, fy: f32, fz: f32, tx: f32, ty: f32, tz: f32, include: u32, exclude: u32, out: Float32Array): boolean
+    /** `radius <= 0` = anywhere on the mesh; deterministic per seed. @c cnavRandom @pack cx 3 */
+    randomPoint(meshId: u32, cx: f32, cy: f32, cz: f32, radius: f32, seed: u32, include: u32, exclude: u32, out: Float32Array): boolean
+    /** The polygon mesh as a triangle soup (xyz per vertex) for debug drawing. @c cnavTriangles @out sized*3 */
+    debugTriangles(meshId: u32): Float32Array
+    /** @c cnavCrowdNew */
+    crowdCreate(meshId: u32, maxAgents: i32, maxRadius: f32): u32
+    /** @c cnavCrowdFree */
+    crowdDestroy(crowdId: u32): void
+    /** → the agent's slot (0..maxAgents-1), -1 when full / off the mesh. @c cnavAgentAdd @pack x 3 */
+    crowdAdd(crowdId: u32, x: f32, y: f32, z: f32, params: Float32Array): i32
+    /** @c cnavAgentRemove */
+    crowdRemove(crowdId: u32, agent: i32): void
+    /** @c cnavAgentSetParams */
+    crowdSetParams(crowdId: u32, agent: i32, params: Float32Array): void
+    /** @c cnavAgentSetTarget @pack x 3 */
+    crowdSetTarget(crowdId: u32, agent: i32, x: f32, y: f32, z: f32): boolean
+    /** @c cnavAgentSetVelocity @pack vx 3 */
+    crowdSetVelocity(crowdId: u32, agent: i32, vx: f32, vy: f32, vz: f32): void
+    /** @c cnavAgentResetTarget */
+    crowdResetTarget(crowdId: u32, agent: i32): void
+    /** @c cnavAgentWarp @pack x 3 */
+    crowdWarp(crowdId: u32, agent: i32, x: f32, y: f32, z: f32): boolean
+    /** Once per fixed step. @c cnavCrowdStep */
+    crowdUpdate(crowdId: u32, dt: f32): void
+    /** Every slot into `out` (CNAV_AGENT_READ_STRIDE floats each); returns maxAgents, 0 when `out` is short.
+     *  @c cnavCrowdReadAll */
+    crowdRead(crowdId: u32, out: Float32Array): i32
+  }
+}
+
+export {}

package/src/bridges/net.d.ts

@@ -0,0 +1,52 @@
+// The multiplayer bridge (`_creatorNet`): engines/net (yojimbo UDP transport).
+// Part of the host contract: every runtime implements this global (runtime/native in C++, the web
+// runtimes in TS). Types are the PRECISE ones the native side reads (see ./types.d.ts); the SDK
+// only sees numbers. The ABI checker (scripts/check-pkg-bridges.mjs) reads this folder.
+import type { f32, i32 } from "./types"
+
+// Object types of the contract (the generator's struct rule; `@c` names the engine's struct).
+/** What the exe was launched as (`--server --port N` / `--connect ADDR`). @c cnetLaunch */
+export type NetLaunch = { role: string, address: string, port: i32, maxClients: i32 }
+/** Link statistics of a server slot (server) / the link (client). @c cnetStats */
+export type NetStats = { rtt: f32, loss: f32, sentKbps: f32, receivedKbps: f32 }
+
+declare global {
+  // ---- multiplayer transport (creator-net / yojimbo) -------------------------------------------
+  // A byte pipe pumped on the JS thread (docs/multiplayer-plan.md). Present only on hosts built
+  // with CREATOR_PKG_NET (desktop, the 3d/full Android variants, iOS); the SDK feature-detects it.
+  // One endpoint per process (creator-net.h "endpoint"): `listen` (server / host) or `connect`
+  // (client), never both. Only `send` / `poll` are hand-written: they turn JS payloads into bytes
+  // (a tag byte says text or binary) and records into JS values.
+  /** @engine net */
+  var _creatorNet: {
+    /** What the exe was launched as, or null. @c cnetGetLaunch */
+    launch(): NetLaunch | null
+    /** Serve on every interface at `port` (wildcard public address). @c cnetListen */
+    listen(port: i32, maxClients: i32): boolean
+    /** Insecure (dev / LAN) connect to "ip:port"; the outcome arrives as a poll record. @c cnetConnect */
+    connect(address: string): boolean
+    /** @c cnetDisconnect */
+    disconnect(): void
+    /** @c cnetKick */
+    kick(client: i32): void
+    /** Queue a payload: channel 0 reliable-ordered, 1 unreliable; `client` ignored on a client.
+     *  A string travels as UTF-8 text and arrives as a string; bytes arrive as an ArrayBuffer. @custom */
+    send(client: i32, channel: i32, data: string | ArrayBuffer | Uint8Array): boolean
+    /** Pump once and return every record since the last call as a flat array of 4-tuples
+     *  [kind, client, arg, payload] — kind 1 connected · 2 disconnected · 3 message · 4 connectFailed;
+     *  arg = channel (message) or reason code; payload = string | ArrayBuffer | null. @custom */
+    poll(): any[] | null
+    /** 0 idle · 1 client · 2 server @c cnetMode */
+    mode(): i32
+    /** Client: 0 disconnected · 1 connecting · 2 connected · 3 failed. A listening server: 2. @c cnetState */
+    state(): i32
+    /** Statistics for a slot (server) / the link (client); null when that link is not connected. @c cnetStatsOf */
+    clientInfo(client: i32): NetStats | null
+    /** yojimbo network simulator on this side of the wire. @c cnetSimulate */
+    simulate(latencyMs: f32, jitterMs: f32, lossPercent: f32): void
+    /** @c cnetReasonString */
+    reasonString(reason: i32, serverSide: boolean): string
+  }
+}
+
+export {}

package/src/bridges/service.d.ts

@@ -0,0 +1,52 @@
+// The service bridge (`_creatorService`): headless `registerService` capabilities
+// (docs/service-channel-plan.md) — the UI-less sibling of the NativeView channel. The host registers
+// named service factories (`registerService("geolocation", factory)`) and the SDK talks to them
+// over the same call / event protocol as viewCall: values, not text (`value` of ./types).
+// Part of the host contract. A HOST bridge (`@host`, see ./app.d.ts): the native side is the
+// `HostService` table of runtime/native/include/creator-pkg/host.gen.h, generated from this file.
+// OPTIONAL AS A WHOLE (`@optional`): a host that did not opt in provides no table and the global is
+// absent — the SDK feature-detects with typeof. Sessions must open cheaply (no permission prompt, no
+// I/O) — prompts belong in the first call that needs them, so a rejected call is the failure
+// surface, never a hung open. The runtime tracks the sessions each world opened and closes them on
+// the world's teardown (`open` / `close` are `@custom` for that bookkeeping).
+import type { i32, value } from "./types"
+
+declare global {
+  /** @host service @optional */
+  var _creatorService: {
+    /** Did the host register a factory under `name`? Backs `Service.isSupported(name)`. */
+    supported(name: string): boolean
+    /** The contract version the half registered as `name` was generated from; 1 for a half written
+     *  by hand, 0 when there is none. On a host that does not say: 1 for a service it has. @custom */
+    version(name: string): i32
+    /** Open a session against the registered factory. `params` is a JSON string. Returns the
+     *  host-allocated session id, or -1 when no factory is registered under `name`. `onEvent`
+     *  delivers service events (the payload as a value, or omitted) until `close`. @custom */
+    open(name: string, params: string, onEvent: (event: string, data?: value) => void): i32
+    /** Invoke a method on a live session, exactly like viewCall: `args` is the array of the call's
+     *  arguments; a value that cannot cross throws here. The host settles exactly one of
+     *  `onComplete(result?)` / `onError(message)`. @custom */
+    call(serviceId: i32, method: string, args: value, onComplete: (result?: value) => void, onError: (err: string) => void): void
+    /** @custom */
+    close(serviceId: i32): void
+  }
+}
+
+/** The slots of `HostService` the runtime calls and JS never sees. */
+export interface HostService {
+  /** `_creatorService.open`: `onEvent` is a BORROWED heap handle (the socket `onMessage` model) —
+   *  deliver with `dispatchBorrowedCall(onEvent, [event, data?])`, `jsFree` it when the session
+   *  dies. Return -1 without taking the handle when `name` has no factory (the runtime frees it). */
+  open(name: string, params: string, onEvent: (event: string, data?: value) => void): i32
+  /** Destroy the session (the app's close AND the runtime's world-swap teardown). */
+  close(serviceId: i32): void
+  /** `_creatorService.version`: the contract version of the half registered as `name` (1 for one
+   *  written by hand, 0 for none). */
+  version?(name: string): i32
+  /** `_creatorService.call`: `args` is the array of the call's arguments, valid for the call. Settle
+   *  exactly one of the two callbacks through the dispatch bridge — `onComplete` with the result as
+   *  ONE value, or with none. */
+  call(serviceId: i32, method: string, args: value, onComplete: (result?: value) => void, onError: (err: string) => void): void
+}
+
+export {}

package/src/bridges/socket.d.ts

@@ -0,0 +1,31 @@
+// The socket bridge (`_creatorSocket`): the SDK `WebSocket` over the host's own client.
+// Part of the host contract. A HOST bridge (`@host`, see ./app.d.ts): the native side is the
+// `HostSocket` table of runtime/native/include/creator-pkg/host.gen.h, generated from this file.
+// The runtime tracks the sockets each world opened and closes them when the world is torn down
+// (`open` / `close` are `@custom` for that bookkeeping); the host owns the connection.
+import type { i32 } from "./types"
+
+declare global {
+  /** @host socket */
+  var _creatorSocket: {
+    /** Open a connection; returns the host's socket id (≥ 0 — failures arrive as an "error"
+     *  event). `onMessage(channel, data?)` is a long-lived listener the host keeps until the
+     *  connection dies: channels "open", "message" (data = the text), "close" (data = the code),
+     *  "error". @custom */
+    open(url: string, onMessage: (channel: string, data?: any) => void): i32
+    send(id: i32, message: string): void
+    /** @custom */
+    close(id: i32): void
+  }
+}
+
+/** The slots of `HostSocket` the runtime calls and JS never sees. */
+export interface HostSocket {
+  /** `_creatorSocket.open`: `onMessage` is a BORROWED heap handle — deliver events with
+   *  `dispatchBorrowedCall(onMessage, [channel, data?])` from any thread, and `jsFree` it exactly
+   *  once when the connection dies (either side). */
+  open(url: string, onMessage: (channel: string, data?: any) => void): i32
+  close(id: i32): void
+}
+
+export {}

package/src/bridges/storage.d.ts

@@ -0,0 +1,33 @@
+// The storage bridge (`_creatorStorage`): the SDK `localStorage` — a key/value map per storage
+// name, persisted by the host as one JSON document per name.
+// Part of the host contract. A HOST bridge (`@host`, see ./app.d.ts): the native side is the
+// `HostStorage` table of runtime/native/include/creator-pkg/host.gen.h, generated from this file.
+// The RUNTIME owns the in-memory map, its lazy load and the debounced whole-map save (every method
+// here is `@custom`); the host only loads and saves whole documents through the `HostStorage`
+// slots. Both slots are optional: a host without them (a headless render, CREATOR_HIDDEN) keeps the
+// map in memory only, and the global is present everywhere.
+
+declare global {
+  /** @host storage */
+  var _creatorStorage: {
+    /** @custom */
+    get(key: string): string | null
+    /** @custom */
+    set(key: string, value: string): void
+    /** @custom */
+    remove(key: string): void
+    /** Switch to another storage name (a launcher isolating the project it is about to run). The
+     *  map is dropped and lazily reloaded under the new name; "default" until called. @custom */
+    select?(name: string): void
+  }
+}
+
+/** The slots of `HostStorage` the runtime calls and JS never sees. */
+export interface HostStorage {
+  /** The JSON document saved under `name`, or null when there is none. */
+  load?(name: string): string | null
+  /** Persist the JSON document under `name` (the whole map; called once per tick at most). */
+  save?(name: string, json: string): void
+}
+
+export {}