API Reference

常數與代碼

應用程式界面（API）呼叫過程中使用一些數字代表不同的操作編號、物件類型、錯誤代碼等，簡要的意義和用途如下。詳細的定義和分項說明請閱讀 api/constants.py。

• CommandType：每種 API 對應的編號，用於報錯訊息。
• GameStatus：遊戲運行狀態，用於查詢目前遊戲是否運行中。
• TerrainType：代表地圖上某一格的地形，用於查詢地圖上指定位置的地形。
• TowerType：防禦塔的種類，用於獲取防禦塔資訊或指定要放置的防禦塔種類。
• EnemyType：攻擊單位的種類，用於獲取攻擊單位資訊或指定派出的攻擊單位種類。
• SpellType：技能的種類，用於查詢技能冷卻時間或指定施放的技能種類。
• TargetStrategy：防禦塔的瞄準策略，用於指定防禦塔如何瞄準攻擊單位。
• ChatSource：聊天室內的發言者，用於調閱聊天室訊息歷史。
• StatusCode：呼叫 API 得到的回覆狀態，用於確認指令執行結果與錯誤處理。

資料結構定義

我們定義了以下跟遊戲相關的資料結構，在呼叫 API 取得遊戲資料時會用到。詳細的定義和分項說明請閱讀 api/structures.py。

• Vector2：兩個整數組成的二維向量。
• ApiException：代表一次失敗的 API 呼叫後回傳的錯誤，附帶關於錯誤來源、錯誤種類、說明文字的資訊。
• Tower：關於一座防禦塔的屬性、數值資訊。
• Enemy：關於一個攻擊單位的屬性、數值資訊。

API 函數

呼叫 API 函數時，如果操作成功並順利取得結果，函數回傳下方表格中列出的型別。如果因為任何原因導致呼叫失敗，函數會回傳一個 ApiException，其中附帶關於此錯誤的資訊（可以由 str、print 等方式檢視錯誤訊息）。呼叫後請注意錯誤處理避免造成程式執行時發生錯誤。

除了 get_game_status() 以外，若在遊戲尚未開始時或遊戲暫停中呼叫其餘任一個函數，會使得 agent 暫停執行直到遊戲繼續運行，並在遊戲重新開始後重新執行該操作。因此設計 agent 時不需要考慮因為遊戲暫停或未開始而造成錯誤的情況。

以下列出所有支援的 API 函數以及簡明用途，詳細資訊請閱讀 Python API library api/game_client.py 中的說明。

分類	簡述	函數簽章	發布版本
一般	獲得遊戲狀態	get_game_status() -> GameStatus	v1.0.0
一般	獲得遊戲剩餘時間	get_remain_time() -> float	v1.0.0
一般	獲得分數資訊	get_scores(owned: bool) -> int	v1.0.0
一般	獲得金錢數量	get_money(owned: bool) -> int	v1.0.0
一般	獲得每秒收入	get_income(owned: bool) -> int	v1.0.0
一般	設定遊戲名稱	set_name(name: str) -> None	v1.0.0
地圖	獲得全部地形	get_all_terrain() -> list[list[TerrainType]]	v1.0.0
地圖	獲得單格地形	get_terrain(pos: Vector2) -> TerrainType	v1.0.0
攻擊單位	獲得攻擊單位波編號	get_current_wave() -> int	v1.0.0
攻擊單位	獲取距離下波攻擊單位時間	get_time_until_next_wave() -> float	v1.0.0
攻擊單位	獲得系統單位路徑	get_system_path(fly: bool) -> list[Vector2]	v1.0.0
攻擊單位	獲得對手單位路徑	get_opponent_path(fly: bool) -> list[Vector2]	v1.0.0
攻擊單位	生成單位	spawn_unit(type: EnemyType) -> None	v1.0.0
攻擊單位	獲得單位冷卻時間	get_unit_cooldown(type: EnemyType) -> float	v1.0.0
攻擊單位	獲得全部攻擊單位資訊	get_all_enemies(owned: bool) -> list[Enemy]	v1.0.0
防禦塔	放置防禦塔	place_tower(type: TowerType, level: str, coord: Vector2) -> None	v1.0.0
防禦塔	獲得全部防禦塔資訊	get_all_towers(owned: bool) -> list[Tower]	v1.0.0
防禦塔	獲得單一防禦塔資訊	get_tower(owned: bool, coord: Vector2) -> Tower	v1.0.0
防禦塔	出售防禦塔	sell_tower(coord: Vector2) -> None	v1.0.0
防禦塔	設定防禦塔策略	set_strategy(coord: Vector2, strategy: TargetStrategy) -> None	v1.0.0
法術	使用法術	cast_spell(type: SpellType, position: Vector2) -> None	v1.0.0
法術	獲取法術冷卻時間	get_spell_cooldown(self, owned: bool, type: SpellType) -> float	v1.0.0
聊天室	發送訊息	send_chat(msg: str) -> None	v1.0.0
聊天室	讀取聊天室	get_chat_history(num: int) -> list[tuple[ChatSource, str]]	v1.0.0
聊天室	設定聊天室名稱顏色	set_chat_name_color(color: str) -> None	v1.0.0
其他	像素貓	pixelcat() -> str	v1.1.1

全域通行頂級榮耀特選尊貴專屬至尊終身極享體驗限量貴賓卡友 API 函數

分類	簡述	價格	函數簽章	發布版本
???	設定剩餘的 燦爛星辰信仰晶核	0	set_the_radiant_core_of_stellar_faith(quota: int) -> None	1.3.0
???	取得目前剩餘的 燦爛星辰信仰晶核	0	get_the_radiant_core_of_stellar_faith() -> None	1.3.0
???	讓對手連續斷線 5 次	2500	disconnect() -> None	1.3.0
???	商店所有物品 9 折（永久）	4500	ntu_student_id_card() -> str	1.3.0
???	播放精美音效	400	metal_pipe() -> None	1.3.0
???	發送彈幕	floor(len * font_size(pt) / 2)	spam(s: str, font_size: int, color: tuple(int, int, int)) -> None	1.3.0
???	五秒內無敵（被攻擊不會讓對手加分）	2000	super_star() -> None	1.3.0
???	一秒內派兵無 CD（還是會被理論 rate limit $\approx$ 100 bound 住）	3500	turbo_on() -> None	1.3.0
???	使用害羞幽靈偷取對方金錢	1000	boo() -> bool	1.3.2

說明

1. 如果先前沒有呼叫過 set_the_radiant_core_of_stellar_faith 而且不是在 至尊終身特選極享體驗限量貴賓卡友全域通行頂級榮耀特選尊貴專屬大使巔峰挑戰賽 期間，get_the_radiant_core_of_stellar_faith 函數回傳 -1
2. 在 至尊終身特選極享體驗限量貴賓卡友全域通行頂級榮耀特選尊貴專屬大使巔峰挑戰賽 期間無法使用 set_the_radiant_core_of_stellar_faith 函數，燦爛星辰信仰晶核 值將會由系統自動設置

Note

燦爛星辰信仰晶核 與 至尊終身特選極享體驗限量貴賓卡友全域通行頂級榮耀特選尊貴專屬大使巔峰挑戰賽 是台大資訊營實體活動的一部分。現在 agent 可以無限制的自由使用與 燦爛星辰信仰晶核 相關的所有 API。