@zylem/game-lib 0.6.4 → 0.7.0

package/dist/entity-type-map-C94h2TDW.d.ts

@@ -0,0 +1,781 @@
+import { Sprite, Color, Object3D, ColorRepresentation, Light, Fog, FogExp2, Scene } from 'three';
+import { G as GameEntity, I as GameEntityOptions, M as BaseNode } from './entity-DNkYKfdp.js';
+import { a as Vec3Input, b as Vec2Input, T as TexturePath, M as MaterialOptions } from './material-Wz83vTTp.js';
+import { S as SetupContext, f as UpdateContext, D as DestroyContext, C as CleanupContext } from './base-node-life-cycle-CnJ-7zX-.js';
+import { C as CollisionHandlerDelegate } from './world-C9zdyl5d.js';
+import { ParticleEmitterBehaviorOptions, ParticleEffectDefinition, ParticleEmitterHandle } from '@zylem/behaviors/particle-emitter';
+
+type SpriteImage = {
+    name: string;
+    file: string;
+};
+type SpriteAnimation = {
+    name: string;
+    frames: string[];
+    speed: number | number[];
+    loop: boolean;
+};
+type ZylemSpriteOptions = GameEntityOptions & {
+    images?: SpriteImage[];
+    animations?: SpriteAnimation[];
+    size?: Vec3Input;
+    collisionSize?: Vec3Input;
+};
+declare const SPRITE_TYPE: unique symbol;
+declare class ZylemSprite extends GameEntity<ZylemSpriteOptions> {
+    static type: symbol;
+    protected sprites: Sprite[];
+    protected spriteMap: Map<string, number>;
+    protected currentSpriteIndex: number;
+    protected animations: Map<string, any>;
+    protected currentAnimation: any;
+    protected currentAnimationFrame: string;
+    protected currentAnimationIndex: number;
+    protected currentAnimationTime: number;
+    constructor(options?: ZylemSpriteOptions);
+    create(): this;
+    protected createSpritesFromImages(images: SpriteImage[]): void;
+    protected createAnimations(animations: SpriteAnimation[]): void;
+    setSprite(key: string): void;
+    setAnimation(name: string, delta: number): void;
+    private getCurrentRotationQuaternion;
+    private syncSpriteMaterials;
+    spriteSetup(_params: SetupContext<ZylemSpriteOptions>): void;
+    spriteUpdate(params: UpdateContext<ZylemSpriteOptions>): void;
+    spriteDestroy(params: DestroyContext<ZylemSpriteOptions>): void;
+    buildInfo(): Record<string, any>;
+}
+type SpriteOptions = BaseNode | Partial<ZylemSpriteOptions>;
+declare function createSprite(...args: Array<SpriteOptions>): ZylemSprite;
+
+type ZylemSphereOptions = GameEntityOptions & {
+    radius?: number;
+};
+declare const SPHERE_TYPE: unique symbol;
+declare class ZylemSphere extends GameEntity<ZylemSphereOptions> {
+    static type: symbol;
+    constructor(options?: ZylemSphereOptions);
+    buildInfo(): Record<string, any>;
+}
+type SphereOptions = BaseNode | Partial<ZylemSphereOptions>;
+declare function createSphere(...args: Array<SphereOptions>): ZylemSphere;
+
+type ZylemRectOptions = GameEntityOptions & {
+    width?: number;
+    height?: number;
+    fillColor?: Color | string | null;
+    strokeColor?: Color | string | null;
+    strokeWidth?: number;
+    radius?: number;
+    padding?: number;
+    stickToViewport?: boolean;
+    screenPosition?: Vec2Input;
+    zDistance?: number;
+    anchor?: Vec2Input;
+    bounds?: {
+        screen?: {
+            x: number;
+            y: number;
+            width: number;
+            height: number;
+        };
+        world?: {
+            left: number;
+            right: number;
+            top: number;
+            bottom: number;
+            z?: number;
+        };
+    };
+};
+declare const RECT_TYPE: unique symbol;
+declare class ZylemRect extends GameEntity<ZylemRectOptions> {
+    static type: symbol;
+    private _sprite;
+    private _mesh;
+    private _texture;
+    private _canvas;
+    private _ctx;
+    private _cameraRef;
+    private _lastCanvasW;
+    private _lastCanvasH;
+    constructor(options?: ZylemRectOptions);
+    private createSprite;
+    private redrawRect;
+    getWidth(): number;
+    getHeight(): number;
+    private roundedRectPath;
+    private toCssColor;
+    /**
+     * Get the viewport resolution from the renderer DOM element,
+     * falling back to the camera's screenResolution if the renderer
+     * is not available (e.g. when using the new RendererManager path).
+     */
+    private getResolution;
+    private rectSetup;
+    private rectUpdate;
+    private updateStickyTransform;
+    private worldToScreen;
+    private computeScreenBoundsFromOptions;
+    updateRect(options?: Partial<Pick<ZylemRectOptions, 'width' | 'height' | 'fillColor' | 'strokeColor' | 'strokeWidth' | 'radius'>>): void;
+    buildInfo(): Record<string, any>;
+}
+type RectOptions = BaseNode | Partial<ZylemRectOptions>;
+declare function createRect(...args: Array<RectOptions>): ZylemRect;
+
+type ZylemTextOptions = GameEntityOptions & {
+    text?: string;
+    fontFamily?: string;
+    fontSize?: number;
+    fontColor?: Color | string;
+    backgroundColor?: Color | string | null;
+    padding?: number;
+    stickToViewport?: boolean;
+    screenPosition?: Vec2Input;
+    zDistance?: number;
+};
+declare const TEXT_TYPE: unique symbol;
+declare class ZylemText extends GameEntity<ZylemTextOptions> {
+    static type: symbol;
+    private _sprite;
+    private _texture;
+    private _canvas;
+    private _ctx;
+    private _cameraRef;
+    private _lastCanvasW;
+    private _lastCanvasH;
+    constructor(options?: ZylemTextOptions);
+    create(): this;
+    private createSprite;
+    private measureAndResizeCanvas;
+    private drawCenteredText;
+    private updateTexture;
+    private redrawText;
+    private toCssColor;
+    private textSetup;
+    private textUpdate;
+    private getResolution;
+    private getScreenPixels;
+    private computeWorldExtents;
+    private updateSpriteScale;
+    private updateWorldSpriteScale;
+    private updateStickyTransform;
+    updateText(_text: string): void;
+    buildInfo(): Record<string, any>;
+    /**
+     * Dispose of Three.js resources when the entity is destroyed.
+     */
+    private textDestroy;
+}
+type TextOptions = BaseNode | Partial<ZylemTextOptions>;
+declare function createText(...args: Array<TextOptions>): ZylemText;
+
+type ZylemBoxOptions = GameEntityOptions;
+declare const BOX_TYPE: unique symbol;
+declare class ZylemBox extends GameEntity<ZylemBoxOptions> {
+    static type: symbol;
+    constructor(options?: ZylemBoxOptions);
+    buildInfo(): Record<string, any>;
+}
+type BoxOptions = BaseNode | Partial<ZylemBoxOptions>;
+declare function createBox(...args: Array<BoxOptions>): ZylemBox;
+
+type ZylemPlaneOptions = GameEntityOptions & {
+    tile?: Vec2Input;
+    repeat?: Vec2Input;
+    texture?: TexturePath;
+    /**
+     * Number of subdivisions per axis. Used for both X and Z unless
+     * `subdivisionsX` / `subdivisionsZ` are set, or a `heightMap` /
+     * `heightMap2D` is provided (in which case subdivisions are derived
+     * from the height data).
+     */
+    subdivisions?: number;
+    /** Subdivisions along the X axis (overrides `subdivisions`). */
+    subdivisionsX?: number;
+    /** Subdivisions along the Z axis (overrides `subdivisions`). */
+    subdivisionsZ?: number;
+    /**
+     * If true and no explicit heightmap is provided, each vertex gets a
+     * random height in `[0, 4 * heightScale]`.
+     */
+    randomizeHeight?: boolean;
+    /**
+     * Absolute heights along the X axis, one value per vertex-column
+     * (constant along Z). `length` defines the X vertex count, so
+     * `subdivisionsX` becomes `length - 1`. Values are absolute world-space
+     * heights above/below the plane (multiplied by `heightScale`, default 1).
+     *
+     * Example: `heightMap: [10, 1, -1, 10]` produces 4 X-columns with those
+     * absolute heights, forming ridges parallel to the Z axis.
+     *
+     * Takes precedence over `randomizeHeight`.
+     */
+    heightMap?: number[];
+    /**
+     * Absolute heights as a 2D grid, indexed `heightMap2D[z][x]`. The outer
+     * array's length defines the Z vertex count and each inner array's
+     * length defines the X vertex count (all rows must share the same X
+     * length). Values are absolute (multiplied by `heightScale`).
+     *
+     * Takes precedence over `heightMap` and `randomizeHeight`.
+     */
+    heightMap2D?: number[][];
+    /** Multiplier applied to heightmap / random heights (default 1). */
+    heightScale?: number;
+};
+declare const PLANE_TYPE: unique symbol;
+declare class ZylemPlane extends GameEntity<ZylemPlaneOptions> {
+    static type: symbol;
+    constructor(options?: ZylemPlaneOptions);
+}
+type PlaneOptions = BaseNode | Partial<ZylemPlaneOptions>;
+declare function createPlane(...args: Array<PlaneOptions>): ZylemPlane;
+
+type OnHeldParams = {
+    delta: number;
+    self: ZylemZone;
+    visitor: GameEntity<any>;
+    heldTime: number;
+    globals: any;
+};
+type OnEnterParams = Pick<OnHeldParams, 'self' | 'visitor' | 'globals'>;
+type OnExitParams = Pick<OnHeldParams, 'self' | 'visitor' | 'globals'>;
+type ZylemZoneOptions = GameEntityOptions & {
+    size?: Vec3Input;
+    static?: boolean;
+    onEnter?: (params: OnEnterParams) => void;
+    onHeld?: (params: OnHeldParams) => void;
+    onExit?: (params: OnExitParams) => void;
+};
+declare const ZONE_TYPE: unique symbol;
+declare class ZylemZone extends GameEntity<ZylemZoneOptions> implements CollisionHandlerDelegate {
+    static type: symbol;
+    private _enteredZone;
+    private _exitedZone;
+    private _zoneEntities;
+    constructor(options?: ZylemZoneOptions);
+    handlePostCollision({ delta }: {
+        delta: number;
+    }): boolean;
+    handleIntersectionEvent({ other, delta, }: {
+        other: any;
+        delta: number;
+    }): void;
+    onEnter(callback: (params: OnEnterParams) => void): this;
+    onHeld(callback: (params: OnHeldParams) => void): this;
+    onExit(callback: (params: OnExitParams) => void): this;
+    entered(other: any): void;
+    exited(delta: number, key: string): void;
+    held(delta: number, other: any): void;
+}
+type ZoneOptions = BaseNode | Partial<ZylemZoneOptions>;
+declare function createZone(...args: Array<ZoneOptions>): ZylemZone;
+
+interface EntityLoaderDelegate {
+    /** Initiates loading (may be async internally, but call returns immediately) */
+    load(): void;
+    /** Returns data synchronously (may be null if still loading) */
+    data(): any;
+}
+
+type AnimationOptions = {
+    key: string;
+    pauseAtEnd?: boolean;
+    pauseAtPercentage?: number;
+    fadeToKey?: string;
+    fadeDuration?: number;
+};
+
+/**
+ * Interface for entities that provide custom debug information
+ */
+interface DebugInfoProvider {
+    getDebugInfo(): Record<string, any>;
+}
+
+type AnimationObject = {
+    key?: string;
+    path: string;
+};
+type CollisionShapeType = 'capsule' | 'bounds' | 'trimesh' | 'model';
+type ZylemActorOptions = GameEntityOptions & {
+    static?: boolean;
+    animations?: AnimationObject[];
+    models?: string[];
+    scale?: Vec3Input;
+    material?: MaterialOptions;
+    collisionShape?: CollisionShapeType;
+    /**
+     * Opt-in: also strip the root bone's Y translation track so the
+     * mixer never overrides the bind-pose hip Y. Useful when the
+     * actor is shown statically (e.g. a lobby preview) and you want
+     * to suppress the bind→animation Y "snap" at load time. Defaults
+     * to false because most FBX exports use the Y track as a
+     * hip-height calibration that the renderer needs to keep feet on
+     * the ground.
+     */
+    stripRootMotionY?: boolean;
+};
+declare const ACTOR_TYPE: unique symbol;
+declare class ZylemActor extends GameEntity<ZylemActorOptions> implements EntityLoaderDelegate, DebugInfoProvider {
+    static type: symbol;
+    private _object;
+    private _collisionSource;
+    private _animationDelegate;
+    private _modelFileNames;
+    private _assetLoader;
+    private _loadGeneration;
+    private _loadStatus;
+    controlledRotation: boolean;
+    hasWarnedDynamicTrimesh: boolean;
+    constructor(options?: ZylemActorOptions);
+    create(): this;
+    load(): void;
+    data(): any;
+    needsDeferredModelCollision(): boolean;
+    synchronizeRuntimeCollider(): void;
+    actorUpdate(params: UpdateContext<ZylemActorOptions>): void;
+    actorDestroy(): void;
+    _cleanup(params: CleanupContext<this>): void;
+    playAnimation(animationOptions: AnimationOptions): void;
+    get object(): Object3D | null;
+    get collisionSource(): Object3D | null;
+    getDebugInfo(): Record<string, any>;
+    private getResolvedCollisionShape;
+    private requiresLoadedCollisionSource;
+    private getRuntimeCollisionSource;
+    private getCollisionSourceSelection;
+    private disposeRuntimeState;
+    private loadModelsDeferred;
+    private applyMaterialOverrides;
+    /**
+     * Produce a cloned material with the requested color/opacity applied.
+     *
+     * Cloning preserves any textures (`map`, `normalMap`, `roughnessMap`, …)
+     * that came with the loaded model — colour acts as a multiplicative tint on
+     * top of them, matching standard PBR behaviour. We fall back to a fresh
+     * `MeshStandardMaterial` only when the source material has no `.color`
+     * field (e.g. custom `ShaderMaterial`).
+     */
+    private tintMaterial;
+}
+type ActorOptions = BaseNode | ZylemActorOptions;
+declare function createActor(...args: Array<ActorOptions>): ZylemActor;
+
+type ZylemDiskOptions = GameEntityOptions & {
+    innerRadius?: number;
+    outerRadius?: number;
+    thetaSegments?: number;
+};
+declare const DISK_TYPE: unique symbol;
+declare class ZylemDisk extends GameEntity<ZylemDiskOptions> {
+    static type: symbol;
+    constructor(options?: ZylemDiskOptions);
+    buildInfo(): Record<string, any>;
+}
+type DiskOptions = BaseNode | Partial<ZylemDiskOptions>;
+declare function createDisk(...args: Array<DiskOptions>): ZylemDisk;
+
+type ZylemConeOptions = GameEntityOptions & {
+    /** Base radius of the cone */
+    radius?: number;
+    /** Height of the cone */
+    height?: number;
+    /** Number of radial segments (higher = smoother) */
+    radialSegments?: number;
+};
+declare const CONE_TYPE: unique symbol;
+/**
+ * A cone entity with configurable radius, height, and radial segments.
+ * Uses a Rapier cone collider for physics.
+ */
+declare class ZylemCone extends GameEntity<ZylemConeOptions> {
+    static type: symbol;
+    constructor(options?: ZylemConeOptions);
+    buildInfo(): Record<string, any>;
+}
+type ConeOptions = BaseNode | Partial<ZylemConeOptions>;
+/**
+ * Create a cone entity.
+ * @param args Options or child nodes
+ */
+declare function createCone(...args: Array<ConeOptions>): ZylemCone;
+
+type ZylemPyramidOptions = GameEntityOptions & {
+    /** Base radius of the pyramid */
+    radius?: number;
+    /** Height of the pyramid */
+    height?: number;
+};
+declare const PYRAMID_TYPE: unique symbol;
+/**
+ * A pyramid entity (4-sided cone).
+ * Uses ConeGeometry with 4 radial segments for the visual mesh
+ * and a Rapier cone collider for physics.
+ */
+declare class ZylemPyramid extends GameEntity<ZylemPyramidOptions> {
+    static type: symbol;
+    constructor(options?: ZylemPyramidOptions);
+    buildInfo(): Record<string, any>;
+}
+type PyramidOptions = BaseNode | Partial<ZylemPyramidOptions>;
+/**
+ * Create a pyramid entity.
+ * @param args Options or child nodes
+ */
+declare function createPyramid(...args: Array<PyramidOptions>): ZylemPyramid;
+
+type ZylemCylinderOptions = GameEntityOptions & {
+    /** Top radius of the cylinder */
+    radiusTop?: number;
+    /** Bottom radius of the cylinder */
+    radiusBottom?: number;
+    /** Height of the cylinder */
+    height?: number;
+    /** Number of radial segments (higher = smoother) */
+    radialSegments?: number;
+};
+declare const CYLINDER_TYPE: unique symbol;
+/**
+ * A cylinder entity with configurable top/bottom radii, height, and segments.
+ * Uses a Rapier cylinder collider for physics.
+ */
+declare class ZylemCylinder extends GameEntity<ZylemCylinderOptions> {
+    static type: symbol;
+    constructor(options?: ZylemCylinderOptions);
+    buildInfo(): Record<string, any>;
+}
+type CylinderOptions = BaseNode | Partial<ZylemCylinderOptions>;
+/**
+ * Create a cylinder entity.
+ * @param args Options or child nodes
+ */
+declare function createCylinder(...args: Array<CylinderOptions>): ZylemCylinder;
+
+type ZylemPillOptions = GameEntityOptions & {
+    /** Radius of the capsule hemispheres */
+    radius?: number;
+    /** Length of the cylindrical middle section */
+    length?: number;
+    /** Number of cap segments (higher = smoother) */
+    capSegments?: number;
+    /** Number of radial segments (higher = smoother) */
+    radialSegments?: number;
+};
+declare const PILL_TYPE: unique symbol;
+/**
+ * A pill/capsule entity with configurable radius and cylindrical length.
+ * Uses Three.js CapsuleGeometry for rendering and Rapier capsule collider for physics.
+ */
+declare class ZylemPill extends GameEntity<ZylemPillOptions> {
+    static type: symbol;
+    constructor(options?: ZylemPillOptions);
+    buildInfo(): Record<string, any>;
+}
+type PillOptions = BaseNode | Partial<ZylemPillOptions>;
+/**
+ * Create a pill (capsule) entity.
+ * @param args Options or child nodes
+ */
+declare function createPill(...args: Array<PillOptions>): ZylemPill;
+
+type ZylemParticleSystemOptions = GameEntityOptions & ParticleEmitterBehaviorOptions & {
+    preset?: ParticleEffectDefinition;
+};
+declare const PARTICLE_SYSTEM_TYPE: unique symbol;
+declare class ZylemParticleSystem extends GameEntity<ZylemParticleSystemOptions> {
+    static type: symbol;
+    __zylemParticleSystemEntity: true;
+    private particleHandle;
+    constructor(options?: Partial<ZylemParticleSystemOptions>, initializeBehavior?: boolean);
+    private bindStandaloneTransforms;
+    private resolveParticleHandle;
+    play(): void;
+    stop(): void;
+    pause(): void;
+    restart(): void;
+    burst(): void;
+    isPlaying(): boolean;
+    getSystem(): ParticleEmitterHandle['getSystem'] extends () => infer T ? T : null;
+    buildInfo(): Record<string, string>;
+}
+declare function createParticleSystem(options?: Partial<ZylemParticleSystemOptions>): ZylemParticleSystem;
+
+type Vec3 = {
+    x: number;
+    y: number;
+    z: number;
+};
+/**
+ * Shadow-camera / shadow-map options shared across the light types that
+ * support casting shadows (directional, point, spot).
+ *
+ * The orthographic frustum fields (`left` / `right` / `top` / `bottom`) only
+ * apply to directional lights -- TypeScript enforces this via the tagged
+ * union below -- but we keep a single shape for ergonomic reuse.
+ */
+interface LightShadowOptions {
+    /** Shadow map resolution (square). Defaults: directional 2048, point/spot 1024. */
+    mapSize?: number;
+    /** Shadow camera near plane. Default 0.1. */
+    near?: number;
+    /** Shadow camera far plane. Default 500. */
+    far?: number;
+    /** Shadow bias (negative values can help acne). */
+    bias?: number;
+    /** PCF blur radius. */
+    radius?: number;
+    /** Directional-only: orthographic frustum left bound. Default -100. */
+    left?: number;
+    /** Directional-only: orthographic frustum right bound. Default 100. */
+    right?: number;
+    /** Directional-only: orthographic frustum top bound. Default 100. */
+    top?: number;
+    /** Directional-only: orthographic frustum bottom bound. Default -100. */
+    bottom?: number;
+}
+interface BaseLightOptions {
+    name?: string;
+    /** Light colour. Default `#ffffff`. */
+    color?: ColorRepresentation;
+    /** Scalar intensity multiplier. Default `1`. */
+    intensity?: number;
+    /** World-space position. Default `{0,0,0}`. Not meaningful for ambient. */
+    position?: Vec3;
+}
+interface AmbientLightOptions extends BaseLightOptions {
+    type: 'ambient';
+}
+interface HemisphereLightOptions extends BaseLightOptions {
+    type: 'hemisphere';
+    /** Sky colour. Falls back to `color` if omitted, else `#ffffff`. */
+    skyColor?: ColorRepresentation;
+    /** Ground colour. Default `#000000`. */
+    groundColor?: ColorRepresentation;
+}
+interface DirectionalLightOptions extends BaseLightOptions {
+    type: 'directional';
+    /** World-space point the light aims at. Default origin. */
+    target?: Vec3;
+    /** Enable shadow casting. Default `false`. */
+    castShadow?: boolean;
+    /** Shadow camera / map tuning. */
+    shadow?: LightShadowOptions;
+}
+interface PointLightOptions extends BaseLightOptions {
+    type: 'point';
+    /** Maximum range of the light (0 = infinite). */
+    distance?: number;
+    /** Physical falloff exponent. Default `2` (three.js default). */
+    decay?: number;
+    castShadow?: boolean;
+    /** Shadow options (directional-only frustum fields are ignored). */
+    shadow?: Omit<LightShadowOptions, 'left' | 'right' | 'top' | 'bottom'>;
+}
+interface SpotLightOptions extends BaseLightOptions {
+    type: 'spot';
+    /** World-space point the cone aims at. Default origin. */
+    target?: Vec3;
+    /** Maximum range of the light (0 = infinite). */
+    distance?: number;
+    /** Physical falloff exponent. Default `2`. */
+    decay?: number;
+    /** Cone angle in radians. Default `Math.PI / 3`. */
+    angle?: number;
+    /** Penumbra softness in `[0, 1]`. Default `0`. */
+    penumbra?: number;
+    castShadow?: boolean;
+    /** Shadow options (directional-only frustum fields are ignored). */
+    shadow?: Omit<LightShadowOptions, 'left' | 'right' | 'top' | 'bottom'>;
+}
+type ZylemLightOptions = AmbientLightOptions | HemisphereLightOptions | DirectionalLightOptions | PointLightOptions | SpotLightOptions;
+declare const LIGHT_TYPE: unique symbol;
+type ZylemLightGameOptions = ZylemLightOptions & GameEntityOptions;
+/**
+ * `GameEntity` wrapper around a `THREE.Light` (plus its optional target) so
+ * lights can be added to a stage via the standard `stage.add(...)` pipeline.
+ *
+ * The underlying light lives inside `this.group` at the group's local origin,
+ * and the group's world position is set to `options.position` when the stage
+ * attaches the entity to the scene. For directional and spot lights, an
+ * optional target `Object3D` is added as a sibling inside the same group at a
+ * local offset of `target - position`, so moving the group also moves the
+ * aim point.
+ */
+declare class ZylemLight extends GameEntity<ZylemLightGameOptions> {
+    static type: symbol;
+    /** The underlying THREE.js light instance. Populated in `create()`. */
+    light: Light | null;
+    /** The target `Object3D` for directional / spot lights, when configured. */
+    lightTarget: Object3D | null;
+    constructor(options: ZylemLightOptions);
+    create(): this;
+    /**
+     * Dispose the shadow map render target before delegating to the engine's
+     * standard cleanup (which removes the group from its parent scene).
+     */
+    protected _cleanup(params: CleanupContext<this>): void;
+}
+/**
+ * Create a light entity that can be added to a stage with `stage.add(...)`.
+ *
+ * The `type` discriminant narrows the accepted option keys, so TypeScript
+ * surfaces an error if you try to set, say, `angle` on an ambient light.
+ *
+ * @example
+ * ```ts
+ * stage.add(createLight({ type: 'ambient', intensity: 1.5 }));
+ * stage.add(createLight({
+ *   type: 'directional',
+ *   position: { x: 8, y: 12, z: 6 },
+ *   target: { x: 0, y: 0, z: 0 },
+ *   castShadow: true,
+ * }));
+ * ```
+ */
+declare function createLight(options: ZylemLightOptions): ZylemLight;
+
+/** Three.js fog model. Linear uses start/end; exp² uses density. */
+type ZylemFogType = 'linear' | 'exp2';
+/** Optional vertical falloff (a.k.a. ground/height fog). */
+interface ZylemFogHeightOptions {
+    /** Master toggle. Defaults to `false`. */
+    enabled?: boolean;
+    /** World-space Y at which fog stops attenuating (becomes fully clear). */
+    level?: number;
+    /**
+     * Density falloff per world-unit beneath `level`. Higher values produce
+     * sharper transitions; values <= 0 disable the height contribution.
+     */
+    falloff?: number;
+}
+/**
+ * Optional 3D animated noise applied to fog density.
+ *
+ * Specifying a `noise` block enables noise modulation; omit it to disable.
+ */
+interface ZylemFogNoiseOptions {
+    /** Spatial scale of the noise; lower = larger pockets of clearer / denser fog. */
+    scale?: number;
+    /** Modulation strength in `[0, 1]`. 0 = no effect, 1 = full ±100% modulation. */
+    strength?: number;
+    /** Animation speed (world-units per second of advect). */
+    speed?: number;
+}
+interface ZylemFogOptions {
+    /** Fog model. Default `'linear'`. */
+    type?: ZylemFogType;
+    /** Fog colour. Default `'#9aa3ad'` (neutral grey). */
+    color?: ColorRepresentation;
+    /** Exp² density coefficient. Only used when `type === 'exp2'`. Default `0.015`. */
+    density?: number;
+    /** Linear-fog start distance. Only used when `type === 'linear'`. Default `10`. */
+    start?: number;
+    /** Linear-fog end distance. Only used when `type === 'linear'`. Default `250`. */
+    end?: number;
+    /** Optional vertical falloff. Disabled by default. */
+    height?: ZylemFogHeightOptions;
+    /** Optional 3D animated noise. Disabled by default. */
+    noise?: ZylemFogNoiseOptions;
+    /** Display name (mostly for debug overlays). */
+    name?: string;
+}
+declare const FOG_TYPE: unique symbol;
+type ZylemFogGameOptions = ZylemFogOptions & GameEntityOptions;
+/**
+ * `GameEntity` that owns a Three.js fog instance plus optional height /
+ * noise modulators.
+ *
+ * Why not just expose `scene.fog` directly? Modelling fog as an entity:
+ * - Keeps stage authoring uniform with lights, particles, etc.
+ * - Gives a natural hook for cleanup when the stage tears down.
+ * - Allows multiple stages / loads to swap fog cleanly via the existing
+ *   entity lifecycle, including the wasm-runtime-managed stages.
+ *
+ * The entity attaches a tiny empty {@link Group} to the scene so that the
+ * standard {@link GameEntity#_cleanup} pathway removes it from its parent
+ * during destroy; the actual fog effect is wired up via
+ * {@link attachToScene} which is invoked by `ZylemScene.addEntityGroup`.
+ */
+declare class ZylemFog extends GameEntity<ZylemFogGameOptions> {
+    static type: symbol;
+    /** The underlying Three.js fog instance. Populated in `create()`. */
+    threeFog: Fog | FogExp2 | null;
+    /** Scene the fog is currently attached to (null when detached). */
+    private attachedScene;
+    private readonly patcher;
+    private patcherEnabled;
+    constructor(options?: ZylemFogOptions);
+    create(): this;
+    /**
+     * Hook into the host scene: stamp `scene.fog` and -- if height / noise
+     * are enabled -- start patching the scene's materials.
+     *
+     * Called by `ZylemScene.addEntityGroup` once it has identified this
+     * entity as a fog entity.
+     *
+     * @param scene The Three.js scene that will host the fog.
+     */
+    attachToScene(scene: Scene): void;
+    /**
+     * Per-frame tick. The base `GameEntity._update` is invoked first (so
+     * user `onUpdate` callbacks still run), then the patcher advances its
+     * time uniform and picks up any newly-spawned materials.
+     */
+    _update(params: UpdateContext<this>): void;
+    protected _cleanup(params: CleanupContext<this>): void;
+    private resolveUniformValues;
+}
+/**
+ * Create a fog entity that can be added to a stage with `stage.add(...)`.
+ *
+ * @example
+ * Default greyish fog -- no arguments needed:
+ * ```ts
+ * stage.add(createFog());
+ * ```
+ *
+ * @example
+ * Exp² fog with animated, ground-hugging haze:
+ * ```ts
+ * stage.add(createFog({
+ *   type: 'exp2',
+ *   color: '#aabbcc',
+ *   density: 0.015,
+ *   height: { enabled: true, level: 5, falloff: 0.2 },
+ *   noise: { scale: 0.05, strength: 0.15, speed: 0.1 },
+ * }));
+ * ```
+ */
+declare function createFog(options?: ZylemFogOptions): ZylemFog;
+
+/**
+ * Maps entity type symbols to their class types.
+ * Used by getEntityByName to infer return types.
+ */
+interface EntityTypeMap {
+    [SPRITE_TYPE]: ZylemSprite;
+    [SPHERE_TYPE]: ZylemSphere;
+    [RECT_TYPE]: ZylemRect;
+    [TEXT_TYPE]: ZylemText;
+    [BOX_TYPE]: ZylemBox;
+    [PLANE_TYPE]: ZylemPlane;
+    [ZONE_TYPE]: ZylemZone;
+    [ACTOR_TYPE]: ZylemActor;
+    [DISK_TYPE]: ZylemDisk;
+    [CONE_TYPE]: ZylemCone;
+    [PYRAMID_TYPE]: ZylemPyramid;
+    [CYLINDER_TYPE]: ZylemCylinder;
+    [PILL_TYPE]: ZylemPill;
+    [PARTICLE_SYSTEM_TYPE]: ZylemParticleSystem;
+    [LIGHT_TYPE]: ZylemLight;
+    [FOG_TYPE]: ZylemFog;
+}
+/**
+ * Type helper: if T is a known type symbol, return the mapped entity type.
+ * Otherwise return BaseNode.
+ */
+type EntityForType<T> = T extends keyof EntityTypeMap ? EntityTypeMap[T] : BaseNode;
+
+export { type AmbientLightOptions as $, ACTOR_TYPE as A, BOX_TYPE as B, type CollisionShapeType as C, DISK_TYPE as D, createPyramid as E, ZylemPyramid as F, PYRAMID_TYPE as G, createCylinder as H, ZylemCylinder as I, CYLINDER_TYPE as J, createPill as K, ZylemPill as L, PILL_TYPE as M, createParticleSystem as N, type OnHeldParams as O, PLANE_TYPE as P, ZylemParticleSystem as Q, RECT_TYPE as R, SPHERE_TYPE as S, TEXT_TYPE as T, PARTICLE_SYSTEM_TYPE as U, type ZylemParticleSystemOptions as V, createLight as W, ZylemLight as X, LIGHT_TYPE as Y, ZylemBox as Z, type ZylemLightOptions as _, createSphere as a, type HemisphereLightOptions as a0, type DirectionalLightOptions as a1, type PointLightOptions as a2, type SpotLightOptions as a3, type LightShadowOptions as a4, createFog as a5, ZylemFog as a6, FOG_TYPE as a7, type ZylemFogOptions as a8, type ZylemFogType as a9, type ZylemFogHeightOptions as aa, type ZylemFogNoiseOptions as ab, type EntityTypeMap as ac, type EntityForType as ad, ZylemSphere as b, createBox as c, createSprite as d, ZylemSprite as e, SPRITE_TYPE as f, type SpriteImage as g, type SpriteAnimation as h, createPlane as i, ZylemPlane as j, createZone as k, ZylemZone as l, ZONE_TYPE as m, type OnEnterParams as n, type OnExitParams as o, createActor as p, ZylemActor as q, createText as r, ZylemText as s, createRect as t, ZylemRect as u, createDisk as v, ZylemDisk as w, createCone as x, ZylemCone as y, CONE_TYPE as z };