Add GSplat procedural shape scripts and example, other fixes and imrovements

[mvaligursky]

Summary

• inspired by Add GSplatProcedural class for generating GSplatData from images #8077
• Adds three new ESM scripts for rendering procedural shapes as Gaussian splats: images, lines/arrows/AABBs, and text
• Implements deferred destruction for GSplat resources to handle asynchronous sorter lifecycle, which avoids handling it on the user side
• Adds dynamic container update support with centersVersion tracking
• Fixes AABB propagation for dynamic GSplat containers
• Adds new procedural-shapes example demonstrating CAD-style visualization
• Added GSplatFormat.createSimpleFormat(device) helper for basic splat format

New Scripts

gsplat-image.mjs

Renders an image asset as Gaussian splats, one splat per non-transparent pixel. The image is sized to fit in a 1x1 unit space (matching PlaneGeometry), centered at the origin on the XZ plane.

gsplat-lines.mjs

Renders line-based primitives as Gaussian splats:

• Lines: Start/end points with colors and thickness
• Arrows: Lines with 3D pyramid arrowheads (4-sided)
• AABBs: Wireframe bounding boxes

Primitives are added/removed via API, and the container is automatically rebuilt when dirty.

gsplat-text.mjs

Renders text strings as Gaussian splats using canvas-based text rendering. Supports:

• Configurable font size, family, fill/stroke colors
• Stroke width and padding
• Automatic transparent pixel skipping

Engine Changes

Deferred Resource Destruction (gsplat-resource-cleanup.js)

• New GSplatResourceCleanup class manages per-device queues of resources pending destruction
• Resources with refCount > 0 (still in use by sorter) are queued for deferred destruction
• GSplatResourceBase.destroy() now handles deferral automatically via _actualDestroy() pattern
• Derived classes override _actualDestroy() for their specific cleanup
• Processed once per frame from GSplatDirector.update()

Dynamic Container Updates

• Added centersVersion property to GSplatResourceBase for tracking center data changes
• Added update(numSplats, centersUpdated) method to GSplatContainer
• GSplatManager detects version changes and re-uploads centers to sorter
• GSplatPlacementStateTracker tracks centersVersion for state invalidation

AABB Propagation Fix

• GSplatPlacement.aabb now returns resource.aabb by default (dynamic fallback)
• Custom AABB only set when explicitly provided via customAabb setter
• Fixes sorting issues with dynamic containers where AABB bounds were stale

Sort Worker Improvements

• Added one-time warning for sortKey overflow (splats lost due to AABB bounds issues)
• Helps diagnose when resource AABB doesn't encompass all splat centers

New Example

procedural-shapes.example.mjs

CAD-style visualization demonstrating all new scripts:

• Bicycle model with bottom-up box reveal effect
• Yellow AABB wireframes around wheels
• Cyan dimension arrows showing length, height, width
• Text labels for each dimension
• Image-based ground plane and gear wall
• Toggle control to show/hide lines and labels

[Copilot]

Pull request overview

This PR adds support for procedural Gaussian splat shapes with three new ESM scripts (images, lines/arrows/AABBs, and text), implements deferred destruction for GSplat resources to handle asynchronous sorter lifecycle, adds dynamic container update support with centersVersion tracking, fixes AABB propagation for dynamic GSplat containers, and includes a new procedural-shapes example demonstrating CAD-style visualization.

Changes:

• Added deferred resource destruction mechanism via GSplatResourceCleanup to safely handle resources still in use by the sorter
• Added centersVersion tracking to GSplat resources for detecting and propagating center data changes to the sorter
• Fixed AABB handling in GSplatPlacement to return resource.aabb as fallback when no custom AABB is set
• Added three new procedural shape scripts: gsplat-image.mjs, gsplat-lines.mjs, and gsplat-text.mjs
• Added GSplatFormat.createSimpleFormat() helper for basic splat formats with uniform-scale and no rotation
• Added GSplatContainer.update() method to replace direct numSplats setter with better control over center updates
• Added one-time warning in sort worker for splats lost due to AABB bounds issues
• Added new procedural-shapes example demonstrating all new scripts with CAD-style bicycle visualization

