@threenative/core 0.2.0 → 0.3.1

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-BFiGneTL.d.ts

@@ -0,0 +1,156 @@
+import { AudioListener, Object3D, Audio, Vector3, PositionalAudio } from 'three';
+
+interface IAudioBusOptions {
+    readonly camera: Object3D;
+    readonly gestureTarget?: EventTarget;
+    readonly listener?: AudioListener;
+    readonly source?: () => EventTarget | undefined;
+    /**
+     * Ceiling on simultaneously sounding one-shots. Past it the oldest voice is stopped and its
+     * slot reused: a firefight generates far more cues than a listener can resolve, and the newest
+     * event is always the one they need to hear. Looping voices from `music` are exempt.
+     * Defaults to 48.
+     */
+    readonly maxVoices?: number;
+}
+interface IAudioPlayOptions {
+    readonly fade?: number;
+    readonly loop?: boolean;
+    readonly volume?: number;
+    /**
+     * Metres from the source where positional attenuation begins; `playAt` only. Three's panner
+     * default of 1 m makes a shot 20 m away all but inaudible — raise this to keep mid-distance
+     * sounds loud. Must be finite and positive.
+     */
+    readonly refDistance?: number;
+    /**
+     * How fast volume falls off past `refDistance`; `playAt` only. 0 keeps the sound at full
+     * volume at any distance. Must be finite and non-negative.
+     */
+    readonly rolloffFactor?: number;
+    /**
+     * Pitch offset in cents; ±100 is a semitone. Applied before the first sample rather than
+     * through three's `setDetune`, which ramps over ~30 ms and turns a percussive attack into an
+     * audible sweep. A few dozen cents of per-shot spread is what stops a repeated sample
+     * comb-filtering with its own copies into a metallic buzz.
+     */
+    readonly detune?: number;
+    /**
+     * Seconds of the buffer to pass before an exponential cut-off. A 1.4 s gunshot fired ten times
+     * a second stacks fourteen overlapping tails into mush; truncating all but the last keeps the
+     * transient and drops the wash. Must be finite and positive.
+     */
+    readonly cutoffSeconds?: number;
+    /**
+     * Low-pass corner in Hz. Air and geometry eat the top of a sound as it crosses a space, and a
+     * sample played flat at every range is the loudest tell that a game's audio is not in a place.
+     * Must be finite and positive.
+     */
+    readonly lowpassHz?: number;
+}
+interface IAudioRuntimeSnapshot {
+    readonly queued: number;
+    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;
+    readonly listener: AudioListener;
+    constructor(options: IAudioBusOptions);
+    get queued(): number;
+    get voices(): number;
+    /**
+     * Retired voices held for reuse. This is the number that used to climb without limit: it is
+     * 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>;
+    /**
+     * A cue with no place: the listener's own weapon, UI, narration.
+     *
+     * The returned voice is valid for as long as it is sounding. Once it ends the bus reclaims it
+     * and may hand the same object to a later cue, so a caller holding the reference past that
+     * point is addressing somebody else's sound. Read `isPlaying` before touching a voice you kept.
+     */
+    play(buffer: AudioBuffer, options?: IAudioPlayOptions): Audio;
+    /**
+     * A cue somewhere in the world, at a fixed point or riding a moving object.
+     *
+     * A `Vector3` source is read in the coordinate space of the camera's parent, which is the
+     * scene in the ordinary case. Pass an `Object3D` to weld the cue to something that moves.
+     *
+     * The same reclaim rule as `play` applies to the returned voice.
+     */
+    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;
+}
+declare function audioRuntimeSnapshot(): IAudioRuntimeSnapshot;
+
+export { AudioBus as A, type IAudioBusOptions as I, audioRuntimeSnapshot as a, type IAudioPlayOptions as b };

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 };