Introduction

Kóoch is a GPU-driven game engine written in Rust, with an editor.

The rendering path is a Nanite-style GPU-driven meshlet pipeline: the hot loop runs in compute on the GPU, and the CPU only coordinates. The ECS stays on the CPU — that is a deliberate, settled decision, not a stage on the way to something else. What goes to the GPU is graphics, effects and their derivatives; physics will follow if and when rapier3d gains GPU support.

This is a personal, experimental project — not a stable production tool. The documentation reflects that: it explains what is, not what should be. Where something is missing or broken, this book says so and links the issue.

Audience

Two readers, with overlapping needs:

1. Engine users — anyone writing a game on top of Kóoch. Start with Your First Project, then The Editor.
2. Engine contributors — anyone touching crates/*. Start with Crate Graph and the Decisions Log.

Status

Early development. The pieces work together end to end — window, ECS, scene serialisation, meshlet renderer, sky, physics, editor — but the feature surface is narrow on purpose and APIs break freely.

What works today:

• An 18-crate Rust workspace plus a facade, edition 2024.
• GPU-driven meshlet rendering with a LOD chain, plus glTF mesh loading. A frame is a list of views, so the editor’s viewport and the game’s camera render from one stage.
• Cook-Torrance lighting driven by the light components — see Lighting. New as of #441; before it, the renderer painted the world-space normal as colour and a scene with lights looked exactly like one without.
• Rigid-body physics on rapier3d: colliders, joints, collision events, sensors, materials, and custom gravity fields that sum.
• Procedural sky and volumetric clouds.
• Scene serialisation (.scene, RON) driven by reflection, with more than one scene loadable at once.
• Input as data: an action is an asset, with composites and processors, editable in a panel.
• An editor: viewport, hierarchy, Inspector, Console, asset browser, drag-and-drop, dockable layout, undo/redo, project Hub, a Game panel beside the View panel, and Play/Stop that snapshots and restores the authored world. Hovering a field shows its doc comment, units included.
• A project’s own components and systems, written in Rust, loaded into the editor as a dylib.

What does not work yet, stated plainly:

• No hot reload. Seeing a code change means rebuilding and reopening the editor (#648).
• No build button. cargo build is yours to run (#158).
• Reflection is shallow. No Vec<T>, no HashMap, no user enums in components (#649).
• No shadows. Lit with no shadows is where the renderer is: better than a normal painted as colour, and it cannot tell you where anything is touching (#476).
• No global illumination, which is why punctual light defaults are larger than physics says they should be (#450). The Lighting page explains the trade rather than hiding it.

Stack

License

All Rights Reserved. Copyright (C) 2025-2026 Matías Galarza (“Lobinux”, lobinuxsoft).

The repository is public so the work can be read and so the project can use branch protection and Pages. That is not a licence to use it: see LICENSE.md.

How to read this book

User Guide and Scripting are the public API surface. Architecture covers internals. Reference holds the long-form material: the Decisions Log is a chronological record of architectural choices, why they were made, and what was traded away.

Two files in the repository outrank this book when they disagree: docs/MEMORY.md is canonical on decisions, and docs/ROADMAP.md is canonical on order.