@zephyr3d/scene 0.9.27 → 0.10.0

package/dist/scene/physics_settings.js

@@ -0,0 +1,157 @@
+import { Vector3 } from '@zephyr3d/base';
+
+/** Number of collision layers. @public */ const PHYSICS_LAYER_COUNT = 16;
+const ALL_LAYERS = (1 << PHYSICS_LAYER_COUNT) - 1;
+/**
+ * Physics settings saved with a scene.
+ *
+ * @remarks
+ * Plain data: the scene package does not simulate anything. A physics package
+ * reads these when it simulates the scene, and picks up later changes through
+ * {@link ScenePhysicsSettings.version}. A scene without settings
+ * ({@link Scene.physicsSettings} null) uses the physics package's defaults,
+ * which match the defaults here.
+ *
+ * @public
+ */ class ScenePhysicsSettings {
+    _gravity;
+    _fixedTimeStep;
+    _maxSubSteps;
+    _interpolation;
+    _waitForCollidersOnStart;
+    _layerNames;
+    _layerMasks;
+    _version;
+    constructor(){
+        this._gravity = new Vector3(0, -9.81, 0);
+        this._fixedTimeStep = 1 / 60;
+        this._maxSubSteps = 8;
+        this._interpolation = true;
+        this._waitForCollidersOnStart = true;
+        this._layerNames = Array.from({
+            length: PHYSICS_LAYER_COUNT
+        }, (_, i)=>ScenePhysicsSettings.defaultLayerName(i));
+        this._layerMasks = new Array(PHYSICS_LAYER_COUNT).fill(ALL_LAYERS);
+        this._version = 0;
+    }
+    /** Name a layer has until renamed. */ static defaultLayerName(layer) {
+        return layer === 0 ? 'Default' : `Layer ${layer}`;
+    }
+    /** Increases whenever a setting changes. */ get version() {
+        return this._version;
+    }
+    /** Gravity in m/s². Default (0, -9.81, 0). Returns a copy; assign to change it. */ get gravity() {
+        return new Vector3(this._gravity);
+    }
+    set gravity(value) {
+        if (!this._gravity.equalsTo(value)) {
+            this._gravity.set(value);
+            this._version++;
+        }
+    }
+    /** Length of one simulation step, in seconds. Default 1/60. */ get fixedTimeStep() {
+        return this._fixedTimeStep;
+    }
+    set fixedTimeStep(value) {
+        value = Math.max(1e-4, value);
+        if (value !== this._fixedTimeStep) {
+            this._fixedTimeStep = value;
+            this._version++;
+        }
+    }
+    /** Most simulation steps taken in one frame. Default 8: real time down to 7.5 frames per second at the default step. */ get maxSubSteps() {
+        return this._maxSubSteps;
+    }
+    set maxSubSteps(value) {
+        value = Math.max(1, Math.floor(value));
+        if (value !== this._maxSubSteps) {
+            this._maxSubSteps = value;
+            this._version++;
+        }
+    }
+    /** Whether moving bodies are drawn between simulation steps. Default true. */ get interpolation() {
+        return this._interpolation;
+    }
+    set interpolation(value) {
+        if (!!value !== this._interpolation) {
+            this._interpolation = !!value;
+            this._version++;
+        }
+    }
+    /** Whether the simulation waits for mesh and terrain colliders before starting. Default true. */ get waitForCollidersOnStart() {
+        return this._waitForCollidersOnStart;
+    }
+    set waitForCollidersOnStart(value) {
+        if (!!value !== this._waitForCollidersOnStart) {
+            this._waitForCollidersOnStart = !!value;
+            this._version++;
+        }
+    }
+    /** Display name of a layer. */ getLayerName(layer) {
+        return this._layerNames[layer] ?? '';
+    }
+    setLayerName(layer, name) {
+        if (layer >= 0 && layer < PHYSICS_LAYER_COUNT && this._layerNames[layer] !== name) {
+            this._layerNames[layer] = name;
+            this._version++;
+        }
+    }
+    /** Whether colliders on layers `a` and `b` collide. All layers collide by default. */ getLayerCollision(a, b) {
+        return !!((this._layerMasks[a] ?? 0) & 1 << b);
+    }
+    /** Sets whether colliders on layers `a` and `b` collide; applies to both orders. */ setLayerCollision(a, b, enabled) {
+        if (a < 0 || a >= PHYSICS_LAYER_COUNT || b < 0 || b >= PHYSICS_LAYER_COUNT) {
+            return;
+        }
+        if (this.getLayerCollision(a, b) === !!enabled && this.getLayerCollision(b, a) === !!enabled) {
+            return;
+        }
+        if (enabled) {
+            this._layerMasks[a] |= 1 << b;
+            this._layerMasks[b] |= 1 << a;
+        } else {
+            this._layerMasks[a] &= ~(1 << b);
+            this._layerMasks[b] &= ~(1 << a);
+        }
+        this._version++;
+    }
+    /** Layer names as saved: a JSON array of 16 strings. @internal */ get layerNamesData() {
+        return JSON.stringify(this._layerNames);
+    }
+    set layerNamesData(value) {
+        let names;
+        try {
+            names = JSON.parse(value);
+        } catch  {
+            names = null;
+        }
+        for(let i = 0; i < PHYSICS_LAYER_COUNT; i++){
+            const name = Array.isArray(names) ? names[i] : undefined;
+            this.setLayerName(i, typeof name === 'string' ? name : ScenePhysicsSettings.defaultLayerName(i));
+        }
+    }
+    /**
+   * Collision matrix as saved: 16 comma separated masks, bit `b` of mask `a`
+   * set when layers `a` and `b` collide. Made symmetric on load: a pair collides
+   * if either order says so. @internal
+   */ get layerMatrixData() {
+        return this._layerMasks.join(',');
+    }
+    set layerMatrixData(value) {
+        const parts = value.split(',');
+        const masks = Array.from({
+            length: PHYSICS_LAYER_COUNT
+        }, (_, i)=>{
+            const n = Number(parts[i]);
+            return parts[i] !== undefined && parts[i].trim() !== '' && Number.isFinite(n) ? n & ALL_LAYERS : ALL_LAYERS;
+        });
+        for(let a = 0; a < PHYSICS_LAYER_COUNT; a++){
+            for(let b = a; b < PHYSICS_LAYER_COUNT; b++){
+                this.setLayerCollision(a, b, !!(masks[a] >> b & 1) || !!(masks[b] >> a & 1));
+            }
+        }
+    }
+}
+
+export { PHYSICS_LAYER_COUNT, ScenePhysicsSettings };
+//# sourceMappingURL=physics_settings.js.map

