galaxy-code-organization

name: galaxy-code-organization description: File structure, include order, and modular layout for Galaxy script projects. Use when splitting a monolithic script into multiple files, establishing the MapScript.galaxy bootstrap chain, organizing UI into sub-files, or setting up Enums/GlobalVariables/Header/MapInit. Covers which files are auto-generated by the editor and must never be edited (MapScript.galaxy, LibHASH.galaxy, LibHASH_h.galaxy). Do not use for language syntax questions (use galaxy-language-fundamentals).

Galaxy Code Organization & File Splitting

Galaxy scripts in a SC2 map can be split across many .galaxy files using include. This keeps code maintainable and modular. The SC2-IngameDevTools mod is the #1 primary reference for file structure and module layout.

Key References

SC2-IngameDevTools Handler-Module Layout (PRIMARY PATTERN)

The SC2-IngameDevTools project organises each feature as a self-contained handler file in Script/. There is one main coordinator, a shared utilities folder, and a _h.galaxy header for forward declarations.

Folder & file structure

Script/
├── DevToolsMain.galaxy          ← coordinator: includes all handlers, calls all _Init()
├── debug.galaxy                 ← global debug helpers: print(), console(), err()
├── debug_h.galaxy               ← forward declarations only (header pattern)
├── split_string.galaxy          ← utility (string split)
├── ItemList.galaxy              ← shared data structure (aggregator)
├── ItemListListBoxFormat.galaxy ← formatting helpers for ItemList
├── AbilityHandler.galaxy        ← feature handler (one per module)
├── AbilityOrderHandler.galaxy
├── ActorMessageHandler.galaxy
├── BehaviorHandler.galaxy
├── CameraHandler.galaxy
├── CameraShakeHandler.galaxy
├── CatalogLinkHandler.galaxy
├── CatalogValueHandler.galaxy
├── CheatHandler.galaxy
├── DataEditorHandler.galaxy
├── DataTableHandler.galaxy
├── DoodadHandler.galaxy
├── EffectHandler.galaxy
├── FogHandler.galaxy
├── LightingHandler.galaxy
├── PlayerHandler.galaxy
├── PortraitHandler.galaxy
├── RaceHandler.galaxy
├── SkinHandler.galaxy
├── SoundtrackHandler.galaxy
├── UnitHandler.galaxy
├── UpgradeHandler.galaxy
├── UserDataHandler.galaxy
├── WeaponHandler.galaxy
├── FreeCamHandler.galaxy
├── ItemList/
│   ├── index.galaxy             ← the actual ItemList implementation
│   └── Listbox.galaxy           ← listbox sub-feature
└── DevTools/
    ├── helpers.galaxy           ← shared helper functions (spawn point, movement tracker)
    ├── helpers_h.galaxy         ← forward declarations for helpers
    ├── ChatCommand.galaxy       ← chat command subsystem
    └── ChatCommand/
        └── Commands.galaxy        ← registered chat commands

Main coordinator (DevToolsMain.galaxy)

include "Script/debug"
include "Script/DevTools/helpers"
include "Script/ActorMessageHandler"
include "Script/BehaviorHandler"
include "Script/EffectHandler"
include "Script/UnitHandler"
include "Script/UpgradeHandler"
include "Script/WeaponHandler"
include "Script/AbilityHandler"
include "Script/CatalogValueHandler"
include "Script/CatalogLinkHandler"
include "Script/LightingHandler"
include "Script/DataTableHandler"
include "Script/DataEditorHandler"
include "Script/CameraHandler"
include "Script/FogHandler"
include "Script/DevTools/ChatCommand"
include "Script/DevTools/ChatCommand/Commands"

void DevToolsMain_Init() {
    DevTools_ChatCommand_Init();
    helpersInit();
    ActorMessageHandler_Init();
    CatalogValueHandler_Init();
    UnitHandler_Init();
    BehaviorHandler_Init();
    EffectHandler_Init();
    LightingHandler_Init();
    // ... every handler's _Init() called here
    DevTools_ChatCommand_Commands_Init();
}

Entry point wiring (Lib7C0075CB.galaxy — editor-generated lib file)

include "TriggerLibs/natives"
include "Lib7C0075CB_h"
include "TriggerLibs/NativeLib"
include "Script/DevToolsMain"

void TestMap_main() {
    DevToolsMain_Init();
}
void lib7C0075CB_InitCustomScript() {
    TestMap_main();
}
bool lib7C0075CB_InitLib_completed = false;
void lib7C0075CB_InitLib() {
    if (lib7C0075CB_InitLib_completed) { return; }
    lib7C0075CB_InitLib_completed = true;
    lib7C0075CB_InitCustomScript();
}

Header file pattern (debug_h.galaxy)

