Overview
This file covers the two facts every other file in this directory rests on: the one-way relationship between SushiEngine and SushiRuntime, and the layer stack the modules are arranged into.
1. The head and the battery
SushiEngine is a head; SushiRuntime is a plugged-in component — the battery. The engine is the product a game is built against: it owns the loop, the world, and — as it grows — the window, the renderer, and the editor. SushiRuntime is a hardware-agnostic orchestration backbone the engine hands work to.
The dependency points one way only:
SushiEngine ──depends on──▶ SushiRuntimeThe runtime never knows the engine exists. It has no concept of a game, a frame, an entity, a component, or a renderer; it schedules an abstract task graph across whatever hardware is present. This is deliberate, and it is the rule that keeps both projects changeable: the engine may be rewritten without touching the runtime, and the runtime may gain backends without the engine noticing.
A practical consequence: a feature that only composes the runtime’s public API belongs in the engine. A feature that needs the runtime to do something it cannot yet do belongs in SushiRuntime, behind its public API — not bolted onto the engine as a workaround.
2. Layers
Each layer depends only on the ones below.
| Layer | Headers | Responsibility |
|---|---|---|
| SushiLoop core | engine/world/loop/include/SushiEngine/loop/ — engine/world/loop/include/SushiEngine/loop/app.hpp, engine/world/loop/include/SushiEngine/loop/fixed_timestep.hpp, engine/world/loop/include/SushiEngine/loop/input.hpp, engine/world/loop/include/SushiEngine/loop/rollback.hpp, engine/world/loop/include/SushiEngine/loop/net.hpp; plus engine/foundation/core/include/SushiEngine/core/random_number_generator.hpp |
The Loop::App authoring API over a fixed-step deterministic loop; plus seeded RNG, per-tick input capture, rollback snapshots, and loopback network reconciliation (see rollback, SushiLoop core, and the milestones). |
| UI | engine/domain/ui/include/SushiEngine/ui/ — engine/domain/ui/include/SushiEngine/ui/rect.hpp, engine/domain/ui/include/SushiEngine/ui/components.hpp, engine/domain/ui/include/SushiEngine/ui/layout.hpp, engine/domain/ui/include/SushiEngine/ui/interaction.hpp, engine/domain/ui/include/SushiEngine/ui/ui.hpp |
Retained ECS UI (Unity UGUI-shaped): RectTransform/Canvas/UIImage/UIText/UIButton components, the resolve_rect anchor solver, the pointer/click model, and the UI façade that builds, lays out, and drives a canvas of buttons (see docs/architecture/DOMAIN_UI.md). |
| Physics | engine/domain/physics/include/SushiEngine/physics/ — core/, geometry/, collision/, constraints/, solver/, scene/, aero/, character/ (plus cooking/, its own row below) |
Body state and handles, shapes and mass properties, broad/narrowphase, constraint descriptors and their projections, the XPBD solvers behind IConstraintSolver, the world lifecycle, the wind field, and the character mover (see docs/architecture/DOMAIN_PHYSICS.md). Deformable and articulated non-rigid materials are docs/design/MATTER_SYSTEM.md’s. |
| Geometry | engine/domain/geometry/include/SushiEngine/geometry/ — engine/domain/geometry/include/SushiEngine/geometry/triangle_mesh.hpp, engine/domain/geometry/include/SushiEngine/geometry/mesh_utilities.hpp, engine/domain/geometry/include/SushiEngine/geometry/mesh_distance_query.hpp, engine/domain/geometry/include/SushiEngine/geometry/signed_distance_field.hpp |
Engine-neutral triangle geometry: the mesh value types, topology analysis and repair, a host closest-point hierarchy, and the shared signed-distance baker that queries it. Links nothing — no Vulkan, no SYCL, no runtime — because both the renderer and the physics read it and neither may own it. |
| Cooking | engine/domain/physics/include/SushiEngine/physics/cooking/ — engine/domain/physics/include/SushiEngine/physics/cooking/cooking_parameters.hpp, engine/domain/physics/include/SushiEngine/physics/cooking/cooking_report.hpp, engine/domain/physics/include/SushiEngine/physics/cooking/cooker_interface.hpp, engine/domain/physics/include/SushiEngine/physics/cooking/cooked_asset_store.hpp, engine/domain/physics/include/SushiEngine/physics/cooking/collision_cooker.hpp, engine/domain/physics/include/SushiEngine/physics/cooking/mesh_post_processor.hpp, engine/domain/physics/include/SushiEngine/physics/cooking/cooking_service.hpp |
The offline pipeline that turns an imported mesh into a simulation asset: docs/design/PHYSICS_SYSTEM/README.md §8.2’s fidelity dial, the cook report and the thresholds that fail a bad cook loudly, the ICookingStage/IMeshCooker/ICookedAssetStore seams, the content-hash cache, the collision cooker that produces .sushicollision, and the ordered import chain that runs it on a worker thread. Host-only, links only Geometry (plus Threads), and never linked into a shipping runtime path — an importer that needs a GPU is an importer that fails on a build machine. Getting triangles out of a file is a MeshLoader seam the consumer wires, which is why this module needs no cgltf (see §8 of docs/design/PHYSICS_SYSTEM/README.md). Cooking a non-rigid material is docs/design/MATTER_SYSTEM.md’s. |
| Atmosphere | engine/domain/atmosphere/include/SushiEngine/atmosphere/ — engine/domain/atmosphere/include/SushiEngine/atmosphere/fourier_transform.hpp, engine/domain/atmosphere/include/SushiEngine/atmosphere/quasigeostrophic_core.hpp |
T1, the global dynamical core: two-layer moist quasi-geostrophic flow on a latitude/longitude grid, from which cyclones, fronts, the jet and storm tracks emerge rather than being placed (see §5 of docs/design/ATMOSPHERE_SYSTEM/README.md). Links nothing, for the same reason Geometry does — its consumers are gameplay queries, the regional nest’s parent forcing, and a headless probe, and none should need a device to ask what the weather is. The regional nest (T2) is a Vulkan compute service and stays under engine/presentation/render/source/atmosphere/. |
| Animation | engine/domain/animation/include/SushiEngine/animation/ — skeleton*.hpp, clip*.hpp, animator_*.hpp, engine/domain/animation/include/SushiEngine/animation/blend_tree.hpp, engine/domain/animation/include/SushiEngine/animation/avatar_mask.hpp, engine/domain/animation/include/SushiEngine/animation/additive.hpp, engine/domain/animation/include/SushiEngine/animation/pose_modifier.hpp, ik_*.hpp, engine/domain/animation/include/SushiEngine/animation/morph.hpp, engine/domain/animation/include/SushiEngine/animation/generic_track.hpp, engine/domain/animation/include/SushiEngine/animation/humanoid.hpp, engine/domain/animation/include/SushiEngine/animation/retarget.hpp, engine/domain/animation/include/SushiEngine/animation/edit_preview.hpp, engine/domain/animation/include/SushiEngine/animation/animation_database.hpp |
Skeletal-animation stack (phases A0–A9): skeleton/clip/controller/mask assets, the deterministic animator_step, the AnimatorEvaluator (blend trees, mask-gated layers, additive), the IK / pose-modifier stack, morph + generic tracks, humanoid retargeting, and controller JSON authoring, behind the IAnimationDatabase seam (see docs/architecture/DOMAIN_ANIMATION.md). |
| Execution | engine/foundation/execution/include/SushiEngine/execution/ — engine/foundation/execution/include/SushiEngine/execution/access.hpp, engine/foundation/execution/include/SushiEngine/execution/interval.hpp, engine/foundation/execution/include/SushiEngine/execution/node_descriptor.hpp, engine/foundation/execution/include/SushiEngine/execution/hazard.hpp, engine/foundation/execution/include/SushiEngine/execution/context.hpp |
The seam every subsystem allocates and schedules through: the access algebra (AccessIntent, BufferInterval, DeterminismClass), the normative hazard semantic, and the Context/Graph/Buffer names a compile-time backend policy resolves. SushiRuntime is one implementation of it (engine/foundation/execution/include/SushiEngine/execution/backend/runtime_backend.hpp), not the thing the engine is typed against (see the ECS and the system graph and docs/design/UNIFIED_HAZARD_MODEL.md). |
| Schedule | engine/foundation/ecs/include/SushiEngine/ecs/schedule.hpp |
Compiles systems to an execution graph and replays it. |
| Commands | engine/foundation/ecs/include/SushiEngine/ecs/command_buffer.hpp |
Records structural changes, applied at a barrier. |
| World | engine/foundation/ecs/include/SushiEngine/ecs/world.hpp |
Entities, archetypes, spawn/destroy, component access. |
| Storage | engine/foundation/ecs/include/SushiEngine/ecs/archetype.hpp, engine/foundation/ecs/include/SushiEngine/ecs/chunk.hpp |
Archetype chunks of structure-of-arrays columns. |
| Identity | engine/foundation/ecs/include/SushiEngine/ecs/entity.hpp, engine/foundation/ecs/include/SushiEngine/ecs/component.hpp |
Entity handles, component ids, access tags. |
| Value types | engine/foundation/core/include/SushiEngine/core/types.hpp |
The single seam for scalars and vectors (see the value-type seam). |
engine/include/SushiEngine/SushiEngine.hpp is the umbrella header that pulls the surface
together.