@skewedaspect/sage 0.9.0-beta.9 → 0.9.0

package/dist/classes/bindings/toggle.d.ts

@@ -101,9 +101,10 @@ export declare class ToggleBinding implements Binding {
      */
     process(state: InputState, eventBus: GameEventBus): void;
     /**
-     * Reset edge-detection state so the next input is evaluated from a clean baseline.
+     * Reset edge-detection state for a context activation. When a state is provided, primes from the current physical
+     * input so that already-held inputs don't produce phantom edges in the newly activated context.
      */
-    resetEdgeState(): void;
+    resetEdgeState(state?: InputState): void;
     /**
      * Reset toggle to its initial state
      */

package/dist/classes/bindings/trigger.d.ts

@@ -70,9 +70,10 @@ export declare class TriggerBinding implements Binding {
      */
     process(state: InputState, eventBus: GameEventBus): void;
     /**
-     * Reset edge-detection state so the next input is evaluated from a clean baseline.
+     * Reset edge-detection state for a context activation. When a state is provided, primes from the current physical
+     * input so that already-held inputs don't produce phantom rising edges in the newly activated context.
      */
-    resetEdgeState(): void;
+    resetEdgeState(state?: InputState): void;
     /**
      * Returns a JSON-serializable representation of this trigger binding.
      */

package/dist/classes/bindings/value.d.ts

@@ -96,7 +96,7 @@ export declare class ValueBinding implements Binding {
     /**
      * No-op for value bindings — they have no edge-detection state to reset.
      */
-    resetEdgeState(): void;
+    resetEdgeState(_state?: InputState): void;
     /**
      * Returns a JSON-serializable representation of this value binding.
      */

package/dist/classes/entity.d.ts

@@ -188,6 +188,19 @@ export declare class GameEntity<EntityState extends object = object> implements
      * @internal
      */
     $detachFromNode(): void;
+    /**
+     * Add this entity to a named outline layer for visual highlighting.
+     * Requires the entity to be attached to a node in a level with outlines configured.
+     *
+     * @param layerName - The name of the outline layer (must exist on the current level)
+     */
+    highlight(layerName: string): void;
+    /**
+     * Remove this entity from an outline layer, or from all layers if no name given.
+     *
+     * @param layerName - Specific layer to remove from, or omit to remove from all
+     */
+    unhighlight(layerName?: string): void;
     /**
      * Adds a child entity to this entity's hierarchy.
      * Sets the child's parent to this entity. If both entities have nodes, parents the child's node.

package/dist/classes/gameEngine.d.ts

@@ -57,6 +57,7 @@ export declare class GameEngine {
     logger: LoggingUtility;
     raycast: RaycastHelper;
     timer: GameTimer;
+    largeWorldRendering: boolean;
     started: boolean;
     private _log;
     private _beforeStartHook;
@@ -72,7 +73,7 @@ export declare class GameEngine {
      * @param engines
      * @param managers
      */
-    constructor(canvas: GameCanvas, renderEngine: AbstractEngine, physics: HavokPlugin, eventBus: GameEventBus, logger: LoggingUtility, raycast: RaycastHelper, timer: GameTimer, engines: Engines, managers: Managers);
+    constructor(canvas: GameCanvas, renderEngine: AbstractEngine, physics: HavokPlugin, eventBus: GameEventBus, logger: LoggingUtility, raycast: RaycastHelper, timer: GameTimer, engines: Engines, managers: Managers, largeWorldRendering?: boolean);
     /**
      * Register a function to be called before the game engine starts
      * @param hook

package/dist/classes/gameLevel.d.ts

@@ -1,5 +1,4 @@
-import { Scene, TransformNode, Vector3 } from '@babylonjs/core';
-import { StaticSound } from '@babylonjs/core/AudioV2/abstractAudio/staticSound';
+import { Scene, StaticSound, TransformNode, Vector3 } from '@babylonjs/core';
 import { LevelConfig, LevelContext } from "../interfaces/level.d.ts";
 import { GameEntity } from "./entity.d.ts";
 import { Level } from "./level.d.ts";
@@ -54,6 +53,14 @@ export declare class GameLevel extends Level {
      * Import all meshes from the configured scene file (GLB/GLTF/Babylon) into the scene.
      */
     private _loadSceneFile;
+    /**
+     * Extract the scene file path from the config, which can be a string or SceneConfig object.
+     */
+    private _getScenePath;
+    /**
+     * Check if the scene config specifies a right-handed coordinate system.
+     */
+    private _isRightHanded;
     /**
      * Set up the scene environment: IBL (image-based lighting) for PBR reflections and/or a visible skybox.
      */
@@ -89,6 +96,11 @@ export declare class GameLevel extends Level {
      * Apply shared light properties from a config to an existing light.
      */
     private _applyLightConfig;
+    /**
+     * Set up clustered lighting: create a container, move eligible lights into it,
+     * and fix PBR material falloff for compatibility.
+     */
+    private _setupClustering;
     private _toVector3;
     private _toColor3;
     /**

package/dist/classes/input/mouse.d.ts

@@ -50,21 +50,23 @@ export declare class MouseInputPlugin {
      */
     $teardown(): Promise<void>;
     /**
-     * Set up mouse event listeners
+     * Set up pointer and wheel event listeners. We use pointer events instead of mouse events
+     * because BabylonJS calls preventDefault() on pointerdown, which suppresses the
+     * corresponding mousedown/mouseup per the Pointer Events spec.
      */
     private _setupMouseEvents;
     /**
-     * Handle mouse button down events
+     * Handle pointer down events (mouse buttons)
      */
-    private _handleMouseDown;
+    private _handlePointerDown;
     /**
-     * Handle mouse button up events
+     * Handle pointer up events (mouse buttons)
      */
-    private _handleMouseUp;
+    private _handlePointerUp;
     /**
-     * Handle mouse move events
+     * Handle pointer move events (mouse position)
      */
-    private _handleMouseMove;
+    private _handlePointerMove;
     /**
      * Handle mouse wheel events
      */

package/dist/classes/level.d.ts

@@ -1,7 +1,9 @@
 import { Scene } from '@babylonjs/core';
+import { ClusteredLightContainer } from '@babylonjs/core/Lights/Clustered/clusteredLightContainer';
 import { LoggerInterface } from "../interfaces/logger.d.ts";
 import { LevelConfig, LevelContext, LevelInstance, PropertyHandler } from "../interfaces/level.d.ts";
 import { GameEngine } from "./gameEngine.d.ts";
+import { OutlineManager } from "../managers/outline.d.ts";
 /**
  * Abstract base class for game levels.
  *
@@ -25,6 +27,8 @@ export declare abstract class Level implements LevelInstance {
     protected readonly _log: LoggerInterface;
     protected readonly _context: LevelContext;
     protected _scene: Scene | null;
+    clusteredLights: ClusteredLightContainer | null;
+    outlines: OutlineManager | null;
     /**
      * Creates a new Level instance.
      *

package/dist/engines/audio.d.ts

@@ -1,5 +1,4 @@
-import { AudioBus } from '@babylonjs/core/AudioV2/abstractAudio/audioBus';
-import { IStaticSoundOptions, StaticSound } from '@babylonjs/core/AudioV2/abstractAudio/staticSound';
+import { AudioBus, IStaticSoundOptions, StaticSound } from '@babylonjs/core';
 import { Disposable } from "../interfaces/lifecycle.d.ts";
 import { LoggingUtility } from "../utils/logger.d.ts";
 export declare class AudioEngine implements Disposable {

package/dist/engines/scene.d.ts

@@ -1,4 +1,4 @@
-import { AbstractEngine, AbstractMesh, AssetContainer, DirectionalLight, FreeCamera, HemisphericLight, Light, Mesh, PhysicsAggregate, PhysicsShapeType, PointLight, Scene, SpotLight, Vector3 } from '@babylonjs/core';
+import { AbstractEngine, AbstractMesh, AssetContainer, DirectionalLight, FreeCamera, HemisphericLight, Light, Mesh, PhysicsAggregate, PhysicsShapeType, PointLight, RectAreaLight, Scene, SpotLight, Vector3 } from '@babylonjs/core';
 import { HavokPhysicsWithBindings } from '@babylonjs/havok';
 import { GameCanvas } from "../interfaces/game.d.ts";
 import { Disposable } from "../interfaces/lifecycle.d.ts";
@@ -13,7 +13,7 @@ export declare class SceneEngine implements Disposable {
      * Creates a new scene with physics enabled
      */
     createScene(): Scene;
-    enablePhysics(scene: Scene, gravityVector?: Vector3): void;
+    enablePhysics(scene: Scene, gravityVector?: Vector3, floatingOriginWorldRadius?: number): void;
     /**
      * Creates a free camera at the specified position, targeting the origin. Attaches controls to the provided
      * canvas, or falls back to the engine's default canvas.
@@ -58,6 +58,16 @@ export declare class SceneEngine implements Disposable {
      * @param intensity - Default: 1.0
      */
     createSpotLight(name: string, position: Vector3, direction: Vector3, angle: number, exponent: number, scene: Scene, intensity?: number): SpotLight;
+    /**
+     * Creates a rectangular area light (emits from a flat rectangle in the -Z direction)
+     * @param name
+     * @param position
+     * @param width
+     * @param height
+     * @param scene
+     * @param intensity - Default: 1.0
+     */
+    createRectAreaLight(name: string, position: Vector3, width: number, height: number, scene: Scene, intensity?: number): RectAreaLight;
     /**
      * Creates a sphere mesh. Defaults: diameter 1, 32 segments.
      * @param name

package/dist/handlers/collider.d.ts

@@ -5,6 +5,9 @@ import { LevelManager } from "../managers/level.d.ts";
  * Supports the following properties on scene nodes:
  * - `collider` (string): Collider type - "box", "sphere", "mesh", or "none"
  * - `collider_mesh` (boolean): On a child node, marks it as the collision source for parent's "mesh" collider
+ * - `collider_mass` (number): Mass for the physics body. Defaults to 0 (static). Set > 0 for dynamic bodies.
+ * - `collider_kinematic` (boolean): When true, sets `disablePreStep = false` so the physics body
+ *   tracks mesh transform each frame. Required for animated colliders (doors, elevators, platforms).
  *
  * For "mesh" colliders, if a child node has `collider_mesh: true`, that child's geometry
  * is used for collision and the child is made invisible.

package/dist/handlers/postProcessing.d.ts

@@ -1,9 +1,3 @@
 import { Scene } from '@babylonjs/core';
 import { PostProcessingConfig } from "../interfaces/level.d.ts";
-/**
- * Apply post-processing effects to a scene based on a declarative config.
- * Creates BabylonJS rendering pipelines and configures them according to the provided settings.
- *
- * This is a level-config handler, not a node property handler.
- */
-export declare function applyPostProcessing(scene: Scene, config: PostProcessingConfig): void;
+export declare function applyPostProcessing(scene: Scene, config: PostProcessingConfig): Promise<void>;

package/dist/handlers/postProcessingFrameGraph.d.ts

@@ -0,0 +1,3 @@
+import { Scene } from '@babylonjs/core';
+import { PostProcessingConfig } from "../interfaces/level.d.ts";
+export declare function applyFrameGraphPostProcessing(scene: Scene, config: PostProcessingConfig): Promise<void>;

package/dist/handlers/postProcessingPipeline.d.ts

@@ -0,0 +1,9 @@
+import { Scene } from '@babylonjs/core';
+import { PostProcessingConfig } from "../interfaces/level.d.ts";
+/**
+ * Apply post-processing effects to a scene based on a declarative config.
+ * Creates BabylonJS rendering pipelines and configures them according to the provided settings.
+ *
+ * This is a level-config handler, not a node property handler.
+ */
+export declare function applyPipelinePostProcessing(scene: Scene, config: PostProcessingConfig): void;

package/dist/interfaces/binding.d.ts

@@ -109,10 +109,13 @@ export interface Binding {
      */
     process(state: InputState, eventBus: GameEventBus): void;
     /**
-     * Reset any internal edge-detection state. Called when a binding's context is reactivated so that stale state
-     * from a previous activation doesn't swallow the first input event.
+     * Reset edge-detection state for a context activation. When an input state is provided, the binding primes its
+     * internal state from the current physical input so that already-held inputs don't produce phantom edges. Without
+     * a state, resets to a clean baseline (false).
+     *
+     * @param state - Last known input state for this binding's device, if available
      */
-    resetEdgeState(): void;
+    resetEdgeState(state?: InputState): void;
     /**
      * Convert the binding to a JSON-serializable object.
      */

package/dist/interfaces/game.d.ts

@@ -25,4 +25,10 @@ export interface SageOptions {
     logLevel?: LogLevel;
     /** Audio channel names. If provided, SAGE initializes AudioV2 with one bus per channel. */
     audioChannels?: string[];
+    /**
+     * Enable Large World Rendering for scenes with coordinates far from origin.
+     * Uses float64 CPU matrices and floating origin to prevent GPU precision loss.
+     * Also enables multi-region Havok physics when physics are active.
+     */
+    largeWorldRendering?: boolean;
 }

package/dist/interfaces/level.d.ts

@@ -36,6 +36,10 @@ export interface LevelContext {
 export interface SpawnDefinition {
     /** The entity type name to spawn */
     entity: string;
+    /** Optional human-readable name for the spawned entity instance. */
+    name?: string;
+    /** Tags to apply to the spawned entity (merged with definition tags). */
+    tags?: string[];
     /** Additional configuration passed to the entity's initial state */
     config?: Record<string, unknown>;
 }
@@ -44,17 +48,36 @@ export interface SpawnDefinition {
  * Used to configure entities that are marked with the 'entity' property in scene files.
  */
 export interface EntityDefinition {
+    /** Optional name override for the entity (overrides the scene node name). */
+    name?: string;
+    /** Tags to apply to the entity (merged with definition tags). */
+    tags?: string[];
     /** Additional configuration passed to the entity's initial state */
     config?: Record<string, unknown>;
 }
+/**
+ * Configuration for loading a scene file.
+ * Can be a simple string path (backward compatible) or an object with options.
+ */
+export interface SceneConfig {
+    /** Path to the scene file (.glb, .gltf, .babylon, etc.) */
+    path: string;
+    /**
+     * Whether the scene data is in a right-handed coordinate system.
+     * When true, sets `scene.useRightHandedSystem = true` before loading,
+     * which tells BabylonJS to interpret all coordinates as right-handed.
+     * Typically needed for .babylon files exported from Blender.
+     */
+    rightHanded?: boolean;
+}
 /**
  * Configuration for a game level loaded from YAML
  */
 export interface LevelConfig {
     /** The name of the level */
     name: string;
-    /** Path to the scene file (.glb, .babylon) */
-    scene?: string;
+    /** Scene file path, or configuration object with path and options */
+    scene?: string | SceneConfig;
     /** Name of a registered custom Level class to use instead of GameLevel */
     class?: string;
     /** Configuration passed to custom Level class */
@@ -89,6 +112,10 @@ export interface LevelConfig {
     sounds?: Record<string, LevelSoundConfig>;
     /** Post-processing effects configuration */
     postProcessing?: PostProcessingConfig;
+    /** Clustered lighting configuration for many-light scenes */
+    clustering?: ClusteringConfig;
+    /** Named outline layers for entity highlighting */
+    outlines?: Record<string, OutlineLayerConfig>;
 }
 /**
  * Reusable 3D vector config for positions, directions, and rotations.
@@ -112,7 +139,7 @@ export interface ColorConfig {
  */
 export interface CameraDefinition {
     /** Camera type (required for create mode, omit for override mode) */
-    type?: 'free' | 'arcRotate' | 'universal';
+    type?: 'free' | 'arcRotate' | 'universal' | 'geospatial';
     /** Mark as the active camera for this level */
     active?: boolean;
     /** Attach canvas input controls */
@@ -135,6 +162,17 @@ export interface CameraDefinition {
     lowerBetaLimit?: number;
     upperBetaLimit?: number;
     wheelPrecision?: number;
+    planetRadius?: number;
+    yaw?: number;
+    pitch?: number;
+    center?: Vec3Config;
+    checkCollisions?: boolean;
+    radiusMin?: number;
+    radiusMax?: number;
+    pitchMin?: number;
+    pitchMax?: number;
+    yawMin?: number;
+    yawMax?: number;
 }
 /**
  * Configuration for a single light. If `type` is present, a new light is created.
@@ -142,7 +180,7 @@ export interface CameraDefinition {
  */
 export interface LightDefinition {
     /** Light type (required for create mode, omit for override mode) */
-    type?: 'hemispheric' | 'directional' | 'point' | 'spot';
+    type?: 'hemispheric' | 'directional' | 'point' | 'spot' | 'rectarea';
     intensity?: number;
     diffuse?: ColorConfig;
     specular?: ColorConfig;
@@ -151,6 +189,8 @@ export interface LightDefinition {
     groundColor?: ColorConfig;
     angle?: number;
     exponent?: number;
+    width?: number;
+    height?: number;
 }
 /**
  * Configuration for the scene environment: skybox visuals and IBL (image-based lighting) for PBR reflections.
@@ -192,6 +232,11 @@ export interface LevelSoundConfig {
  * Configuration for post-processing effects applied to a level's scene.
  */
 export interface PostProcessingConfig {
+    /**
+     * Rendering backend. 'pipeline' uses DefaultRenderingPipeline, 'frameGraph' uses Frame Graph.
+     * Default: 'pipeline'.
+     */
+    renderer?: 'pipeline' | 'frameGraph';
     bloom?: {
         weight?: number;
         threshold?: number;
@@ -226,6 +271,32 @@ export interface PostProcessingConfig {
         edge?: number;
         color?: number;
     };
+    /** Volumetric lighting (Frame Graph only). Warns if used with pipeline renderer */
+    volumetric?: {
+        extinction?: number;
+        scattering?: number;
+    };
+}
+/**
+ * Configuration for clustered lighting. When enabled, all eligible point and spot lights
+ * are rendered via a screen-space clustering system for improved multi-light performance.
+ * Hemispheric, directional, and rect area lights are unaffected.
+ */
+export interface ClusteringConfig {
+    enabled: boolean;
+    horizontalTiles?: number;
+    verticalTiles?: number;
+    depthSlices?: number;
+    maxRange?: number;
+}
+/**
+ * Configuration for a named selection outline layer.
+ * Defines the visual style for screen-space entity outlines.
+ */
+export interface OutlineLayerConfig {
+    color?: ColorConfig;
+    thickness?: number;
+    occlusionStrength?: number;
 }
 /**
  * Constructor signature for Level classes.

package/dist/managers/audio.d.ts

@@ -1,4 +1,4 @@
-import { IStaticSoundOptions, StaticSound } from '@babylonjs/core/AudioV2/abstractAudio/staticSound';
+import { IStaticSoundOptions, StaticSound } from '@babylonjs/core';
 import { AudioEngine } from "../engines/audio.d.ts";
 import { Disposable } from "../interfaces/lifecycle.d.ts";
 import { LoggingUtility } from "../utils/logger.d.ts";

package/dist/managers/binding.d.ts

@@ -35,6 +35,8 @@ export declare class BindingManager implements Disposable {
     private _activeContexts;
     /** The most recent device type that produced intentional input */
     private _lastActiveDeviceType;
+    /** Last input state per device, used to prime edge state on context activation */
+    private _lastInputState;
     /** Active captureInput() state, or null when not capturing */
     private _captureState;
     /** Event bus for handling game events */

package/dist/managers/outline.d.ts

@@ -0,0 +1,16 @@
+import { Scene, SelectionOutlineLayer } from '@babylonjs/core';
+import { GameEntity } from "../classes/entity.d.ts";
+import { OutlineLayerConfig } from "../interfaces/level.d.ts";
+export declare class OutlineManager {
+    private _scene;
+    private _layers;
+    constructor(scene: Scene, configs?: Record<string, OutlineLayerConfig>);
+    get(name: string): SelectionOutlineLayer | undefined;
+    create(name: string, config?: OutlineLayerConfig): SelectionOutlineLayer;
+    highlightEntity(layerName: string, entity: GameEntity): void;
+    unhighlightEntity(layerName: string, entity: GameEntity): void;
+    unhighlightEntityAll(entity: GameEntity): void;
+    clear(layerName: string): void;
+    dispose(): void;
+    private _rebuildSelection;
+}

package/dist/postProcessingFrameGraph-CaMgQzR-.js

@@ -0,0 +1,70 @@
+import { Constants as e, FrameGraph as t, FrameGraphBloomTask as n, FrameGraphChromaticAberrationTask as r, FrameGraphClearTextureTask as i, FrameGraphCopyToBackbufferColorTask as a, FrameGraphGeometryRendererTask as o, FrameGraphGrainTask as s, FrameGraphImageProcessingTask as c, FrameGraphObjectRendererTask as l, FrameGraphSSAO2RenderingPipelineTask as u, FrameGraphSharpenTask as d, ImageProcessingConfiguration as f } from "@babylonjs/core";
+//#region src/handlers/postProcessingFrameGraph.ts
+var p = {
+	hable: f.TONEMAPPING_STANDARD,
+	reinhard: f.TONEMAPPING_STANDARD,
+	hejidawson: f.TONEMAPPING_STANDARD,
+	photographic: f.TONEMAPPING_STANDARD,
+	aces: f.TONEMAPPING_ACES
+};
+async function m(m, h) {
+	let g = m.activeCamera;
+	if (!g) return;
+	let _ = m.getEngine(), v = new t(m), y = v.textureManager.createRenderTargetTexture("sage-fg-color", {
+		size: {
+			width: 100,
+			height: 100
+		},
+		sizeIsPercentage: !0,
+		options: {
+			formats: [e.TEXTUREFORMAT_RGBA],
+			samples: 4
+		}
+	}), b = new i("sage-clear", v);
+	b.targetTexture = y, v.addTask(b);
+	let x = new l("sage-render", v, m);
+	x.targetTexture = b.outputTexture, x.depthTexture = b.outputDepthTexture, x.camera = g, x.objectList = {
+		meshes: m.meshes,
+		particleSystems: m.particleSystems
+	}, x.isMainObjectRenderer = !0, v.addTask(x);
+	let S = x.outputTexture;
+	if (h.ssao) {
+		let e = new o("sage-geometry", v, m);
+		v.addTask(e);
+		let t = new u("sage-ssao", v, .5, 1);
+		t.sourceTexture = S, t.depthTexture = e.geometryViewDepthTexture, t.normalTexture = e.geometryViewNormalTexture, t.camera = g, v.addTask(t), h.ssao.radius !== void 0 && (t.ssao.radius = h.ssao.radius), h.ssao.samples !== void 0 && (t.ssao.samples = h.ssao.samples), h.ssao.totalStrength !== void 0 && (t.ssao.totalStrength = h.ssao.totalStrength), S = t.outputTexture;
+	}
+	if (h.bloom) {
+		let e = new n("sage-bloom", v, h.bloom.weight ?? .5, h.bloom.kernel ?? 128, h.bloom.threshold ?? .1, !0, h.bloom.scale ?? .5);
+		e.sourceTexture = S, v.addTask(e), S = e.outputTexture;
+	}
+	if (h.grain) {
+		let e = new s("sage-grain", v);
+		e.sourceTexture = S, v.addTask(e), h.grain.intensity !== void 0 && (e.postProcess.intensity = h.grain.intensity), h.grain.animated !== void 0 && (e.postProcess.animated = h.grain.animated), S = e.outputTexture;
+	}
+	if (h.sharpen) {
+		let e = new d("sage-sharpen", v);
+		e.sourceTexture = S, v.addTask(e), h.sharpen.edge !== void 0 && (e.postProcess.edgeAmount = h.sharpen.edge), h.sharpen.color !== void 0 && (e.postProcess.colorAmount = h.sharpen.color), S = e.outputTexture;
+	}
+	if (h.chromaticAberration) {
+		let e = new r("sage-chromab", v);
+		e.sourceTexture = S, v.addTask(e), h.chromaticAberration.amount !== void 0 && (e.postProcess.aberrationAmount = h.chromaticAberration.amount), S = e.outputTexture;
+	}
+	if (h.tonemap || h.vignette) {
+		let e = new c("sage-imgproc", v);
+		if (e.sourceTexture = S, v.addTask(e), h.tonemap && (e.postProcess.toneMappingEnabled = !0, h.tonemap.operator && (e.postProcess.toneMappingType = p[h.tonemap.operator] ?? f.TONEMAPPING_STANDARD)), h.vignette && (e.postProcess.vignetteEnabled = !0, h.vignette.weight !== void 0 && (e.postProcess.vignetteWeight = h.vignette.weight), h.vignette.stretch !== void 0 && (e.postProcess.vignetteStretch = h.vignette.stretch), h.vignette.color)) {
+			let t = h.vignette.color;
+			e.postProcess.vignetteColor.set(t.r, t.g, t.b, 1);
+		}
+		S = e.outputTexture;
+	}
+	h.volumetric && console.warn("[SAGE] Volumetric lighting config is recognized but automatic light detection is not yet supported. Use scene.frameGraph to add FrameGraphVolumetricLightingTask manually.");
+	let C = new a("sage-output", v);
+	C.sourceTexture = S, v.addTask(C), m.cameraToUseForPointers = g, m.frameGraph = v, _.onResizeObservable.add(async () => {
+		await v.buildAsync();
+	}), await v.buildAsync();
+}
+//#endregion
+export { m as applyFrameGraphPostProcessing };
+
+//# sourceMappingURL=postProcessingFrameGraph-CaMgQzR-.js.map

package/dist/postProcessingFrameGraph-CaMgQzR-.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"postProcessingFrameGraph-CaMgQzR-.js","names":[],"sources":["../src/handlers/postProcessingFrameGraph.ts"],"sourcesContent":["//----------------------------------------------------------------------------------------------------------------------\n// Frame Graph Post-Processing Backend\n//\n// Builds a directed task chain using BabylonJS Frame Graph system.\n// Each post-processing effect is a separate task chained via texture handles.\n//----------------------------------------------------------------------------------------------------------------------\n\nimport {\n    Constants,\n    FrameGraph,\n    FrameGraphBloomTask,\n    FrameGraphChromaticAberrationTask,\n    FrameGraphClearTextureTask,\n    FrameGraphCopyToBackbufferColorTask,\n    FrameGraphGeometryRendererTask,\n    FrameGraphGrainTask,\n    FrameGraphImageProcessingTask,\n    FrameGraphObjectRendererTask,\n    FrameGraphSSAO2RenderingPipelineTask,\n    FrameGraphSharpenTask,\n    type FrameGraphTextureHandle,\n    ImageProcessingConfiguration,\n    type Scene,\n} from '@babylonjs/core';\n\nimport type { PostProcessingConfig } from '../interfaces/level.ts';\n\n//----------------------------------------------------------------------------------------------------------------------\n\n/**\n * Map from user-facing tonemap operator names to BabylonJS constants.\n * BabylonJS only has STANDARD (0) and ACES (1) — the other names all map to STANDARD.\n */\nconst TONEMAP_OPERATORS : Record<string, number> = {\n    hable: ImageProcessingConfiguration.TONEMAPPING_STANDARD,\n    reinhard: ImageProcessingConfiguration.TONEMAPPING_STANDARD,\n    hejidawson: ImageProcessingConfiguration.TONEMAPPING_STANDARD,\n    photographic: ImageProcessingConfiguration.TONEMAPPING_STANDARD,\n    aces: ImageProcessingConfiguration.TONEMAPPING_ACES,\n};\n\n//----------------------------------------------------------------------------------------------------------------------\n\nexport async function applyFrameGraphPostProcessing(scene : Scene, config : PostProcessingConfig) : Promise<void>\n{\n    const camera = scene.activeCamera;\n    if(!camera)\n    {\n        return;\n    }\n\n    const engine = scene.getEngine();\n    const fg = new FrameGraph(scene);\n\n    // Create the main render target texture\n    const colorTexture = fg.textureManager.createRenderTargetTexture('sage-fg-color', {\n        size: { width: 100, height: 100 },\n        sizeIsPercentage: true,\n        options: { formats: [ Constants.TEXTUREFORMAT_RGBA ], samples: 4 },\n    });\n\n    // 1. Clear\n    const clearTask = new FrameGraphClearTextureTask('sage-clear', fg);\n    clearTask.targetTexture = colorTexture;\n    fg.addTask(clearTask);\n\n    // 2. Render objects\n    const renderTask = new FrameGraphObjectRendererTask('sage-render', fg, scene);\n    renderTask.targetTexture = clearTask.outputTexture;\n    renderTask.depthTexture = clearTask.outputDepthTexture;\n    renderTask.camera = camera;\n    renderTask.objectList = { meshes: scene.meshes, particleSystems: scene.particleSystems };\n    renderTask.isMainObjectRenderer = true;\n    fg.addTask(renderTask);\n\n    // Track the current output texture through the chain\n    let currentTexture : FrameGraphTextureHandle = renderTask.outputTexture;\n\n    // 3. SSAO (needs geometry renderer for depth/normals)\n    if(config.ssao)\n    {\n        const geoTask = new FrameGraphGeometryRendererTask('sage-geometry', fg, scene);\n        fg.addTask(geoTask);\n\n        const ssaoTask = new FrameGraphSSAO2RenderingPipelineTask('sage-ssao', fg, 0.5, 1.0);\n        ssaoTask.sourceTexture = currentTexture;\n        ssaoTask.depthTexture = geoTask.geometryViewDepthTexture;\n        ssaoTask.normalTexture = geoTask.geometryViewNormalTexture;\n        ssaoTask.camera = camera;\n        fg.addTask(ssaoTask);\n\n        if(config.ssao.radius !== undefined) { ssaoTask.ssao.radius = config.ssao.radius; }\n        if(config.ssao.samples !== undefined) { ssaoTask.ssao.samples = config.ssao.samples; }\n        if(config.ssao.totalStrength !== undefined) { ssaoTask.ssao.totalStrength = config.ssao.totalStrength; }\n\n        currentTexture = ssaoTask.outputTexture;\n    }\n\n    // 4. Bloom\n    if(config.bloom)\n    {\n        const bloomTask = new FrameGraphBloomTask(\n            'sage-bloom',\n            fg,\n            config.bloom.weight ?? 0.5,\n            config.bloom.kernel ?? 128,\n            config.bloom.threshold ?? 0.1,\n            true,\n            config.bloom.scale ?? 0.5\n        );\n        bloomTask.sourceTexture = currentTexture;\n        fg.addTask(bloomTask);\n\n        currentTexture = bloomTask.outputTexture;\n    }\n\n    // 5. Grain\n    if(config.grain)\n    {\n        const grainTask = new FrameGraphGrainTask('sage-grain', fg);\n        grainTask.sourceTexture = currentTexture;\n        fg.addTask(grainTask);\n\n        if(config.grain.intensity !== undefined) { grainTask.postProcess.intensity = config.grain.intensity; }\n        if(config.grain.animated !== undefined) { grainTask.postProcess.animated = config.grain.animated; }\n\n        currentTexture = grainTask.outputTexture;\n    }\n\n    // 6. Sharpen\n    if(config.sharpen)\n    {\n        const sharpenTask = new FrameGraphSharpenTask('sage-sharpen', fg);\n        sharpenTask.sourceTexture = currentTexture;\n        fg.addTask(sharpenTask);\n\n        if(config.sharpen.edge !== undefined) { sharpenTask.postProcess.edgeAmount = config.sharpen.edge; }\n        if(config.sharpen.color !== undefined) { sharpenTask.postProcess.colorAmount = config.sharpen.color; }\n\n        currentTexture = sharpenTask.outputTexture;\n    }\n\n    // 7. Chromatic aberration\n    if(config.chromaticAberration)\n    {\n        const chromTask = new FrameGraphChromaticAberrationTask('sage-chromab', fg);\n        chromTask.sourceTexture = currentTexture;\n        fg.addTask(chromTask);\n\n        if(config.chromaticAberration.amount !== undefined)\n        {\n            chromTask.postProcess.aberrationAmount = config.chromaticAberration.amount;\n        }\n\n        currentTexture = chromTask.outputTexture;\n    }\n\n    // 8. Image processing (tonemap + vignette)\n    if(config.tonemap || config.vignette)\n    {\n        const imgTask = new FrameGraphImageProcessingTask('sage-imgproc', fg);\n        imgTask.sourceTexture = currentTexture;\n        fg.addTask(imgTask);\n\n        if(config.tonemap)\n        {\n            imgTask.postProcess.toneMappingEnabled = true;\n\n            if(config.tonemap.operator)\n            {\n                imgTask.postProcess.toneMappingType\n                    = TONEMAP_OPERATORS[config.tonemap.operator]\n                    ?? ImageProcessingConfiguration.TONEMAPPING_STANDARD;\n            }\n        }\n\n        if(config.vignette)\n        {\n            imgTask.postProcess.vignetteEnabled = true;\n\n            if(config.vignette.weight !== undefined) { imgTask.postProcess.vignetteWeight = config.vignette.weight; }\n            if(config.vignette.stretch !== undefined)\n            {\n                imgTask.postProcess.vignetteStretch = config.vignette.stretch;\n            }\n            if(config.vignette.color)\n            {\n                const vc = config.vignette.color;\n                imgTask.postProcess.vignetteColor.set(vc.r, vc.g, vc.b, 1);\n            }\n        }\n\n        currentTexture = imgTask.outputTexture;\n    }\n\n    // 9. Volumetric lighting — not yet wired up for automatic light detection\n    if(config.volumetric)\n    {\n        console.warn(\n            '[SAGE] Volumetric lighting config is recognized but automatic light detection is not yet supported. '\n            + 'Use scene.frameGraph to add FrameGraphVolumetricLightingTask manually.'\n        );\n    }\n\n    // 10. Output to screen\n    const copyTask = new FrameGraphCopyToBackbufferColorTask('sage-output', fg);\n    copyTask.sourceTexture = currentTexture;\n    fg.addTask(copyTask);\n\n    // Wire up the scene — cameraToUseForPointers is needed because activeCamera becomes null between tasks\n    scene.cameraToUseForPointers = camera;\n    scene.frameGraph = fg;\n\n    // Rebuild on resize\n    engine.onResizeObservable.add(async () =>\n    {\n        await fg.buildAsync();\n    });\n\n    // Initial build\n    await fg.buildAsync();\n}\n\n//----------------------------------------------------------------------------------------------------------------------\n"],"mappings":"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"}

package/dist/sage.d.ts

@@ -38,6 +38,7 @@ export type { CreateEntityOptions } from "./managers/entity.d.ts";
 export type { TransitionOptions } from "./managers/level.d.ts";
 export { AudioManager } from "./managers/audio.d.ts";
 export type { ChannelInfo } from "./managers/audio.d.ts";
+export { OutlineManager } from "./managers/outline.d.ts";
 export { SaveManager } from "./managers/save.d.ts";
 export type { SaveData, SerializedEntity } from "./managers/save.d.ts";
 export { generateId } from "./utils/id.d.ts";