@threenative/core 0.1.0

package/dist/audio-3vkjtiuo.d.ts

@@ -0,0 +1,35 @@
+import { AudioListener, Object3D, Audio, Vector3, PositionalAudio } from 'three';
+
+interface AudioBusOptions {
+    readonly camera: Object3D;
+    readonly gestureTarget?: EventTarget;
+    readonly listener?: AudioListener;
+    readonly source?: () => EventTarget | undefined;
+}
+interface AudioPlayOptions {
+    readonly fade?: number;
+    readonly loop?: boolean;
+    readonly volume?: number;
+}
+interface AudioRuntimeSnapshot {
+    readonly queued: number;
+    readonly voices: number;
+}
+declare class AudioBus {
+    #private;
+    readonly listener: AudioListener;
+    constructor(options: AudioBusOptions);
+    get queued(): number;
+    get voices(): number;
+    setCamera(camera: Object3D): void;
+    reparent(camera: Object3D): void;
+    unlock(): Promise<void>;
+    play(buffer: AudioBuffer, options?: AudioPlayOptions): Audio;
+    playAt(buffer: AudioBuffer, source: Object3D | Vector3, options?: AudioPlayOptions): PositionalAudio;
+    music(buffer: AudioBuffer, options?: AudioPlayOptions): Audio;
+    stop(): void;
+    dispose(): void;
+}
+declare function audioRuntimeSnapshot(): AudioRuntimeSnapshot;
+
+export { AudioBus as A, audioRuntimeSnapshot as a, type AudioBusOptions as b, type AudioPlayOptions as c };

package/dist/game-DRPs3M7r.d.ts

