Cocos2d-x 中 debugDraw 使用完整教學

編輯：關於C語言

功能簡介

debugDraw 是 Box2D 物理引擎內建的除錯繪圖功能，可將剛體形狀、關節、AABB 包圍盒、質心等幾何資訊以線框形式繪製在螢幕上，極大地協助物理模擬的開發與調試。Cocos2d-x 整合了 GLESDebugDraw 類別，僅需少量設定即可啟用。

接入步驟

1. 複製核心檔案

從 Cocos2d-x 原始碼目錄 external/Box2D/DebugDraw/ 複製下列兩個檔案到專案 Classes 目錄：

GLES-Render.h
GLES-Render.cpp

2. 建立世界時啟用 DebugDraw

// 於場景初始化或 PhysicsWorld 建立處
#include "GLES-Render.h"

// PTM_RATIO 為像素/米換算比例，通常為 32.0f
GLESDebugDraw *debugDraw = new GLESDebugDraw(PTM_RATIO);
world->SetDebugDraw(debugDraw);

// 設定要繪製的旗標（可組合）
uint32 flags = 0;
flags |= b2Draw::e_shapeBit;        // 形狀輪廓
flags |= b2Draw::e_jointBit;        // 關節連線
flags |= b2Draw::e_aabbBit;         // AABB 包圍盒
flags |= b2Draw::e_pairBit;         // 廣階配對
flags |= b2Draw::e_centerOfMassBit; // 質心標記
debugDraw->SetFlags(flags);

3. 覆寫 Layer 的 draw() 方法

void PhysicsLayer::draw(Renderer *renderer, const Mat4 &transform, uint32_t flags) {
    Layer::draw(renderer, transform, flags);

    // 1. 開啟頂點屬性
    GL::enableVertexAttribs(GL::VERTEX_ATTRIB_FLAG_POSITION);

    // 2. 保存模型視圖矩陣
    kmGLPushMatrix();

    // 3. 套用場景變換（與節點座標系對齊）
    kmGLMultMatrix(&transform);

    // 4. 讓 Box2D 繪製除錯幾何
    world->DrawDebugData();

    // 5. 還原矩陣
    kmGLPopMatrix();

    // 6. 檢查 GL 錯誤（Debug 模式下建議保留）
    CHECK_GL_ERROR_DEBUG();
}

4. 背景顏色建議

除錯線框通常為白色或亮色，**務必將場景背景設為深色（黑色/深灰）**，否則線框極難看清。可在 Scene::init() 中設定：

auto layer = LayerColor::create(Color4B(30, 30, 30, 255)); // 深灰背景
this->addChild(layer);

常見問題與解決

現象	原因	解決
完全看不到線框	背景顏色過淺 / 矩陣未正確套用	設深色背景；確認 `kmGLMultMatrix(&transform)`
線框位置偏移	PTM_RATIO 不一致 / 節點縮放未考慮	確保 `PTM_RATIO` 與物理世界建立時一致；`draw()` 中正確套用 `transform`
效能嚴重下降	大量物體啟用 debugDraw	僅在開發建構啟用；發布版用 `#if COCOS2D_DEBUG` 條件編譯排除
編譯錯誤：找不到 GLES-Render	檔案未加入專案 / 路徑錯誤	確認 `Classes/GLES-Render.*` 存在且在 `Android.mk`/`CMakeLists.txt` 列入

進階技巧

自訂顏色： 繼承 GLESDebugDraw 覆寫 DrawPolygon、DrawSolidPolygon 等方法，依物體類型（玩家/敵人/道具）給予不同顏色。
條件編譯： 在 PhysicsLayer.h 用 #if COCOS2D_DEBUG > 0 包裹 debugDraw 相關成員與 draw() 覆寫，發布包自動移除。
搭配 ImGui： 在 draw() 後呼叫 ImGui_ImplCocos2dx_RenderDrawData，即可在同一幀疊加 UI 除錯面板。