Cod3x is the OpenMW-Lua engineering field manual.
It is an API companion, handbook, cookbook, performance guide, historical record, and tooling reference. The goal is not merely to tell you which function exists. The goal is to make the engine legible enough that you can reason about what your script is doing, why it is doing it, where the cost lives, and which mistakes have already been paid for.
Start here
Read Why Cod3x Exists, then choose Zero to Hero if OpenMW Lua is new to you. After that, build the mental model in Getting Started. If you already ship OpenMW Lua, Good Designs, Engineering Practice, and Performance are the useful parts immediately.
If something looks clever, inspect Anti-Patterns. If a design looks simpler than the problem it solves, inspect Good Designs. If a rule sounds suspiciously specific, there is a fair chance the explanation is in Paid For With Blood. If a machine is helping you work, read So You Want To Code With AI? before giving it the keys.
Follow the evidence graph
Cod3x pages are meant to give you three ways out of an idea: the doctrine, a reusable implementation, and the history that tested it.
| If you are thinking about... | Reusable H3 pattern | Production or historical trail |
|---|---|---|
| explicit state transitions | StateMachine | S3maphore state and lifecycle · generation counters |
| synchronous local observation | Signal | Events and Interfaces · pooling example |
| bounded temporary ownership | Pool | Pooling and Signals |
| caching and invalidation | memoize | Caching Without Creating New Bugs · resolver invalidation |
| path and VFS hygiene | normalizePath | VFS and Paths |
| bounded update work | Budget and Timing Helpers | S3maphore documentation · Every Frame Is a Budget |
| settings plus transient state | ProtectedTable | Storage and Lifecycle |
| Morrowind UI composition | H3UI and UI Recipes | UI: From Nothing to Something |
| investigation and proof | Pr0f1l3r | Source-Diving Workflow · Historical Evidence Index |
Other useful pairings are Result for explicit error values, ScriptContext for narrow shared-module introspection, randomGen for allocation-conscious random calls, and uiSnapshot for structural UI inspection. For settled-input work, see Debounce; for one-shot or rate-limited polling, see Once and Cooldown.
The useful path is usually principle → H3 pattern → production implementation → receipt. Use the links at the point where the idea becomes actionable; the history is not decoration.
What this manual is built from
Cod3x is not written from generic Lua advice. Its initial corpus is the complete available history of the St4sh, DreamScripts, Starwind Builder, and Rubic0n repositories, plus the current Cod3x annotations and OpenMW-facing production code in the St4sh.
That corpus contains thousands of fixes, experiments, reversions, performance passes, cache designs, event systems, sandbox boundaries, profiler work, and runtime changes. The history is useful precisely because the current code did not spring into existence fully formed.
See Provenance and Research Corpus for how evidence is classified and how historical code is used.
Read by problem
- New to OpenMW Lua: The OpenMW Lua Mental Model
- Unsure where an API exists: Script Contexts
- Confused by objects, records, and
types: Objects, Records, Types, and Cells - Choosing between events and interfaces: Events and Interfaces
- Writing stateful code: Storage, Save State, and Lifecycle
- Trying to put literally anything on screen: UI: From Nothing to Something
- Deciding whether advice is a fact or an opinion: Contracts, Measurements, Derivations, and Preferences
- Thinking about
pcall: Error Handling - Chasing performance: Measure First
- Profiling in game: Pr0f1l3r
- Reading LuaJIT output: Bytecode and Traces
- Trying to optimize the engine boundary: Engine Boundaries
- Wondering why Rubic0n exists: When Lua-Side Optimization Stops Being Enough