Architecture Overview

SiliconGhetto is a browser-first game runtime platform written in Rust and TypeScript, compiled to WebAssembly, and rendered via wgpu. This document describes the high-level architecture and how runtime, content, rendering, input, tools, save/replay, and first-party templates 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. Platform composition: Games are versioned compositions of runtime settings, worlds, content packs, capabilities, and tool contracts.
  4. Data-driven: Game state and content move through schemas, registries, migration records, and replayable input streams.
  5. Minimal runtime: Ship only what’s needed. No framework bloat, no unused abstractions.
  6. 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 primary / WebGL2 fallback            │
└──────────────────────────────────────────────────────────────┘

Crate Dependency Graph

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

sg_kernel ──→ sg_runtime ──→ sg_content
     │              │              │
     └────────→ sg_save      sg_tools_api
                    │              │
              sg_observability ←───┘

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_kernel, sg_runtime, sg_content, sg_save, sg_tools_api, sg_observability, and sg_platform_contracts.

The sg_engine crate provides pack-template integration for the first-party survival pack. The platform center is the runtime contract: capabilities, registries, schedules, content packs, saves, replay, tools, and observability.

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-first rendering with WebGL2 fallback only when hardware WebGPU is unavailable or unsuitable

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.