Data Storage

Vulkan Schnee uses EnTT for high-performance data-oriented ECS, combined with wrapper classes for game logic.

Core Concepts

Entity

entt::entity is a lightweight handle (32-bit integer). Entities own components stored in the registry.

Registry

Engine::Ecs::RegistryManager::get() provides access to the global EnTT registry. All component data lives here.

auto& registry = Engine::Ecs::RegistryManager::get();
entt::entity entity = registry.create();
registry.emplace<Engine::Ecs::Transform>(entity, glm::mat4{1.0f});

Components

Components are pure data structs in the Engine::Ecs namespace (defined in Engine/include/Engine/Ecs/EcsData.h).

namespace Engine::Ecs {
    struct Transform {
        glm::mat4 matrix;
    };
 
    struct WorldTransform {
        glm::mat4 matrix;
    };
 
    struct Tick {
        Engine::Core::ITickable* tickable;
        int32_t priority;
    };
}

Architecture Pattern

Vulkan Schnee uses composition for data, inheritance for type safety.

Data layer: EnTT components store raw data for cache-friendly iteration. Logic layer: C++ classes wrap entities and provide game logic.

Entity (Base Class)

Engine::Entities::Entity wraps an entt::entity handle.

Fields:

• entt::entity data_ - Handle to ECS entity
• std::vector<std::unique_ptr<Engine::Components::Logic>> components_ - Logic components, not ECS components
• bool allowTicking_ - Allows this entity to register for ticking
• int32_t tickPriority_ - Sort key for tick order

Usage:

class Entity {
protected:
    entt::entity data_ = entt::null;
    std::vector<std::unique_ptr<Engine::Components::Logic>> components_;
    bool allowTicking_ = false;
    int32_t tickPriority_ = 0;
};

Entities register themselves for ticking:

void Entity::enableTick(bool enable) {
    auto& registry = Engine::Ecs::RegistryManager::get();
    if (enable && canEverTick()) {
        registry.emplace_or_replace<Engine::Ecs::Tick>(data_, this, tickPriority_);
    } else if (registry.all_of<Engine::Ecs::Tick>(data_)) {
        registry.remove<Engine::Ecs::Tick>(data_);
    }
}

Actor (Subclass)

Engine::Entities::Actor extends Entity with transform and scene graph.

Additional fields:

• std::optional<std::shared_ptr<SceneNode>> sceneNode - Scene graph node
• Scene* owningScene_ - Scene that owns the actor
• std::weak_ptr<Engine::Components::Scene> rootComponent_ - Optional root scene component
• bool hasEndedPlay_ - Prevents duplicate endPlay() execution

Usage:

class Actor : public Entity {
public:
    glm::vec3 getActorLocation() const;
    void setActorLocation(glm::vec3 newLocation);
    glm::mat4 getWorldTransform() const;
};

Actors live in the scene graph. Transform changes propagate through hierarchy.

Data Flow

1. Actor Creation

// Scene spawns actor
Actor* actor = scene->spawnActor<MyActor>(spawnTransform);
 
// Actor constructor creates ECS entity internally
// Entity base class initializes: data_ = registry.create()

2. Component Attachment

// MeshComponent wraps mesh rendering data
class MeshComponent {
    entt::entity componentEntity;  // Separate entity for component data
    Engine::Ecs::StaticMeshData* staticMeshData;
};
 
// Constructor creates component entity and attaches data
MeshComponent::MeshComponent(...) {
    auto& registry = Engine::Ecs::RegistryManager::get();
    componentEntity = registry.create();
    staticMeshData = &registry.emplace<Engine::Ecs::StaticMeshData>(componentEntity);
    registry.emplace<Engine::Ecs::Parent>(componentEntity, actor->getEcsEntity());
}

3. Data Synchronization

Scene graph transforms sync to ECS:

// SceneNode marks transforms dirty
registry.emplace_or_replace<Engine::Ecs::TransformDirty>(entity);
 
// Engine syncs hierarchy
auto view = registry.view<Engine::Ecs::TransformDirty, Engine::Ecs::WorldTransform>();
for (auto entity : view) {
    // Update world transform from parent chain
}

4. Rendering Query

Renderer iterates ECS components directly (no wrapper overhead):