@@ -0,0 +1,269 @@
+import { Texture, Vector2, Object3D, Camera, Vector3, Scene as Scene$1 } from 'three';
+import { StoreApi } from 'zustand/vanilla';
+
+interface AssetLoaderOptions {
+    readonly basePath?: string;
+    readonly model?: (url: string) => Promise<unknown>;
+    readonly texture?: (url: string) => Promise<Texture>;
+    readonly audio?: (url: string) => Promise<AudioBuffer>;
+}
+interface AssetLoader {
+    model<T = unknown>(path: string): Promise<T>;
+    texture(path: string): Promise<Texture>;
+    audio(path: string): Promise<AudioBuffer>;
+    release(kind: "audio" | "model" | "texture", path: string): boolean;
+    clear(): void;
+}
+declare function createAssetLoader(options?: AssetLoaderOptions): AssetLoader;
+
+interface InputAction {
+    readonly buttons?: readonly number[];
+    readonly down?: readonly string[];
+    readonly left?: readonly string[];
+    readonly pointer?: boolean;
+    readonly right?: readonly string[];
+    readonly up?: readonly string[];
+}
+type InputBindings = Record<string, InputAction>;
+interface InputGamepad {
+    readonly axes: ArrayLike<number>;
+    readonly buttons: readonly {
+        readonly pressed: boolean;
+    }[];
+}
+type InputPlatformSource = () => readonly (InputGamepad | null)[];
+interface RawInputState {
+    readonly keys: ReadonlySet<string>;
+    readonly pointer: {
+        buttons: number;
+        down: boolean;
+        readonly position: Vector2;
+    };
+    readonly gamepad: {
+        axes: readonly number[];
+        buttons: readonly boolean[];
+    };
+}
+declare class InputMap {
+    #private;
+    readonly raw: RawInputState;
+    constructor(bindings?: InputBindings, target?: EventTarget, pointerTarget?: EventTarget, source?: InputPlatformSource);
+    vector(name: string): Vector2;
+    pressed(name: string): boolean;
+    justPressed(name: string): boolean;
+    justReleased(name: string): boolean;
+    tick(): void;
+    clear(): void;
+    dispose(): void;
+}
+declare function input(bindings?: InputBindings, target?: EventTarget, pointerTarget?: EventTarget, source?: InputPlatformSource): InputMap;
+
+interface Random {
+    (): number;
+    pick<T>(items: readonly T[]): T;
+    range(min: number, max: number): number;
+    state: number;
+}
+declare function createRandom(seed?: number): Random;
+
+type RendererKind = "webgpu" | "webgl2";
+interface RendererLike {
+    readonly domElement: HTMLCanvasElement;
+    readonly kind: RendererKind;
+    readonly raw: unknown;
+    compute(node: unknown): void;
+    render(scene: Object3D, camera: Camera): void;
+    setOutputNode(node: unknown): void;
+    setSize(width: number, height: number, updateStyle?: boolean): void;
+    dispose(): void;
+}
+interface RendererPlatformSource {
+    createCanvas(): HTMLCanvasElement;
+    hasWebGPU(): boolean;
+    observeResize(canvas: HTMLCanvasElement, resize: () => void): () => void;
+    readSize(canvas: HTMLCanvasElement): readonly [width: number, height: number];
+}
+interface RendererOptions {
+    canvas?: HTMLCanvasElement;
+    preferWebGPU?: boolean;
+    source?: RendererPlatformSource;
+    webgpuFactory?: (canvas: HTMLCanvasElement) => Promise<unknown> | unknown;
+    webgl2Factory?: (canvas: HTMLCanvasElement) => unknown;
+}
+declare function createRenderer(options?: RendererOptions): Promise<RendererLike>;
+
+type EntitySnapshot = Record<string, Record<string, unknown> & {
+    tags?: string[];
+}>;
+interface Debuggable {
+    debug(): Record<string, unknown>;
+}
+declare function autoFields(entity: object): Record<string, unknown>;
+declare class Registry {
+    #private;
+    add<T extends object>(name: string, entity: T): T;
+    get<T extends object = object>(name: string): T | undefined;
+    remove(name: string): void;
+    clear(): void;
+    snapshot(): EntitySnapshot;
+}
+
+type ScheduleHandle = (() => void) & {
+    cancel(): void;
+    readonly active: boolean;
+};
+type TweenProperties<T extends object> = {
+    [K in keyof T]?: number;
+};
+declare class Scheduler {
+    #private;
+    get size(): number;
+    after(delay: number, callback: () => void): ScheduleHandle;
+    every(callback: (dt: number) => void): ScheduleHandle;
+    tween<T extends object>(target: T, properties: TweenProperties<T>, duration: number): Promise<void>;
+    tick(dt: number): void;
+    clear(): void;
+}
+
+type StatePatch<T extends Record<string, unknown>> = Partial<T> | ((state: T) => Partial<T>);
+type GameStore<T extends Record<string, unknown>> = StoreApi<T> & {
+    set(patch: StatePatch<T>): void;
+    flush(): void;
+    start(): void;
+    stop(): void;
+};
+declare function createGameStore<T extends Record<string, unknown>>(initial: T, intervalMs?: number): GameStore<T>;
+
+interface ViewportSize {
+    readonly aspect: number;
+    readonly height: number;
+    readonly width: number;
+}
+interface ViewportOptions {
+    readonly camera: Camera;
+    readonly renderer: RendererLike;
+    readonly source?: ViewportPlatformSource;
+}
+type ViewportResizeHandler = (size: ViewportSize) => void;
+interface ViewportPlatformSource {
+    observeResize(canvas: HTMLCanvasElement, resize: () => void): () => void;
+    readSize(canvas: HTMLCanvasElement): ViewportSize;
+}
+declare class Viewport {
+    #private;
+    readonly camera: Camera;
+    readonly renderer: RendererLike;
+    constructor(options: ViewportOptions);
+    get size(): ViewportSize;
+    projectPosition(screen: Vector2, z?: number): Vector3;
+    unprojectPosition(world: Vector3): Vector2;
+    onResize(handler: ViewportResizeHandler): () => void;
+    resize(): void;
+    dispose(): void;
+}
+
+declare abstract class Scene<TState extends Record<string, unknown> = Record<string, unknown>, TPhysics = undefined> {
+    static readonly initialState: Record<string, unknown> | undefined;
+    load(_ctx: Ctx<TState, TPhysics>): void | Promise<void>;
+    enter(_ctx: Ctx<TState, TPhysics>): SceneEnterResult<TState, TPhysics>;
+    exit(_ctx: Ctx<TState, TPhysics>): void;
+    update(_ctx: Ctx<TState, TPhysics>, _dt: number): void;
+    render(_ctx: Ctx<TState, TPhysics>): void;
+}
+type SceneConstructor<TState extends Record<string, unknown> = Record<string, unknown>, TPhysics = undefined> = new () => Scene<TState, TPhysics>;
+type SceneFrame<TState extends Record<string, unknown> = Record<string, unknown>, TPhysics = undefined> = (ctx: Ctx<TState, TPhysics>, dt: number) => void;
+type SceneEnterResult<TState extends Record<string, unknown> = Record<string, unknown>, TPhysics = undefined> = // biome-ignore lint/suspicious/noConfusingVoidType: void preserves existing Scene.enter overrides.
+void | SceneFrame<TState, TPhysics>;
+interface Ctx<TState extends Record<string, unknown> = Record<string, unknown>, TPhysics = undefined> {
+    readonly fps: number;
+    readonly renderer: RendererLike;
+    readonly viewport: Viewport;
+    readonly scene: Scene$1;
+    readonly camera: Camera;
+    readonly entities: Registry;
+    readonly add: (object: Object3D) => Object3D;
+    readonly input: InputMap;
+    readonly assets: AssetLoader;
+    readonly after: (delay: number, callback: () => void) => ScheduleHandle;
+    readonly every: (callback: (dt: number) => void) => ScheduleHandle;
+    readonly state: GameStore<TState>;
+    readonly tween: <T extends object>(target: T, properties: {
+        [K in keyof T]?: number;
+    }, duration: number) => Promise<void>;
+    readonly random: Random;
+    readonly goto: (name: string) => Promise<void>;
+    physics: TPhysics;
+}
+
+type PluginCleanup = () => void;
+interface GamePluginRuntime {
+    fixedStep(ticks: number): number;
+    readonly random?: Pick<Random, "state">;
+    rapier?: string | null;
+    readonly seed: number | null;
+    readonly step: number;
+}
+interface GamePlatformSource {
+    readonly devToolsHost?: Record<string, unknown>;
+    readonly input: NonNullable<ConstructorParameters<typeof InputMap>[3]>;
+    readonly inputTarget?: EventTarget;
+    readonly renderer: NonNullable<RendererOptions["source"]>;
+    readonly viewport: NonNullable<ViewportOptions["source"]>;
+    mountCanvas(canvas: HTMLCanvasElement, container?: HTMLElement): void;
+    unmountCanvas(canvas: HTMLCanvasElement): void;
+}
+type GamePluginFunction<TState extends Record<string, unknown> = Record<string, unknown>, TPhysics = undefined> = (ctx: Ctx<TState, TPhysics>) => undefined | PluginCleanup;
+interface GamePluginHooks<TState extends Record<string, unknown> = Record<string, unknown>, TPhysics = undefined> {
+    setup?(ctx: Ctx<TState, TPhysics>, runtime?: GamePluginRuntime): undefined | PluginCleanup | Promise<undefined | PluginCleanup>;
+    beforeUpdate?(ctx: Ctx<TState, TPhysics>, dt: number): void;
+    update?(ctx: Ctx<TState, TPhysics>, dt: number): void;
+    sceneExit?(ctx: Ctx<TState, TPhysics>): void;
+    dispose?(ctx: Ctx<TState, TPhysics>): void;
+}
+type GamePlugin<TState extends Record<string, unknown> = Record<string, unknown>, TPhysics = undefined> = GamePluginFunction<TState, TPhysics> | GamePluginHooks<TState, TPhysics>;
+interface GameConfig<TState extends Record<string, unknown> = Record<string, unknown>, TPhysics = undefined> {
+    readonly assets?: AssetLoaderOptions;
+    readonly camera?: CameraConfig;
+    readonly canvas?: HTMLCanvasElement;
+    readonly container?: HTMLElement;
+    readonly input?: InputBindings;
+    readonly initialState?: TState;
+    readonly inputTarget?: EventTarget;
+    readonly maxSteps?: number;
+    readonly platform?: GamePlatformSource;
+    readonly plugins?: readonly GamePlugin<TState, TPhysics>[];
+    readonly render?: Pick<RendererOptions, "preferWebGPU">;
+    readonly renderer?: RendererOptions;
+    readonly seed?: number;
+    readonly scenes: Record<string, SceneConstructor<TState, TPhysics>>;
+    readonly step?: number;
+    readonly start: string;
+    readonly stateFlushMs?: number;
+}
+interface PerspectiveCameraConfig {
+    readonly projection: "perspective";
+    readonly fov?: number;
+    readonly near?: number;
+    readonly far?: number;
+}
+interface OrthogonalCameraConfig {
+    readonly projection: "orthogonal";
+    readonly size: number;
+    readonly near?: number;
+    readonly far?: number;
+}
+type CameraConfig = PerspectiveCameraConfig | OrthogonalCameraConfig;
+interface Game<TState extends Record<string, unknown> = Record<string, unknown>, TPhysics = undefined> {
+    readonly ctx: Ctx<TState, TPhysics> | undefined;
+    readonly scene: Scene<TState, TPhysics> | undefined;
+    readonly state: GameStore<TState>;
+    /** Rebuilds the requested scene from the game's declared initial state. */
+    goto(name: string): Promise<void>;
+    start(): Promise<void>;
+    pause(): void;
+    resume(): void;
+    stop(): void;
+}
+declare function defineGame<TState extends Record<string, unknown>, TPhysics = undefined>(config: GameConfig<TState, TPhysics>): Game<TState, TPhysics>;
+
+export { type AssetLoader as A, autoFields as B, type CameraConfig as C, type Debuggable as D, type EntitySnapshot as E, createAssetLoader as F, type Game as G, createGameStore as H, type InputAction as I, createRandom as J, createRenderer as K, defineGame as L, input as M, type OrthogonalCameraConfig as O, type PerspectiveCameraConfig as P, type RendererLike as R, Scene as S, Viewport as V, type GamePluginRuntime as a, type GamePluginHooks as b, type AssetLoaderOptions as c, type Ctx as d, type GameConfig as e, type GamePlatformSource as f, type GamePlugin as g, type GamePluginFunction as h, type GameStore as i, type InputBindings as j, InputMap as k, type PluginCleanup as l, type Random as m, type RawInputState as n, Registry as o, type RendererKind as p, type RendererOptions as q, type SceneConstructor as r, type SceneEnterResult as s, type SceneFrame as t, type ScheduleHandle as u, Scheduler as v, type StatePatch as w, type ViewportOptions as x, type ViewportResizeHandler as y, type ViewportSize as z };

package/dist/hot.d.ts

@@ -0,0 +1,17 @@
+import { a as audioRuntimeSnapshot } from './audio-3vkjtiuo.js';
+import { G as Game } from './game-DRPs3M7r.js';
+import 'three';
+import 'zustand/vanilla';
+
+interface HotDiagnostics {
+    readonly reloads: number;
+    readonly entities: number;
+    readonly sceneObjects: number;
+    readonly canvases: number;
+    readonly audio: ReturnType<typeof audioRuntimeSnapshot>;
+    readonly physics: number | null;
+}
+declare function assertPortableState(state: unknown): void;
+declare function acceptHotUpdate<TState extends Record<string, unknown>, TPhysics>(game: Game<TState, TPhysics>, hot: ImportMeta["hot"]): void;
+
+export { type HotDiagnostics, acceptHotUpdate, assertPortableState };

package/dist/hot.js

@@ -0,0 +1,109 @@
+import 'three';
+
+// src/audio.ts
+var buses = /* @__PURE__ */ new Set();
+function audioRuntimeSnapshot() {
+  let queued = 0;
+  let voices = 0;
+  for (const bus of buses) {
+    queued += bus.queued;
+    voices += bus.voices;
+  }
+  return { queued, voices };
+}
+
+// src/hot.ts
+var isDev = import.meta.env?.DEV === true;
+function assertPortableState(state) {
+  visitPortable(state, "state", /* @__PURE__ */ new Set());
+}
+function acceptHotUpdate(game, hot) {
+  if (hot === void 0) return;
+  hot.accept();
+  const carried = hot.data.threenative;
+  const reloads = carried?.reloads ?? 0;
+  if (carried !== void 0) restoreState(game, carried.state);
+  if (isDev && typeof window !== "undefined") {
+    const host = window;
+    host.__THREENATIVE__ = {
+      ...host.__THREENATIVE__,
+      hot: () => diagnostics(game, reloads),
+      snapshot: host.__THREENATIVE__?.snapshot ?? (() => ({}))
+    };
+  }
+  let disposed = false;
+  hot.dispose((data) => {
+    if (disposed) return;
+    disposed = true;
+    try {
+      game.state.flush();
+      const state = game.state.getState();
+      assertPortableState(state);
+      data.threenative = { reloads: reloads + 1, state };
+    } catch (error) {
+      data.threenative = void 0;
+      hot.invalidate(error instanceof Error ? error.message : String(error));
+      throw error;
+    } finally {
+      game.stop();
+    }
+  });
+}
+function restoreState(game, carried) {
+  assertPortableState(carried);
+  const defaults = game.state.getState();
+  const state = { ...defaults };
+  const dropped = Object.keys(carried).filter((key) => !(key in defaults));
+  const added = Object.keys(defaults).filter((key) => !(key in carried));
+  for (const key of Object.keys(defaults)) {
+    if (key in carried) state[key] = carried[key];
+  }
+  game.state.setState(state);
+  if (dropped.length > 0 || added.length > 0)
+    console.info(
+      `ThreeNative hot reload state shape: dropped [${dropped.join(", ")}]; added [${added.join(", ")}]`
+    );
+}
+function diagnostics(game, reloads) {
+  const ctx = game.ctx;
+  let sceneObjects = 0;
+  ctx?.scene.traverse(() => {
+    sceneObjects += 1;
+  });
+  const physics = ctx?.physics;
+  return {
+    reloads,
+    entities: ctx === void 0 ? 0 : Object.keys(ctx.entities.snapshot()).length,
+    sceneObjects,
+    canvases: typeof document === "undefined" ? 0 : document.querySelectorAll("canvas").length,
+    audio: audioRuntimeSnapshot(),
+    physics: typeof physics?.numBodies === "function" ? physics.numBodies() : null
+  };
+}
+function visitPortable(value, path, ancestors) {
+  if (value === null) return;
+  if (typeof value === "string" || typeof value === "boolean") return;
+  if (typeof value !== "object") {
+    if (typeof value === "number" && Number.isFinite(value)) return;
+    if (typeof value === "number")
+      throw new Error(`Hot reload state ${path} must contain only finite numbers.`);
+    throw new Error(`Hot reload state ${path} must contain only JSON-shaped values.`);
+  }
+  if (ancestors.has(value)) throw new Error(`Hot reload state ${path} contains a cycle.`);
+  if (Array.isArray(value)) {
+    ancestors.add(value);
+    for (let index = 0; index < value.length; index += 1)
+      visitPortable(value[index], `${path}[${index}]`, ancestors);
+    ancestors.delete(value);
+    return;
+  }
+  const prototype = Object.getPrototypeOf(value);
+  if (prototype !== Object.prototype && prototype !== null)
+    throw new Error(`Hot reload state ${path} must contain only plain objects.`);
+  ancestors.add(value);
+  for (const key of Object.keys(value))
+    visitPortable(value[key], `${path}.${key}`, ancestors);
+  ancestors.delete(value);
+}
+
+export { acceptHotUpdate, assertPortableState };