package/dist/scene/physics_settings.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"physics_settings.js","sources":["../../src/scene/physics_settings.ts"],"sourcesContent":["import { Vector3 } from '@zephyr3d/base';\r\n\r\n/** Number of collision layers. @public */\r\nexport const PHYSICS_LAYER_COUNT = 16;\r\nconst ALL_LAYERS = (1 << PHYSICS_LAYER_COUNT) - 1;\r\n\r\n/**\r\n * Physics settings saved with a scene.\r\n *\r\n * @remarks\r\n * Plain data: the scene package does not simulate anything. A physics package\r\n * reads these when it simulates the scene, and picks up later changes through\r\n * {@link ScenePhysicsSettings.version}. A scene without settings\r\n * ({@link Scene.physicsSettings} null) uses the physics package's defaults,\r\n * which match the defaults here.\r\n *\r\n * @public\r\n */\r\nexport class ScenePhysicsSettings {\r\n  private readonly _gravity: Vector3;\r\n  private _fixedTimeStep: number;\r\n  private _maxSubSteps: number;\r\n  private _interpolation: boolean;\r\n  private _waitForCollidersOnStart: boolean;\r\n  private readonly _layerNames: string[];\r\n  private readonly _layerMasks: number[];\r\n  private _version: number;\r\n  constructor() {\r\n    this._gravity = new Vector3(0, -9.81, 0);\r\n    this._fixedTimeStep = 1 / 60;\r\n    this._maxSubSteps = 8;\r\n    this._interpolation = true;\r\n    this._waitForCollidersOnStart = true;\r\n    this._layerNames = Array.from({ length: PHYSICS_LAYER_COUNT }, (_, i) =>\r\n      ScenePhysicsSettings.defaultLayerName(i)\r\n    );\r\n    this._layerMasks = new Array<number>(PHYSICS_LAYER_COUNT).fill(ALL_LAYERS);\r\n    this._version = 0;\r\n  }\r\n  /** Name a layer has until renamed. */\r\n  static defaultLayerName(layer: number) {\r\n    return layer === 0 ? 'Default' : `Layer ${layer}`;\r\n  }\r\n  /** Increases whenever a setting changes. */\r\n  get version() {\r\n    return this._version;\r\n  }\r\n  /** Gravity in m/s². Default (0, -9.81, 0). Returns a copy; assign to change it. */\r\n  get gravity(): Vector3 {\r\n    return new Vector3(this._gravity);\r\n  }\r\n  set gravity(value: Vector3) {\r\n    if (!this._gravity.equalsTo(value)) {\r\n      this._gravity.set(value);\r\n      this._version++;\r\n    }\r\n  }\r\n  /** Length of one simulation step, in seconds. Default 1/60. */\r\n  get fixedTimeStep() {\r\n    return this._fixedTimeStep;\r\n  }\r\n  set fixedTimeStep(value: number) {\r\n    value = Math.max(1e-4, value);\r\n    if (value !== this._fixedTimeStep) {\r\n      this._fixedTimeStep = value;\r\n      this._version++;\r\n    }\r\n  }\r\n  /** Most simulation steps taken in one frame. Default 8: real time down to 7.5 frames per second at the default step. */\r\n  get maxSubSteps() {\r\n    return this._maxSubSteps;\r\n  }\r\n  set maxSubSteps(value: number) {\r\n    value = Math.max(1, Math.floor(value));\r\n    if (value !== this._maxSubSteps) {\r\n      this._maxSubSteps = value;\r\n      this._version++;\r\n    }\r\n  }\r\n  /** Whether moving bodies are drawn between simulation steps. Default true. */\r\n  get interpolation() {\r\n    return this._interpolation;\r\n  }\r\n  set interpolation(value: boolean) {\r\n    if (!!value !== this._interpolation) {\r\n      this._interpolation = !!value;\r\n      this._version++;\r\n    }\r\n  }\r\n  /** Whether the simulation waits for mesh and terrain colliders before starting. Default true. */\r\n  get waitForCollidersOnStart() {\r\n    return this._waitForCollidersOnStart;\r\n  }\r\n  set waitForCollidersOnStart(value: boolean) {\r\n    if (!!value !== this._waitForCollidersOnStart) {\r\n      this._waitForCollidersOnStart = !!value;\r\n      this._version++;\r\n    }\r\n  }\r\n  /** Display name of a layer. */\r\n  getLayerName(layer: number) {\r\n    return this._layerNames[layer] ?? '';\r\n  }\r\n  setLayerName(layer: number, name: string) {\r\n    if (layer >= 0 && layer < PHYSICS_LAYER_COUNT && this._layerNames[layer] !== name) {\r\n      this._layerNames[layer] = name;\r\n      this._version++;\r\n    }\r\n  }\r\n  /** Whether colliders on layers `a` and `b` collide. All layers collide by default. */\r\n  getLayerCollision(a: number, b: number) {\r\n    return !!((this._layerMasks[a] ?? 0) & (1 << b));\r\n  }\r\n  /** Sets whether colliders on layers `a` and `b` collide; applies to both orders. */\r\n  setLayerCollision(a: number, b: number, enabled: boolean) {\r\n    if (a < 0 || a >= PHYSICS_LAYER_COUNT || b < 0 || b >= PHYSICS_LAYER_COUNT) {\r\n      return;\r\n    }\r\n    if (this.getLayerCollision(a, b) === !!enabled && this.getLayerCollision(b, a) === !!enabled) {\r\n      return;\r\n    }\r\n    if (enabled) {\r\n      this._layerMasks[a] |= 1 << b;\r\n      this._layerMasks[b] |= 1 << a;\r\n    } else {\r\n      this._layerMasks[a] &= ~(1 << b);\r\n      this._layerMasks[b] &= ~(1 << a);\r\n    }\r\n    this._version++;\r\n  }\r\n  /** Layer names as saved: a JSON array of 16 strings. @internal */\r\n  get layerNamesData() {\r\n    return JSON.stringify(this._layerNames);\r\n  }\r\n  set layerNamesData(value: string) {\r\n    let names: unknown;\r\n    try {\r\n      names = JSON.parse(value);\r\n    } catch {\r\n      names = null;\r\n    }\r\n    for (let i = 0; i < PHYSICS_LAYER_COUNT; i++) {\r\n      const name = Array.isArray(names) ? names[i] : undefined;\r\n      this.setLayerName(i, typeof name === 'string' ? name : ScenePhysicsSettings.defaultLayerName(i));\r\n    }\r\n  }\r\n  /**\r\n   * Collision matrix as saved: 16 comma separated masks, bit `b` of mask `a`\r\n   * set when layers `a` and `b` collide. Made symmetric on load: a pair collides\r\n   * if either order says so. @internal\r\n   */\r\n  get layerMatrixData() {\r\n    return this._layerMasks.join(',');\r\n  }\r\n  set layerMatrixData(value: string) {\r\n    const parts = value.split(',');\r\n    const masks = Array.from({ length: PHYSICS_LAYER_COUNT }, (_, i) => {\r\n      const n = Number(parts[i]);\r\n      return parts[i] !== undefined && parts[i].trim() !== '' && Number.isFinite(n)\r\n        ? n & ALL_LAYERS\r\n        : ALL_LAYERS;\r\n    });\r\n    for (let a = 0; a < PHYSICS_LAYER_COUNT; a++) {\r\n      for (let b = a; b < PHYSICS_LAYER_COUNT; b++) {\r\n        this.setLayerCollision(a, b, !!((masks[a] >> b) & 1) || !!((masks[b] >> a) & 1));\r\n      }\r\n    }\r\n  }\r\n}\r\n"],"names":["PHYSICS_LAYER_COUNT","ALL_LAYERS","ScenePhysicsSettings","_gravity","_fixedTimeStep","_maxSubSteps","_interpolation","_waitForCollidersOnStart","_layerNames","_layerMasks","_version","Vector3","Array","from","length","_","i","defaultLayerName","fill","layer","version","gravity","value","equalsTo","set","fixedTimeStep","Math","max","maxSubSteps","floor","interpolation","waitForCollidersOnStart","getLayerName","setLayerName","name","getLayerCollision","a","b","setLayerCollision","enabled","layerNamesData","JSON","stringify","names","parse","isArray","undefined","layerMatrixData","join","parts","split","masks","n","Number","trim","isFinite"],"mappings":"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"}

