ActionsApi.setGlobalDebugText(text)方法說明與使用範例

| Chrono Divide | 2 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/1198

以下內容基於倉庫中的 @chronodivide/game-api 的型別宣告檔案與說明文件。

在 package/dist/index.d.ts 中，ActionsApi 提供了 setGlobalDebugText 方法，並給出了其用途與限制：

24  /**
25   * Prints a persistent multiline debug string in the game client at a fixed position on the screen
26   *
27   * **IMPORTANT**: This method only works when bot debug mode is enabled
28   *
29   * If the bot is in online mode, it will send this text as a player action (only enabled for bot accounts).
30   * The game client also needs to have r.debug_text=1 enabled in the dev console.
31   *
32   * If the bot is in offline mode, this method will still generate actions that may increase the replay file size
33   * significantly.
34   */
35  setGlobalDebugText(text: string | undefined): void;

說明文件 package/README.md 進一步解釋了使用前提與注意事項：

120  ### Unit debug labels and global debug text
...
126  - Displaying a sticky always-on-top multiline text, at a fixed position on the screen, below the chat area. To use this, call `actionsApi.setGlobalDebugText`. This text is also persistent and offers no scrolling functionality. The value is simply overwritten. Use this feature to display relevant debug stats on the screen. Logging should be done using the bot logger instead.
128  In both cases, debug text will be printed in the game client only if the console variable `r.debug_text=1` is set.
130  **IMPORTANT**: Both `actionsApi.setUnitDebugText` and `actionsApi.setGlobalDebugText` will generate a player action as workaround for not being able to directly remote control a game client. This is a consequence of the bot code running in its own sandbox and not being directly connected to a game client. As a result, this can generate considerable network noise, as well as increased replay file size. For this reason, both functions only work when bot debug mode is enabled and require an account with bot privileges in online mode.

如何在程式中使用
SupalosaBot 在 updateDebugState 函式中展示了 setGlobalDebugText 的實際用法。該函式會彙總各種除錯資訊，在除錯模式開啟時定期刷新這些內容：

124  private updateDebugState(game: GameApi) {
125      if (!this.getDebugMode()) {
126          return;
127      }
128      // Update the global debug text.
129      const myPlayer = game.getPlayerData(this.name);
130      const harvesters = game.getVisibleUnits(this.name, "self", (r) => r.harvester).length;

133      let globalDebugText = `Cash: ${myPlayer.credits} | Harvesters: ${harvesters}\n`;
134      globalDebugText += this.queueController.getGlobalDebugText(this.gameApi, this.productionApi);
135      globalDebugText += this.missionController.getGlobalDebugText(this.gameApi);
136      globalDebugText += this.matchAwareness?.getGlobalDebugText();

138      this.missionController.updateDebugText(this.actionsApi);

140      // Tag enemy units with IDs
141      game.getVisibleUnits(this.name, "enemy").forEach((unitId) => {
142          this.actionsApi.setUnitDebugText(unitId, unitId.toString());
143      });

145      this.actionsApi.setGlobalDebugText(globalDebugText);
146  }

這裡透過 actionsApi.setGlobalDebugText(globalDebugText) 將整理好的狀態資訊（現金、採礦車數量、任務佇列等）輸出至遊戲介面的固定位置，方便除錯時即時查看。

總結
setGlobalDebugText(text) 會在遊戲客戶端的固定位置顯示多行文字，僅在除錯模式下有效。

  • 在線模式 下，該呼叫會產生一條玩家操作（僅對具有 bot 權限的帳號開放）。

  • 離線模式 下，這些操作也會寫入回放檔，因此可能大幅增加檔案體積。

必須在客戶端的開發者主控台執行：

r.debug_text=1

並確保某個玩家被設為：

r.debug_bot=<index>

才能看到這些文字。

在倉庫範例中，SupalosaBot 利用該函式定期展示資源與指揮邏輯等資訊，便於開發者掌握當前 AI 的狀態。

 

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

This article was last edited at