gaesup-world 1.3.2 → 1.4.0

package/dist/core/camera/core/CameraOcclusion.d.cts

@@ -0,0 +1,60 @@
+import * as THREE from 'three';
+/**
+ * Fades what hides the camera's subject (`collisionMode: 'fade'`). One per scene, since materials and batches are shared
+ * scene state. A sweep collects contacts (`begin`, `collect`, `finish`); `update` animates each fade and restores what
+ * stopped occluding. How an occluder turns see-through is `SeeThrough`'s part.
+ */
+export declare class CameraOcclusion {
+    /** Distance to the nearest contact of the current sweep that pushes the camera instead of fading. */
+    solid: number;
+    private readonly scene;
+    private readonly looks;
+    private readonly active;
+    private readonly idle;
+    private readonly hitMeshes;
+    private readonly hitParts;
+    private readonly hitDistances;
+    private hits;
+    private ray;
+    private radius;
+    private limit;
+    private mesh;
+    private kind;
+    private explicit;
+    private fadeMode;
+    private flush;
+    constructor(scene: THREE.Scene);
+    /** Starts collecting the contacts of a sweep along `ray` up to `limit`. */
+    begin(ray: THREE.Ray, radius: number, limit: number): this;
+    /**
+     * Collects the mesh's contacts: fades, or pushes for ground-like faces unless `explicit` (the mesh asked to fade).
+     * False when the mesh cannot fade and must push (see `SeeThrough.kindOf`).
+     */
+    collect(mesh: THREE.Mesh, explicit: boolean): boolean;
+    /** Fades what the sweep touched nearer than `distance`, where the camera ends up after pushing. */
+    finish(distance: number): void;
+    /**
+     * Moves every fade toward `opacity` while it occludes and back after, and restores what stopped occluding. Once the
+     * camera leaves fade mode (`fadeMode` false) and everything faded back, the kept copies are freed.
+     */
+    update(deltaTime: number, opacity?: number, fadeMode?: boolean): void;
+    /** Restores every faded occluder at once and frees every copy and proxy. */
+    dispose(): void;
+    private readonly onContact;
+    /**
+     * The batch holds its faded instances at zero scale and their proxies are intangible, so the sweep tests the proxies
+     * as the batch's own instances. A batch no longer collected (the camera went back to pushing) lets them fade back.
+     */
+    private collectProxies;
+    private addHit;
+    private touch;
+    /** The kept fade of this mesh and part, brought up to date, unless the mesh draws with other materials by now. */
+    private reuse;
+    private park;
+    private clearIdle;
+}
+export declare function getCameraOcclusion(scene: THREE.Scene): CameraOcclusion;
+/** The scene's occlusion fader if a fade has ever been collected there; never creates one. */
+export declare function peekCameraOcclusion(scene: THREE.Scene): CameraOcclusion | undefined;
+/** Restores the scene's faded occluders and frees the fader. */
+export declare function disposeCameraOcclusion(scene: THREE.Scene): void;

package/dist/core/camera/core/CameraOcclusion.d.ts