package/dist/scene/scene.js

@@ -1,11 +1,11 @@
-import { makeObservable, Disposable, DRef, Vector4, Vector3, Ray, DWeakRef } from '@zephyr3d/base';
+import { makeObservable, Disposable, DRef, Vector4, Vector3, Ray } from '@zephyr3d/base';
 import { SceneNode } from './scene_node.js';
 import { Octree } from './octree.js';
 import { RaycastVisitor } from './raycast_visitor.js';
 import { Environment } from './environment.js';
 import '../values.js';
+import { getDevice, tryGetApp } from '../app/api.js';
 import '../render/render_queue.js';
-import { getDevice } from '../app/api.js';
 import { SceneRenderer } from '../render/renderer.js';
 import '../render/lightpass.js';
 import '../material/shader/helper.js';
@@ -13,15 +13,17 @@ import '../render/sky.js';
 import '../render/clipmap.js';
 import '../render/envlight.js';
 import '../render/primitive.js';
+import '@zephyr3d/device';
+import '../render/lod.js';
 import '../material/lambert.js';
 import '../material/blinn.js';
 import '../material/unlit.js';
+import '../material/meshmaterial.js';
 import '../material/particle.js';
 import '../material/subsurfaceprofile.js';
-import '../material/skin.js';
+import '../material/sssprofile.js';
+import '../material/sss.js';
 import '../material/eye.js';
