================================================================================
                        DEBUG OVERLAY - QUICK REFERENCE
================================================================================

HOW IT WORKS:
- Click the "Debug" button in Custom Scripts tab
- It opens a fullscreen green panel and runs your script
- Type HideDebugHUD() to close it

IMPORTANT: Always run DC() first before other debug commands!
Without clearing first, output may not display correctly.

EXAMPLE:
    DC()
    DPI()

================================================================================
                              BASIC FUNCTIONS
================================================================================

Debug_Print(msg)          -- Print a message to overlay
Debug_Clear()             -- Clear the overlay
ShowDebugHUD()            -- Open the overlay
HideDebugHUD()            -- Close the overlay

EXAMPLE:
    Debug_Clear()
    Debug_Print("Hello!")
    Debug_Print("Testing something...")

================================================================================
                           SEARCH FUNCTIONS
================================================================================

Debug_Search(pattern)     -- Search _G for pattern (CLEARS screen first)
Debug_SearchAdd(pattern)  -- Search and APPEND (doesn't clear)

EXAMPLE - Single search:
    Debug_Search("minimap")

EXAMPLE - Multiple searches at once:
    Debug_Clear()
    Debug_SearchAdd("fow")
    Debug_SearchAdd("minimap")
    Debug_SearchAdd("player")

OUTPUT shows:
    [F] = function
    [T] = table
    [S] = string
    [N] = number

================================================================================
                        FUNCTION EXISTS CHECKS
================================================================================

Debug_FuncExists(name)              -- Check if one function exists
Debug_FuncExistsMulti(names)        -- Check multiple functions

EXAMPLE - Single:
    Debug_FuncExists("BP_GetUpgradeBlueprint")
    Debug_FuncExists("Player_GetSquads")
    Debug_FuncExists("FakeFunctionName")

EXAMPLE - Multiple:
    Debug_FuncExistsMulti({
        "GE_EntitySpawn",
        "Player_GetSquads",
        "FOW_RevealAll",
        "SBP",
        "FakeFunctionThatDoesntExist"
    })

================================================================================
                          BLUEPRINT TESTING
================================================================================

Debug_BPCheck(name, bpFunc)         -- Quick check if BP exists
Debug_BPList(list, bpFunc)          -- Check a list of BP names
Debug_BPName(name, bpFunc)          -- Check BP + BP_GetName works
Debug_TestBP(name, bpFunc)          -- DETAILED test with error info

NOTE: bpFunc defaults to BP_GetUpgradeBlueprint if not provided

EXAMPLE - Quick check:
    Debug_BPCheck("UPGRADE_DOUBLE_BIT_AXE")

EXAMPLE - Check a list:
    Debug_BPList({
        "UPGRADE_DOUBLE_BIT_AXE",
        "UPGRADE_CROSSCUT_SAW",
        "UPGRADE_LUMBER_PRESERVATION",
        "FAKE_UPGRADE_NAME"
    })

EXAMPLE - With different BP function:
    Debug_BPCheck("some_entity_name", BP_GetEntityBlueprint)
    Debug_BPCheck("some_squad_name", BP_GetSquadBlueprint)

EXAMPLE - Detailed test (shows exactly what failed):
    Debug_TestBP("UPGRADE_DOUBLE_BIT_AXE")

OUTPUT:
    [1] BP function exists: OK
    [2] Got BP handle: userdata [userdata]
    [3] BP_GetName: upgrade_double_bit_axe
    === ALL TESTS PASSED ===

Or if it fails:
    [1] BP function exists: OK
    [2] BP returned nil - name not found

================================================================================
                           SBP PATH TESTING
================================================================================

Debug_SBPPath(pathString)           -- Check if SBP.X.Y.Z path exists

EXAMPLE:
    Debug_SBPPath("SBP.CRUSADER_CMP.UNIT_SCOUT_MANSURAH_CRU")
    Debug_SBPPath("SBP.ENGLISH.UNIT_VILLAGER_ENG")

================================================================================
                            SQUAD TESTING
================================================================================

Debug_SquadType(typeName)           -- Check if first squad is of type
Debug_AllSquads()                   -- List all your squads

EXAMPLE:
    Debug_SquadType("scar_knight")
    Debug_SquadType("villager")

EXAMPLE - See all your squads:
    Debug_AllSquads()

================================================================================
                         TABLE INSPECTION
================================================================================

Debug_TableFuncs(tableName)         -- List all functions in a table
Debug_Exists(name)                  -- Check if name exists in _G
Debug_ExistsMultiple(names)         -- Check multiple names

EXAMPLE:
    Debug_TableFuncs("Player")
    Debug_TableFuncs("UI")
    Debug_TableFuncs("Squad")

================================================================================
                      ERROR TESTING (DETAILED)
================================================================================

Debug_TryCall(func, arg1, arg2...)  -- Call function, show error if fails
Debug_Test(label, function)         -- Test expression with error catching
Debug_TestMulti(tests)              -- Test multiple expressions

EXAMPLE - Try a function call:
    Debug_TryCall(BP_GetUpgradeBlueprint, "UPGRADE_DOUBLE_BIT_AXE")
    Debug_TryCall(Player_GetResource, Game_GetLocalPlayer(), RT_Food)

EXAMPLE - Test custom expression:
    Debug_Test("Get local player", function()
        return Game_GetLocalPlayer()
    end)

    Debug_Test("Get food amount", function()
        return Player_GetResource(Game_GetLocalPlayer(), RT_Food)
    end)

EXAMPLE - Test multiple things:
    Debug_TestMulti({
        {"LocalPlayer", function() return Game_GetLocalPlayer() end},
        {"Food", function() return Player_GetResource(Game_GetLocalPlayer(), RT_Food) end},
        {"Wood", function() return Player_GetResource(Game_GetLocalPlayer(), RT_Wood) end},
        {"SquadCount", function() return SGroup_Count(Player_GetSquads(Game_GetLocalPlayer())) end}
    })

================================================================================
                        SBP & TYPE DISCOVERY
================================================================================

Debug_ListCivs()                -- List all civilizations in SBP table
Debug_SBPCiv("CHINESE")         -- List all blueprints for a civilization
Debug_SBPSearch("CHINESE", "siege")  -- Search civ's blueprints for pattern
Debug_SearchTable("SBP", "pattern")  -- Search any table for pattern
Debug_ScarType("myVar", myVar)       -- Check scartype of a variable
Debug_ListScarTypes()                -- List all ST_* constants
Debug_ListPlayers()                  -- List all players in game (YOU/AI/HUMAN)
Debug_FOWReveal()                    -- Reveal fog of war
Debug_FOWHide()                      -- Hide fog of war
Debug_CameraPos()                    -- Show current camera position
Debug_PlayerInfo()                   -- Show player race and age
Debug_Resources()                    -- Show player resources (food/wood/gold/stone)
Debug_GameInfo()                     -- Show game difficulty, replay status, etc.
Debug_EventRunning()                 -- Check if event/cinematic is playing
Debug_HasUpgrade("UPGRADE_NAME")     -- Check if player has an upgrade
Debug_GroupCount("sg_myGroup")       -- Count units in SGroup or EGroup
Debug_CmdLine("cheat")               -- Check if command line arg is set

EXAMPLE - Find all Chinese siege units:
    Debug_SBPSearch("CHINESE", "siege")

EXAMPLE - Check what type a variable is:
    local sg = Player_GetSquads(Game_GetLocalPlayer())
    Debug_ScarType("sg", sg)         -- Shows: sg = ST_SGROUP

EXAMPLE - List all civs then explore one:
    Debug_ListCivs()
    Debug_SBPCiv("ENGLISH")

================================================================================
                           SHORT ALIASES
================================================================================

Instead of typing full names, use these shortcuts:

    DC()              = Debug_Clear()
    DP("msg")         = Debug_Print("msg")
    DS("pattern")     = Debug_Search("pattern")
    DSA("pattern")    = Debug_SearchAdd("pattern")
    DE("name")        = Debug_Exists("name")
    DFE("name")       = Debug_FuncExists("name")
    DBP("name")       = Debug_BPCheck("name")
    DSQ("type")       = Debug_SquadType("type")
    DTC(func, args)   = Debug_TryCall(func, args)
    DTB("name")       = Debug_TestBP("name")
    DT("label", fn)   = Debug_Test("label", fn)
    DLC()             = Debug_ListCivs()
    DSBP("civ")       = Debug_SBPCiv("civ")
    DSBPS("civ","pat") = Debug_SBPSearch("civ", "pattern")
    DST("tbl","pat")  = Debug_SearchTable("table", "pattern")
    DSCT("name",var)  = Debug_ScarType("name", var)
    DLST()            = Debug_ListScarTypes()
    DLP()             = Debug_ListPlayers()
    DFOW()            = Debug_FOWReveal()
    DFOWH()           = Debug_FOWHide()
    DCAM()            = Debug_CameraPos()
    DPI()             = Debug_PlayerInfo()
    DRES()            = Debug_Resources()
    DGI()             = Debug_GameInfo()
    DER()             = Debug_EventRunning()
    DHU("name")       = Debug_HasUpgrade("UPGRADE_NAME")
    DGC("group")      = Debug_GroupCount("sg_myGroup")
    DCL("arg")        = Debug_CmdLine("cheat")

EXAMPLE using shortcuts (always start with DC!):
    DC()
    DPI()
    DRES()
    DLP()
    DLC()
    DSBP("CHINESE")

================================================================================
                         COMMON WORKFLOWS
================================================================================

WORKFLOW 1: Find all functions related to something
    Debug_Search("minimap")
    -- or multiple:
    DC()
    DSA("minimap")
    DSA("fog")
    DSA("fow")

WORKFLOW 2: Check if specific functions exist before using them
    Debug_FuncExistsMulti({
        "FOW_RevealAll",
        "Minimap_Enable",
        "Player_GetResource"
    })

WORKFLOW 3: Test a blueprint before using it
    Debug_TestBP("UPGRADE_DOUBLE_BIT_AXE")

WORKFLOW 4: Find all functions in a table/namespace
    Debug_TableFuncs("Player")
    Debug_TableFuncs("Squad")
    Debug_TableFuncs("FOW")

WORKFLOW 5: Debug why something isn't working
    Debug_TestMulti({
        {"Step 1: Get player", function() return Game_GetLocalPlayer() end},
        {"Step 2: Get squads", function() return Player_GetSquads(Game_GetLocalPlayer()) end},
        {"Step 3: Count", function() return SGroup_Count(Player_GetSquads(Game_GetLocalPlayer())) end}
    })

WORKFLOW 6: Custom debugging with prints
    Debug_Clear()
    local p = Game_GetLocalPlayer()
    Debug_Print("Player: " .. tostring(p))

    local sg = Player_GetSquads(p)
    Debug_Print("Squads: " .. tostring(sg))

    local count = SGroup_Count(sg)
    Debug_Print("Count: " .. tostring(count))

WORKFLOW 7: Explore SBP blueprints by civilization
    DC()                            -- Always clear first!
    DLC()                           -- See all civs
    DSBP("CHINESE")                 -- List all Chinese blueprints
    DSBPS("CHINESE", "siege")       -- Filter Chinese siege units
    DSBPS("ENGLISH", "longbow")     -- Find English longbow entries

WORKFLOW 8: Discover what types a unit responds to
    DC()                            -- Always clear first!
    DSQ("scar_siege")
    DSQ("scar_bombard")
    DSQ("scar_ranged")


================================================================================
                              TIPS
================================================================================

1. IMPORTANT: Always run DC() FIRST before any other debug command!
   Without clearing first, output may not display correctly.

2. Use Debug_SearchAdd() (DSA) for multiple searches, not Debug_Search()

3. When something crashes, use Debug_TestBP() or Debug_TryCall()
   to see the actual error message

4. Debug_AllSquads() is great for seeing what units you have

5. Debug_TableFuncs("TableName") helps discover available functions

6. All functions use pcall internally so they won't crash your game

7. Use DLC() and DSBP() to explore blueprints by civilization

8. Use DTT() to test if a scar_type matches your current units

9. DSBPS() is great for filtering specific unit types (siege, cavalry, etc.)


================================================================================