// Query all mesh components for rendering
auto view = registry.view<Engine::Ecs::MeshComponentRef>();
for (auto entity : view) {
    auto& meshRef = view.get<Engine::Ecs::MeshComponentRef>(entity);
    for (Engine::Components::Mesh* mesh : meshRef.components) {
        // Upload transform, draw mesh
    }
}

Wrapper vs ECS Storage

Wrapper Classes (Slow Path)

Game logic uses wrappers: Actor, MeshComponent, Scene.

Purpose:

• Type-safe API
• Virtual functions (beginPlay, tick, endPlay)
• Complex operations (physics, input, animation)

Access pattern:

actor->setActorLocation(newPos);  // Wrapper method
// → Updates scene graph
// → Marks ECS transform dirty

ECS Storage (Fast Path)

Renderer uses ECS directly for hot loops.

Purpose:

• Cache-friendly iteration
• SIMD-friendly data layout
• Parallel processing

Access pattern:

auto view = registry.view<Engine::Ecs::WorldTransform, Engine::Ecs::MeshPrimitiveData>();
for (auto entity : view) {
    // Process thousands of entities per frame
}

Common Patterns

Registry Queries

auto& registry = Engine::Ecs::RegistryManager::get();
 
// Single component
if (registry.any_of<Engine::Ecs::TransformDirty>(entity)) {
    auto& transform = registry.get<Engine::Ecs::WorldTransform>(entity);
}
 
// Multiple components
auto view = registry.view<Engine::Ecs::StaticMeshData, Engine::Ecs::Parent>();
for (auto entity : view) {
    auto [mesh, parent] = view.get(entity);
}
 
// Exclude components
auto view = registry.view<Engine::Ecs::Tick>(entt::exclude<Engine::Ecs::SimulatesPhysics>);

Dirty Flags

Transform changes use two-stage dirty tracking:

Stage 1: Scene graph sync

registry.emplace<Engine::Ecs::TransformDirty>(entity);
// Engine propagates hierarchy
// Clears TransformDirty after sync

Stage 2: GPU upload

Engine::Ecs::RendererDirtyList::push(entity);
// RenderingDataManager uploads to GPU
// Clears RendererDirtyList after upload

Separation prevents race conditions when transforms change during tick.

Asset Loading

Asset pipeline uses staged components:

// 1. Request asset load
registry.emplace<Engine::Ecs::AssetRequested>(entity);
 
// 2. Pipeline loads async, replaces with data
auto& meshData = registry.emplace<Engine::Ecs::MeshPrimitiveData>(entity);
registry.remove<Engine::Ecs::AssetRequested>(entity);
 
// 3. Renderer queries loaded data
auto view = registry.view<Engine::Ecs::MeshPrimitiveData>(entt::exclude<Engine::Ecs::AssetRequested>);

Example: Tick System

// Game code: Actor ticking (wrapper)
void ExampleScene::tick(double dt) {
    rat->rotateActor(glm::vec3(10.0f * dt, 90.0f * dt, 0.0f));
}
 
// Behind the scenes: ECS query
auto& registry = Engine::Ecs::RegistryManager::get();
auto tickView = registry.view<Engine::Ecs::Tick>();
for (auto entity : tickView) {
    auto& tickComponent = tickView.get<Engine::Ecs::Tick>(entity);
    tickComponent.tickable->tick(deltaTime);
}

Key Files

File	Purpose
Engine/include/Engine/Ecs/EcsData.h	All ECS component definitions
Engine/include/Engine/Ecs/RegistryManager.h	Registry singleton
Engine/include/Engine/Entity/Entity.h	Base wrapper class
Engine/include/Engine/Entity/Actor.h	Transform wrapper
Engine/src/Engine/Ecs/FrameProcessing.cpp	Asset loading pipeline
Engine/src/Engine/Renderer/RenderingDataManager.cpp	Rendering queries

Performance Notes

EnTT provides O(1) component access and cache-friendly iteration. Use wrappers for game logic, ECS for hot loops.

Wrapper overhead: Acceptable for tick/input (runs once per entity per frame). ECS direct access: Required for rendering (processes thousands of primitives per frame).

Transform hierarchy sync runs once per frame before rendering. Dirty flags minimize work.