Architecture Overview

SiliconGhetto is a browser-first game engine written in Rust, compiled to WebAssembly, and rendered via wgpu. This document describes the high-level architecture and how the major subsystems interact.

Design Principles

  1. Browser-first: Every architectural decision optimizes for the browser runtime. Native builds exist for development tooling and testing, not as a primary target.
  2. Worker-first: The game loop runs in a Web Worker using OffscreenCanvas, keeping the main thread responsive.
  3. Data-driven: Game state is structured as ECS components that can be authored, serialized, and validated as data.
  4. Minimal runtime: Ship only what’s needed. No framework bloat, no unused abstractions.
  5. Isolation by default: Cross-origin isolation headers are always present, enabling SharedArrayBuffer and future WASM threading.

System Architecture

┌──────────────────────────────────────────────────────────────┐
│                      Browser Runtime                          │
├──────────────────────────┬───────────────────────────────────┤
│  Main Thread             │  Worker Thread                     │
│  ┌────────────────────┐  │  ┌──────────────────────────────┐ │
│  │ HTML/CSS Shell      │  │  │ sg_app    (lifecycle)        │ │
│  │ Input Capture       │──→  │ sg_scene  (bevy_ecs world)   │ │
│  │ Overlay UI          │  │  │ sg_render (wgpu pipeline)    │ │
│  │ A11y Layer          │  │  │ sg_input  (state machine)    │ │
│  └────────────────────┘  │  │ sg_assets (loader)            │ │
│                          │  │ OffscreenCanvas → wgpu surface │ │
│                          │  └──────────────────────────────┘ │
├──────────────────────────┴───────────────────────────────────┤
│                    WASM (wasm32-unknown-unknown)               │
├──────────────────────────────────────────────────────────────┤
│                    wgpu → WebGPU / WebGL2                      │
└──────────────────────────────────────────────────────────────┘

Crate Dependency Graph

sg_core ←── sg_math
  ↑            ↑
  │            │
sg_scene ──→ sg_render ──→ wgpu
  ↑            ↑
  │            │
sg_app ──→ sg_worker ──→ sg_input
  ↑
  │
sg_assets ──→ sg_manifest

Leaf crates (no internal dependencies): sg_core, sg_math, sg_audio, sg_ui Integration crates: sg_app (ties everything together), sg_demo_shared (demo utilities) Tool crates: sg_cli (developer CLI), sg_manifest (game package definitions) Platform crates: sg_platform_contracts (engine↔platform shared types)

Game Loop

The engine uses a fixed-timestep game loop with variable rendering:

┌─────────────────────────────────────────────┐
│ requestAnimationFrame callback              │
│  1. Calculate delta time                    │
│  2. Accumulate time                         │
│  3. While accumulated >= fixed_step:        │
│     ├─ Run physics / game logic systems     │
│     └─ Consume one fixed_step               │
│  4. Prepare render data (sprite batches)    │
│  5. Submit GPU commands                     │
│  6. Present frame                           │
│  7. Update performance counters             │
│  8. Request next frame                      │
└─────────────────────────────────────────────┘

Fixed timestep (default 1/60s) ensures deterministic physics regardless of frame rate. Rendering happens every frame at the display’s refresh rate.

Rendering Pipeline

See rendering.md for the full rendering architecture.

The rendering layer is built on wgpu and supports:

  • 2D sprite batching with instanced rendering
  • 3D mesh rendering with depth testing and lighting
  • WGSL shaders
  • WebGPU with automatic WebGL2 fallback

ECS Architecture

See data-driven.md for the data-driven design philosophy.

The ECS layer uses bevy_ecs standalone:

  • Components: Plain Rust structs with #[derive(Component)]
  • World: Single bevy_ecs::World holds all entities and components
  • Queries: Type-safe queries iterate over entities matching component patterns
  • Resources: Global state accessed via the World

Asset Pipeline

Assets are loaded via sg_assets:

  • Development: Fetch from local server via HTTP
  • Production: Bundled with the WASM binary or loaded from CDN
  • Format: glTF 2.0 for 3D, KTX2/Basis for textures (see ADR-005)

Platform Integration

The engine communicates with the platform layer via contracts defined in sg_platform_contracts:

  • GameEntry: Metadata for published games
  • ArtifactStore: Trait for storage backends
  • GameManifest: Package definition (sg-game.toml)

See platform-vision.md for the full platform design.