> ## Documentation Index
> Fetch the complete documentation index at: https://lastwar.tech/llms.txt
> Use this file to discover all available pages before exploring further.

# Lua scripting architecture

> How the C# hot-update tier hands off to xLua, the module tree, boot sequence, require() resolution, and the BaseClass OOP convention used across the codebase.

The C# tier's only job, once it finishes booting, is to spin up xLua and get out of the way. Nearly everything a player experiences, city, army, hero, world map, chat, every one of the 3,178 commands, is Lua.

## Module tree

| Directory     | Files | Purpose                                                                         |
| ------------- | ----: | ------------------------------------------------------------------------------- |
| `UI/`         | 9,802 | Per-screen UI logic, the largest tree by far                                    |
| `Net/`        | 2,790 | Networking: dispatch core + all 2,777 command classes                           |
| `DataCenter/` | 2,226 | Client-side state managers, the "model" layer, \~825 lazy-singleton managers    |
| `Scene/`      |   880 | In-world/3D scene & rendering glue                                              |
| `Chat/`       |   169 | The dedicated chat subsystem (see [Alliance, chat & mail](/alliance-chat-mail)) |
| `Framework/`  |   112 | The actual engine: base classes, event system, logger, loaded first             |

\* `UI/`, `Net/`, and `DataCenter/` counts are undercounts (a manifest path-truncation artifact affects a subset of entries in these three trees); true counts are somewhat higher. See [Extraction methodology](/methodology) for the extraction methodology.

## Boot sequence

```text theme={null}
XLuaManager.Initialize()
  → new LuaEnv(); AddLoader(CustomLoader)     // the one game-specific require() hook
  → require("Common.Main")                     // table/string/bit/Unity-math utils
  → require("Framework.FrameworkMain")          // BaseClass OOP, DataCenter service locator, event system
GameEntry.Lua.StartGame()
  → require("GameMain"); GameMain.Start()
      LuaEntry:init()                           // player/session state root
      PBController.InitPBConfig()               // no-op in this build (misleadingly named, real proto loading is PBController.InitBytes/LoadBytes)
      ~90 × DataCenter.<Manager>:Startup()      // one per gameplay system
```

## `require()` resolution: how a module path finds its bytes

A single custom loader, layered under stock xLua's searcher chain, resolves `"DataCenter.Global.LuaEntry"` in order: a dev-only local override → a table-config ZIP lookup (if the path contains `LuaDatatable`) → raw disk read in the Unity Editor → **the `LWLF` bundle** (production path, confirms and refines [Extraction methodology](/methodology)'s reverse-engineered format exactly) → a TextAsset fallback.

## The `BaseClass(...)` OOP pattern

Every Lua file in the codebase uses one convention: prototype-chain classes over plain tables, via `OptClass.Declare` (a from-scratch, self-optimizing class system, not stock Lua OOP). Constructors chain automatically root-to-leaf; a computed-property ("getter") mechanism only attaches its extra metatable indirection to classes that actually define getters.

```lua theme={null}
local MailGetMessage = BaseClass("MailGetMessage", SFSBaseMessage)
local base = SFSBaseMessage
local OnCreate = function(self, mailId, mailType, senderUid)
  base.OnCreate(self)                              -- explicit super-call convention
  self.sfsObj:PutUtfString("uid", mailId)
  ...
end
MailGetMessage.OnCreate = OnCreate
return MailGetMessage
```

## Relationship to the C# hot-update layer

Three independently-versioned payloads, confirmed by reading the version-check parser directly: asset bundles (covers the C# `.mdl` assemblies), the Lua bundle, and the data tables each carry their own version field and can update independently. They are *not* fully independent, though; the Lua bootstrap itself (`XLuaManager`, the custom loader) lives inside the hot-update C# tier, so a broken C# release could in principle break the Lua loader before any Lua code runs.