Skip to main content
Once the C# tier finishes booting, it spins up xLua and mostly gets out of the way, keeping only the transport, the login plumbing, and the world-map viewport protocol. Nearly everything a player experiences, city, army, hero, world map, chat, and all 3,115 commands in the Lua catalog, is Lua. The exceptions are the 54 commands only C# handles, see Dispatch order.

Module tree

Counts are from a walk of the 1.0.364 LWLF bundle (version 825, 18,733 modules); the rest sit in Common/, Global/, Util/, RedPoint/, and a few smaller trees. An earlier version of this table, built from the 1.0.351 manifest, undercounted UI/, Net/, and DataCenter/ because of a path-truncation artifact.

Boot sequence

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.

Relationship to the C# hot-update layer

Four independently-versioned payloads, confirmed by reading the version-check parser directly: asset bundles, the C# .mdl assemblies (through the dllres manifest), the Lua bundle, and the data tables each carry their own version field and can update independently (see Startup, version-check & hot-update). 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.

Dispatch order

Every incoming extension response goes to C# first (1.0.364 C# MessageFactory.DispatchResponse; static-analysis-only):
  • C# MessageFactory handles 71 wire names itself. Everything else becomes a Lua table and goes through GameMain.Protocal, then SFSNetwork.HandleMessage, then the handler that MsgMap[wire] names. A reply with no MsgMap handler falls through to the chat manager.
  • 18 of the 71 are also in the Lua catalog, and for those C# wins: the Lua HandleMessage never runs. Lua still builds some of the requests, among them world.march.formation.new, world.march.change, world.march.speed.up, train.send, and train.batch.send.
  • 54 commands exist only in C# (53 of the 71, plus world.get.cross) and are missing from any Lua-derived catalog. They include login.ext, check.device.change, change.user.parseid, init.error, the world-map viewport pulls (world.get.block, world.get.new, world.get.cross), push.world.march.new / .del, and push.user.off.
  • Lua-originated and C#-native requests share one _id counter, which resets on reconnect.
  • There’s no protocol-level request timeout or retry: FutureManager.update() is a no-op. Each feature handles a missing reply on its own.
  • Duplicate wire names resolve to one class for both directions: SFSNetwork.GetMsgType uses MsgMap[wire] for sending and receiving.

At-rest Lua obfuscation (“SuperEncrypt”)

Besides the non-standard header that Extraction methodology describes, BaseUtils’ EncryptUtils has an at-rest obfuscation for individual Lua chunks (static-analysis-only):
  • An encrypted chunk starts with 0B 45 4E 43, and the rest of the 32-byte Lua 5.3 header is replaced by S bytes.
  • The source-name string is XORed with a 32-byte key derived through ChaCha.
  • The body is XORed with a ChaCha8 keystream, and the _ENV tail is masked.
The keys come from the same dummy-constant derivation as the file wrappers on Startup, version-check & hot-update.

Hot-patching C# from Lua

Lua can rewrite the C# layer, not only itself (static-analysis-only):
  • CommonUtils.Lua_File_Write gives Lua arbitrary file IO inside the app sandbox, including persistentDataPath/Assemblies/*.mdl, which FM_Mono loads on the next start. A Lua hot update could therefore ship a replacement C# assembly. No use of this path was found in 1.0.364.
  • xLua’s [Hotfix] IL injection isn’t active in 1.0.364. The attribute appears on some C# message classes, but HotfixDelegateBridge is never called, so those classes can’t be patched that way.
  • DevPatchRuntime is unused developer tooling.