tomkrikorian/visionosagents/realitykit-ecs-systems

RealityKit ECS Systems

Quick Start

1. First verify that a documented RealityKit component cannot solve the

problem; use realitykit-visionos-developer component selection when unsure.

1. Use a custom Component for per-entity state and a custom System for

continuous or multi-entity behavior.

1. Register custom components and systems once during app startup before any

scene, asset, or Reality Composer Pro content that depends on them loads.

1. Keep per-frame work in systems, not SwiftUI body code or ad hoc timers.
2. Load the full ECS guide only when implementing or debugging real custom ECS

code.

Load References When

Cross-Routing

• Use realitykit-visionos-developer for general component choice, entity

loading, input, attachments, anchoring, portals, sync, and local USDStageComponent.

• Use realitykit-rendering-materials when custom ECS only exists to drive

materials, lights, post-processing, LOD, splats, or other visual state.

• Use realitykit-animation-physics when custom ECS interacts with animation,

character motion, navigation, collision, physics, particles, or cloth.

• Use realitykit-audio-spatial when systems coordinate entity-owned audio.

Guardrails

• Prefer documented components before custom ECS.
• Register before loading scenes that reference the custom types.
• Keep system queries narrow and update only the entities that need work.
• Do not store SwiftUI-only state in RealityKit components unless entity

ownership is intentional.

• Summarize registration order and query shape when changing ECS code.

Output Expectations

Provide:

• why custom ECS is needed
• which ECS reference was used
• the component data model
• the system query and update cadence
• the registration location and runtime validation step