// ONLY forward declarations — no implementations
void print(string s);
void printT(text t);
void console(string s);
void err(string s);

Single handler module anatomy (BehaviorHandler.galaxy)

// 1. Include shared utilities
include "Script/debug_h"
include "Script/ItemList"

// 2. Path constants with UPPER_SNAKE_CASE
static const string CONTAINERDLG_PATH =
    "UIContainer/ConsoleUIContainer/CatalogManager/BehaviorManager";

// 3. Module struct + global instance
ItemListContainerStruct BehaviorContainer;

// 4. File-private state
static string ItemList;
static ListBoxFilterStruct ListBoxFilter;

// 5. Trigger event functions (bool a, bool b signature)
bool BehaviorListBoxFilterQuery(bool a, bool b) { ... }
bool BehaviorListBoxSelectionChanged(bool a, bool b) { ... }
bool BehaviorContainerSendHandler(bool a, bool b) { ... }

// 6. One public Init function
void BehaviorHandler_Init() {
    playergroup pg = PlayerGroupAll();
    ItemList = "BehaviorList";
    ItemListContainer_InitStandard(BehaviorContainer, CONTAINERDLG_PATH,
        "BehaviorContainerSendHandler");         // trigger registered by STRING name
    ItemListInitFromCatalog(ItemList, c_gameCatalogBehavior, ItemListCatalogFilter);
    ItemList_FilterListInitStandard(ListBoxFilter, "BehaviorListBox",
        BehaviorListBoxSetActive, ItemListItemTextValue,
        CONTAINERDLG_PATH+"/NavList");
    ItemList_FilterListRebuild(ItemList, ListBoxFilter, "", pg);
}

Real-World Include Orders

SSF full include order (scripts/main.galaxy) — secondary reference

include "scripts/Lib/Starcode"       // third-party lib first
include "scripts/Enums"              // pure constants
include "scripts/GlobalVariables"    // structs, global vars, typedefs
include "scripts/secrets"
include "scripts/Header"             // forward declarations
include "scripts/Utilities"          // shared helpers
include "scripts/AchievementsTemplates"
include "scripts/Achievements"
include "scripts/UI/UI-Achievements" // UI panels first (alphabetical)
include "scripts/UI/UI-CustomDefeatFrame"
include "scripts/UI/UI-HeroPanel"
include "scripts/UI/UI-Objectives"
include "scripts/UI/UI-Options"
include "scripts/UI/UI-PlayerBoard"
include "scripts/UI/UI-Popup"
include "scripts/UI/UI-Speedruns"
include "scripts/UI/UI-Stats"
include "scripts/UI/UI-Votekick"
include "scripts/UI/UI-HivePanel"
include "scripts/UI/UI-Revive"
include "scripts/UI/UI-Main"         // UI coordinator last
include "scripts/Bank"
include "scripts/Enemy"
include "scripts/PartTerran"         // content parts
include "scripts/PartProtoss"
include "scripts/PartZerg"
include "scripts/Parts"              // part coordinator last
include "scripts/Hive"
include "scripts/HeroAbilities"
include "scripts/Player"
include "scripts/Collectibles"
include "scripts/HeroSelection"
include "scripts/Tutorial"
include "scripts/Debug"
include "scripts/MapInit"            // map init always last

void main(){
    TriggerAddEventMapInit(TriggerCreate("MapInit_Main"));
}

Alcyone Frontlines include order (scripts/main.galaxy)

include "scripts/GlobalVariables"
include "scripts/MapInit"
include "scripts/Bank"
include "scripts/Player"
include "scripts/Spawner"
include "scripts/Jungle"
include "scripts/UI"
include "scripts/Buildings"
include "scripts/AI"
include "scripts/HeroSelection"
include "scripts/HeroLevelUp"

⚠️ Auto-Generated Files — NEVER Edit

The SC2 editor auto-generates certain .galaxy files. Do not write code in these files — the editor will overwrite any manual changes.

What these files contain (reference only)

MapScript.galaxy — bootstraps the engine:

include "TriggerLibs/NativeLib"
include "LibHASH"             // pulls in the mod library if present
void InitLibs() { libNtve_InitVariables(); libHASH_InitLib(); }
include "scripts/main"        // custom scripts (if standalone map)
void InitCustomScript() { main(); }
void InitMap() { InitLibs(); InitCustomScript(); }

LibHASH.galaxy — a thin editor-generated wrapper that:

• calls libNtve_InitVariables() as its library init
• includes scripts/main once
• exposes public functions as libHASH_gf_* wrappers
• registers a LoadTriggers trigger that calls ProximaInitTriggers() (or equivalent)
• defines libHASH_InitLib() / libHASH_InitTriggers()

All actual logic lives in scripts/ — that is where you write code.

Bootstrap Chain

