MaterialSyncSystem

Applies MaterialComponent authoring values to the THREE.js materials on an entity's mesh objects each frame, including material type switching, PBR properties, and texture slot management.

Overview

MaterialSyncSystem runs every frame and is responsible for:

• Creating or replacing THREE.js materials (MeshStandardMaterial, MeshBasicMaterial, MeshPhongMaterial, MeshPhysicalMaterial) when the type field changes.
• Applying scalar and vector properties (color, roughness, metalness, opacity, emissive, etc.) from the values array to the matching material slots.
• Loading textures from URLs and assigning them to the correct texture slot (map, alphaMap, normalMap, roughnessMap, metalnessMap, aoMap, emissiveMap, bumpMap, displacementMap, lightMap, envMap).
• Disposing stale textures and materials when they are replaced to prevent GPU memory leaks.
• Propagating material changes across multi-material meshes (i.e. objects with a materials array).

Queried components

Component	Access
MaterialComponent	Read (type, values array)
Object3DRef	Read (the live THREE.js mesh)

Behavior notes

• Per-slot values — MaterialComponent.values is an array where each entry maps to one material slot. Entities with multiple materials (e.g. a model with distinct material groups) are handled by index.
• Texture loading — textures are loaded via THREE.TextureLoader and cached internally. A changed URL triggers a fresh load and the old texture is disposed on replacement.
• Change detection — property values are compared to a previous-frame snapshot before being written to the material, so inspector edits during runtime take effect on the next frame without redundant assignments.
• Material type switch — when MaterialComponent.type changes (e.g. from standard to physical), the old material is disposed and a new one is created and assigned to the mesh.

API reference

• Class: MaterialComponent
• Source: core/systems/MaterialSyncSystem.ts