@threenative/core 0.3.0 → 0.3.2

package/dist/world.d.ts

@@ -1,4 +1,175 @@
-import { Vector3, BufferGeometry } from 'three';
+import { Object3D, Mesh, LOD, Vector3, Group, BufferGeometry } from 'three';
+import { I as IComputeDriven, a as IGPUReadbackSample } from './gpu-readback-D2iRvoe9.js';
+import { I as IRendererLike } from './renderer-C6hqZpoG.js';
+import { I as IAssetLoader } from './assets-kyoF7JlJ.js';
+import 'three/webgpu';
+
+interface IWorldErosionOptions {
+    readonly depositionRate: number;
+    readonly erosionRate: number;
+    readonly evaporation: number;
+    readonly iterations: number;
+    readonly rainfall: number;
+    readonly sedimentCapacity: number;
+    readonly timeStep: number;
+}
+
+type MeshSurface = NonNullable<ConstructorParameters<typeof Mesh>[1]>;
+interface IWorldTileCollider {
+    dispose(): void;
+}
+interface IWorldTileColliderInput {
+    readonly field: Heightfield;
+    readonly key: string;
+    readonly object: Object3D;
+    readonly tileX: number;
+    readonly tileZ: number;
+}
+interface IWorldTile {
+    readonly bytes: number;
+    readonly collider: IWorldTileCollider;
+    readonly field: Heightfield;
+    readonly key: string;
+    readonly lod: LOD;
+    readonly lodLevel: number;
+    readonly object: Object3D;
+    readonly skirtVertexCount: number;
+    readonly tileX: number;
+    readonly tileZ: number;
+}
+interface IWorldTilesFollowPosition {
+    readonly x: number;
+    readonly z: number;
+}
+interface IWorldTilesTopologyObservation {
+    readonly columns: number;
+    readonly depth: number;
+    readonly origin: IHeightfieldOrigin;
+    readonly rows: number;
+    readonly width: number;
+}
+interface IWorldTilesOptions {
+    /** Releases a caller-supplied model key when its last tile reference is evicted. */
+    readonly assets?: Pick<IAssetLoader, "release">;
+    /** A game-owned, already-loaded logical model key, or a key resolver per tile. */
+    readonly assetKey?: string | ((tileX: number, tileZ: number) => string);
+    /** Creates the physics body from the field's explicit collider-order copy. */
+    readonly createCollider?: (input: IWorldTileColliderInput) => IWorldTileCollider;
+    /** TSL pass options are game supplied and are forwarded to each resident field. */
+    readonly worldPasses?: IHeightfieldWorldPassOptions;
+    /** Game-owned surface; this class never creates or mutates it. */
+    readonly surface: MeshSurface;
+    readonly residentByteBudget: number;
+    readonly residentTileBudget: number;
+    readonly sampleHeight: IHeightfieldSamplerOptions["sampleHeight"];
+    /** How deep each edge skirt extends below its surface. Defaults to one tile width. */
+    readonly skirtDepth?: number;
+    /** Square tile neighborhood to consider around the followed point. Defaults to 1. */
+    readonly streamRadius?: number;
+    readonly tileResolution: number;
+    readonly tileSize: number;
+    /** Vertex decimation factors. Defaults to 1, 2, and 4 over the same field. */
+    readonly lodFactors?: readonly number[];
+    /** Distances in world units at which the next LOD becomes active. */
+    readonly lodDistances?: readonly number[];
+    /** Explicit game-owned measurement region used by the topology evaluator. */
+    readonly topologyObservation?: IWorldTilesTopologyObservation;
+}
+/**
+ * Stream a bounded square of game-authored heightfields and keep their render and physics units
+ * together. The class composes ordinary THREE.LOD objects and leaves frustum/projection culling
+ * to the renderer's existing scene path.
+ *
+ * @situation stream terrain without cracks
+ * @situation keep generated terrain resident around a moving player
+ * @situation put a generated terrain tile into a game-owned physics world
+ * @alias stream terrain across chunks
+ * @constraint sampleHeight and surface are required game choices; no landform or surface preset is installed
+ * @constraint residentTileBudget and residentByteBudget are hard caps; a tile that cannot fit throws
+ * @override tileSize, tileResolution, lodFactors, lodDistances, skirtDepth, streamRadius, and budgets
+ * @example const tiles = new TerrainTiles({ sampleHeight, surface: gameSurface(), tileSize: 256, tileResolution: 129, residentTileBudget: 25, residentByteBudget: 32_000_000 });
+ */
+declare class TerrainTiles extends Object3D implements IComputeDriven {
+    #private;
+    readonly residentTileBudget: number;
+    readonly residentByteBudget: number;
+    readonly skirtDepth: number;
+    readonly tileResolution: number;
+    readonly tileSize: number;
+    readonly processCadence: "render";
+    constructor(options: IWorldTilesOptions);
+    get released(): boolean;
+    get residentTileCount(): number;
+    get residentBytes(): number;
+    get peakResidentTileCount(): number;
+    get peakResidentBytes(): number;
+    get residentKeys(): readonly string[];
+    get residentColliderKeys(): readonly string[];
+    get lodLevelCount(): number;
+    get lodTransitions(): number;
+    /** Maximum per-render-frame displacement of the visible LOD surface during transitions. */
+    get maxLodPop(): number;
+    /** Maximum number of rendered frames during which an LOD transition remained observable. */
+    get maxLodTransitionFrames(): number;
+    /** Maximum visible edge gap observed across follow/process calls for this residency owner. */
+    get maxSeamGap(): number;
+    /** Maximum remaining visible gap after skirt or bridge coverage observed across follow/process calls. */
+    get maxVisualSeamGap(): number;
+    /** Number of mixed-LOD edge reconciliations observed during this residency lifetime. */
+    get stitchedEdgeCount(): number;
+    get warmupNodes(): readonly unknown[];
+    getTile(key: string): IWorldTile | undefined;
+    follow(position: IWorldTilesFollowPosition | Pick<Vector3, "x" | "z">): void;
+    heightAt(x: number, z: number): number;
+    normalAt(x: number, z: number, target?: Vector3): Vector3;
+    sample(channel: string, x: number, z: number): number;
+    attachRenderer(renderer: IRendererLike): void;
+    process(renderer?: IRendererLike | undefined): void;
+    debug(): Record<string, unknown>;
+    detach(): void;
+    dispose(): void;
+}
+
+type WorldGenerationPath = "gpu" | "cpu-fallback" | "unsupported";
+interface IWorldComputeLimits {
+    readonly maxComputeInvocationsPerWorkgroup: number;
+    readonly maxComputeWorkgroupsPerDimension: number;
+    readonly maxStorageBufferBindingSize: number;
+}
+interface IWorldCapabilities {
+    readonly compute: boolean;
+    /** Whether the host exposed a GPU adapter, even when its limits cannot run the world pass. */
+    readonly gpu: boolean;
+    readonly generation: WorldGenerationPath;
+    readonly limits: IWorldComputeLimits;
+    readonly cpuFallbackIterations: number;
+    readonly reason?: string;
+}
+interface IWorldCapabilitiesOptions {
+    /** Explicitly supplied by a host that already probed its adapter. */
+    readonly gpuAvailable?: boolean;
+    readonly limits?: Partial<IWorldComputeLimits>;
+    readonly minimumWorkgroupsPerDimension?: number;
+    readonly minimumStorageBufferBindingSize?: number;
+    /** A positive value makes CPU generation an explicit, reduced fallback. */
+    readonly cpuFallbackIterations?: number;
+}
+/**
+ * Resolve the active world-generation path from host capability facts.
+ *
+ * The function accepts the adapter facts instead of reaching through a renderer-specific global,
+ * so browser and native hosts can report the same object. Missing limits are not treated as
+ * infinite: a host must either provide a valid GPU limit report or explicitly choose CPU fallback.
+ * GPU generation remains unavailable until a GPU readback can own the canonical field; a host
+ * adapter report therefore never upgrades a CPU fallback into a GPU generation claim.
+ *
+ * @situation decide whether generated terrain can use GPU compute
+ * @situation report why terrain generation is using a reduced CPU fallback
+ * @constraint unsupported is returned when compute limits are unknown or below the requirement; callers must not silently continue
+ * @override minimumWorkgroupsPerDimension, minimumStorageBufferBindingSize, and cpuFallbackIterations
+ * @example const capabilities = getWorldCapabilities({ limits: adapter.limits, cpuFallbackIterations: 8 });
+ */
+declare function getWorldCapabilities(options?: IWorldCapabilitiesOptions): IWorldCapabilities;
 
 interface IHeightfieldOrigin {
     readonly x: number;
@@ -11,11 +182,24 @@ interface IHeightfieldOptions {
     readonly origin: IHeightfieldOrigin;
     readonly rows: number;
     readonly width: number;
+    readonly worldPasses?: IHeightfieldWorldPassOptions;
+}
+interface IHeightfieldWorldPassOptions {
+    /** Maximum TSL compute dispatches submitted by one rendered frame. */
+    readonly dispatchBudget: number;
+    /** Reserved GPU path; true is rejected until GPU readback owns the canonical field. */
+    readonly gpu?: boolean;
+    /** Every physical coefficient is game supplied; core owns no terrain preset. */
+    readonly erosion: IWorldErosionOptions;
 }
 interface IHeightfieldSamplerOptions extends Omit<IHeightfieldOptions, "heights"> {
     /** Game-owned terrain function. It is evaluated once and never retained. */
     readonly sampleHeight: (x: number, z: number) => number;
 }
+interface IStoredHeightfieldChannels {
+    readonly flow?: Float32Array;
+    readonly moisture?: Float32Array;
+}
 /**
  * One height buffer shared by world queries, rendered geometry, and a physics heightfield.
  *
@@ -25,25 +209,40 @@ interface IHeightfieldSamplerOptions extends Omit<IHeightfieldOptions, "heights"
  * again.
  *
  * @situation build terrain geometry and collision from one game-authored height function
+ * @situation generate a terrain a player can walk across
  * @situation query the same ground height or normal that a player sees and collides with
+ * @situation ask how high the ground is here
  * @situation build islands and coastlines from terrain
  * @constraint sampleHeight owns the terrain shape and stays in game source; the framework stores and interpolates its output
  * @constraint rows and columns are vertex counts; geometry is row-major z-then-x and collider export transposes once into Rapier's column-major matrix order
  * @override rows, columns, width, depth, origin, and sampleHeight are explicit on every field
  * @example const field = Heightfield.fromSampler({ rows: 65, columns: 65, width: 64, depth: 64, origin: { x: 0, z: 0 }, sampleHeight: terrainHeight });
  */
-declare class Heightfield {
+declare class Heightfield extends Group implements IComputeDriven {
     #private;
     readonly columns: number;
     readonly depth: number;
     readonly origin: IHeightfieldOrigin;
     readonly rows: number;
     readonly width: number;
-    constructor(options: IHeightfieldOptions);
+    readonly processCadence: "render";
+    readonly warmupNodes: readonly unknown[];
+    constructor(options: IHeightfieldOptions & IStoredHeightfieldChannels);
     static fromSampler(options: IHeightfieldSamplerOptions): Heightfield;
     sample(channel: string, x: number, z: number): number;
+    get released(): boolean;
+    get generationComplete(): boolean;
+    get gpuHeightSample(): IGPUReadbackSample | undefined;
+    attachRenderer(renderer: IRendererLike): void;
+    process(renderer?: IRendererLike | undefined): void;
+    debug(): Record<string, unknown>;
+    detach(): void;
     /** A copy of the canonical row-major samples, safe for game-side analysis. */
     get heights(): Float32Array;
+    /** A copy of the normalized routed-flow channel, when world passes were requested. */
+    get flow(): Float32Array | undefined;
+    /** Bytes retained by this field's CPU channels and its conservative GPU allowance. */
+    get memoryBytes(): number;
     heightAt(x: number, z: number): number;
     normalAt(x: number, z: number, target?: Vector3): Vector3;
     /** The same values transposed once into Rapier's column-major height-matrix order. */
@@ -52,4 +251,4 @@ declare class Heightfield {
     toGeometry(): BufferGeometry;
 }
 
-export { Heightfield, type IHeightfieldOptions, type IHeightfieldOrigin, type IHeightfieldSamplerOptions };
+export { Heightfield, type IHeightfieldOptions, type IHeightfieldOrigin, type IHeightfieldSamplerOptions, type IHeightfieldWorldPassOptions, type IWorldCapabilities, type IWorldTileColliderInput, type IWorldTilesTopologyObservation, TerrainTiles, getWorldCapabilities };