Reference scope#
The catalogue describes known public X4 modding interfaces. An identified name does not establish its entire contract or prove execution in game. Mod files, internal documents and complete source files are not distributed.
Type evidence#
| Evidence | Establishes | Still requires verification |
|---|---|---|
| C declaration | Parameter order, C types and C return type | Export, ABI, context, memory ownership and lifetime |
| X4 XSD | Attribute names, expression types and required attributes | Evaluated types, event payloads and game effects |
| Lua 5.1 / LuaJIT | Standard library contracts | Availability and extensions in the current X4 environment |
| Exact event documentation | Callback arguments and field meanings | Version, registration timing and object lifetimes |
An expression schema type describes an MD expression, not its evaluated type. Filter attributes do not declare event.param types. An ignored result does not prove none, void or nil.
Reading results#
Lua can return several values. Commas separate result positions; a vertical bar separates alternatives. unknown means an unestablished contract, while any depends on context. none and void indicate no direct return, but effects and output buffers may still exist.
C types do not always match their Lua representation. A pointer is cdata; ffi.string copies a C string into a Lua string when memory lifetime is established. Do not convert IDs with a loss of precision. See types and methods, identifiers and cdata.
Events and subscriptions#
| Mechanism | Use |
|---|---|
| Lua event | RegisterEvent with an exact name and callback in the appropriate UI context |
| UI to MD | event_ui_triggered in cue conditions |
| MD engine event | Its event_* condition and exact filters |
These routes have distinct contracts. An MD event name cannot automatically be used with RegisterEvent. Register once per context; establish callback types and counts for the exact sender. The Lua / MD bridge provides an independent learning example.
Examples and verification#
Learning fragments require the stated context, variables and lifecycle. They are not claimed to have run in game without a documented experiment. Incomplete contracts retain explicit limits; do not invent buffer sizes or payload shapes.
Start with the API index. To improve a contract, provide the game version, a primary public source and a small independent example through contributions.