Software design document
This is the top-down design of the Kerosene engine: what it is for, how it is put together, why it is put together that way, and where it is going. It is the place to start when you need the whole picture, and the place to record a design decision so it is not lost.
It is deliberately not a second copy of the rest of the book. Each chapter states the design and the reasoning, then links to the page that holds the detail:
| If you want… | Read |
|---|---|
| to use the engine | Making games |
| a reference for one feature | Documentation |
| the internals of one subsystem | Devnotes |
| Status | 1.0.0-a4 (alpha) |
| Last reviewed | 2026-09-30 |
| Owner | T342 |
| Scope | The workspace in this repository. The demo game lives in a separate repository (kerosene-demo). |
Chapters
- Goals and scope
- Design principles
- Architecture
- Runtime
- Data and the build pipeline
- World and entities
- Subsystems
- Tools
- Public API
- Quality
- Decision log
- Status and roadmap
- Open issues
Editing this document
- One chapter is one file in
src/sdd/. Edit it, and keep the chapter list above and insrc/SUMMARY.mdin step. - Change Last reviewed above when you review the document, not on every typo fix.
- State a design as a rule plus a reason. A rule with no reason cannot be re-examined later.
- Anything that must stay true of the code belongs in a check (
cargo xtask layers, a test), with the chapter pointing at it. A claim only in prose drifts. - New decisions go in the decision log; known gaps go in open issues. Remove an issue when it is fixed.
- Diagrams are mermaid blocks, as in the devnotes.
- Relative links only: CI runs
scripts/check-links.pyover the book.
To preview: mdbook serve in the repository root.