MapScript.galaxy is the map's entry point — it is generated by the editor and should contain minimal code:

include "TriggerLibs/NativeLib"
include "TriggerLibs/LibertyLib"

void InitLibs() { libNtve_InitLib(); libLbty_InitLib(); }

include "scripts/main"          // <-- pulls in all custom scripts

void InitCustomScript() { main(); }
void InitMap() { InitLibs(); InitCustomScript(); }

scripts/main.galaxy is the coordinator — it lists every include in dependency order and defines main():

include "scripts/Lib/Starcode"
include "scripts/Enums"
include "scripts/GlobalVariables"
include "scripts/Header"
include "scripts/Utilities"
// ... all other files ...
include "scripts/MapInit"

void main() {
    TriggerAddEventMapInit(TriggerCreate("MapInit_Main"));
}

main() only registers a single map-init trigger. All actual initialization happens inside that trigger function in MapInit.galaxy.

Include Syntax & Rules

include "scripts/Utilities"          // relative to map root, no .galaxy extension
include "scripts/UI/UI-Main"         // subdirectories are supported
include "scripts/Lib/Starcode"       // third-party / library code in Lib/

Critical rules:

• Paths are relative to the map root (where MapScript.galaxy lives), not to the including file.
• Do not add .galaxy extension — the engine appends it.
• Order matters: a file can only call functions/use types declared in files included before it.
• No circular includes. Each file is included exactly once.
• There is no header guard mechanism — avoid including the same file twice.

File Roles & Naming Conventions

Enums.galaxy — Pure Constants File

All game-wide integer constants go in one file:

// parts
const int c_Part_Terran  = 0;
const int c_Part_Protoss = 1;
const int c_Part_Zerg    = 2;

// game modes
const int c_GameMode_Normal  = 0;
const int c_GameMode_Endless = 1;

// bitflags
const int c_BossFightState_Alive   = 1 << 0;
const int c_BossFightState_Enraged = 1 << 1;
const int c_BossFightState_Dead    = 1 << 2;

// boss IDs
const int c_BossFightID_Flamer  = 0;
const int c_BossFightID_Crusher = 1;

Naming convention: c_CategoryName_IdentifierName
Grouping: Use // category name comment headers to separate groups.
Bitflags: Use 1 << n pattern.

Include Enums.galaxy before GlobalVariables.galaxy so struct fields can reference these constants for array sizes.

GlobalVariables.galaxy — Structs & Global State

Declare all structs, global variables, and typedef funcref here:

// global consts
const int gv_MaxAmountPlayers = 6;
const int gv_MaxAmountParts   = 3;

// funcref blueprints
bool blueprint_BossAbility(unitgroup ug, unit boss);
typedef funcref<blueprint_BossAbility> Blueprint_BossAbility;

// structs
struct PlayerStruct {
    bool activeFlag;
    bank bankfile;
    unit heroUnit;
    int points;
    int[gv_MaxAmountParts] wins;   // array sized by const
    int heroUnlocked;              // stored as bitflag
};

// global arrays
PlayerStruct[gv_MaxAmountPlayers + 1] gv_PlayerStats;

Naming convention: gv_SystemName_VariableName for globals, gv_VariableName for simple globals.
Static locals that are cross-trigger: Declare as static at file scope in the file that owns them.

Header.galaxy — Forward Declarations

Galaxy requires functions to be declared before they are called. When file A calls a function defined in file B (included later), use a forward declaration in Header.galaxy:

// Header.galaxy — comment groups match their source file

// UI-PlayerBoard.galaxy
void PlayerBoard_UpdatePlayer(int playerID);

// Bank.galaxy
void Bank_Save_ForcedAll(int playerID);
void Bank_Save_RequestSave(int playerID);

// Parts.galaxy
void Part_PartFinished();
void Part_InitVariables();

// Player.galaxy
void Player_AddExp(int playerID, fixed amount);

Include Header.galaxy after GlobalVariables.galaxy so declarations can reference struct types.

UI Subdirectory Pattern

Each UI panel gets its own file. A coordinator file (UI-Main.galaxy) initializes all of them:

// scripts/UI/UI-Main.galaxy
void SSFCustomUI_Init() {
    gv_UI_MasterFrame = DialogControlHookupStandard(c_triggerControlTypePanel, "UIContainer/...");
    StatsInterface_Init();
    Votekick_Init();
    Options_Init();
    HeroPanel_Init();
    PlayerBoard_Init();
    // ...
}

In main.galaxy, include individual UI files before UI-Main.galaxy:

include "scripts/UI/UI-HeroPanel"
include "scripts/UI/UI-PlayerBoard"
include "scripts/UI/UI-Options"
// ... all panels first ...
include "scripts/UI/UI-Main"     // coordinator last, so it can call the others

