Skip to content

[BREAKING] Deprecate GSplatComponent#unified and default it to true#8802

Merged
mvaligursky merged 1 commit into
mainfrom
mv-deprecate-gsplat-unified
May 28, 2026
Merged

[BREAKING] Deprecate GSplatComponent#unified and default it to true#8802
mvaligursky merged 1 commit into
mainfrom
mv-deprecate-gsplat-unified

Conversation

@mvaligursky

Copy link
Copy Markdown
Contributor

Marks GSplatComponent#unified as deprecated and flips its default from false to true, making unified gsplat rendering the default mode. Non-unified ("legacy") rendering will be removed in a future release.

Changes:

  • _unified field now initializes to true so new gsplat components use unified rendering by default.
  • unified getter and setter are marked @deprecated + @ignore (hidden from generated docs).
  • Setting unified = false now logs a one-time Debug.deprecated message recommending migration to unified rendering.
  • Reworded all legacy-mode warnings on GSplatComponent (instance get/set, material get/set, onLayerAdded, onLayerRemoved) to clarify those APIs are only available in legacy non-unified mode. A shared UNIFIED_LEGACY_HINT string is appended to each warning so users understand the default flip and how to opt back into legacy mode temporarily.
  • Added a Debug.warnOnce to the previously silent get instance so users hit a clear message when reading gsplat.instance from a unified component (returns null in that case).
  • Updated JSDoc on material get/set to match the new framing ("legacy non-unified mode" instead of "when unified is false").

API Changes:

  • GSplatComponent#unified (get/set) is now @deprecated and hidden from public docs.
  • Default value of GSplatComponent#unified changed from false to true. Existing code that implicitly relied on the old default and uses legacy-only APIs (e.g. gsplat.instance, the material setter) will now hit warnings; the suggested temporary workaround is to explicitly set unified: false when adding the component.

Examples:

  • No example changes in this PR. The existing legacy gsplat picking example serves as a manual smoke test for the deprecation path and will be updated separately.

Flips the default of GSplatComponent#unified from false to true so new
gsplat components use unified rendering by default, and marks the
property as deprecated. Non-unified ("legacy") rendering will be removed
in a future release.

- _unified field now initializes to true.
- unified get/set are marked @deprecated + @ignore (hidden from docs).
- Setting unified=false logs a one-time Debug.deprecated message.
- Reworded all legacy-mode warnings on GSplatComponent (instance get/set,
  material get/set, onLayerAdded, onLayerRemoved) to clarify those APIs
  are only available in legacy non-unified mode. A shared
  UNIFIED_LEGACY_HINT string is appended so users understand the default
  flip and how to opt back into legacy mode temporarily.
- Added a Debug.warnOnce to the previously silent get instance so users
  hit a clear message when reading gsplat.instance from a unified
  component (returns null in that case).
- Updated JSDoc on material get/set to match the new framing.
@mvaligursky mvaligursky self-assigned this May 28, 2026
@mvaligursky mvaligursky changed the title feat(gsplat): deprecate GSplatComponent#unified and default it to true [BREAKING] Deprecate GSplatComponent#unified and default it to true May 28, 2026

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Deprecates GSplatComponent#unified and flips its default to true, making unified gsplat rendering the new default. Legacy mode is retained but warns users when used and is targeted for removal.

Changes:

  • _unified default flipped from false to true; unified getter/setter marked @deprecated + @ignore with a one-time Debug.deprecated log when set to false.
  • Reworded all legacy-mode warnings to share a common UNIFIED_LEGACY_HINT and added a previously-missing warnOnce on get instance in unified mode.
  • Updated JSDoc on material get/set to reflect the new default and framing.

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

@mvaligursky mvaligursky merged commit 2a328e8 into main May 28, 2026
9 checks passed
@mvaligursky mvaligursky deleted the mv-deprecate-gsplat-unified branch May 28, 2026 12:35
mvaligursky added a commit that referenced this pull request May 28, 2026
…nings) (#8803)

Follow-up cleanups to #8802 (flip of GSplatComponent#unified default to
true). Addresses spurious deprecation warnings raised by engine-internal
code, and updates the bundled orbit-camera script to be unified-aware.

- GSplatComponent: route internal mesh-instance probes through the
  private _instance field instead of the deprecated public instance
  getter (set castShadows, addToLayers, removeFromLayers).
- GSplatComponent: silence the spurious Debug.errorOnce in
  onLayerAdded / onLayerRemoved. These are engine-driven event handlers
  subscribed to the layer composition's add/remove events — not
  user-facing APIs — so they now silently no-op in unified mode.
- scripts/camera/orbit-camera.js: _buildAabb now collects AABBs for
  unified gsplats via gsplat.customAabb transformed by the entity's
  world matrix, so unified gsplats contribute to the orbit camera's
  focus AABB instead of being silently skipped.
- examples/.../global-sorting.example.mjs: now that the orbit camera
  correctly builds an AABB for unified gsplats, the prior framing
  (which incidentally relied on an empty AABB at origin) needed an
  explicit pivot — switched to resetAndLookAtPoint targeting the
  statue's world-space centre.