-import '@zephyr3d/device';
-import '../material/meshmaterial.js';
 import '../material/hair.js';
 import '../material/hairstrand.js';
 import '../material/grassmaterial.js';
@@ -35,9 +37,19 @@ import '../material/sprite_std.js';
 import '../utility/blueprint/material/texture.js';
 import '../render/dualdepthpeeling_oit.js';
 import '../shaders/atmosphere.js';
+import '../render/water_interaction.js';
+import { RenderGraphExecutor } from '../render/rendergraph/executor.js';
 import '../render/rendergraph/forward_plus_builder.js';
 import '../render/rendergraph/scene_render_context.js';
+import { SceneSDF } from '../render/sdf/scene_sdf.js';
+import '../render/sdf/global_sdf.js';
+import '../render/gi/voxelize_pass.js';
+import { SceneGI } from '../render/gi/scene_gi.js';
+import { SkinPaletteAtlas } from '../animation/skin_palette_atlas.js';
+import { UpdateQueue } from './update_queue.js';
+import { AnimationBankTrack } from '../animation/animation_bank.js';
 import { ScriptAttachment, normalizeScriptAttachmentConfig, normalizeScriptAttachments } from './script_attachment.js';
+import { getPhysicsWorldFactory } from '../physics/world.js';
 
 /**
  * Represents a renderable world that manages scene graph, spatial indexing, and environment.
@@ -65,16 +77,24 @@ import { ScriptAttachment, normalizeScriptAttachmentConfig, normalizeScriptAttac
    * Populated by {@link Scene.invalidateNodePlacement} and drained by {@link Scene.updateNodePlacement}.
    */ _nodePlaceList;
     /** @internal Environment data (sky/light/IBL). */ _env;
