Crate Graph

Kóoch is a Cargo workspace of 20 crates: 19 under crates/ plus the top-level kooch facade. 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

They sit in nine 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. That is a property of Cargo.toml, not an opinion, so it is read out of the workspace rather than assigned:

python3 .github/scripts/crate_layers.py          # the two tables below
python3 .github/scripts/crate_layers.py --check   # or just: did they drift?

🔴 This page had drifted, and the drift is the argument for that script. It claimed eight layers over 18 crates, put kooch_input and kooch_camera two and three layers below where they are, listed kooch_render in two tables at once, and did not mention kooch_pack at all — while asserting that the layers move “whether or not anyone updates this page”. Derived once by hand is not derived.

Two of those placements are worth a sentence, because neither is where a reader would guess:

• kooch_camera is L5, not L3, because a VirtualCamera asks kooch_gravity::gravity_up which way up is. On a planet, up is not +Y, and a camera rig that assumed it would roll over at the equator. Without kooch_gravity compiled in, the mode falls back to world up.
• kooch_core depends on kooch_pack, which is why the container crate is foundation rather than tooling: the asset server opens .kpack files, so the format has to sit under the crate that reads them.

Inter-layer flow

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

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

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

Detailed dependency table

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

⚠️ examples/example_plugin is a workspace member and is not one of the 20. It is a member so that cargo test builds it — a plugin that stops compiling is a broken ABI, and finding that out from a user is late.

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)

Built on the renderer (L5)

Gizmo interaction (L6)

Editor (L7)

Binary and facade (L8)

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 — Cargo refuses a cycle, so that half needs no enforcing. What is only enforced by review is whether a new edge is the right edge: kooch_camera → kooch_gravity is a real dependency and moved the crate two layers, and nothing objected.

crate_layers.py --check catches the documentation drifting from the graph. It does not catch the graph drifting from the design.

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, then run python3 .github/scripts/crate_layers.py --check — a new crate usually moves somebody else’s layer, and that is the part nobody remembers.