galaxy-debug-data-catalog

name: galaxy-debug-data-catalog description: Debug output, Data Table key-value storage, Catalog runtime field access, UserData, and asset preloading in Galaxy script. Use when reading or writing catalog fields at runtime, storing cross-trigger state in the Data Table, printing debug output, or preloading models and sounds. Do not use for bank save/load (use galaxy-game-systems).

Galaxy Scripting – Debug, Data Table & Catalog

Key References

Debug Output

// Print to the in-game debug window (F7 to open in test mode)
TriggerDebugOutput(c_triggerDebugOutputCode, StringToText("my value: " + IntToString(lv_n)), true);

// Enable/disable debug output globally
TriggerDebugOutputEnable(c_triggerDebugOutputCode, true);

// Open or close the debug window for a player
TriggerDebugWindowOpen(lv_player, true);

// Convenience debug functions (Template / unclassified)
DebugString(lv_player, "lv_unit type: " + UnitGetType(lv_unit));
DebugInt(lv_player, "lv_i", lv_i);
DebugFixed(lv_player, "lv_dist", lv_dist);
DebugUnit(lv_player, lv_unit);
DebugPoint(lv_player, lv_point);

// Debug message type constants
c_triggerDebugOutputCode      // code path output
c_triggerDebugOutputError     // error highlighting
c_triggerDebugOutputMessage   // general message

Data Table (Global Key-Value Store)

The Data Table stores arbitrary values by string name, accessible from any trigger. It survives the scope of individual functions.

⭐ SC2-IngameDevTools DataTable patterns (PRIMARY — use these)

The SC2-IngameDevTools codebase uses the DataTable extensively as a backing store for its ItemList abstraction, chat command parameters, per-player state, and catalog lookups. Key patterns:

// Namespaced keys prevent collisions — use "Module.Feature.Key" format
DataTableSetInt(true, "DataTableListPage."+IntToString(player), page);
int page = DataTableGetInt(true, "DataTableListPage."+IntToString(player));

// Store catalog type integer by catalog name string
DataTableSetInt(true, "Catalog.Unit",    c_gameCatalogUnit);
DataTableSetInt(true, "Catalog.Ability", c_gameCatalogAbil);
// Retrieve: int catalog = DataTableGetInt(true, "Catalog."+catalogName);

// Per-player listbox selection state (DataTable as a UI state cache)
string key = listId+".Selected["+IntToString(player)+"]:"+IntToString(listItem);
DataTableSetString(true, key, ItemListGetVal(itemList, index));
if (DataTableValueExists(true, key)) {
    string val = DataTableGetString(true, key);
}
DataTableValueRemove(true, key);

// Trigger event param passing via DataTable (scoped to trigger execution context)
string paramKey = TriggerEventParamName("DevTools_ChatCommand.Exec."+cmd, "_player");
DataTableSetInt(false, paramKey, player);
int p = DataTableGetInt(false, TriggerEventParamName(EventGenericName(), "_player"));

// ItemList backing store (the full ItemList implementation in ItemList/index.galaxy)
// ItemList is a string key; all data goes into the DataTable with structured keys:
// "ItemList::[listId][index]"      → the value stored at that slot
// "ItemList::[listId].Count"       → current item count
// "ItemList[listId].Active.Player1" → current selection per player

Global (map-wide) data table

// Save values — always pass true for the global (map-wide) scope
DataTableSetInt(true, "myKey", 42);
DataTableSetFixed(true, "position_x", 16.5);
DataTableSetBool(true, "isPhase2", true);
DataTableSetUnit(true, "heroUnit", lv_hero);
DataTableSetString(true, "lastEvent", "SpawnWave");
DataTableSetPoint(true, "spawnPt", lv_point);

// Load values
int    lv_n   = DataTableGetInt(true, "myKey");
fixed  lv_x   = DataTableGetFixed(true, "position_x");
bool   lv_b   = DataTableGetBool(true, "isPhase2");
unit   lv_u   = DataTableGetUnit(true, "heroUnit");
string lv_s   = DataTableGetString(true, "lastEvent");
point  lv_p   = DataTableGetPoint(true, "spawnPt");

// Check existence
bool lv_has = DataTableValueExists(c_dataTableScopeGlobal, "myKey");

// Remove
DataTableValueRemove(c_dataTableScopeGlobal, "myKey");

// Scope constants
c_dataTableScopeGlobal   // map-wide
c_dataTableScopeLocal    // trigger-local

Instance Data Tables

Instance tables let you create multiple independent tables (like a dictionary per unit):

DataTableInstanceCreate();
int lv_dt = DataTableInstanceLastCreated();

DataTableInstanceSetInt(lv_dt, "kills", 0);
DataTableInstanceSetUnit(lv_dt, "owner", lv_unit);

int  lv_k = DataTableInstanceGetInt(lv_dt, "kills");
unit lv_o = DataTableInstanceGetUnit(lv_dt, "owner");

DataTableInstanceClear(lv_dt);

Catalog (Runtime Data Field Access)

The Catalog lets you read and modify game data fields at runtime — damage, range, cost, etc. — from within triggers.

Reading catalog values

// Get the string value of a data field
string lv_val = CatalogFieldValueGet(
    c_gameCatalogUnit,           // which catalog
    "Marine",                    // entry name
    "LifeMax",                   // field name
    lv_player                    // player context
);

