Dokumentace CLua

🧭 Použití CLua jako makrovací nástroj pro Original War

Tato stránka dokumentace se zaměřuje na praktické použití nástroje CLua v podobě, v jaké je distribuován – jako nástroj určený primárně pro moddery hry Original War.

Poznámka: CLua je stále ve vývoji, nicméně dosáhl svého původního cíle — nahradit starý systém Excel maker univerzálnějším a rozšiřitelnějším nástrojem. Další funkce budou přidávány spíš na vyžádání.

📁 Struktura a spuštění

Po stažení a rozbalení CLua (pro Windows nebo Linux) najdete následující strukturu složek:

CLua/
├── CLua.exe (nebo CLua pro Linux)
├── Lua55.dll (lua55.so) # Lua v5.5 knihovna, potřebná pro Lua prostředí a maker 
├── lua/
│   ├── loc/                # Lokalizace podle jazykových souborů
│   ├── OW_Macros/          # Makra pro export/import OW souborů
│   ├── utils/              # Pomocné funkce
│   ├── window/             # Lua soubory definující okna
│   ├── constants.lua       # Konstanty skriptu.
|   ├── CLua.lua            # První načítáné Lua (obsahuje většinu includů)
│   ├── OWMacros.lua        # Modul pro OW Makra (to načte všechny ostatní OWM lua)
|   └── jakýkoliv jiný.lua  # Poté načte všechny ostatní soubory lua v této složce.
├── Tables/
│   └── *.xlsx              # Excel tabulky používané makry
├── gameData/
│   └── */ *.txt, *.wri     # Vygenerované výstupy

Windows: spusť CLua.exe soubor.

Linux: spusť binárku CLua přímo z terminálu. Pokud není spuštěno z terminálu, CLua si otevře vlastní konzolová okna automaticky.

📋 Jak spustit a pracovat

  1. Spusť program – konzolová aplikace načte jazyky (automaticky podle dostupnosti v lua/loc).
    • Defaultně načte 'English', Angličtina též slouží jako fallback.
  2. Zvol makro – seznam OW maker je defaultní obrazovka.
  3. Makro pracuje s Excel soubory – ty se načítají z Tables/ pomocí ClosedXML.
    • Tabulky jsou zdrojem dat z kterých se generují soubory, uprav je dle své potřeby, ale zachovej danou strukturu.
    • Pozn: Pokud bude tabulka otevřená v jiném programu, třeba v Excelu, CLua k němu nebude mít přístup a makro selže.
  4. Výstup se uloží do gameData/ jako prosté textové soubory pro použití v OW.
    • Některá makra také importují data — nově importované tabulky najdeš v Tables/Import/.

📌 Kde najdu výstup?

Všechny výstupy maker (např. vehicles.txt, Upgrades.txt, ...) se ukládají do složky gameData/ a do podsložek v hirearchii OW.

Např: gameData/Data/GameInit/vehicles.txt.

Soubory lze poté zkopírovat do složky konkretního modu hry Original War.

Importní makra (načítání dat z herních souborů) generují výstup opačným směrem — nové Excel tabulky se ukládají do Tables/Import/.

🧪 Uživatelská rozšíření

Jakýkoliv .lua soubor umístěný přímo do kořenové složky Lua/ je automaticky načten CLua při startu (v abecedním pořadí, po načtení všech utils). Vlastní makro tedy stačí vložit jako nový .lua soubor do Lua/ — žádná registrace není potřeba.

Např: když chci změnit základní tabulku, kterou má načítat generování vozidel.

Modul OW_Macros/export_units_vehicles.lua obsahuje proměnné

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};

Lua Ow_Macros/export_units.lua importuje modul vehicles do proměnné export_Units_Vehicles.

export_Units_Vehicles = import("OW_Macros/export_Units_Vehicles");

Takže pokud chci změnit základní (tedy fallbackovou) tabulku a tabulku pro Multiplayer, napíšu do libovolného .lua souboru v kořenové složce jen.

export_Units_Vehicles.XLSXBaseName = "mojeJednotky.xlsx";
export_Units_Vehicles.XLSXNames[2] = "mojeJednotky_MP.xlsx";

Pozn: Konkrétně makra, co používají tabulky Units fungují tak, že pokud list není nalezen v tabulce pro daný GameType, použije se ten z Units.
Díky tomu Units funguje jako fallback.

🧠 Poznámky

  • Bezpečnost: CLua běží v sandboxu – Lua kód nemá přístup mimo složku programu.
  • Následující jsou zcela zakázány (nastaveny na nil): io, package, require, loadfile, dofile, loadstring, load, getmetatable, collectgarbage, setfenv, getenv, newproxy
  • Následující jsou omezeny pouze na bezpečnou podmnožinu:
    • os — dostupné pouze os.clock, os.date, os.difftime, os.time
    • debug — dostupné pouze debug.traceback (také jako globální alias debugTracker, nastaven ještě před uzamčením sandboxu)
  • Metatabulky _G, coroutine, string, table, math a utf8 jsou uzamčeny a nelze je modifikovat.
  • Systémy include() a import() umožňují strukturovaný a bezpečný Lua kód.

🌍 Lokalizace

CLua podporuje více jazyků rozhraní. Aktivní jazyk je uložen v konfiguraci a dostupný jako konstanta LANG. Při startu se vždy jako základ načte loc/English.lua. Pokud LANG není "English", načte se ještě odpovídající soubor z lua/loc/, který přepíše definované stringy.

Pro přidání nového jazyka stačí vytvořit soubor lua/loc/TvůjJazyk.lua a definovat stejné TID_* stringové konstanty jako v English.lua. Jakýkoliv TID_* nedefinovaný v tvém souboru se použije z anglické verze jako fallback.

💫 Kompatibilita s předchozím nástrojem (Makra v Excelu)

  • Tábulky Units, byly výrazně změněny. Nejsou Kompatibilní.
  • Tabulka Multiplayer byla rozdělena na Multiplayer a MP_Texts, kam byly přesunuty jazykové listy,
      nicméne, pokud makro nenajde tabulku MP_Texts, pokusí se načíst listy z Multiplayer. Zde je zpětná Kompatibilita zajištěna.
  • Dialogy kampaně: ID jsou nyní ukládána beze změny (např. DDialog). Starý nástroj ID upravoval — nový výstup proto nemusí být kompatibilní se starými soubory.
      Pozn: Hra při načítání dabingu automaticky mapuje např. DDialog → 01_Dialog.wav, takže výstup CLua je správný.
  • Zbytek podporovaných tabulek je plně kompatibilní.