Skip to content

Architecture

This directory contains maintained architecture documentation for the current implementation.

The current pre-1.0 surface includes sparse residency, queued operations with result channels, the schedule with cadences and the selectable parallel phase executor, movement classes with per-class topology and transition providers, A* with the region-graph precheck, distance-field products and caches, the ECS adapter (EnTT-gated), the versioned DeltaFrame render bridge, compile-gated diagnostics, and the GPU backend interface (interface only in the current pre-1.0 release).

Layer Map

Arrows point from foundations to the higher-level facilities they enable. Optional adapters remain outside the dependency-free core surface.

flowchart TB
  accTitle: tess module dependency layers
  accDescr: Core and storage foundations support block operations and topology, which in turn support queued work, paths, and simulation.

  Core["Core: shapes, coordinates, keys"]
  Storage["Storage: schema, pages, worlds, residency"]
  Block["Block: domains, views, write policies"]
  Ops["Operations: queue, planner, executors, results"]
  Topology["Topology: movement classes and region graph"]
  Path["Path: searches, products, and caches"]
  Sim["Simulation: schedule, agents, movement, deltas"]
  Core --> Storage
  Storage --> Block
  Storage --> Topology
  Block --> Ops
  Topology --> Path
  Storage --> Path
  Ops --> Sim
  Path --> Sim

Optional integration headers sit on explicit boundaries and are never pulled into the dependency-free umbrella by accident.

flowchart TB
  accTitle: Optional integration boundaries
  accDescr: Consumers opt into ECS adapters, the GPU interface, diagnostics, and ImGui panels without changing the dependency-free core.

  Sim["Simulation"] --> ECS["Consumer-provided ECS or EnTT adapter"]
  Storage["Storage"] --> GPU["Consumer-provided GPU backend"]
  Diagnostics["Compile-gated diagnostics"] --> Panels["Consumer-provided ImGui panels"]

Change Propagation

Mutations are useful downstream only when their metadata is declared accurately. Different metadata guards different derived products.

Dirty-Driven Work

flowchart TB
  accTitle: Dirty-driven downstream work
  accDescr: Accurate dirty masks and bounds trigger scheduled maintenance, path-agent replanning, and versioned render delta publication.

  Mutation["Committed mutation"] --> Dirty["Dirty flags and bounds"]
  Dirty --> Triggers["OnDirty tasks and configured pathing match"]
  Triggers --> Work["Rebuild derived state and replan agents"]
  Dirty --> Collector["DeltaCollector invalidations"]
  Collector --> Frame["Publish DeltaFrame"]

Region-Graph Freshness

flowchart TB
  accTitle: Region-graph freshness inputs
  accDescr: Topology versions and graph identity stamps decide whether precheck can trust connectivity or must fall back conservatively.

  TopologyDirty["mark_topology_dirty"] --> Version["Topology version"]
  Stamps["Residency, class, and provider stamps"] --> Freshness
  Version --> Freshness["Region-graph freshness"]
  Freshness --> Precheck["Trust precheck or fall back to A*"]

Path-Cache Validity

flowchart TB
  accTitle: Path cache validity inputs
  accDescr: Content versions and sparse residency generations invalidate cached routes and products before stale results can be returned.

  Dirty["mark_dirty"] --> Version["Chunk content version"]
  Residency["Sparse residency generation"] --> Fingerprint
  Version --> Fingerprint["Cache fingerprint or product dependencies"]
  Fingerprint --> Decision["Reuse cached result or rebuild"]

Maintained notes for implemented areas:

C++ implementation work follows the active style policy.

The umbrella header tess/tess.h exports the dependency-free core surface plus the configured TESS_VERSION_MAJOR, TESS_VERSION_MINOR, and TESS_VERSION_PATCH macros and their typed tess::version / tess::library_version representation. Optional integrations that require consumer-provided EnTT or Dear ImGui declarations are deliberately not included; consumers include those adapter headers explicitly.

surface.json maps each maintained doc to the public symbol names it documents; tools/check_public_surface.py compares that manifest against the headers in TESS_PUBLIC_HEADERS and the generated version-header template. It covers public types, aliases, concepts, constants, free functions, and macros, and rejects both undocumented declarations and stale manifest entries. The check is a required gate in CI's hooks-backstop job; the companion tools/check_public_docs.py requires Doxygen comments for namespace-scope API declarations across every installed header, including public declarations whose definitions live in an implementation header included by an umbrella.

Historical design intent (TDD archive)

The TDD archive preserves the original design intent behind each area. These documents are non-authoritative: the maintained notes above and the code are the source of truth for current behavior.