CLua Documentation

🧭 Using CLua as a Macro Tool for Original War

This page focuses on the practical use of CLua as distributed — a tool primarily intended for modders of the game Original War.

Note: While CLua is still in active development, it has reached its original goal — replacing the old Excel macro system with a more universal and extensible tool. Further features will be added mainly upon request.

📁 Structure & Launch

After downloading and unpacking CLua (for Windows or Linux), you’ll find the following folder structure:

CLua/
├── CLua.exe (or CLua for Linux)
├── Lua55.dll (lua55.so)      # Lua v5.5 library required for scripting
├── lua/
│   ├── loc/                  # Localizations by language files
│   ├── OW_Macros/            # Macros for OW file import/export
│   ├── utils/                # Helper functions
│   ├── window/               # Lua files defining windows
│   ├── constants.lua         # Script constants
│   ├── CLua.lua              # Main entry point (loads core logic)
│   ├── OWMacros.lua          # OW Macros module (loads all other OWM Lua files)
│   └── any other .lua        # Automatically loaded on startup
├── Tables/
│   └── *.xlsx                # Excel sheets used by macros
├── gameData/
│   └── */ *.txt, *.wri       # Generated outputs

Windows: run the CLua.exe file.

Linux: run the CLua binary directly from a terminal. If not launched from a terminal, CLua will open its own console windows automatically.

📋 How to Run & Work with It

  1. Start the program — the console app will load languages automatically from lua/loc. Defaults to English, which is also used as a fallback.

  2. Choose a macro — the list of Original War macros is the default screen.

  3. Macros use Excel files — loaded from the Tables/ folder using ClosedXML.

    • These spreadsheets are the source of all macro data. You can edit them freely, but keep the expected structure.
    • Note: If a table is open in another program (e.g. Excel), CLua won’t be able to access it and the macro will fail.

  4. Output is saved in the gameData/ folder as plain text files ready for use in Original War.

    • Some macros also import data — newly imported tables are placed in Tables/Import/.

📌 Where Are the Outputs?

All generated macro outputs (e.g. vehicles.txt, Upgrades.txt, etc.) are saved in gameData/ and follow the typical Original War folder hierarchy.

Example: gameData/Data/GameInit/vehicles.txt

You can then copy these files into your specific mod’s folder for Original War.

Import macros (reading data from game files) work in the opposite direction — newly generated Excel tables are saved to Tables/Import/.

🧪 User Extensions

Any .lua file placed directly in the lua/ root directory is automatically loaded by CLua on startup (in alphabetical order, after all utils have been loaded). This means you can create your own macros simply by placing a Lua file there — no registration required.

Example: You want to change the default spreadsheet used for generating vehicle data.

The module OW_Macros/export_units_vehicles.lua defines:

XLSXBaseName = "Units.xlsx";
XLSXWithNames = "Name.xlsx";
XLSXNames = {"Units_SP.xlsx", "Units_MP.xlsx", "Units_SKIR.xlsx"};
FolderNames = {"GameInit/","Multiplayer/GameInit/","Skirmish/GameInit/"};
gameTypes = {TID_SIGNLE, TID_MULTI, TID_SKIRMISH};

And OW_Macros/export_units.lua imports that module as:

export_Units_Vehicles = import("OW_Macros/export_Units_Vehicles");

So if you want to override the default (fallback) table and the one for Multiplayer, just write this in any .lua file in the root lua/ directory:

export_Units_Vehicles.XLSXBaseName = "myUnits.xlsx";
export_Units_Vehicles.XLSXNames[2] = "myUnits_MP.xlsx";

📌 Note: Macros using Units sheets behave so that if a specific sheet for a game mode is missing, it falls back to the one in Units.xlsx. This makes Units.xlsx act as a universal fallback.

🧠 Notes

  • Security: CLua runs in a sandbox — Lua code cannot access anything outside the program folder.
  • The following are fully disabled (set to nil): io, package, require, loadfile, dofile, loadstring, load, getmetatable, collectgarbage, setfenv, getenv, newproxy
  • The following are restricted to a safe subset only:
    • os — only os.clock, os.date, os.difftime, os.time are available
    • debug — only debug.traceback is available (also exposed as the global debugTracker, set before the sandbox locks down)
  • The metatables of _G, coroutine, string, table, math, and utf8 are locked and cannot be modified.
  • The include() and import() systems enable structured and safe scripting in Lua.

🌍 Localization

CLua supports multiple UI languages. The active language is set in the configuration and stored as the LANG constant. On startup, loc/English.lua is always loaded first as the base. If LANG differs from "English", the corresponding file from lua/loc/ is loaded on top, overriding the strings it defines.

To add a new language, create a file lua/loc/YourLanguage.lua and define the same TID_* string constants as in English.lua. Any TID_* not defined in your file will fall back to the English version.

💫 Compatibility with Previous Excel Macro Tool

  • The Units sheets have changed significantly and are not compatible with the old tool.
  • The Multiplayer sheet has been split into Multiplayer and MP_Texts (language lists).   If MP_Texts doesn’t exist, the macro will try to load lists from Multiplayer, ensuring backward compatibility.
  • Campaign dialogues: IDs are now stored unchanged (e.g. DDialog). The old tool modified IDs — output from CLua may therefore be incompatible with old files.
      Note: The game automatically maps e.g. DDialog → 01_Dialog.wav when loading dubbing, so the CLua output is correct.
  • All other supported sheets are fully compatible.