About the design documents

Three documents in the repository decide how Labrador is built. They are published here exactly as they are written in docs/design/, read from the same revision as the rest of this site.

PhilosophyThe twelve trade-offs, T1 to T12, each with the side the engine takes, the price it accepts and the point where leaning further becomes a mistake.

ArchitectureThe build targets, the source tree, the ten modules and which may depend on which, and what a game project looks like.

ConventionsNaming, files, and what a comment is for.

How to read them

They describe where the engine is going, not a status report. They are written in the present tense of the target. When code moves, it moves towards them. When a change contradicts one, either the change is wrong or the document is, and the document is amended in the same commit, with the reason.

The trade-offs are vocabulary. Each has a number, and the number stands for the whole argument. “T3: take the simpler model” is a complete comment in a code review. Pages on this site link those numbers to their entries in the philosophy.

They were written for the people building the engine. That makes them the deepest explanation of why Labrador is the way it is, and not a tutorial. If you are new to the engine, Get started and Why Labrador? are the better first reads.