Summary

Introduce inactive mesh instance support in Layer to exclude objects from all renderer loops, enabling efficient long-term deactivation, object pooling, and region streaming without affecting active rendering paths.

Changes

Core

• Added new data structures to track inactive items:
  • _inactiveMeshInstances and _inactiveMeshInstancesSet
  • _inactiveShadowCasters and _inactiveShadowCastersSet
• Updated mesh and shadow-caster management to honor inactive state during add/remove operations.
• Introduced new public API on Layer:
  • setMeshInstanceInactive(meshInstance, inactive) – mark a single mesh instance as inactive/active
  • setMeshInstancesInactive(meshInstances, inactive) – batch operation for multiple instances
  • isMeshInstanceInactive(meshInstance) – query inactive state
  • getInactiveMeshInstances() – retrieve read-only list of inactive mesh instances
• Added internal helper _removeInactiveShadowCasters(meshInstances) to keep inactive shadow casters in sync when deactivating.
• Extended clear() to reset inactive caches alongside active lists.

Behavior

• Deactivating an instance removes it from the active meshInstances and any active shadow caster lists, and places it into the inactive collections.
• Reactivating an instance moves it back to the active lists and re-enables shadow casting if the instance still casts shadows.
• Batch operations mirror single-instance behavior for efficiency.

Misc

• Bumped example dependency in examples/package-lock.json to 2.9.0-beta.1 to reflect changes.

Rationale

• This change optimizes renderer loops by excluding long-term hidden objects from culling, rendering, and shadow casting passes.
• Supports patterns like object pooling, region streaming, and LOD by avoiding per-frame work on unused instances.

API and Migration

• New APIs are additive and non-breaking for existing users. If you don’t use the new methods, behavior remains unchanged.
• Inactive instances are fully excluded from renderer loops until reactivated.

Tests Plan

• Create a layer with multiple mesh instances and deactivate a subset using setMeshInstanceInactive. Verify:
  • Inactive instances are not present in meshInstances or shadowCasters during rendering/culling
  • Reactivation via setMeshInstanceInactive(..., false) returns items to active lists and rendering resumes as expected
• Batch deactivate/activate a region of mesh instances with setMeshInstancesInactive and confirm state changes reflect correctly.
• Verify isMeshInstanceInactive and getInactiveMeshInstances report accurate state.
• Validate that deactivating an instance that does not belong to the layer returns a sane result (no changes).
• Ensure clear/reset path also clears inactive caches without regressions.

Notes

• All existing rendering paths for active objects remain unchanged.
• Shadow casting for reactivated instances respects castShadow at the time of reactivation.

🌿 Generated by Terry

ℹ️ Tag @terragon-labs to ask questions and address PR feedback

📎 Task: https://www.terragonlabs.com/task/b8f2a3b7-9092-4396-9ba9-7baa450b0bbf