package/dist/index.d.ts

@@ -0,0 +1,85 @@
+export { A as AudioBus, b as AudioBusOptions, c as AudioPlayOptions } from './audio-3vkjtiuo.js';
+import { R as RendererLike, a as GamePluginRuntime, b as GamePluginHooks } from './game-DRPs3M7r.js';
+export { A as AssetLoader, c as AssetLoaderOptions, C as CameraConfig, d as Ctx, D as Debuggable, E as EntitySnapshot, G as Game, e as GameConfig, f as GamePlatformSource, g as GamePlugin, h as GamePluginFunction, i as GameStore, I as InputAction, j as InputBindings, k as InputMap, O as OrthogonalCameraConfig, P as PerspectiveCameraConfig, l as PluginCleanup, m as Random, n as RawInputState, o as Registry, p as RendererKind, q as RendererOptions, S as Scene, r as SceneConstructor, s as SceneEnterResult, t as SceneFrame, u as ScheduleHandle, v as Scheduler, w as StatePatch, V as Viewport, x as ViewportOptions, y as ViewportResizeHandler, z as ViewportSize, B as autoFields, F as createAssetLoader, H as createGameStore, J as createRandom, K as createRenderer, L as defineGame, M as input } from './game-DRPs3M7r.js';
+import { AnimationMixer, AnimationClip, Object3D, Sprite } from 'three';
+import { StorageBufferNode, SpriteNodeMaterial, ComputeNode } from 'three/webgpu';
+import { IReplayRecording } from '@threenative/playtest';
+import 'zustand/vanilla';
+
+interface AnimationPlayerOptions {
+    readonly clips: readonly AnimationClip[];
+    readonly root: Object3D;
+}
+interface AnimationPlayOptions {
+    readonly fade?: number;
+}
+declare class AnimationPlayer {
+    #private;
+    readonly mixer: AnimationMixer;
+    constructor(options: AnimationPlayerOptions);
+    get current(): string | undefined;
+    get advancedFrames(): number;
+    play(name: string, options?: AnimationPlayOptions): void;
+    update(dt: number): void;
+    stop(): void;
+    dispose(): void;
+}
+
+interface FixedStepLoopOptions {
+    readonly step?: number;
+    readonly maxSteps?: number;
+    readonly onUpdate: (dt: number) => void;
+    readonly onRender?: () => void;
+    readonly requestFrame?: (callback: (time: number) => void) => number;
+    readonly cancelFrame?: (handle: number) => void;
+}
+declare class FixedStepLoop {
+    #private;
+    readonly step: number;
+    readonly maxSteps: number;
+    constructor(options: FixedStepLoopOptions);
+    get running(): boolean;
+    get fps(): number;
+    start(now?: number): void;
+    stop(): void;
+    stepFrame(now: number): number;
+    advance(ticks: number): number;
+}
+
+interface GPUParticles3DBuffers {
+    readonly positions: StorageBufferNode<"vec3">;
+    readonly velocities: StorageBufferNode<"vec3">;
+}
+interface GPUParticles3DOptions {
+    readonly amount: number;
+    readonly material: SpriteNodeMaterial;
+    readonly start: (buffers: GPUParticles3DBuffers) => ComputeNode;
+    readonly process: (buffers: GPUParticles3DBuffers) => ComputeNode;
+}
+declare class GPUParticles3D extends Sprite {
+    #private;
+    readonly amount: number;
+    readonly buffers: GPUParticles3DBuffers;
+    emitting: boolean;
+    constructor(options: GPUParticles3DOptions);
+    get released(): boolean;
+    attachRenderer(renderer: RendererLike): void;
+    process(renderer?: RendererLike | undefined): void;
+    restart(): void;
+    detach(): void;
+}
+
+type Recording = IReplayRecording;
+type ReplayPublic = {
+    readonly recording: Recording | undefined;
+    readonly runId: symbol;
+};
+declare function replay<TState extends Record<string, unknown> = Record<string, unknown>, TPhysics = undefined>(): GamePluginHooks<TState, TPhysics> & ReplayPublic;
+declare function createReplayDriver(recording: Recording, target: EventTarget, pointerTarget?: EventTarget): ((runtime: GamePluginRuntime) => number) & {
+    prepare: (runtime: GamePluginRuntime) => void;
+    runId: symbol;
+};
+
+declare const version = "0.1.0";
+
+export { type AnimationPlayOptions, AnimationPlayer, type AnimationPlayerOptions, FixedStepLoop, type FixedStepLoopOptions, GPUParticles3D, type GPUParticles3DBuffers, type GPUParticles3DOptions, GamePluginHooks, GamePluginRuntime, type Recording, RendererLike, createReplayDriver, replay, version };