Reviewed changes

Copilot reviewed 28 out of 33 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
src/scene/shader-lib/wgsl/collections/gsplat-chunks-wgsl.js	Fixed import path for gsplatSplat shader chunk
src/scene/shader-lib/wgsl/chunks/gsplat/vert/gsplatSplat.js	Added new shader chunk with Splat struct and setSplat helper
src/scene/shader-lib/wgsl/chunks/gsplat/vert/formats/containerSimpleRead.js	Added simple format read functions for containers
src/scene/shader-lib/glsl/collections/gsplat-chunks-glsl.js	Fixed import path for gsplatSplat shader chunk (GLSL version)
src/scene/shader-lib/glsl/chunks/gsplat/vert/gsplatSplat.js	Added new shader chunk with Splat struct and setSplat helper (GLSL version)
src/scene/shader-lib/glsl/chunks/gsplat/vert/formats/containerSimpleRead.js	Added simple format read functions for containers (GLSL version)
src/scene/gsplat/gsplat-sog-resource.js	Updated to use _actualDestroy() for deferred destruction pattern
src/scene/gsplat/gsplat-resource.js	Removed redundant destroy() override
src/scene/gsplat/gsplat-resource-cleanup.js	New class managing deferred destruction of GSplat resources
src/scene/gsplat/gsplat-resource-base.js	Added centersVersion tracking and deferred destruction via _actualDestroy()
src/scene/gsplat/gsplat-format.js	Added createSimpleFormat() static helper method
src/scene/gsplat/gsplat-container.js	Replaced numSplats setter with update() method supporting centersVersion
src/scene/gsplat-unified/gsplat-unified-sort-worker.js	Added one-time warning for sortKey overflow
src/scene/gsplat-unified/gsplat-placement.js	Changed AABB handling to use resource.aabb as fallback, improved type imports
src/scene/gsplat-unified/gsplat-placement-state-tracker.js	Added centersVersion to tracked state
src/scene/gsplat-unified/gsplat-octree.resource.js	Added centersVersion = 0 for static octree resources
src/scene/gsplat-unified/gsplat-octree-instance.js	Removed redundant placement.aabb.copy() call
src/scene/gsplat-unified/gsplat-manager.js	Added centersVersion tracking to detect and propagate center updates to sorter
src/scene/gsplat-unified/gsplat-director.js	Added GSplatResourceCleanup.process() call in update loop
src/framework/components/gsplat/system.js	Simplified customAabb cloning using nullish coalescing
src/framework/components/gsplat/component.js	Removed automatic customAabb assignment, simplified setter logic
scripts/esm/gsplat/gsplat-text.mjs	New script for rendering text as Gaussian splats
scripts/esm/gsplat/gsplat-lines.mjs	New script for rendering lines, arrows, and AABBs as Gaussian splats
scripts/esm/gsplat/gsplat-image.mjs	New script for rendering images as Gaussian splats
scripts/esm/gsplat/gsplat-flipbook.mjs	Updated comments to reflect deferred destruction handling
examples/thumbnails/gaussian-splatting_procedural-shapes_small.webp	Small thumbnail for procedural-shapes example
examples/thumbnails/gaussian-splatting_procedural-shapes_large.webp	Large thumbnail for procedural-shapes example
examples/src/examples/gaussian-splatting/procedural-shapes.example.mjs	New example demonstrating procedural shapes with CAD-style bicycle visualization
examples/src/examples/gaussian-splatting/procedural-shapes.controls.mjs	Controls for procedural-shapes example
examples/src/examples/gaussian-splatting/procedural-instanced.example.mjs	Updated to use container.update() with centersUpdated=false
examples/src/examples/gaussian-splatting/paint.example.mjs	Added credit attribution for apartment model
examples/src/examples/gaussian-splatting/editor.example.mjs	Added credit attribution for apartment model

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.