Parts Pattern — Per-Content Modularity

When content is split by campaign mission / chapter / faction, use a coordinator + per-part files:

// In main.galaxy — include individual parts BEFORE coordinator
include "scripts/PartTerran"
include "scripts/PartProtoss"
include "scripts/PartZerg"
include "scripts/Parts"        // coordinator included last

Each Part*.galaxy owns its content and exposes a TriggerCreate() function:

// PartTerran.galaxy
void PartTerran_AreaJunker_Second_Open() { ... }
void PartTerran_TriggerCreate() {
    TriggerAddEventXxx(TriggerCreate("PartTerran_SomeHandler"), ...);
}

Parts.galaxy coordinates between parts (handles part transitions, shared state):

// Parts.galaxy
static const int observer_AmountWaypoints = 11;
static point[observer_AmountWaypoints] observer_Waypoints;

void Part_InitVariables() { ... }
void Part_PartFinished() {
    PartTerran_TriggerCreate();   // calls into part files
}

Lib Subdirectory — Third-Party Code

Put external/library code in scripts/Lib/:

include "scripts/Lib/Starcode"    // third-party utility library

This keeps library code clearly separated from your own code.

Function Naming Convention

All functions follow a SystemName_ActionName pattern:

• MapInit_ActivePlayers() — belongs to MapInit system
• Bank_Save_RequestSave(int playerID) — belongs to Bank system, Save subsystem
• PlayerBoard_UpdatePlayer(int playerID) — belongs to PlayerBoard UI
• Utility_IsNumber(string input) — belongs to Utilities
• PartTerran_AreaJunker_Second_Open() — Part + Area + Action

This makes it immediately obvious which file a function lives in.

Recommended File Include Order in main.galaxy

// 1. Third-party libraries (no dependencies)
include "scripts/Lib/Starcode"

// 2. Pure constants (no dependencies)
include "scripts/Enums"

// 3. Global state (depends on Enums for array sizes)
include "scripts/GlobalVariables"

// 4. Secret/config (if any)
include "scripts/secrets"

// 5. Forward declarations (depends on GlobalVariables for types)
include "scripts/Header"

// 6. Shared utilities (may depend on GlobalVariables)
include "scripts/Utilities"

// 7. Templates/data-only files
include "scripts/AchievementsTemplates"

// 8. Feature files alphabetical (depend on headers + globals)
include "scripts/Achievements"
include "scripts/Bank"
include "scripts/Enemy"

// 9. UI files — panels first, coordinator last
include "scripts/UI/UI-HeroPanel"
include "scripts/UI/UI-PlayerBoard"
include "scripts/UI/UI-Main"

// 10. Part files — individual parts first, coordinator last
include "scripts/PartTerran"
include "scripts/PartProtoss"
include "scripts/PartZerg"
include "scripts/Parts"

// 11. High-level systems that depend on parts
include "scripts/Hive"
include "scripts/HeroAbilities"
include "scripts/Player"
include "scripts/Collectibles"
include "scripts/HeroSelection"
include "scripts/Tutorial"

// 12. Debug and init last
include "scripts/Debug"
include "scripts/MapInit"

static Variables for Trigger Parameters

When a trigger needs to pass data to its handler function (since trigger functions take no parameters), use static file-scope variables as a parameter register:

// In Utilities.galaxy
static int Utility_DelayedTextTagDestroyer_ParamTextTag;
static trigger Utility_DelayedTextTagDestroyer_Trigger;

void Utility_DelayedTextTagCreate(text inText, color inColor, point position, playergroup pg, fixed offset) {
    Utility_DelayedTextTagDestroyer_ParamTextTag = TextTagCreate(...);
    TriggerExecute(Utility_DelayedTextTagDestroyer_Trigger, false, false);
}

bool Utility_DelayedTextTagDestroyer(bool testCond, bool runActions) {
    int textTag = Utility_DelayedTextTagDestroyer_ParamTextTag;  // capture immediately
    Wait(3.5, c_timeGame);
    TextTagDestroy(textTag);
    return true;
}

Capture the static into a local variable at the top of the handler before any Wait() calls.

Common Error: "Scri: Script load failed: Function not found"

If the SC2 editor or test map throws:

Scri: Script load failed: Function not found

and the function clearly exists in your .galaxy files, the most common cause is file encoding.

Fix: Save the offending .galaxy file as UTF-8 without BOM (not "UTF-8 with BOM").

In VS Code:

1. Open the file.
2. Click the encoding indicator in the bottom-right status bar (e.g. UTF-8 with BOM).
3. Select "Save with Encoding" -> choose "UTF-8" (no BOM).

The SC2 engine cannot parse files saved with a BOM (EF BB BF) prefix, which causes it to fail to locate any functions defined in that file, even if the code itself is correct.