@chronodivide/game-api 使用教學與完整 API 對照表

| Chrono Divide | 158 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/1181

以下內容來自 @chronodivide/game-api 套件。其 TypeScript 定義檔 (dist/index.d.ts) 提供了完整的 API 描述。
主要可使用的類別及方法摘要如下：

1. ActionsApi

常用於對遊戲下指令，例如建造、賣建築、控制單位等

方法 說明
placeBuilding(buildingName, rx, ry) 在指定座標放置建築物
sellObject(objectId) 賣掉指定 ID 的物件
sellBuilding(buildingId) 已過時，改用 sellObject
toggleRepairWrench(buildingId) 切換建築物的維修扳手
toggleAlliance(toPlayer, enabled) 與指定玩家結盟/解除
pauseProduction(queueType)、resumeProduction(queueType) 暫停或恢復某生產佇列
queueForProduction(queueType, objName, objType, quantity) 將物件加入生產佇列
unqueueFromProduction(queueType, objName, objType, quantity) 從生產佇列取消物件
activateSuperWeapon(type, tile, tile2?) 施放超級武器
orderUnits(unitIds, orderType, ...) 給單位下達各種指令（移動、攻擊等）
sayAll(text) 在遊戲內全體發言
setGlobalDebugText(text) 顯示全局除錯文字（需啟用 bot debug 模式）
setUnitDebugText(unitId, text) 在單位上顯示除錯文字（需啟用 bot debug 模式）
quitGame() 結束當前遊戲

2. GameApi

提供查詢遊戲狀態的功能

方法 說明
isPlayerDefeated(playerName) 判斷玩家是否已被擊敗
areAlliedPlayers(p1, p2) 兩名玩家是否為同盟
canPlaceBuilding(playerName, buildingName, tile) 指定位置是否能建造
getBuildingPlacementData(objName) 取得建築基礎大小與中心格
getPlayers() 列出所有玩家名稱
getPlayerData(playerName) 取得玩家各項資料
getAllTerrainObjects() 取得地表物件 ID 列表
getAllUnits(filter?) / getNeutralUnits(filter?) 取得所有（或中立）單位 ID
getUnitsInArea(tileRange) 取得區域內單位 ID
getVisibleUnits(playerName, type, filter?) 取得玩家可見的單位
getGameObjectData(objId) / getUnitData(unitId) 取得物件/單位資料
getAllSuperWeaponData() 所有超級武器資料
getGeneralRules()等 取得多種 ini 規則檔內容
generateRandomInt(min, max)、generateRandom() 使用內部 PRNG 產生亂數
getTickRate()、getBaseTickRate() 取得當前/基礎遊戲速度
getCurrentTick()、getCurrentTime() 取得目前遊戲刻或時間

3. GameInstanceApi

控制離線/線上遊戲實例

方法 說明
isFinished() 判斷遊戲是否結束
update() 在離線模式推進一回合；線上模式則等待下一回合
getCurrentTick()、getTickRate() 取得當前刻或速度
getPlayerStats() 取得玩家統計資料
saveReplay(targetDir?) 儲存回放檔
dispose() 釋放遊戲資源

4. MapApi

提供地圖資訊與路徑尋找功能

方法 說明
getRealMapSize() 取得真實地圖尺寸
getStartingLocations() 各玩家起始位置
getTheaterType() 地形風格
getTile(rx, ry) 取得指定座標的格子
getTilesInRect(rect) / getTilesInRect(baseTile, size) 取得範圍格子
getObjectsOnTile(tile) 取得格子上的物件
hasBridgeOnTile(tile)、hasHighBridgeOnTile(tile) 是否有橋梁
isPassableTile(tile, speedType, onBridge, subCell) 格子是否可通行
findPath(speedType, subCell, from, to, options?) 尋找路徑
isVisibleTile(tile, playerName, tileElevation?) 某玩家是否能看見此格
getTileResourceData(tile) / getAllTilesResourceData() 取得資源資料

5. ProductionApi

查詢及操作生產相關資訊

方法 說明
isAvailableForProduction(objRules) 是否能生產此物件
getAvailableObjects(queueType?) 目前可生產的物件清單
getQueueTypeForObject(objRules) 物件屬於哪種生產佇列
getQueueData(queueType) 取得佇列狀態

6. PublicApi 與 cdapi

cdapi 為 PublicApi 的實例，負責初始化及建立遊戲

方法 說明
init(mixDir) 初始化，指定原版 RA2 資料目錄
getAvailableMaps() 列出可用地圖名稱
getAvailableGameModes(mapName) 查詢地圖支援的模式
createGame(opts) 建立線上或離線遊戲，回傳GameInstanceApi

7. RulesApi

讀取 rules.ini 等規則檔內容

此類別提供多數以 get 開頭的函式，用來擷取建築、單位、武器、彈頭等規則資訊，例如 getBuilding(name)、getWeapon(name)、getCountry(name) 等。

8. 其他

  • LoggerApi：提供 debug、info、warn 等日誌方法

  • Bot：實作 AI 時的基底類別，覆寫 onGameStart、onGameTick、onGameEvent 等方法

  • GameMath：一組確保跨平台一致的數學函式（pow、sqrt、sin 等）

此外，檔案中還定義了多個列舉型別與資料介面，例如物件類型 ObjectType、命令類型 OrderType、生產佇列 QueueType、以及超級武器類型 SuperWeaponType等，供呼叫方法時使用。

基本使用流程

  1. 先 import { cdapi, Bot, OrderType, ... } from "@chronodivide/game-api"。

  2. 呼叫 cdapi.init(mixDir) 初始化。

  3. 使用自訂的 Bot 子類別實作 onGameStart 等方法。

  4. 透過 cdapi.createGame(opts) 建立遊戲並取得 GameInstanceApi。

  5. 在遊戲迴圈中 (while (!game.isFinished()) await game.update()) 使用 GameApi 取得資訊、ActionsApi 發出指令、ProductionApi 控制生產。

  6. 完成後可 saveReplay() 取得回放檔。

以上即為 @chronodivide/game-api 的主要可用方法與使用方式概觀。若需更詳細的型別與屬性，請直接參考套件內的 dist/index.d.ts 定義檔。

 

→Red Alert 2：玩家可建造的建築清單

 

→返回《Chrono Divide Bot 開發指南》

This article was last edited at