Engma

A ultra-minimalist meta-engine framework built in Zig. Engma implements generic abstraction over concrete implementation details, providing an extensible interface across world representations, physics implementations, etc. with 0 overhead.

Quick Start

# Build and run native
zig build run

# Build for web (WASM)
zig build web

# Just build
zig build

Architecture

The engine uses a modular system architecture with compile-time configuration:

src/
├── main.zig              # Entry point and system orchestration
└── engma/                # Core engine module
    ├── mod.zig               # Module exports
    ├── lib/                  # Core libraries
    │   ├── math.zig          # SIMD vector/matrix operations
    │   ├── input.zig         # Input state management
    │   ├── render.zig        # Rendering abstraction
    │   ├── audio.zig         # Audio system
    │   └── debug.zig         # Debug utilities
    ├── world/                # World representations
    │   └── greedy.zig        # Greedy meshing voxel world
    ├── physics/              # Physics solvers
    │   └── quake.zig         # Quake-style movement
    └── shader/               # Shader modules
        └── cube/             # Basic cube shader
            ├── mod.zig           # Shader interface
            ├── shader.glsl       # GLSL source
            └── shader.glsl.zig   # Generated bytecode

System Configuration

The engine uses a unified system structure for compile-time configuration:

const Engine = struct {
    systems: struct {
        world: engma.world.greedy,
        gfx: engma.lib.render(engma.shader.cube),
        body: engma.player.quake,
        keys: engma.lib.input,
        audio: engma.lib.audio,
        debug: engma.lib.debug,
    },
    // ...
};

All systems implement a common interface with init, tick, draw, event, and deinit methods called via compile-time reflection.

Performance Features

• Zero-cost abstractions: All polymorphism resolved at compile time
• SIMD operations: Vector math using @Vector(3, f32) primitives
• Bitpacked data: Efficient voxel storage with 8:1 compression
• Greedy meshing: Optimized mesh generation for voxel worlds
• GPU-resident geometry: Minimal CPU-GPU data transfers

Controls

Input	Action
WASD	Movement (forward/back/strafe)
Mouse	Camera orientation
Space	Jump
LMB	Toggle mouse capture
Escape	Release mouse

Build System

Dependencies

Managed via build.zig.zon:

• sokol-zig: Cross-platform graphics and input
• shdc: Shader compilation pipeline
• cimgui: Immediate mode GUI

Targets

• Native: Direct executable for desktop platforms
• Web: WASM build with Emscripten for browser deployment

Shader Pipeline

GLSL shaders are compiled to multiple targets:

• GLSL 4.10 (Desktop OpenGL)
• GLSL 3.00 ES (WebGL)
• Metal (macOS)
• WGSL (WebGPU)

Mathematical Foundations

Voxel World

• 4096 voxels compressed to 512 bytes via bitpacking
• Bit operations: bits[i>>3] |= 1<<(i&7)
• Greedy meshing with face culling
• O(n) mesh generation where n = visible faces

Physics

• Quake-style movement with air control and ground friction
• AABB collision detection with swept tests
• Multi-step integration for temporal stability
• Spatial queries via world.get(x,y,z)

Rendering

• Generic Mesh{vertices, indices} interface
• MVP matrix transformations
• Uniform buffer management via sokol-gfx

System Interfaces

All engine systems follow these contracts:

// Universal system interface
fn init(system: *System, engine: Engine) void
fn tick(system: *System, engine: Engine) void
fn draw(system: *System, engine: Engine) void
fn event(system: *System, engine: Engine) void
fn deinit(system: *System, engine: Engine) void

World System

fn get(x: i32, y: i32, z: i32) bool
fn mesh(vertices: []Vertex, indices: []u16) Mesh

Physics System

fn view() Mat4
fn mouse(dx: f32, dy: f32) void