InstancedMeshSystem

Builds and maintains the THREE.InstancedMesh objects for every entity that has an InstancedMeshComponent, and writes per-instance matrices from the TransformComponent of each owned instance-slot entity every frame.

Overview

InstancedMeshSystem is responsible for:

• Creating a THREE.InstancedMesh (primitive kinds) or a THREE.Group of THREE.InstancedMesh objects (model kind) when a group entity is first encountered.
• Rebuilding the instanced mesh when geometry parameters, mesh kind, or instance count change.
• Reading the TransformComponent of each InstanceSlotComponent entity listed in InstancedMeshComponent.instanceEntityIds every frame and writing the composed world matrix into the instance buffer.
• Applying castShadow / receiveShadow changes to the underlying THREE.InstancedMesh.
• Cleaning up THREE.InstancedMesh objects from the scene when the group entity is removed.

Managed components

Component	Role
InstancedMeshComponent	Configuration, instance list, and live mesh reference
InstanceSlotComponent	Per-instance ownership metadata (groupEntityId, slotIndex)
TransformComponent	Per-instance position / rotation / scale, read each frame
Object3DRef	Scene attachment point for the group entity

Scheduling

Runs after ObjectManagementSystem and before TransformSyncSystem so that newly created slot entities have their transforms initialized before the matrix write pass.

Notes

• InstancedMeshComponent.instancedMesh is set and owned by this system. Never read or write this field in hydration or factory code.
• Adding slots at runtime: push the new entity ID into InstancedMeshComponent.instanceEntityIds after the slot entity is fully created. The system will resize the buffer on the next frame.
• Removing slots: destroy the slot entity with world.destroyEntity(slotId) and remove its ID from instanceEntityIds. The system rebuilds the buffer on the next frame.