Lua in X4 UI

Register the files#

Declare UI files in ui.xml, placing shared definitions before modules that use them. Declare third-party dependencies and verify their versions. The world and menus may not be ready when the file is loaded; registering callbacks and reading an existing ship are different stages.

<addon name="wiki_example">
  <environment type="menus">
    <file name="ui/wiki_example.lua" />
  </environment>
</addon>

A custom window#

Use the Helper window guide for text and buttons, or a settings API for ordinary options. A new interface can stand alone; an extension of an existing action should start from the standard menu callback.

Do not block rendering#

Handlers should return quickly. Waiting in a loop freezes UI. Use an event and separate result for world changes rather than repeating the operation on every table refresh.

Lifecycle#

Install handlers once per context. Resolve references again after loading or menu reconstruction, and avoid accumulating wrappers. The example rejects callbacks from an obsolete adapter instance. That check does not unregister the handler; free frames and transient state separately.

WikiPanel = {}
local instance = WikiPanel
RegisterEvent("Wiki.Example", function(_, payload)
    if WikiPanel ~= instance then return end
    -- Обработка относится к актуальному экземпляру.
end)

Further reading#

Lua ↔ MD, custom windows and standard UI extensions.