Cocos2d-x 3.5 TiledMap 加載斷言失敗：地圖數據異常與 GID 為 0 導致 getTileAt 返回 nullptr 排查

錯誤現象

調用 `itemLayer->getTileAt(point)` 時觸發斷言失敗，但同樣代碼加載另一張地圖正常。

核心原因：地圖編輯器導出數據異常，存在 GID 非 0 但無對應 Tile 的「幽靈格子」

• `getTileGIDAt(point)` 返回非 0 → 認為有 Tile
• 實際圖層數據中該位置**無圖塊引用** → `getTileAt` 返回 `nullptr`
• 斷言宏 `CCASSERT(node != nullptr, ...)` 觸發崩潰

排查驗證步驟

1. 在 Tiled Map Editor 中打開報錯地圖 → 檢查該圖層是否有**隱藏圖層、鎖定圖層、未正確保存**
2. 導出為 JSON (`map.tmj`)，搜索該坐標 `(x,y)` 的 `gid` 值是否與圖塊集 `firstgid` 對應 3. 對比正常地圖，查看 `data` 數組中是否有「孤立 gid」

代碼層面防禦性修復（推薦）

int gid = itemLayer->getTileGIDAt(tileCoord);
if (gid != 0) {
    // 關鍵：先判斷 gid 是否在當前 tileset 範圍內
    auto tileset = itemLayer->getTileSet();
    if (tileset && gid >= tileset->_firstGid && gid < tileset->_firstGid + tileset->_tileCount) {
        Sprite* tile = itemLayer->getTileAt(tileCoord);
        if (tile) {  // 雙重保險
            tile->setAnchorPoint(Vec2::ANCHOR_MIDDLE);
            // 後續邏輯...
        } else {
            CCLOGWARN("Tile at (%d,%d) has GID %d but getTileAt returns nullptr", 
                      tileCoord.x, tileCoord.y, gid);
        }
    } else {
        CCLOGWARN("Invalid GID %d at (%d,%d) - not in tileset range", 
                  gid, tileCoord.x, tileCoord.y);
    }
}

根治方案：重新製作/導出地圖

1. 在 Tiled Map Editor 中**另存為**新文件（清理潛在損壞元數據）
2. 確保所有圖層**可見、未鎖定**、圖塊集**正確關聯** 3. 導出前執行 **「驗證地圖」**（Map → Validate）檢查錯誤 4. 重新導出 `.tmx` + 圖片資源，替換項目中文件

經驗總結

• Cocos2d-x `getTileAt` **不保證**非 0 GID 必有 Sprite，需雙重判空
• 地圖編輯器（Tiled）操作不當（如刪除圖塊集未清理引用）是高發原因
• 建立地圖驗證流程：CI 中加載所有地圖跑一遍 `getTileGIDAt` 掃描異常 GID

總結

斷言失敗源於 **地圖數據存在無效 GID**，而非代碼邏輯錯誤。短期在代碼加雙重判空防崩潰，長期**重新製作地圖並建立驗證機制**徹底根治。同樣代碼加載另一張圖正常，證明邏輯無誤，問題在具體 `.tmx` 文件。