ActionsApi.setUnitDebugText(unitId, text)方法說明與使用範例

| Chrono Divide | 1 Reads

Copyright Notice: This article is an original work licensed under the CC 4.0 BY-NC-ND license. If you wish to repost this article, please include the original source link and this copyright notice.
Source link: https://v2know.com/article/1199

ActionsApi.setUnitDebugText 會在遊戲中為指定單位顯示一段除錯文字，通常用於輔助重播或即時除錯。該方法定義於 @chronodivide/game-api 套件中，其函式簽名如下（見 dist/index.d.ts）：

setUnitDebugText(unitId: number, text: string | undefined): void;

說明文件 README.md 提到，此功能需依賴客戶端命令 r.debug_text = 1，並且必須在 bot 啟用了 debug mode 的情況下才能顯示：

We also take advantage of the in‑game bot debug functionality …
r.debug_text = true;
This will debug the bot which has been configured with `setDebugMode(true)`.

更詳細的介紹可於 @chronodivide/game-api 的 README 文件中找到。文檔說明了兩種除錯文字：單位標籤（unit labels）與全域文字（global text），並指出呼叫這些 API 會產生額外的網路流量或回放檔案體積，因此僅在除錯模式下啟用：

Unit debug labels and global debug text

  • 顯示附加於單位或建築上的多行除錯字串。要使用此功能，bot 實作應呼叫 actionsApi.setUnitDebugText。該文字一旦設定將持續顯示，直到被新值覆蓋。

...

IMPORTANT: 兩個方法 actionsApi.setUnitDebugText 和 actionsApi.setGlobalDebugText 都會產生玩家操作（player action）… 因此僅在 bot 除錯模式下啟用，並需有 bot 權限帳號。

在程式碼中的使用方式
setUnitDebugText 常用於標註單位所屬任務或顯示自定義單位 ID。例如在 missionController.ts 中，當將單位加入或移出任務時會更新標籤：

private addUnitToMission(mission: Mission<any>, unit: GameObjectData, actionsApi: ActionsApi) {
    mission.addUnit(unit.id);
    this.unitIdToMission.set(unit.id, mission);
    actionsApi.setUnitDebugText(unit.id, mission.getUniqueName() + "_" + unit.id);
}

private removeUnitFromMission(mission: Mission<any>, unitId: number, actionsApi: ActionsApi) {
    mission.removeUnit(unitId);
    this.unitIdToMission.delete(unitId);
    actionsApi.setUnitDebugText(unitId, undefined);
}

更新所有任務單位的標籤則由 updateDebugText 完成：

public updateDebugText(actionsApi: ActionsApi) {
    this.missions.forEach((mission) => {
        mission
            .getUnitIds()
            .forEach((unitId) => actionsApi.setUnitDebugText(unitId, `${unitId}: ${mission.getUniqueName()}`));
    });
}

在 bot.ts 的除錯模式中，也會為敵方單位標註 ID：

game.getVisibleUnits(this.name, "enemy").forEach((unitId) => {
    this.actionsApi.setUnitDebugText(unitId, unitId.toString());
});

典型使用範例

✅ 確保啟用 debug mode
建立 SupalosaBot 時呼叫 .setDebugMode(true)，並在客戶端主控台輸入：

r.debug_bot = 1;
r.debug_text = true;

這樣才能在重播或實際對戰中看到標籤。

✅ 設定／更新單位標籤

// 將某單位標記為“偵察任務_42”
actionsApi.setUnitDebugText(42, "scoutMission_42");

// 若需清除，傳入 undefined
actionsApi.setUnitDebugText(42, undefined);

✅ 批量管理
在任務控制器中遍歷單位列表，對每個單位呼叫 setUnitDebugText，即可於介面上即時看到每個單位所屬任務。

小結
setUnitDebugText 是除錯用 API，會將文字直接渲染在單位或建築物上方。

正確使用流程包括：

  • ✅ 開啟 debug 模式

  • ✅ 在需要時呼叫此方法以設定／清除文字

  • ⚠️ 注意會產生額外的網路資料與回放體積，僅建議於除錯時使用

透過於控制器或其他邏輯中靈活呼叫此函式，可直觀展示 AI 行為與狀態，有助於除錯與分析。

→返回《@chronodivide/game-api 使用教學與完整 API 對照表》

This article was last edited at