@@ -0,0 +1,60 @@
+import * as THREE from 'three';
+/**
+ * Fades what hides the camera's subject (`collisionMode: 'fade'`). One per scene, since materials and batches are shared
+ * scene state. A sweep collects contacts (`begin`, `collect`, `finish`); `update` animates each fade and restores what
+ * stopped occluding. How an occluder turns see-through is `SeeThrough`'s part.
+ */
+export declare class CameraOcclusion {
+    /** Distance to the nearest contact of the current sweep that pushes the camera instead of fading. */
+    solid: number;
+    private readonly scene;
+    private readonly looks;
+    private readonly active;
+    private readonly idle;
+    private readonly hitMeshes;
+    private readonly hitParts;
+    private readonly hitDistances;
+    private hits;
+    private ray;
+    private radius;
+    private limit;
+    private mesh;
+    private kind;
+    private explicit;
+    private fadeMode;
+    private flush;
+    constructor(scene: THREE.Scene);
+    /** Starts collecting the contacts of a sweep along `ray` up to `limit`. */
+    begin(ray: THREE.Ray, radius: number, limit: number): this;
+    /**
+     * Collects the mesh's contacts: fades, or pushes for ground-like faces unless `explicit` (the mesh asked to fade).
+     * False when the mesh cannot fade and must push (see `SeeThrough.kindOf`).
+     */
+    collect(mesh: THREE.Mesh, explicit: boolean): boolean;
+    /** Fades what the sweep touched nearer than `distance`, where the camera ends up after pushing. */
+    finish(distance: number): void;
+    /**
+     * Moves every fade toward `opacity` while it occludes and back after, and restores what stopped occluding. Once the
+     * camera leaves fade mode (`fadeMode` false) and everything faded back, the kept copies are freed.
+     */
+    update(deltaTime: number, opacity?: number, fadeMode?: boolean): void;
+    /** Restores every faded occluder at once and frees every copy and proxy. */
+    dispose(): void;
+    private readonly onContact;
+    /**
+     * The batch holds its faded instances at zero scale and their proxies are intangible, so the sweep tests the proxies
+     * as the batch's own instances. A batch no longer collected (the camera went back to pushing) lets them fade back.
+     */
+    private collectProxies;
+    private addHit;
+    private touch;
+    /** The kept fade of this mesh and part, brought up to date, unless the mesh draws with other materials by now. */
+    private reuse;
+    private park;
+    private clearIdle;
+}
+export declare function getCameraOcclusion(scene: THREE.Scene): CameraOcclusion;
+/** The scene's occlusion fader if a fade has ever been collected there; never creates one. */
+export declare function peekCameraOcclusion(scene: THREE.Scene): CameraOcclusion | undefined;
+/** Restores the scene's faded occluders and frees the fader. */
+export declare function disposeCameraOcclusion(scene: THREE.Scene): void;

package/dist/core/camera/core/CameraSystem.d.cts

