@threenative/core 0.3.0 → 0.3.2

package/dist/assets-kyoF7JlJ.d.ts

@@ -0,0 +1,103 @@
+import { Texture, Object3D, AnimationClip } from 'three';
+
+interface IAssetLoaderOptions {
+    readonly basePath?: string;
+    /**
+     * URL of the manifest written by the asset compile step (`public/assets.manifest.json`).
+     * Defaults to `assets.manifest.json` resolved against `basePath`. A logical path is resolved
+     * to its compiled output through it; a manifest that is absent — 404 or unfetchable — falls
+     * back to loading every path verbatim, while one that is served malformed or with an unknown
+     * version throws.
+     */
+    readonly manifest?: string;
+    /**
+     * Directory the game's uncompiled assets live in, relative to `basePath`.
+     *
+     * Only consulted when there is no manifest, and only after the verbatim path has been tried. It
+     * is what makes the delete-test possible: remove everything the asset pipeline produced and the
+     * game still finds `assets/rock.png` where the author put it, just slower and uncompressed.
+     * Defaults to the compile step's own default source directory.
+     */
+    readonly sourcePath?: string;
+    readonly model?: (url: string) => Promise<unknown>;
+    readonly texture?: (url: string) => Promise<Texture>;
+    readonly audio?: (url: string) => Promise<AudioBuffer>;
+    /**
+     * The live renderer (`IRendererLike.raw`), handed to `KTX2Loader.detectSupport()` exactly
+     * once so compiled KTX2 textures transcode to a format this machine's GPU actually supports.
+     * Required for games whose textures compile to `.ktx2`; without it such a load throws rather
+     * than silently uploading decoded RGBA.
+     */
+    readonly renderer?: unknown;
+}
+/** The structural slice of three's `KTX2Loader` core depends on. */
+interface IKTX2LoaderLike {
+    detectSupport(renderer: unknown): unknown;
+    load(url: string, onLoad: (texture: Texture) => void, onProgress?: (event: ProgressEvent<EventTarget>) => void, onError?: (error: unknown) => void): unknown;
+    setTranscoderPath(path: string): unknown;
+}
+/**
+ * Present only when a renderer was handed to the asset loader. `ready` settles once support
+ * detection ran; it rejects naming the renderer and platform when no compressed format is
+ * supported, and `defineGame` awaits it during boot so such a target fails at construction.
+ */
+interface ICompressedTextureSupport {
+    /**
+     * The one shared instance, also handed to `GLTFLoader.setKTX2Loader()` for models. Resolves
+     * `undefined` when the renderer exposed no surface to probe (see `createKtx2Loader`).
+     */
+    readonly loader: Promise<IKTX2LoaderLike | undefined>;
+    readonly ready: Promise<void>;
+}
+interface IAssetLoader {
+    readonly compressedTextures?: ICompressedTextureSupport;
+    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;
+    /**
+     * Where a logical path is served from, in the order worth trying — the manifest's
+     * content-addressed output when a manifest exists, otherwise the verbatim and source paths.
+     * For loaders this surface does not wrap (an HDR sky, a font, a data file) — a game must never
+     * hard-code a hashed output name, which changes on every rebuild.
+     */
+    resolve(path: string): Promise<readonly string[]>;
+    /**
+     * How many loads this loader has been asked for and how many have settled (resolved or
+     * rejected). A loading view reads the ratio; the runtime folds it into `ctx.startup.progress`
+     * while the start scene loads, so the bar moves with the bytes instead of jumping 0 to 1.
+     *
+     * `requestedBytes` and `settledBytes` are the same ledger weighed by the `bytes` the compile
+     * step already records for every manifest entry, and they are what a loading bar should read.
+     * A file count treats a 710 MB model and a 4 KB icon alike: one real game's bar reached 92%
+     * on eleven small assets and then stood still for the entire download of the twelfth. Both
+     * stay 0 for a game with no manifest, where no size is knowable before the bytes arrive.
+     */
+    readonly progress: {
+        readonly requested: number;
+        readonly requestedBytes: number;
+        readonly settled: number;
+        readonly settledBytes: number;
+    };
+    clear(): void;
+}
+/**
+ * Repair an exported rig whose clips are Z-mirrored against its own bind pose, in place.
+ *
+ * The signature (PRD-324, the whole Wildwood animal pack): the file's bind faces its own +Z, but
+ * every animation track is expressed in a Z-mirrored frame — position tracks hold `(x, y, −z)`
+ * where the bind holds `(x, y, z)`, and quaternion tracks hold `(−x, −y, z, w)`, the conjugation
+ * of the same mirror. Played as authored, every animal faces backwards with its spine folded:
+ * head behind pelvis, healthy bone lengths, zero errors anywhere.
+ *
+ * An exporter writes exactly this when it converts a rig's bind to one convention and forgets its
+ * animation tracks. The loader repairs it before the game ever sees it: detection votes per
+ * tracked bone on whether the clip's translation Z sits negated against the bind, and only an
+ * overwhelming vote (at least `MIRROR_VOTE_MINIMUM` bones, `MIRROR_VOTE_SHARE` of them) converts
+ * every track — positions negate Z, quaternions negate X and Y, once, across all clips. A file
+ * that does not carry the signature is left byte-identical.
+ */
+declare function reconcileMirroredClips(root: Object3D, clips: readonly AnimationClip[]): boolean;
+declare function createAssetLoader(options?: IAssetLoaderOptions): IAssetLoader;
+
+export { type IAssetLoader as I, type IAssetLoaderOptions as a, createAssetLoader as c, reconcileMirroredClips as r };

