Architecture

Crate Map

Patina is built as 13 focused Rust crates in a Cargo workspace. Each crate owns a single domain, with strict dependency boundaries and no circular references.

Dependency Graph

Crate dependencies (arrows show "depends on")

                    ┌──────────────┐
                    │ patina-runner │  (CLI app)
                    └──────┬───────┘
                           │
              ┌────────────┼────────────────┐
              ▼            ▼                ▼
        ┌──────────┐ ┌──────────┐    ┌───────────┐
        │ gdeditor │ │ gdscene  │    │ gdresource│
        └────┬─────┘ └────┬─────┘    └─────┬─────┘
             │            │                │
             ├────────────┼────────────────┤
             ▼            ▼                ▼
        ┌──────────┐ ┌──────────┐    ┌──────────────────┐
        │ gdobject │ │gdscript- │    │ gdphysics2d      │
        └────┬─────┘ │interop   │    │ gdserver2d       │
             │       └────┬─────┘    │ gdrender2d       │
             │            │          │ gdaudio           │
             │            │          │ gdplatform        │
             ▼            ▼          └────────┬─────────┘
        ┌──────────┐                          │
        │gdvariant │◄─────────────────────────┘
        └────┬─────┘
             │
             ▼
        ┌──────────┐
        │  gdcore  │  (foundation — no deps)
        └──────────┘

All Crates

Foundation

gdcore

Foundation types: math (Vector2/3, Transform2D/3D, Color, Quaternion), object IDs, NodePath, StringName, error handling. Every other crate depends on this.

gdvariant

depends on gdcore

Godot-compatible Variant tagged union. 20 types from Nil to Dictionary, with serialization support. The dynamic type system for all node properties.

Object System

gdobject

depends on gdcore, gdvariant

Object system: class registration, property metadata, signal declarations. Bridges static Rust types to Godot's dynamic object model.

gdresource

depends on gdcore, gdobject, gdvariant

Resource loading and caching. Parses .tres files, manages a thread-safe resource cache with Arc-based sharing.

Scene Management

gdscene

depends on gdcore, gdobject, gdresource, gdvariant

SceneTree, Node, PackedScene, MainLoop, and lifecycle management. Parses .tscn files, instances nodes, manages tree hierarchy, signals, groups, and frame stepping.

Runtime Services

gdphysics2d

depends on gdcore, gdvariant

2D physics simulation: rigid bodies, collision shapes, spatial queries, Godot-compatible physics stepping.

gdserver2d

depends on gdcore, gdvariant

2D rendering server: draw commands, viewport management, render state. Decouples scene logic from rendering backend.

gdrender2d

depends on gdcore, gdserver2d

2D rendering pipeline: sprite batching, z-sorting, camera transforms. Consumes draw commands from gdserver2d.

gdaudio

depends on gdcore

Audio playback system: bus routing, stream management, spatial audio foundations.

gdplatform

depends on gdcore

Platform abstraction: window management, input events, OS integration. Thin layer over platform-specific APIs.

Scripting

gdscript-interop

depends on gdcore, gdobject, gdvariant

GDScript interoperability: script attachment, method dispatch, and property access for scripted nodes.

Editor

gdeditor

depends on gdcore, gdobject, gdscene, gdvariant

Editor support: scene tree dock, inspector, project/editor settings, and editor-side tooling.

Applications

patina-runner

depends on gdcore, gdobject, gdresource, gdscene, gdvariant

Headless CLI runner: loads .tscn, runs N frames with MainLoop, dumps tree state as JSON. Used for CI testing and validation.

Architecture is stable

The crate boundaries and dependency graph are unlikely to change. New crates may be added but existing contracts are locked. See the getting started guide for usage examples.