Cod3xDocs
guide

Performance

Profiling, hot paths, caches, engine boundaries, LuaJIT analysis, and benchmark design.

“OpenMW Lua is slow” is not a diagnosis.

A useful performance investigation asks where the time or memory goes.

The cost may be:

  • Lua execution;
  • allocation;
  • table/string churn;
  • a repeated global/property lookup;
  • an engine query;
  • userdata construction/finalization;
  • serialization;
  • event dispatch;
  • ray casting or physics;
  • a C++ binding;
  • a LuaJIT trace abort or side exit;
  • GC behavior;
  • work that never belonged on every frame in the first place.

Start with Measure First. Use Pr0f1l3r for in-engine telemetry. Events, Serialization, and Boundary Traffic covers message-heavy systems. Move into Bytecode, Traces, and Engine Boundaries only when the evidence points there.

Do not start with the cleverest optimization you know.

Measure First Find the layer, establish a baseline, and make one claim at a time. Hot Paths, Hoisting, and Precomputation Localize and precompute where the path is actually hot, not everywhere on principle. Caching Without Creating New Bugs Cache by semantic lifetime, record absence explicitly, and invalidate next to the cause. Allocation and Garbage Collection Distinguish transient churn, retained memory, userdata lifetime, and collector pacing. Engine Boundaries The Lua code is only one layer; bindings, userdata, queries, and C++ work often dominate. Events, Serialization, and Boundary Traffic Message passing has semantic and representation costs; reduce crossings before micro-optimizing payload syntax. LuaJIT Bytecode Analysis Read what the VM receives before guessing what source syntax costs. LuaJIT Traces, Aborts, and Side Exits Understand what got compiled, where it bailed out, and whether that matters to the workload. Pr0f1l3r In-engine timing, allocation attribution, throughput windows, and LuaJIT trace telemetry. Benchmarking Without Lying to Yourself Pin inputs, isolate mechanisms, warm up deliberately, and state what the benchmark does not model. When Lua-Side Optimization Stops Being Enough What Rubic0n teaches about userdata, GC, finalizers, allocators, and the ceiling below mod code.