// Get as integer or fixed
int   lv_int  = CatalogFieldValueGetAsInt(c_gameCatalogUnit, "Marine", "LifeMax", lv_player);
fixed lv_real = libNtve_gf_CatalogFieldValueGetAsReal(c_gameCatalogWeapon, "C-14Rifle", "Range", lv_player);

// Catalog constants
c_gameCatalogUnit
c_gameCatalogWeapon
c_gameCatalogAbil
c_gameCatalogEffect
c_gameCatalogBehavior
c_gameCatalogUpgrade
c_gameCatalogModel
c_gameCatalogSound
c_gameCatalogActor

Writing catalog values

// Set a field for a player (overrides for that player)
bool lv_ok = CatalogFieldValueSet(
    c_gameCatalogWeapon, "C-14Rifle", "Range",
    lv_player, "8"               // value as string
);

// Modify relative to current value
CatalogFieldValueModify(
    c_gameCatalogUnit, "Marine", "LifeMax",
    lv_player, c_upgradeOperAdd, "25"    // add 25 HP
);

// Set as real
libNtve_gf_CatalogFieldValueSetAsReal(
    c_gameCatalogWeapon, "C-14Rifle", "Range",
    lv_player, 9.0
);

Array fields

// Field array element — for fields like Weapons[0].Range
int lv_count = CatalogFieldValueCount(c_gameCatalogUnit, "Marine", "Weapons", lv_player);
string lv_wpn = CatalogFieldValueGet(c_gameCatalogUnit, "Marine", "Weapons[0]", lv_player);

Catalog references

// Read a link reference (e.g., which weapon a unit uses)
string lv_ref = CatalogReferenceGet(c_gameCatalogUnit, "Marine", "Weapons[0]", lv_player);

// get as int
int lv_ri = CatalogReferenceGetAsInt(c_gameCatalogUnit, "Marine", "Weapons[0]", lv_player);

User Data

User data allows embedding custom typed values directly in game data entries (configured in the editor's data module).

// Load a user data value by category and field
string lv_val = UserDataGetString("MyCategory", lv_entryName, "MyField", 0, lv_player);
int    lv_i   = UserDataGetInt("MyCategory", lv_entryName, "MyField", 0, lv_player);
fixed  lv_f   = UserDataGetFixed("MyCategory", lv_entryName, "MyField", 0, lv_player);
text   lv_t   = UserDataGetText("MyCategory", lv_entryName, "MyField", 0, lv_player);
color  lv_c   = UserDataGetColor("MyCategory", lv_entryName, "MyField", 0, lv_player);

Preloading Assets

Preload before they're needed to avoid hitches:

PreloadAsset("Assets\\Textures\\MyHero.dds");
PreloadModel("Assets\\Units\\Hero\\Hero.m3");
PreloadImage("Assets\\UI\\HeroPortrait.dds");
PreloadLayout("Assets\\UI\\MyDialog.SC2Layout");

// Preload model animations — native function (NOT a libNtve helper):
ModelAnimationLoad("Assets\\Units\\Hero\\Hero.m3",  "Assets\\Units\\Hero\\Hero_Attack.m3a");
ModelAnimationLoadOverriding("Assets\\Units\\Hero\\Hero.m3", "Assets\\Override\\Hero_Walk.m3a");
ModelAnimationUnload("Assets\\Units\\Hero\\Hero.m3", "Assets\\Units\\Hero\\Hero_Attack.m3a");
// (modelPath, animPath) — animPath is the .m3a animation file

Trigger Debugger

The Trigger Debugger is the primary runtime analysis tool for Galaxy scripts.

Full documentation: Trigger Debugger guide

Launching

The game must be in Windowed mode for the debug window to appear.

Recommended initial config

Right-click the bottom subview → uncheck all "Show" options except Show Errors and Show User Output. This dramatically reduces performance overhead from the debugger.

Key tabs

Setting breakpoints in Script Code tab

1. Right-click in the Script Code tab → Add/Remove Breakpoint on the desired line.
2. When execution hits the breakpoint, the game pauses and the debugger gains focus.
3. Use the dropdown menus in the subviews to switch between Globals, Locals, Watch, Callstack, or Breakpoints views.
4. The Locals view is the most useful — it shows every local variable and event parameter in the currently paused function.

Profiling workflow (from Optimizing Code guide)

1. Run the map with the debugger open.
2. In Triggers Tab, sort by Total Time — this reveals which trigger causes the most cumulative lag.
3. In Trigger Profiling Tab, enable Show Natives and Show SubCalls — this exposes exactly which native functions inside the trigger are the hottest.
4. Optimize the inner-loop first: even a small improvement in a hot inner loop compounds multiplicatively.

Note: Unit Custom Values are not tracked in the Variables Tab. If you use custom values for debugging, build your own debug UI.

Data Table: Performance & Scope Guidelines

(Expanded from the Data Tables guide)

Search time comparison

Use arrays for small, typed, well-defined collections. Use Data Tables when the collection is large, dynamic, or mixed-type.

Scope rules

Memory leak risk: The Global data table is permanent. Entries added but never removed will accumulate. Always call DataTableValueRemove(c_dataTableScopeGlobal, "key") or DataTableClear(c_dataTableScopeGlobal) when data is no longer needed. Local tables are cleaned up automatically when their trigger finishes.