package/dist/{audio-Dp2mXpD3.d.ts → audio-BFiGneTL.d.ts}

@@ -53,6 +53,19 @@ interface IAudioRuntimeSnapshot {
     readonly voices: number;
     /** Retired voices held for reuse. Bounded by peak concurrency, never by session length. */
     readonly pooled: number;
+    /**
+     * Voices stopped mid-cue by `pause` and holding their position. Nonzero here while a game
+     * claims to be running is a menu that muted the world and forgot to give it back.
+     */
+    readonly paused: number;
+    /**
+     * Cue-shaping options this runtime accepted and could not honour, sorted and de-duplicated.
+     *
+     * The native host binds neither a biquad filter nor a schedulable `detune`, so `lowpassHz` and
+     * `detune` are silently dropped there. A mix tuned on the web and shipped to a phone is flat in
+     * a way nothing else reports, and a build can be failed on this.
+     */
+    readonly unsupported: readonly string[];
 }
 declare class AudioBus {
     #private;
@@ -65,6 +78,41 @@ declare class AudioBus {
      * now bounded by how many cues have ever sounded at once, so a gate can pin it.
      */
     get pooled(): number;
+    /** Voices holding their position across a `pause`. */
+    get pausedVoices(): number;
+    /** True between `pause` and `resume`. */
+    get paused(): boolean;
+    /** The master volume last asked for — the target, not a point some ramp is passing through. */
+    get volume(): number;
+    /** @see IAudioRuntimeSnapshot.unsupported */
+    get unsupported(): readonly string[];
+    /**
+     * The whole bus's level, which is what a volume slider and a duck both move.
+     *
+     * One bus per category — ambience, effects, music — makes this the mixer: ducking the wood
+     * under a discovery cue is `ambience.setVolume(0.35, 0.4)` and `setVolume(1, 0.8)` after. It
+     * rides the listener's gain, so it costs nothing per voice and applies to cues already sounding.
+     *
+     * A bus constructed with a shared `listener` shares that listener's master with every other bus
+     * on it; give each category its own bus (the default) to mix them apart.
+     *
+     * @param volume Linear gain, 0 or greater.
+     * @param fade Seconds to reach it. Defaults to a 15 ms settle, which is a level change rather
+     * than a fade — the shortest move that does not click.
+     */
+    setVolume(volume: number, fade?: number): void;
+    /**
+     * Stop every sounding voice where it stands and hold its position.
+     *
+     * The difference from `stop` is what happens next: a paused bed resumes mid-bar, a stopped one
+     * starts over. Cues asked for while paused stay queued and sound on `resume`, so a menu opened
+     * during a burst does not fire the backlog at the player when they close it.
+     *
+     * The audio context keeps running — suspending it would silence every other bus sharing it.
+     */
+    pause(): void;
+    /** Sound the held voices again from where they stopped, then release anything queued. */
+    resume(): void;
     setCamera(camera: Object3D): void;
     reparent(camera: Object3D): void;
     unlock(): Promise<void>;
@@ -86,6 +134,20 @@ declare class AudioBus {
      */
     playAt(buffer: AudioBuffer, source: Object3D | Vector3, options?: IAudioPlayOptions): PositionalAudio;
     music(buffer: AudioBuffer, options?: IAudioPlayOptions): Audio;
+    /**
+     * Stop one voice and give it back to the pool.
+     *
+     * The missing primitive: `stop()` silenced every voice or none, and stopping the handle
+     * directly does not work — three's `Audio.stop()` detaches `onended` before stopping the node,
+     * so the bus's reclaim hook never fires and the voice leaks out of the pool while staying in
+     * the scene. A game that wants one entity's loop to end needs exactly this, and `playAt` with
+     * `loop` is the obvious way to reach for it.
+     *
+     * Returns false for a voice this bus is not sounding — a stale handle from a voice already
+     * recycled, or one belonging to another bus. Reported rather than thrown: a caller stopping a
+     * sound that already ended has made no mistake.
+     */
+    stopVoice(voice: Audio<AudioNode>): boolean;
     stop(): void;
     dispose(): void;
 }

package/dist/canvas-layer-BLVijiUJ.d.ts

@@ -0,0 +1,62 @@
+import * as three from 'three';
+import { Camera, Vector2, Vector3, Scene, OrthographicCamera } from 'three';
+import { I as IRendererLike } from './renderer-C6hqZpoG.js';
+
+interface IViewportSize {
+    readonly aspect: number;
+    readonly height: number;
+    readonly width: number;
+}
+interface IViewportInsets {
+    readonly bottom: number;
+    readonly left: number;
+    readonly right: number;
+    readonly top: number;
+}
+interface IViewportSafeArea extends IViewportInsets {
+    /** The safe rectangle in drawable pixel coordinates, with y measured from the top edge. */
+    readonly height: number;
+    readonly source: "full-drawable-fallback" | "measured";
+    readonly width: number;
+    readonly x: number;
+    readonly y: number;
+}
+interface IViewportOptions {
+    readonly camera: Camera;
+    readonly renderer: IRendererLike;
+    readonly source?: IViewportPlatformSource;
+}
+type ViewportResizeHandler = (size: IViewportSize) => void;
+interface IViewportPlatformSource {
+    observeResize(canvas: HTMLCanvasElement, resize: () => void): () => void;
+    readSize(canvas: HTMLCanvasElement): IViewportSize;
+    readSafeArea?(canvas: HTMLCanvasElement, size: IViewportSize): IViewportInsets | undefined;
+}
+declare class Viewport {
+    #private;
+    readonly camera: Camera;
+    readonly renderer: IRendererLike;
+    constructor(options: IViewportOptions);
+    get size(): IViewportSize;
+    get safeArea(): IViewportSafeArea;
+    projectPosition(screen: Vector2, z?: number, target?: Vector3): Vector3;
+    unprojectPosition(world: Vector3, target?: Vector2): Vector2;
+    onResize(handler: ViewportResizeHandler): () => void;
+    resize(): void;
+    dispose(): void;
+}
+
+/** A Godot-shaped render surface that is independent of the world camera and post pipeline. */
+declare class CanvasLayer {
+    #private;
+    readonly scene: Scene<three.Object3DEventMap>;
+    readonly camera: OrthographicCamera;
+    /** Declares that this layer covers the framebuffer, allowing the world pass to be skipped. */
+    opaque: boolean;
+    constructor(viewport: Pick<Viewport, "onResize" | "size">);
+    dispose(): void;
+    /** Subscribe to drawable-size changes after this layer has updated its camera. */
+    onResize(handler: (size: IViewportSize) => void): () => void;
+}
+
+export { CanvasLayer as C, type IViewportOptions as I, Viewport as V };