Scene System

Scene System Architecture

The Scene System in EntropyCanvasSDK is designed to be a high-performance, hybrid architecture that combines the raw speed of an ECS (Entity Component System) with the rich interchange capabilities of USD (Universal Scene Description).

Components

graph TD
    Net["Network Packet"] --> Replicator["SceneReplicator"]
    Replicator -->|Schema Offsets| ECS["SceneGraph<br/>(Flecs World)"]
    USD["USD Stage"] <-->|Sync| ECS
    
    subgraph "Flecs World"
        Entity["Entity"]
        Prop["Component Data<br/>(Flat Memory)"]
    end

1. SceneGraph

The SceneGraph is a lightweight wrapper around a flecs::world. It provides the foundational entity management:

• Hierarchy: Parent/Child relationships using Flecs relations.
• Transforms: Local and World space propagation system.
• Querying: Fast iteration over entities using flecs::query.

2. SceneReplicator

The SceneReplicator is the bridge between the network and the ECS. It uses a Schema-Driven approach to apply updates without generic reflection overhead. This “Bring Your Own Thread Safety” (BYOTS) component allows for lock-free synchronization when managed correctly.

• Registration: Components are registered with a ComponentSchema and a ComponentTrustLevel.
• Direct Write: The replicator uses byte offsets from the schema to write network data directly into component memory (memcpy style operations on flecs::component).
• Zero-Copy: Where possible, data is moved rather than copied.

Trust Levels

• Builtin: SDK-defined components (Transform, Mesh, Light, Camera). Fully trusted/optimized.
• AppRegistered: Custom application components.
• External: Untrusted, sanitized components.

3. USD Integration (UsdSyncService)

USD is used for Persistence and Interchange, but not for the runtime simulation loop.

• Import: importUsdIntoWorld converts USD Prims to Flecs entities on load.
• Export: exportWorldToUsd serializes ECS state back to USDA strings.
• Runtime Sync: syncWorldToStage flushes ECS changes to USD for tools/editors.

Replication Flow

When a property update arrives from the server, it bypasses the USD layer and goes straight to the ECS for maximum performance.

sequenceDiagram
    participant Net as Network
    participant Client as CanvasClient
    participant Rep as SceneReplicator
    participant Reg as SchemaRegistry
    participant ECS as Flecs Component

    Net->>Client: HandlePropertyUpdate
    Client->>Rep: applyPropertyUpdate(Hash, Value)
    Rep->>Reg: Lookup(Hash)
    Reg-->>Rep: Reference to Schema & Offset
    
    Note over Rep, ECS: Direct Memory Write
    Rep->>ECS: memcpy(ptr + offset, value)
    
    ECS-->>App: OnSet System Triggered

Detailed Component Lifecycle

1. Registration: SceneReplicator::registerComponent<T> links a C++ type to a Network Schema.
2. Instantiation: sceneReplicator.createDefaultComponent instantiates the component when an EntityCreated message arrives.
3. Update: SceneReplicator::applyProperty writes values.
4. Post-Process: registerPostProcessor allows hooking into updates (e.g., to rebuild a GPU buffer when Mesh data changes).