Overview

Cod3x

Cod3x is the OpenMW-Lua development companion: Lua Language Server annotations, context-aware diagnostics, and an engineering field manual built from years of production OpenMW Lua, profiler work, repository history, and runtime archaeology.

The annotations answer what exists.

The Cod3x Field Manual answers how to engineer with it, why the rules exist, where the engine costs live, and which mistakes have already been Paid For With Blood.

Field Manual

Start with Why Cod3x Exists, then use the manual by problem:

• Zero to Hero: build your first OpenMW Lua mod
• OpenMW Lua mental model
• script contexts
• objects, records, types, and cells
• error handling
• Good Designs
• performance
• Pr0f1l3r
• LuaJIT bytecode and traces
• Paid For With Blood
• Coding with AI: OpenCode agents, skills, and workflows
• So You Want To Code With AI?

Cod3x is also the map legend for the rest of the site. Follow a rule into an H3 pattern library, a S3maphore production system, or the historical evidence index.

LuaLS setup

Add the Cod3x folder to workspace.library, select LuaJIT, and load the Cod3x context plugin with runtime.plugin:

{
  "workspace.library": ["/absolute/path/to/Cod3x"],
  "runtime.version": "LuaJIT",
  "runtime.plugin": "/absolute/path/to/Cod3x/omw_context_plugin.lua"
}

Cod3x ships an example config at examples/openmw-mod/.luarc.json.

Declare script context

Add a context annotation near the top of every OpenMW-facing script:

---@omw-context player

Available contexts are global, local, player, menu, and load, plus Cod3x's shared-code sets runtime, all, and none.

For shared code, combine contexts with |:

---@omw-context global | player

Use scoped context assertions when only a narrow block has a stronger runtime guarantee:

---@omw-context global | player
local core = require 'openmw.core'

---@omw-context-next player
local camera = require 'openmw.camera'

See Script Contexts for the model and exact semantics.

Type your own interfaces

Keep interface metadata in your workspace; OpenMW does not load it:

---@meta

---@class openmw.interfaces
---@field MyMod? openmw.interfaces.MyMod

---@class openmw.interfaces.MyMod
---@field version string
---@field doThing fun(target: unknown): boolean

Editor formatting

Cod3x's context plugin uses virtual LuaLS transforms. They improve context-aware diagnostics but must not become the source text for on-type formatting edits.

If VS Code/VSCodium inserts or indents text incorrectly, disable LuaLS on-type formatting for the workspace. The example .luarc.json carries the recommended settings.