@@ -20,6 +20,8 @@ export declare class CameraSystem extends BaseCameraSystem {
     /** Frame-local orbit input; keep the owned configuration and controller view in sync. */
     updateOrbit(orbitYaw: number, orbitPitch: number): void;
     update(deltaTime: number): void;
+    /** Restores what the controllers changed in the scene, such as faded occluders. */
+    destroy(): void;
     calculate(props: CameraCalcProps): void;
     getCameraState(name: string): CameraState | undefined;
     getCurrentCameraState(): CameraState | undefined;

package/dist/core/camera/core/CameraSystem.d.ts

@@ -20,6 +20,8 @@ export declare class CameraSystem extends BaseCameraSystem {
     /** Frame-local orbit input; keep the owned configuration and controller view in sync. */
     updateOrbit(orbitYaw: number, orbitPitch: number): void;
     update(deltaTime: number): void;
+    /** Restores what the controllers changed in the scene, such as faded occluders. */
+    destroy(): void;
     calculate(props: CameraCalcProps): void;
     getCameraState(name: string): CameraState | undefined;
     getCurrentCameraState(): CameraState | undefined;

package/dist/core/camera/core/constants.d.cts

@@ -23,6 +23,7 @@ export declare const CAMERA_DEFAULTS: {
     readonly FOCUS: false;
     readonly ENABLE_COLLISION: true;
     readonly COLLISION_MARGIN: 0.1;
+    readonly COLLISION_FADE_OPACITY: 0.3;
     readonly SMOOTHING: {
         readonly POSITION: 0.08;
         readonly ROTATION: 0.1;

package/dist/core/camera/core/constants.d.ts

@@ -23,6 +23,7 @@ export declare const CAMERA_DEFAULTS: {
     readonly FOCUS: false;
     readonly ENABLE_COLLISION: true;
     readonly COLLISION_MARGIN: 0.1;
+    readonly COLLISION_FADE_OPACITY: 0.3;
     readonly SMOOTHING: {
         readonly POSITION: 0.08;
         readonly ROTATION: 0.1;

package/dist/core/camera/core/seeThrough.d.cts

@@ -0,0 +1,64 @@
+import * as THREE from 'three';
+/**
+ * `geometry.userData` key under which a merged geometry lists its parts: the draw offset (index offset, or vertex offset
+ * without an index) where each part ends, ascending. Such a geometry fades part by part instead of as a whole.
+ */
+export declare const MERGED_PARTS_KEY = "mergedParts";
+/** A whole mesh swaps its material; an instance is drawn apart by a proxy; a merged part draws in its own group. */
+export type FadeKind = 'whole' | 'instance' | 'part';
+/** One occluder made see-through: a mesh, or one instance or merged part of it. */
+export type Fade = {
+    kind: FadeKind;
+    mesh: THREE.Mesh;
+    /** The instance or merged part; -1 for a whole mesh. */
+    part: number;
+    /** What the mesh drew with when the fade was made. */
+    original: THREE.Material | THREE.Material[];
+    /** The distinct original materials, and a see-through copy and the opacity of each. */
+    sources: THREE.Material[];
+    copies: THREE.Material[];
+    opacities: number[];
+    /** `original` with each material replaced by its copy. */
+    faded: THREE.Material | THREE.Material[];
+    /** Draws the instance while its batch holds it at zero scale; its matrix is the instance's own. */
+    proxy: THREE.Mesh | null;
+    /** Draw range of a merged part. */
+    start: number;
+    count: number;
+    /** 0 opaque to 1 fully faded. */
+    amount: number;
+    /** Seconds it still counts as occluding; each contact sets it again. */
+    hold: number;
+    shown: boolean;
+};
+/** The part of a merged geometry that draw offset `offset` belongs to, or -1. */
+export declare function partAt(geometry: THREE.BufferGeometry, offset: number): number;
+/**
+ * Makes occluders see-through without changing anything they share: each fade draws with copies of its own. A whole mesh
+ * swaps its material, a batch holds the instance at zero scale while a proxy draws it, and a merged part draws in a group
+ * of its own. A fade is undone only where the mesh still draws what it made; an owner that replaced a material, geometry
+ * or instance keeps its change.
+ */
+export declare class SeeThrough {
+    private readonly merged;
+    /** How the mesh can fade: null when invisible, batched, a shader material, or a merged mesh already split in groups. */
+    kindOf(mesh: THREE.Mesh): FadeKind | null;
+    /** A fade of the mesh, instance or part, not shown yet; null when the mesh cannot fade or a material cannot be copied. */
+    create(mesh: THREE.Mesh, part: number): Fade | null;
+    /**
+     * Brings a kept fade up to date with the mesh, whose materials, instances or merged parts may have changed since it
+     * last showed. False when it no longer fits: other materials, a part or instance gone, a material that no longer copies.
+     */
+    refresh(fade: Fade): boolean;
+    show(fade: Fade): void;
+    /** Puts back what the fade changed, where the mesh still draws what the fade left it. */
+    hide(fade: Fade): void;
+    /** Whether the mesh still draws what the fade made: its owner may have replaced a material, geometry or instances. */
+    owns(fade: Fade): boolean;
+    /** Undoes the fade where it still can and frees its copies. */
+    release(fade: Fade): void;
+    /** Takes the part's draw range, or the instance's geometry and color, from the mesh as it is now; false once gone. */
+    private locate;
+    /** Draws a merged mesh with one group per faded part, or as before once none is left. */
+    private layout;
+}

package/dist/core/camera/core/seeThrough.d.ts

@@ -0,0 +1,64 @@
+import * as THREE from 'three';
+/**
+ * `geometry.userData` key under which a merged geometry lists its parts: the draw offset (index offset, or vertex offset
+ * without an index) where each part ends, ascending. Such a geometry fades part by part instead of as a whole.
+ */
+export declare const MERGED_PARTS_KEY = "mergedParts";
+/** A whole mesh swaps its material; an instance is drawn apart by a proxy; a merged part draws in its own group. */
+export type FadeKind = 'whole' | 'instance' | 'part';
+/** One occluder made see-through: a mesh, or one instance or merged part of it. */
+export type Fade = {
+    kind: FadeKind;
+    mesh: THREE.Mesh;
+    /** The instance or merged part; -1 for a whole mesh. */
+    part: number;
+    /** What the mesh drew with when the fade was made. */
+    original: THREE.Material | THREE.Material[];
+    /** The distinct original materials, and a see-through copy and the opacity of each. */
+    sources: THREE.Material[];
+    copies: THREE.Material[];
+    opacities: number[];
+    /** `original` with each material replaced by its copy. */
+    faded: THREE.Material | THREE.Material[];
+    /** Draws the instance while its batch holds it at zero scale; its matrix is the instance's own. */
+    proxy: THREE.Mesh | null;
+    /** Draw range of a merged part. */
+    start: number;
+    count: number;
+    /** 0 opaque to 1 fully faded. */
+    amount: number;
+    /** Seconds it still counts as occluding; each contact sets it again. */
+    hold: number;
+    shown: boolean;
+};
+/** The part of a merged geometry that draw offset `offset` belongs to, or -1. */
+export declare function partAt(geometry: THREE.BufferGeometry, offset: number): number;
+/**
+ * Makes occluders see-through without changing anything they share: each fade draws with copies of its own. A whole mesh
+ * swaps its material, a batch holds the instance at zero scale while a proxy draws it, and a merged part draws in a group
+ * of its own. A fade is undone only where the mesh still draws what it made; an owner that replaced a material, geometry
+ * or instance keeps its change.
+ */
+export declare class SeeThrough {
+    private readonly merged;
+    /** How the mesh can fade: null when invisible, batched, a shader material, or a merged mesh already split in groups. */
+    kindOf(mesh: THREE.Mesh): FadeKind | null;
+    /** A fade of the mesh, instance or part, not shown yet; null when the mesh cannot fade or a material cannot be copied. */
+    create(mesh: THREE.Mesh, part: number): Fade | null;
+    /**
+     * Brings a kept fade up to date with the mesh, whose materials, instances or merged parts may have changed since it
+     * last showed. False when it no longer fits: other materials, a part or instance gone, a material that no longer copies.
+     */
+    refresh(fade: Fade): boolean;
+    show(fade: Fade): void;
+    /** Puts back what the fade changed, where the mesh still draws what the fade left it. */
+    hide(fade: Fade): void;
+    /** Whether the mesh still draws what the fade made: its owner may have replaced a material, geometry or instances. */
+    owns(fade: Fade): boolean;
+    /** Undoes the fade where it still can and frees its copies. */
+    release(fade: Fade): void;
+    /** Takes the part's draw range, or the instance's geometry and color, from the mesh as it is now; false once gone. */
+    private locate;
+    /** Draws a merged mesh with one group per faded part, or as before once none is left. */
+    private layout;
+}

package/dist/core/camera/core/types.d.cts

@@ -12,6 +12,12 @@ export interface CameraConstants {
     FRAME_RATE_LERP_SPEED: number;
 }
 export type CameraCollisionTargets = 'scene' | 'colliders';
+/**
+ * What the camera does about a mesh between it and the character: `push` moves the camera in front of it, `fade` keeps
+ * the camera where it is and turns the mesh see-through until it stops occluding. A mesh (or an ancestor) overrides the
+ * option with `userData.cameraCollisionMode`.
+ */
+export type CameraCollisionMode = 'push' | 'fade';
 export interface CameraBounds {
     minX?: number;
     maxX?: number;
@@ -40,6 +46,13 @@ export interface CameraOption {
     collisionMargin?: number;
     /** 'colliders' tests only meshes on CAMERA_COLLIDER_LAYER and falls back to the whole scene when none exist. */
     collisionTargets?: CameraCollisionTargets;
+    /**
+     * How `enableCollision` handles occluders; `push` (default) or `fade`. Fade still pushes for ground (surfaces facing
+     * up), meshes marked `userData.cameraCollisionMode: 'push'`, invisible meshes and materials it cannot fade.
+     */
+    collisionMode?: CameraCollisionMode;
+    /** Opacity a faded occluder reaches, 0–1, relative to its own (default 0.3). */
+    collisionFadeOpacity?: number;
     smoothing?: {
         position?: number;
         rotation?: number;
@@ -136,6 +149,8 @@ export interface CameraSystemConfig {
     enableCollision: boolean;
     collisionMargin?: number;
     collisionTargets?: CameraCollisionTargets;
+    collisionMode?: CameraCollisionMode;
+    collisionFadeOpacity?: number;
     orbitYaw?: number;
     orbitPitch?: number;
     smoothing?: {
@@ -172,6 +187,8 @@ export interface ICameraController {
     name: string;
     defaultConfig: Partial<CameraSystemConfig>;
     update(props: CameraCalcProps, state: CameraSystemState): void;
+    /** Restores what the controller changed in the scene (faded occluders) and frees what it made for that. */
+    dispose?(): void;
 }
 export interface Obstacle {
     object: THREE.Mesh;

package/dist/core/camera/core/types.d.ts

@@ -12,6 +12,12 @@ export interface CameraConstants {
     FRAME_RATE_LERP_SPEED: number;
 }
 export type CameraCollisionTargets = 'scene' | 'colliders';
+/**
+ * What the camera does about a mesh between it and the character: `push` moves the camera in front of it, `fade` keeps
+ * the camera where it is and turns the mesh see-through until it stops occluding. A mesh (or an ancestor) overrides the
+ * option with `userData.cameraCollisionMode`.
+ */
+export type CameraCollisionMode = 'push' | 'fade';
 export interface CameraBounds {
     minX?: number;
     maxX?: number;
@@ -40,6 +46,13 @@ export interface CameraOption {
     collisionMargin?: number;
     /** 'colliders' tests only meshes on CAMERA_COLLIDER_LAYER and falls back to the whole scene when none exist. */
     collisionTargets?: CameraCollisionTargets;
+    /**
+     * How `enableCollision` handles occluders; `push` (default) or `fade`. Fade still pushes for ground (surfaces facing
+     * up), meshes marked `userData.cameraCollisionMode: 'push'`, invisible meshes and materials it cannot fade.
+     */
+    collisionMode?: CameraCollisionMode;
+    /** Opacity a faded occluder reaches, 0–1, relative to its own (default 0.3). */
+    collisionFadeOpacity?: number;
     smoothing?: {
         position?: number;
         rotation?: number;
@@ -136,6 +149,8 @@ export interface CameraSystemConfig {
     enableCollision: boolean;
     collisionMargin?: number;
     collisionTargets?: CameraCollisionTargets;
+    collisionMode?: CameraCollisionMode;
+    collisionFadeOpacity?: number;
     orbitYaw?: number;
     orbitPitch?: number;
     smoothing?: {
@@ -172,6 +187,8 @@ export interface ICameraController {
     name: string;
     defaultConfig: Partial<CameraSystemConfig>;
     update(props: CameraCalcProps, state: CameraSystemState): void;
+    /** Restores what the controller changed in the scene (faded occluders) and frees what it made for that. */
+    dispose?(): void;
 }
 export interface Obstacle {
     object: THREE.Mesh;

package/dist/core/camera/utils/camera.d.cts

@@ -2,10 +2,13 @@ import { RapierRigidBody } from '@react-three/rapier';
 import * as THREE from 'three';
 import { ActiveStateType } from '../../motions/core/types.cjs';
 import { CAMERA_CONSTANTS } from '../core/constants.cjs';
-import { CameraOptionType, CameraBounds, CollisionCheckResult, type CameraCollisionTargets } from '../core/types.cjs';
+import { CameraOptionType, CameraBounds, CollisionCheckResult, type CameraCollisionMode, type CameraCollisionTargets } from '../core/types.cjs';
 export declare function invalidateCollisionCache(): void;
-/** Frame hot path: writes the collision-safe camera position into `out` without collecting obstacles. */
-export declare function resolveCollisionPosition(from: THREE.Vector3, to: THREE.Vector3, scene: THREE.Scene, radius: number, excludedObjects: THREE.Object3D[] | undefined, out: THREE.Vector3, targets?: CameraCollisionTargets): THREE.Vector3;
+/**
+ * Frame hot path: writes the collision-safe camera position into `out` without collecting obstacles. `mode` is the
+ * camera's collision mode; fading meshes leave the position alone and are faded by the scene's occlusion fader.
+ */
+export declare function resolveCollisionPosition(from: THREE.Vector3, to: THREE.Vector3, scene: THREE.Scene, radius: number, excludedObjects: THREE.Object3D[] | undefined, out: THREE.Vector3, targets?: CameraCollisionTargets, mode?: CameraCollisionMode): THREE.Vector3;
 export { CAMERA_CONSTANTS };
 export declare const cameraUtils: {
     tempVectors: {

package/dist/core/camera/utils/camera.d.ts

@@ -2,10 +2,13 @@ import { RapierRigidBody } from '@react-three/rapier';
 import * as THREE from 'three';
 import { ActiveStateType } from '../../motions/core/types.js';
 import { CAMERA_CONSTANTS } from '../core/constants.js';
-import { CameraOptionType, CameraBounds, CollisionCheckResult, type CameraCollisionTargets } from '../core/types.js';
+import { CameraOptionType, CameraBounds, CollisionCheckResult, type CameraCollisionMode, type CameraCollisionTargets } from '../core/types.js';
 export declare function invalidateCollisionCache(): void;
-/** Frame hot path: writes the collision-safe camera position into `out` without collecting obstacles. */
-export declare function resolveCollisionPosition(from: THREE.Vector3, to: THREE.Vector3, scene: THREE.Scene, radius: number, excludedObjects: THREE.Object3D[] | undefined, out: THREE.Vector3, targets?: CameraCollisionTargets): THREE.Vector3;
+/**
+ * Frame hot path: writes the collision-safe camera position into `out` without collecting obstacles. `mode` is the
+ * camera's collision mode; fading meshes leave the position alone and are faded by the scene's occlusion fader.
+ */
+export declare function resolveCollisionPosition(from: THREE.Vector3, to: THREE.Vector3, scene: THREE.Scene, radius: number, excludedObjects: THREE.Object3D[] | undefined, out: THREE.Vector3, targets?: CameraCollisionTargets, mode?: CameraCollisionMode): THREE.Vector3;
 export { CAMERA_CONSTANTS };
 export declare const cameraUtils: {
     tempVectors: {

package/dist/core/camera/utils/sphereSweep.d.cts

@@ -11,7 +11,14 @@ export declare function sweepSphereBounds(mesh: Mesh, ray: Ray, radius: number,
  * ray.direction must be normalized. Infinity means no contact within maxDistance.
  */
 export declare function sweepSphereTriangle(ray: Ray, radius: number, surface: Triangle, maxDistance: number, point: Vector3): number;
+/**
+ * Receives every contact of a sweep that collects them, not only the nearest: the instance (-1 outside instanced and
+ * batched meshes), the index offset of the triangle's first corner, the distance, and the triangle's world normal turned
+ * toward the ray origin. The normal is reused by the next contact.
+ */
+export type SweepContact = (instance: number, offset: number, distance: number, normal: Vector3) => void;
 /** Mesh sweep uses exact triangles after a conservative world-AABB broad phase.
  * Output point is caller-owned. Animated vertices use Mesh.getVertexPosition.
+ * `onContact` also receives every contact within `maxDistance`, per instance and triangle.
  */
-export declare function sweepSphereMesh(mesh: Mesh, ray: Ray, radius: number, maxDistance: number, point: Vector3): number;
+export declare function sweepSphereMesh(mesh: Mesh, ray: Ray, radius: number, maxDistance: number, point: Vector3, onContact?: SweepContact): number;

package/dist/core/camera/utils/sphereSweep.d.ts

@@ -11,7 +11,14 @@ export declare function sweepSphereBounds(mesh: Mesh, ray: Ray, radius: number,
  * ray.direction must be normalized. Infinity means no contact within maxDistance.
  */
 export declare function sweepSphereTriangle(ray: Ray, radius: number, surface: Triangle, maxDistance: number, point: Vector3): number;
+/**
+ * Receives every contact of a sweep that collects them, not only the nearest: the instance (-1 outside instanced and
+ * batched meshes), the index offset of the triangle's first corner, the distance, and the triangle's world normal turned
+ * toward the ray origin. The normal is reused by the next contact.
+ */
+export type SweepContact = (instance: number, offset: number, distance: number, normal: Vector3) => void;
 /** Mesh sweep uses exact triangles after a conservative world-AABB broad phase.
  * Output point is caller-owned. Animated vertices use Mesh.getVertexPosition.
+ * `onContact` also receives every contact within `maxDistance`, per instance and triangle.
  */
-export declare function sweepSphereMesh(mesh: Mesh, ray: Ray, radius: number, maxDistance: number, point: Vector3): number;
+export declare function sweepSphereMesh(mesh: Mesh, ray: Ray, radius: number, maxDistance: number, point: Vector3, onContact?: SweepContact): number;

package/dist/core/editor/components/panels/CameraSettingsTab/types.d.cts

@@ -5,7 +5,7 @@ export type CameraSettingsMode = {
 };
 export type CameraSettingsFieldKind = 'range' | 'checkbox';
 export type CameraSettingsFieldValue = number | boolean;
-export type CameraSettingsFieldPath = 'xDistance' | 'yDistance' | 'zDistance' | 'fov' | 'enableZoom' | 'zoomSpeed' | 'minZoom' | 'maxZoom' | 'enableCollision' | 'enableFocus' | 'focusDistance' | 'smoothing.position' | 'smoothing.rotation' | 'smoothing.fov' | 'bounds.minY' | 'bounds.maxY';
+export type CameraSettingsFieldPath = 'xDistance' | 'yDistance' | 'zDistance' | 'fov' | 'enableZoom' | 'zoomSpeed' | 'minZoom' | 'maxZoom' | 'enableCollision' | 'collisionMode' | 'collisionFadeOpacity' | 'enableFocus' | 'focusDistance' | 'smoothing.position' | 'smoothing.rotation' | 'smoothing.fov' | 'bounds.minY' | 'bounds.maxY';
 export type CameraSettingsField = {
     key: string;
     label: string;

package/dist/core/editor/components/panels/CameraSettingsTab/types.d.ts

@@ -5,7 +5,7 @@ export type CameraSettingsMode = {
 };
 export type CameraSettingsFieldKind = 'range' | 'checkbox';
 export type CameraSettingsFieldValue = number | boolean;
-export type CameraSettingsFieldPath = 'xDistance' | 'yDistance' | 'zDistance' | 'fov' | 'enableZoom' | 'zoomSpeed' | 'minZoom' | 'maxZoom' | 'enableCollision' | 'enableFocus' | 'focusDistance' | 'smoothing.position' | 'smoothing.rotation' | 'smoothing.fov' | 'bounds.minY' | 'bounds.maxY';
+export type CameraSettingsFieldPath = 'xDistance' | 'yDistance' | 'zDistance' | 'fov' | 'enableZoom' | 'zoomSpeed' | 'minZoom' | 'maxZoom' | 'enableCollision' | 'collisionMode' | 'collisionFadeOpacity' | 'enableFocus' | 'focusDistance' | 'smoothing.position' | 'smoothing.rotation' | 'smoothing.fov' | 'bounds.minY' | 'bounds.maxY';
 export type CameraSettingsField = {
     key: string;
     label: string;

package/dist/core/rendering/postprocess/WorldPostProcessing.d.cts

@@ -1,10 +1,35 @@
 export type WorldPostProcessingProps = {
-    quality?: 'performance' | 'balanced' | 'quality';
+    /** Preset for the defaults below. `cinematic` is `quality` plus screen-space GI and reflections. */
+    quality?: 'performance' | 'balanced' | 'quality' | 'cinematic';
     antialias?: 'none' | 'traa';
     ambientOcclusion?: boolean;
     aoRadius?: number;
     aoSamples?: number;
     aoResolutionScale?: number;
+    /**
+     * Screen-space global illumination: one bounce of indirect diffuse light with its own occlusion, which takes the
+     * place of `ambientOcclusion`. Needs a WebGPU device and a perspective camera; elsewhere it stays off.
+     */
+    globalIllumination?: boolean;
+    /** World units a surface gathers bounced light and occlusion from. */
+    giRadius?: number;
+    /** Samples along each gathering direction, 1–32. Cost grows with it. */
+    giSteps?: number;
+    /** Strength of the bounced light. */
+    giIntensity?: number;
+    /** Fraction of the canvas resolution GI renders at, 0.25–1. */
+    giResolutionScale?: number;
+    /** Screen-space reflections on metals and glossy surfaces. Needs a WebGPU device; elsewhere it stays off. */
+    reflections?: boolean;
+    /** World units a reflected ray travels. */
+    reflectionDistance?: number;
+    /** Ray-march density, 0.05–1. Cost grows with it. */
+    reflectionQuality?: number;
+    reflectionIntensity?: number;
+    /** Fraction of the canvas resolution reflections render at, 0.25–1. */
+    reflectionResolutionScale?: number;
+    /** Surfaces rougher than this reflect nothing and march no rays. */
+    reflectionMaxRoughness?: number;
     /** Increment after teleport, world replacement, or authoritative network correction. */
     historyVersion?: number;
     bloomStrength?: number;

package/dist/core/rendering/postprocess/WorldPostProcessing.d.ts

@@ -1,10 +1,35 @@
 export type WorldPostProcessingProps = {
-    quality?: 'performance' | 'balanced' | 'quality';
+    /** Preset for the defaults below. `cinematic` is `quality` plus screen-space GI and reflections. */
+    quality?: 'performance' | 'balanced' | 'quality' | 'cinematic';
     antialias?: 'none' | 'traa';
     ambientOcclusion?: boolean;
     aoRadius?: number;
     aoSamples?: number;
     aoResolutionScale?: number;
+    /**
+     * Screen-space global illumination: one bounce of indirect diffuse light with its own occlusion, which takes the
+     * place of `ambientOcclusion`. Needs a WebGPU device and a perspective camera; elsewhere it stays off.
+     */
+    globalIllumination?: boolean;
+    /** World units a surface gathers bounced light and occlusion from. */
+    giRadius?: number;
+    /** Samples along each gathering direction, 1–32. Cost grows with it. */
+    giSteps?: number;
+    /** Strength of the bounced light. */
+    giIntensity?: number;
+    /** Fraction of the canvas resolution GI renders at, 0.25–1. */
+    giResolutionScale?: number;
+    /** Screen-space reflections on metals and glossy surfaces. Needs a WebGPU device; elsewhere it stays off. */
+    reflections?: boolean;
+    /** World units a reflected ray travels. */
+    reflectionDistance?: number;
+    /** Ray-march density, 0.05–1. Cost grows with it. */
+    reflectionQuality?: number;
+    reflectionIntensity?: number;
+    /** Fraction of the canvas resolution reflections render at, 0.25–1. */
+    reflectionResolutionScale?: number;
+    /** Surfaces rougher than this reflect nothing and march no rays. */
+    reflectionMaxRoughness?: number;
     /** Increment after teleport, world replacement, or authoritative network correction. */
     historyVersion?: number;
     bloomStrength?: number;

package/dist/core/rendering/postprocess/screenSpaceLighting.d.cts

@@ -0,0 +1,51 @@
+import { type Camera } from 'three';
+import type { Node, PassNode, TextureNode } from 'three/webgpu';
+type Tsl = typeof import('three/tsl');
+type GiModule = typeof import('three/addons/tsl/display/SSGINode.js');
+type ReflectionModule = typeof import('three/addons/tsl/display/SSRNode.js');
+type DenoiseModule = typeof import('three/addons/tsl/display/DenoiseNode.js');
+/** Uniform-only controls: changing them never rebuilds a shader or the pipeline. */
+export type ScreenSpaceLightingSettings = {
+    giRadius: number;
+    giSteps: number;
+    giIntensity: number;
+    giResolutionScale: number;
+    reflectionDistance: number;
+    reflectionQuality: number;
+    reflectionIntensity: number;
+    reflectionResolutionScale: number;
+    reflectionMaxRoughness: number;
+};
+export type ScreenSpaceLightingModules = {
+    gi: GiModule | null;
+    reflections: ReflectionModule | null;
+    denoise: DenoiseModule | null;
+};
+export type ScreenSpaceLighting = {
+    /** The scene colour with bounced light, its occlusion and reflections, drawn once per frame. */
+    color: TextureNode;
+    update(settings: ScreenSpaceLightingSettings): void;
+    dispose(): void;
+};
+type Disposable = {
+    dispose(): void;
+};
+/** Disposes every resource even when one throws, then rethrows the first failure. */
+export declare function disposeAll(resources: readonly (Disposable | null | undefined)[]): void;
+/** Loads the addons the enabled effects need; GI comes with the filter that smooths it. */
+export declare function loadScreenSpaceLighting(gi: boolean, reflections: boolean): Promise<ScreenSpaceLightingModules>;
+/**
+ * Scene-pass outputs the GI and reflection passes read, picked per material when its shader builds: `normal` holds the
+ * view normal and roughness, `surface` the base colour and metalness. Only standard and physical materials reflect
+ * (others write roughness 1), and unlit materials write black, so they receive no bounced light.
+ */
+export declare function surfaceOutputs(tsl: Tsl): {
+    normal: Node;
+    surface: Node;
+};
+/**
+ * Lumen-style screen-space lighting over a scene pass that writes `surfaceOutputs`. Both effects land in one texture,
+ * so temporal AA accumulates the GI noise and bloom reads the lit colour once.
+ */
+export declare function createScreenSpaceLighting(tsl: Tsl, modules: ScreenSpaceLightingModules, scenePass: PassNode, camera: Camera, temporal: boolean): ScreenSpaceLighting;
+export {};