---
title: Lua in X4 UI
summary: File registration, initialization order, callback lifecycle and responsive UI behavior.
section: ui
kind: guide
status: reference
tags: ["X4","modding","lua","ui"]
sources: ["https://wiki.egosoft.com/X4%20Foundations%20Wiki/Modding%20Support/"]
---
## 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.




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

## A custom window


Use the [Helper window guide](wiki:create-ui) for text and buttons, or a [settings API](wiki:ui-settings) for ordinary options. A new interface can stand alone; an extension of an existing action should start from the [standard menu callback](wiki:extend-ui).



## 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.




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

## Further reading


[Lua ↔ MD](wiki:md-lua-bridge), [custom windows](wiki:create-ui) and [standard UI extensions](wiki:extend-ui).