+    /** @internal */ _sdf;
+    /** @internal */ _gi;
     /** @internal Frame counter that last updated this scene. */ _updateFrame;
     /** @internal Unique scene ID. */ _id;
-    /** @internal One-shot per-frame update queue (runs before render). */ _nodeUpdateQueue;
+    /**
+   * @internal One-shot per-frame update queue (runs before render). Thousands of nodes may
+   * re-queue themselves every frame, so duplicates are told by a stamp on the node
+   */ _nodeUpdateQueue;
     /** @internal */ _drawableUpdateQueue;
     /** @internal One-shot per-frame-per-camera update queue. */ _perCameraUpdateQueue;
     /** @internal Main camera reference. */ _mainCamera;
     /** @internal Arbitrary metadata loaded with the scene (optional). */ _metaData;
+    /** @internal Physics settings saved with the scene (optional). */ _physicsSettings;
+    _physicsWorld;
     /** @internal Lighting unit model used by this scene. */ _lightingMode;
     /** @internal Number of physical meters represented by one scene unit. */ _metersPerUnit;
     /** @internal User-attached script entries (engine-defined). */ _scripts;
+    /** @internal Virtual texture users updated by every camera rendering this scene. */ _virtualTextureClients;
     /**
    * Creates an instance of Scene.
    *
@@ -91,20 +111,43 @@ import { ScriptAttachment, normalizeScriptAttachmentConfig, normalizeScriptAttac
         this._name = name ?? '';
         this._octree = new Octree(this, 8, 8);
         this._nodePlaceList = new Set();
-        this._nodeUpdateQueue = [];
-        this._drawableUpdateQueue = [];
-        this._perCameraUpdateQueue = [];
+        this._nodeUpdateQueue = new UpdateQueue((node)=>node._updateQueueStamp, (node, stamp)=>node._updateQueueStamp = stamp);
+        // Drawables made without mixinDrawable get the field on first use
+        this._drawableUpdateQueue = new UpdateQueue((drawable)=>drawable._drawableQueueStamp, (drawable, stamp)=>drawable._drawableQueueStamp = stamp);
+        this._perCameraUpdateQueue = new UpdateQueue((node)=>node._perCameraQueueStamp, (node, stamp)=>node._perCameraQueueStamp = stamp);
         this._env = new Environment();
+        this._sdf = null;
+        this._gi = null;
         this._updateFrame = -1;
         this._rootNode = new DRef();
         this._rootNode.set(new SceneNode(this));
         this._rootNode.get().name = 'Root';
         this._metaData = null;
+        this._physicsSettings = null;
+        this._physicsWorld = null;
         this._lightingMode = 'legacy';
         this._metersPerUnit = 1;
         this._scripts = [];
+        this._virtualTextureClients = [];
         this._mainCamera = new DRef();
     }
+    /** Virtual texture users updated by every camera rendering this scene. */ get virtualTextureClients() {
+        return this._virtualTextureClients;
+    }
+    /**
+   * Registers a virtual texture user. Every camera rendering the scene then updates and fills
+   * its pages between the depth prepass and the light pass. WebGPU only.
+   */ addVirtualTextureClient(client) {
+        if (!this._virtualTextureClients.includes(client)) {
+            this._virtualTextureClients.push(client);
+        }
+    }
+    /** Unregisters a virtual texture user. The client keeps ownership of its texture. */ removeVirtualTextureClient(client) {
+        const index = this._virtualTextureClients.indexOf(client);
+        if (index >= 0) {
+            this._virtualTextureClients.splice(index, 1);
+        }
+    }
     /**
    * Gets the unique identifier of the scene.
    */ get id() {
@@ -154,6 +197,18 @@ import { ScriptAttachment, normalizeScriptAttachmentConfig, normalizeScriptAttac
    */ get env() {
         return this._env;
     }
+    /** Signed distance field data of the scene, off until enabled. */ get sdf() {
+        if (!this._sdf) {
+            this._sdf = new SceneSDF(this);
+        }
+        return this._sdf;
+    }
+    /** Global illumination of the scene, off until enabled. */ get gi() {
+        if (!this._gi) {
+            this._gi = new SceneGI(this);
+        }
+        return this._gi;
+    }
     /** Lighting unit model. Legacy remains the default for backward compatibility. */ get lightingMode() {
         return this._lightingMode;
     }
@@ -190,6 +245,58 @@ import { ScriptAttachment, normalizeScriptAttachmentConfig, normalizeScriptAttac
         this._metaData = val;
     }
     /**
+   * Physics settings of the scene, or null to use the physics package's
+   * defaults. Only scenes simulated with a physics package need them.
+   */ get physicsSettings() {
+        return this._physicsSettings;
+    }
+    set physicsSettings(val) {
+        this._physicsSettings = val ?? null;
+    }
+    /**
+   * The physics simulation of this scene, or null when no physics
+   * implementation is loaded.
+   *
+   * @remarks
+   * Created the first time it is needed - when a node with physics data
+   * ({@link SceneNode.physics}) enters the scene, or when this is read - by the
+   * implementation loaded with `initPhysics`. See {@link Scene.setPhysicsWorld}
+   * to give the scene one directly.
+   */ get physicsWorld() {
+        if (!this._physicsWorld && !this.disposed) {
+            const factory = getPhysicsWorldFactory();
+            if (factory) {
+                this._physicsWorld = factory(this);
+            }
+        }
+        return this._physicsWorld;
+    }
+    /**
+   * Gives the scene a physics world, replacing and disposing the current one;
+   * null removes it until it is next needed.
+   *
+   * @remarks
+   * The physics data of the scene's nodes moves to the new world.
+   */ setPhysicsWorld(world) {
+        const current = this._physicsWorld;
+        if (current === (world ?? null)) {
+            return;
+        }
+        if (world && world.scene !== this) {
+            throw new Error('The physics world belongs to another scene.');
+        }
+        this.rootNode.iterate((node)=>{
+            node.physics?._hostDetached();
+        });
+        this._physicsWorld = world ?? null;
+        current?.dispose();
+        if (world) {
+            this.rootNode.iterate((node)=>{
+                node.physics?._hostAttached();
+            });
+        }
+    }
+    /**
    * Attached script filename or identifier (engine-specific).
    *
    * @remarks
@@ -327,8 +434,9 @@ import { ScriptAttachment, normalizeScriptAttachmentConfig, normalizeScriptAttac
    * - To update continuously each frame, call `queueUpdateNode(this)` from within the node's `update` method.
    * - Duplicate scheduling within the same frame is prevented.
    */ queueUpdateNode(node) {
-        if (node && this._nodeUpdateQueue.findIndex((val)=>val.get() === node) < 0) {
-            this._nodeUpdateQueue.push(new DWeakRef(node));
+        // Only nodes of this scene, so a node waits in one update queue at most, as its stamp assumes
+        if (node && node.scene === this) {
+            this._nodeUpdateQueue.add(node);
         }
     }
     /**
@@ -341,8 +449,8 @@ import { ScriptAttachment, normalizeScriptAttachmentConfig, normalizeScriptAttac
    * - To update continuously each frame, call `queueUpdateDrawable(this)` from within the drawable's `updateState` method.
    * - Duplicate scheduling within the same frame is prevented.
    */ queueUpdateDrawable(drawable) {
-        if (drawable && this._drawableUpdateQueue.indexOf(drawable) < 0) {
-            this._drawableUpdateQueue.push(drawable);
+        if (drawable && drawable.getNode()?.scene === this) {
+            this._drawableUpdateQueue.add(drawable);
         }
     }
     /**
@@ -357,8 +465,8 @@ import { ScriptAttachment, normalizeScriptAttachmentConfig, normalizeScriptAttac
    * - To run per-camera work continuously, re-queue from `updatePerCamera`.
    * - Duplicate scheduling within the same frame is prevented.
    */ queuePerCameraUpdateNode(node) {
-        if (node && this._perCameraUpdateQueue.findIndex((val)=>val.get() === node) < 0) {
-            this._perCameraUpdateQueue.push(new DWeakRef(node));
+        if (node && node.scene === this) {
+            this._perCameraUpdateQueue.add(node);
         }
     }
     /**
@@ -412,38 +520,66 @@ import { ScriptAttachment, normalizeScriptAttachmentConfig, normalizeScriptAttac
    * - Ensure this runs only once per frame (via `frameInfo.frameCounter`).
    * - Update environment light synchronization.
    * - Dispatch `update` event.
+   * - Update the main camera's controller if its `updatePhase` is `'early'`.
    * - Drain the one-shot node update queue and call `node.update(...)`.
+   * - Dispatch `afterupdate` event; a physics world steps here.
+   * - Call scripts' `onLateUpdate`, then update the main camera's controller if its
+   *   `updatePhase` is `'late'`, then dispatch `lateupdate` event.
    * - Apply pending octree placement updates.
    *
    */ frameUpdate() {
         const frameInfo = getDevice().frameInfo;
         if (frameInfo.frameCounter !== this._updateFrame) {
             this._updateFrame = frameInfo.frameCounter;
+            this._env.wind.update(frameInfo.elapsedFrame * 0.001);
             this.updateEnvLight();
+            const deltaInSeconds = frameInfo.elapsedFrame * 0.001;
             this.dispatchEvent('update', this);
-            this.mainCamera?.updateController();
-            if (this._nodeUpdateQueue.length > 0) {
-                const elapsedInSeconds = frameInfo.elapsedOverall * 0.001;
-                const deltaInSeconds = frameInfo.elapsedFrame * 0.001;
-                const queue = this._nodeUpdateQueue;
-                this._nodeUpdateQueue = [];
-                while(queue.length > 0){
-                    const ref = queue.shift();
-                    const node = ref.get();
-                    if (node?.attached) {
-                        node.update(frameInfo.frameCounter, elapsedInSeconds, deltaInSeconds);
+            this.mainCamera?.updateController(deltaInSeconds, 'early');
+            if (this._nodeUpdateQueue.size > 0 || this._drawableUpdateQueue.size > 0) {
+                RenderGraphExecutor.profileScope('SceneUpdate', ()=>{
+                    if (this._nodeUpdateQueue.size > 0) {
+                        const elapsedInSeconds = frameInfo.elapsedOverall * 0.001;
+                        // Nodes queued while draining are updated next frame
+                        for (const node of this._nodeUpdateQueue.take()){
+                            if (!node.disposed && node.attached) {
+                                node.update(frameInfo.frameCounter, elapsedInSeconds, deltaInSeconds);
+                            }
+                        }
                     }
-                    ref.dispose();
-                }
+                    if (this._drawableUpdateQueue.size > 0) {
+                        for (const drawable of this._drawableUpdateQueue.take()){
+                            drawable.updateState();
+                        }
+                    }
+                });
             }
-            if (this._drawableUpdateQueue.length > 0) {
-                for (const drawable of this._drawableUpdateQueue){
-                    drawable.updateState();
+            this.dispatchEvent('afterupdate', this);
+            tryGetApp()?.engine?.lateUpdate(deltaInSeconds, (host)=>host === this || host instanceof SceneNode && host.scene === this);
+            this.mainCamera?.updateController(deltaInSeconds, 'late');
+            this.dispatchEvent('lateupdate', this);
+            this.updateNodePlacement(this._octree, this._nodePlaceList);
+            const camera = this.mainCamera;
+            if (camera && (this._gi?.enabled || this._sdf?.enabled)) {
+                const cameraPos = camera.getWorldPosition();
+                // The voxel scene feeds the field's compositing, so it goes first
+                if (this._gi?.enabled) {
+                    RenderGraphExecutor.profileScope('GIVoxelize', ()=>this._gi.update(cameraPos, deltaInSeconds));
+                }
+                if (this._sdf?.enabled) {
+                    RenderGraphExecutor.profileScope('SceneSDF', ()=>this._sdf.update(cameraPos, deltaInSeconds));
+                }
+                // Lighting reads what the field just composited
+                if (this._gi?.enabled) {
+                    RenderGraphExecutor.profileScope('GILighting', ()=>this._gi.updateLighting(camera));
                 }
-                this._drawableUpdateQueue = [];
             }
-            this.updateNodePlacement(this._octree, this._nodePlaceList);
         }
+        // Palettes written by animation updates are uploaded once all nodes and bank tracks are updated
+        RenderGraphExecutor.profileScope('Animation', ()=>{
+            AnimationBankTrack.updateAll(getDevice().frameInfo.elapsedFrame * 0.001);
+            SkinPaletteAtlas.flushPending();
+        });
     }
     /**
    * Performs per-camera scene updates for the current frame.
@@ -454,19 +590,20 @@ import { ScriptAttachment, normalizeScriptAttachmentConfig, normalizeScriptAttac
    *
    * @param camera - The camera being updated for.
    */ frameUpdatePerCamera(camera) {
-        if (this._perCameraUpdateQueue.length > 0) {
-            const frameInfo = getDevice().frameInfo;
-            const elapsedInSeconds = frameInfo.elapsedOverall * 0.001;
-            const deltaInSeconds = frameInfo.elapsedFrame * 0.001;
-            const queue = this._perCameraUpdateQueue;
-            this._perCameraUpdateQueue = [];
-            while(queue.length > 0){
-                const ref = queue.shift();
-                ref.get()?.updatePerCamera(camera, elapsedInSeconds, deltaInSeconds);
-                ref.dispose();
-            }
+        if (this._perCameraUpdateQueue.size > 0) {
+            RenderGraphExecutor.profileScope('SceneUpdatePerCamera', ()=>{
+                const frameInfo = getDevice().frameInfo;
+                const elapsedInSeconds = frameInfo.elapsedOverall * 0.001;
+                const deltaInSeconds = frameInfo.elapsedFrame * 0.001;
+                for (const node of this._perCameraUpdateQueue.take()){
+                    if (!node.disposed) {
+                        node.updatePerCamera(camera, elapsedInSeconds, deltaInSeconds);
+                    }
+                }
+            });
         }
         this.updateNodePlacement(this._octree, this._nodePlaceList);
+        SkinPaletteAtlas.flushPending();
     }
     /**
    * Applies placement changes for nodes in `list` to the given `octree`.
@@ -507,9 +644,18 @@ import { ScriptAttachment, normalizeScriptAttachmentConfig, normalizeScriptAttac
    * - Main camera reference wrapper
    *
    */ onDispose() {
+        this._nodeUpdateQueue.clear();
+        this._drawableUpdateQueue.clear();
+        this._perCameraUpdateQueue.clear();
         this._env.dispose();
+        this._gi?.dispose();
+        this._gi = null;
+        this._sdf?.dispose();
+        this._sdf = null;
         this._rootNode.dispose();
         this._mainCamera.dispose();
+        this._physicsWorld?.dispose();
+        this._physicsWorld = null;
     }
 }