Crate Graph

Kóoch is a Cargo workspace of 18 internal crates plus one top-level facade crate. The structure is intentionally fine-grained: each subsystem lives in its own crate so that downstream crates only depend on what they actually need. This keeps compile times low when iterating on a single subsystem and makes the dependency surface auditable at a glance.

Layers at a glance

The 18 internal crates (plus the top-level kooch facade) sit in eight layers. Each layer may only depend on layers below it.

The layer of a crate is its longest path to a crate with no internal dependencies — derived from cargo metadata, not assigned by hand. That matters: it means a crate moves layer when its dependencies change, whether or not anyone updates this page.

Inter-layer flow

The arrow direction reads as “A depends on B”. Within a layer, crates are siblings.

flowchart TD
    L7["L7 · binary + facade<br/>kooch_editor · kooch"]
    L6["L6 · editor<br/>kooch_editor_core"]
    L5["L5 · gizmo interaction<br/>kooch_gizmos_handles"]
    L4["L4 · built on domain<br/>kooch_render · kooch_gizmos · kooch_gravity"]
    L3["L3 · domain<br/>kooch_physics · kooch_camera<br/>kooch_lighting · kooch_world · kooch_remote"]
    L2["L2 · primitives<br/>kooch_ecs · kooch_window · kooch_input · kooch_audio"]
    L1["L1 · core<br/>kooch_core"]
    L0["L0 · foundation<br/>kooch_plugin_api · kooch_ecs_macros"]

    L7 --> L6
    L6 --> L5
    L6 --> L4
    L6 --> L3
    L6 --> L2
    L5 --> L4
    L4 --> L3
    L3 --> L2
    L2 --> L1
    L1 --> L0

Detailed dependency table

Per-crate internal dependencies (external deps like wgpu, winit, etc. are omitted).

Crate roles

Foundation (L0)

Crates with no internal dependencies. They can be built in isolation and form the type vocabulary the rest of the engine uses.

Core (L1)

Primitives (L2)

Small purpose-built crates that depend on kooch_core and nothing else.

Domain (L3)

Crates built directly on the ECS.

Built on domain (L4)

Gizmo interaction (L5)

Editor (L6)

Binary and facade (L7)

Layering rules

Important: Lower layers must not depend on higher layers. If you find yourself wanting kooch_core to know about kooch_render, you have an inversion. Common fixes: introduce a trait at the lower layer and implement it at the higher layer, or pass behavior in via a generic / closure.

The dependency graph is acyclic by construction. CI does not enforce this yet — manual review during code review.

Why so many crates?

Three reasons:

1. Compile-time isolation. Iterating on kooch_render does not recompile kooch_ecs or kooch_window. Cargo’s incremental compilation benefits from real crate boundaries far more than from module boundaries inside one giant crate.

2. Feature gating. The facade can compose user-facing builds (a headless server build skips kooch_render and kooch_window; an editor build pulls in kooch_editor_core). Single-crate builds cannot do this ergonomically.

3. Reasoning surface. Knowing that kooch_world cannot accidentally reach into kooch_render because Cargo enforces it makes refactors safer than relying on lint rules.

Tradeoff: more Cargo.toml files to maintain, more pub use re-exports when types need to cross crate boundaries, slightly higher first-build time. For an engine in early development the compile-time win outweighs the ergonomic cost.

Adding a new crate

1. Create crates/kooch_yourthing/ with Cargo.toml extending workspace.package fields and Cargo.toml [workspace.dependencies] for external deps.
2. Add it to the members array in the root Cargo.toml.
3. Add it under [workspace.dependencies] so other crates can depend on it via workspace = true.
4. If it’s user-facing, re-export from kooch::* and add a feature flag to the top-level Cargo.toml [features] section.
5. Document its role in this page.