Co-authored-by: Martin Valigursky <mvaligursky@snapchat.com>
mvaligursky added a commit that referenced this pull request May 28, 2026
)

The legacy gsplat picking example documents itself as "using legacy
(non-unified) mode" but its addComponent('gsplat', { ... }) calls never
specified unified: false. After #8802 flipped the default to true, the
example was silently created in unified mode and crashed in its click
handler when it accessed gsplat.instance.meshInstance (instance is null
in unified mode).

Adding unified: false restores legacy mode as the example documents,
and produces exactly the one expected DEPRECATED: GSplatComponent#unified
warning on startup — the intended migration signal from #8802.

Co-authored-by: Martin Valigursky <mvaligursky@snapchat.com>
mvaligursky added a commit that referenced this pull request May 28, 2026
Follow-up cleanup to the unified-default flip (#8802, #8803, #8804).
Unified rendering is now the default and the unified property is
@deprecated/@ignore, so the public API docs and examples shouldn't be
framed around "unified mode" any more — it's just gsplat rendering.

Engine source:
- GSplatComponent: remove the "## Unified Rendering" section from the
  class JSDoc; strip the JSDoc blocks from material get/set and
  highQualitySH get/set (both are legacy-only and only documented the
  unified/non-unified distinction). Drop "unified" qualifiers from
  workBufferUpdate, workBufferModifier, setParameter, and
  getInstanceTexture JSDocs.
- GSplatComponentSystem: drop "in unified mode" from the
  material:created and frame:ready event JSDocs, and from the
  getMaterial JSDoc.
- GSplatParams: rename "Parameters for GSplat unified system" to
  "Parameters for the GSplat system"; drop "unified" qualifier from
  dataFormat, material, and format JSDocs.
- GSplatContainer: drop "non-unified rendering" from the class example
  comment, drop unified: true from the addComponent example, drop
  "unified" qualifier from the centers JSDoc.

Examples (gaussian-splatting folder):
- Remove unified: true from every addComponent('gsplat', { ... }) call
  (~40 occurrences across 29 files) — it's now the default and the
  property is deprecated.
- Reword/remove comments that mention "unified" framing now that it's
  just the standard path (e.g. "Create hotel gsplat with unified set
  to true" → "Create hotel gsplat").
- Drop three stale orbit-pivot comments ("unified gsplats have no mesh
  AABB for focusEntity framing") — these became factually incorrect
  once #8803 made orbit-camera unified-aware.
- Update global-sorting example header from "demonstrates unified
  gsplat rendering" to "demonstrates global gsplat sorting" to reflect
  what the example actually shows.

Remaining "unified" mentions in the engine are all either internal
(private fields, code comments, code branches), runtime warning strings
(which must keep the property name), @ignore'd JSDoc, or directory
names — none render in public docs.

Co-authored-by: Martin Valigursky <mvaligursky@snapchat.com>
mvaligursky added a commit that referenced this pull request May 28, 2026
Follow-up cleanup to the unified-default flip (#8802, #8803, #8804).
Unified rendering is now the default and the unified property is
@deprecated/@ignore, so the public API docs and examples shouldn't be
framed around "unified mode" any more — it's just gsplat rendering.

Engine source:
- GSplatComponent: remove the "## Unified Rendering" section from the
  class JSDoc; strip the JSDoc blocks from material get/set and
  highQualitySH get/set (both are legacy-only and only documented the
  unified/non-unified distinction). Drop "unified" qualifiers from
  workBufferUpdate, workBufferModifier, setParameter, and
  getInstanceTexture JSDocs.
- GSplatComponentSystem: drop "in unified mode" from the
  material:created and frame:ready event JSDocs, and from the
  getMaterial JSDoc.
- GSplatParams: rename "Parameters for GSplat unified system" to
  "Parameters for the GSplat system"; drop "unified" qualifier from
  dataFormat, material, and format JSDocs.
- GSplatContainer: drop "non-unified rendering" from the class example
  comment, drop unified: true from the addComponent example, drop
  "unified" qualifier from the centers JSDoc.

Examples (gaussian-splatting folder):
- Remove unified: true from every addComponent('gsplat', { ... }) call
  (~40 occurrences across 29 files) — it's now the default and the
  property is deprecated.
- Reword/remove comments that mention "unified" framing now that it's
  just the standard path (e.g. "Create hotel gsplat with unified set
  to true" → "Create hotel gsplat").
- Drop three stale orbit-pivot comments ("unified gsplats have no mesh
  AABB for focusEntity framing") — these became factually incorrect
  once #8803 made orbit-camera unified-aware.
- Update global-sorting example header from "demonstrates unified
  gsplat rendering" to "demonstrates global gsplat sorting" to reflect
  what the example actually shows.

Remaining "unified" mentions in the engine are all either internal
(private fields, code comments, code branches), runtime warning strings
(which must keep the property name), @ignore'd JSDoc, or directory
names — none render in public docs.

Co-authored-by: Martin Valigursky <mvaligursky@snapchat.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants