Data-Oriented Architecture: ECS & Scenes

Zith has native support for data-oriented programming through components (POD data), entities (component containers), and scenes (memory regions / arenas).

Components

Components are plain-data component structs (see Type System). They are copy-by-default, C-compatible, and may contain pure transformation functions.

component Position { [x, y]: f32 }

component Velocity { dx: f32, dy: f32 }

component Health {
    hp: u32,
    max_hp: u32,

    fn takeDamage(self: lend, damage: u32) {
        self.hp = if (self.hp > damage) { self.hp - damage } else { 0 };
    }
}

Component constraints (all must hold):

• All fields are primitives or other components (no structs, unions, enums that aren't integers).
• No trait implementations (no implement ComponentName as Trait).
• Inline functions allowed, but only pure transformations — no I/O, allocation, or global mutation.
• Copy is always bitwise (memcpy-safe).
• Layout is C-compatible (no vtable, no fat pointers).
• No self-referential fields (?unique Self, ?belong Self).

Scenes (Memory Regions)

A Scene is a memory region (arena / zone allocator). Entering a new scene replaces the previous one — resetting memory rather than stacking. A scene may specify a custom Allocator.

// Default allocator
scene GameLevel {
    let terrain  = @allocate(Terrain, levelData);
    let entities = @allocate([_]Entity, entityList);
    runLevel(terrain, entities);
    // all memory freed here
}

// Custom bump allocator
scene GameFrame: BumpAllocator {
    let scratch = @allocate([4096]u8);
    renderFrame(scratch);
}

Scene Organisation

scene MainMenu {
    entity MenuButton { /* ... */ }
    entity TextDisplay { /* ... */ }
}

scene GameLevel {
    entity Player { /* ... */ }
    entity Enemy { /* ... */ }
    entity Item { /* ... */ }
}

// Transition between scenes
transition(MainMenu, GameLevel);   // old scene dies, new scene allocates

ECS Patterns

Use a scene per logical region for cache-friendly simulation logic and lifecycle-scoped allocation.

scene MainLevel { /* all main level entities and resources */ }
scene BossRoom  { /* boss-specific entities */ }

// Memory is automatically reclaimed when exiting a scene

Intrinsic Prefixes

• @ — compiler intrinsics / reflection: @allocate, @struct, @members, etc.
• # — variable/field attributes: #volatile, #thread_local, #wontRemain, etc.

Related: Type System | Memory Management