Lua scripting architecture

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)
`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 for the extraction methodology.

Boot sequence

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

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.

Front Matter

Bootstrap & Transport

Protocol Surface

Gameplay Domains

Client Internals

Building the Client

Lua scripting architecture

Module tree

Boot sequence

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

The `BaseClass(...)` OOP pattern

Relationship to the C# hot-update layer

​Module tree

​Boot sequence

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

​The BaseClass(...) OOP pattern

​Relationship to the C# hot-update layer

Module tree

Boot sequence

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

The `BaseClass(...)` OOP pattern

Relationship to the C# hot-update layer