From 22e66cef3bc17b9433be9af646a8e272842815a4 Mon Sep 17 00:00:00 2001 From: 964293341 Date: Sat, 11 May 2024 21:05:56 +0800 Subject: [PATCH 1/2] docs(PyAPI): :memo: add docs for PyAPI --- CAPI/python/PyAPI/API.py | 14 +-- CAPI/python/PyAPI/DebugAPI.py | 8 +- CAPI/python/PyAPI/Interface.py | 210 +++++++++++++++++++++++++++++---- CAPI/python/PyAPI/logic.py | 2 +- 4 files changed, 201 insertions(+), 33 deletions(-) diff --git a/CAPI/python/PyAPI/API.py b/CAPI/python/PyAPI/API.py index 3b336b58..2a2a2375 100644 --- a/CAPI/python/PyAPI/API.py +++ b/CAPI/python/PyAPI/API.py @@ -10,8 +10,8 @@ def __init__(self, logic: ILogic) -> None: self.__logic = logic self.__pool = ThreadPoolExecutor(20) - def Move(self, timeInMilliseconds: int, angle: float) -> Future[bool]: - return self.__pool.submit(self.__logic.Move, timeInMilliseconds, angle) + def Move(self, timeInMilliseconds: int, angleInRadian: float) -> Future[bool]: + return self.__pool.submit(self.__logic.Move, timeInMilliseconds, angleInRadian) def MoveRight(self, timeInMilliseconds: int) -> Future[bool]: return self.Move(timeInMilliseconds, pi * 0.5) @@ -25,8 +25,8 @@ def MoveUp(self, timeInMilliseconds: int) -> Future[bool]: def MoveDown(self, timeInMilliseconds: int) -> Future[bool]: return self.Move(timeInMilliseconds, 0) - def Attack(self, angle: float) -> Future[bool]: - return self.__pool.submit(self.__logic.Attack, angle) + def Attack(self, angleInRadian: float) -> Future[bool]: + return self.__pool.submit(self.__logic.Attack, angleInRadian) def Recover(self, recover: int) -> Future[bool]: return self.__pool.submit(self.__logic.Recover, recover) @@ -76,7 +76,7 @@ def GetFullMap(self) -> List[List[THUAI7.PlaceType]]: def GetPlaceType(self, cellX: int, cellY: int) -> THUAI7.PlaceType: return self.__logic.GetPlaceType(cellX, cellY) - def GetConstructionState(self, cellX: int, cellY: int) -> tuple: + def GetConstructionState(self, cellX: int, cellY: int) -> Tuple[int, int]: return self.__logic.GetConstructionState(cellX, cellY) def GetWormholeHp(self, cellX: int, cellY: int) -> int: @@ -112,7 +112,7 @@ def HaveView(self, gridX: int, gridY: int) -> bool: self.GetSelfInfo().viewRange, ) - def Print(self, cont: str) -> None: + def Print(self, string: str) -> None: pass def PrintShip(self) -> None: @@ -184,7 +184,7 @@ def GetFullMap(self) -> List[List[THUAI7.PlaceType]]: def GetPlaceType(self, cellX: int, cellY: int) -> THUAI7.PlaceType: return self.__logic.GetPlaceType(cellX, cellY) - def GetConstructionState(self, cellX: int, cellY: int) -> tuple: + def GetConstructionState(self, cellX: int, cellY: int) -> Tuple[int, int]: return self.__logic.GetConstructionState(cellX, cellY) def GetWormholeHp(self, cellX: int, cellY: int) -> int: diff --git a/CAPI/python/PyAPI/DebugAPI.py b/CAPI/python/PyAPI/DebugAPI.py index 0cade2ff..820f0daf 100644 --- a/CAPI/python/PyAPI/DebugAPI.py +++ b/CAPI/python/PyAPI/DebugAPI.py @@ -199,7 +199,7 @@ def GetFullMap(self) -> List[List[THUAI7.PlaceType]]: def GetPlaceType(self, cellX: int, cellY: int) -> THUAI7.PlaceType: return self.__logic.GetPlaceType(cellX, cellY) - def GetConstructionState(self, cellX: int, cellY: int) -> tuple: + def GetConstructionState(self, cellX: int, cellY: int) -> Tuple[int, int]: return self.__logic.GetConstructionState(cellX, cellY) def GetWormholeHp(self, cellX: int, cellY: int) -> int: @@ -235,8 +235,8 @@ def HaveView(self, gridX: int, gridY: int) -> bool: self.GetSelfInfo().viewRange, ) - def Print(self, cont: str) -> None: - self.__logger.info(cont) + def Print(self, string: str) -> None: + self.__logger.info(string) def PrintShip(self) -> None: for ship in self.__logic.GetShips(): @@ -440,7 +440,7 @@ def GetFullMap(self) -> List[List[THUAI7.PlaceType]]: def GetPlaceType(self, cellX: int, cellY: int) -> THUAI7.PlaceType: return self.__logic.GetPlaceType(cellX, cellY) - def GetConstructionState(self, cellX: int, cellY: int) -> tuple: + def GetConstructionState(self, cellX: int, cellY: int) -> Tuple[int, int]: return self.__logic.GetConstructionState(cellX, cellY) def GetWormholeHp(self, cellX: int, cellY: int) -> int: diff --git a/CAPI/python/PyAPI/Interface.py b/CAPI/python/PyAPI/Interface.py index 884fef3e..dbe92363 100644 --- a/CAPI/python/PyAPI/Interface.py +++ b/CAPI/python/PyAPI/Interface.py @@ -75,7 +75,7 @@ def HaveMessage(self) -> bool: pass @abstractmethod - def GetMessage(self) -> Tuple[int, str]: + def GetMessage(self) -> Tuple[int, Union[str, bytes]]: pass @abstractmethod @@ -134,181 +134,349 @@ def BuildShip(self, shipType: THUAI7.ShipType, birthIndex: int) -> bool: class IAPI(metaclass=ABCMeta): - """ - 选手可执行的操作，应当保证所有函数的返回值都应当为 `asyncio.Future`，例如下面的移动函数：\n - 指挥本角色进行移动： - - `timeInMilliseconds` 为移动时间，单位为毫秒 - - `angleInRadian` 表示移动的方向，单位是弧度，使用极坐标——竖直向下方向为 x 轴，水平向右方向为 y 轴\n - 发送信息、接受信息，注意收消息时无消息则返回 `nullopt` - """ - @abstractmethod def SendMessage(self, toPlayerID: int, message: Union[str, bytes]) -> Future[bool]: + """发送消息 + + :param toPlayerID: 接收方队内编号, 舰船为1~4, 基地为0 + :param message: 待发送消息, 分为 `str` 型和 `bytes` 型 + :return: 发送是否成功, 通过 `.result()` 方法等待获取 `bool` + """ pass @abstractmethod def HaveMessage(self) -> bool: + """检查是否拥有待接收消息 + + :return: 是否拥有待接收消息 + """ pass @abstractmethod - def GetMessage(self) -> Tuple[int, str]: + def GetMessage(self) -> Tuple[int, Union[str, bytes]]: + """接收消息队列的第一个消息 + + :return: 消息发送方的队内编号与消息, 如无消息发送方编号为-1 + """ pass - # 获取游戏目前所进行的帧数 @abstractmethod def GetFrameCount(self) -> int: - "获取游戏目前所进行的帧数" + """获取当前帧率 + + :raise: `NotImplementedError` + """ pass @abstractmethod def Wait(self) -> Future[bool]: - "等待下一帧" + """等待一帧 + - 在 `Setting.Asynchronous() == True` 下 + + :return: 等待是否成功, 通过 `.result()` 方法等待获取 `bool` + """ pass @abstractmethod def EndAllAction(self) -> Future[bool]: + """发出停止一切行动指令 + + :return: 是否进入无行动状态, 通过 `.result()` 方法等待获取 `bool` + """ pass @abstractmethod def GetShips(self) -> List[THUAI7.Ship]: + """获取本队所有舰船 + + :return: 本队所有舰船 + """ pass @abstractmethod def GetEnemyShips(self) -> List[THUAI7.Ship]: + """获取敌方舰船 + - 需要敌方舰船处于视野内, 对于 `TeamAPI` 指所有舰船视野 + + :return: 视野内敌方所有舰船 + """ pass @abstractmethod def GetBullets(self) -> List[THUAI7.Bullet]: + """获取敌方子弹 + - 需要子弹处于视野内 + + :return: 视野内敌方所有子弹 + :raise: `NotImplementedError` 对于 `TeamAPI` + """ pass @abstractmethod def GetFullMap(self) -> List[List[THUAI7.PlaceType]]: + """获取地图 + + :return: `THUAI7.PlaceType` 的二维数组 + """ pass @abstractmethod def GetGameInfo(self) -> THUAI7.GameInfo: + """获取当前游戏信息 + + :return: 当前游戏信息, 详见 `THUAI7.GameInfo` 定义 + """ pass @abstractmethod def GetPlaceType(self, cellX: int, cellY: int) -> THUAI7.PlaceType: + """获取区域类型 + + :param cellX: X坐标, 单位Cell + :param cellY: Y坐标, 单位Cell + :return: 该坐标的区域类型 + """ pass @abstractmethod - def GetConstructionState(self, cellX: int, cellY: int) -> tuple: + def GetConstructionState(self, cellX: int, cellY: int) -> Tuple[int, int]: + """获取当前建筑状态 + + :param cellX: X坐标, 单位Cell + :param cellY: Y坐标, 单位Cell + :return: 该建筑当前的所属队伍编号与血量 + """ pass @abstractmethod def GetWormholeHp(self, cellX: int, cellY: int) -> int: + """获取当前虫洞状态 + + :param cellX: X坐标, 单位Cell + :param cellY: Y坐标, 单位Cell + :return: 当前虫洞血量 + """ pass @abstractmethod def GetResourceState(self, cellX: int, cellY: int) -> int: + """获取当前资源状态 + + :param cellX: X坐标, 单位Cell + :param cellY: Y坐标, 单位Cell + :return: 当前资源剩余可开采量 + """ pass @abstractmethod def GetHomeHp(self) -> int: + """获取当前大本营血量 + + :return: 当前大本营血量 + """ pass @abstractmethod def GetEnergy(self) -> int: + """获取当前经济 + + :return: 当前经济 + """ pass @abstractmethod def GetScore(self) -> int: + """获取当前得分 + + :return: 当前得分 + """ pass @abstractmethod def GetPlayerGUIDs(self) -> List[int]: + """获取本队所有舰船GUID + + :return: 本队所有舰船GUID + """ pass @abstractmethod def Print(self, string: str) -> None: + """(DEBUG)打印字符串 + + :param string: 待打印字符串 + """ pass @abstractmethod def PrintShip(self) -> None: + """(DEBUG)打印所有舰船 + """ pass @abstractmethod def PrintTeam(self) -> None: + """(DEBUG)打印队伍信息 + """ pass @abstractmethod def PrintSelfInfo(self) -> None: - pass - - @abstractmethod - def GetSelfInfo(self) -> Union[THUAI7.Ship, THUAI7.Team]: + """(DEBUG)打印自身信息, `ShipDebugAPI` 打印舰船信息, `TeamDebugAPI` 打印队伍信息 + """ pass class IShipAPI(IAPI, metaclass=ABCMeta): @abstractmethod def Move(self, timeInMilliseconds: int, angleInRadian: float) -> Future[bool]: + """发出移动指令 + + :param timeInMilliseconds: 期望移动的毫秒数 + :param angleInRadian: 期望移动的弧度数, 向下为x轴正方向, 向右为y轴正方向 + :return: 移动是否成功, 通过 `.result()` 方法等待获取 `bool` + """ pass @abstractmethod def MoveRight(self, timeInMilliseconds: int) -> Future[bool]: + """发出向右移动指令 + + :param timeInMilliseconds: 期望移动的毫秒数 + :return: 移动是否成功, 通过 `.result()` 方法等待获取 `bool` + """ pass @abstractmethod def MoveUp(self, timeInMilliseconds: int) -> Future[bool]: + """发出向上移动指令 + + :param timeInMilliseconds: 期望移动的毫秒数 + :return: 移动是否成功, 通过 `.result()` 方法等待获取 `bool` + """ pass @abstractmethod def MoveLeft(self, timeInMilliseconds: int) -> Future[bool]: + """发出向左移动指令 + + :param timeInMilliseconds: 期望移动的毫秒数 + :return: 移动是否成功, 通过 `.result()` 方法等待获取 `bool` + """ pass @abstractmethod def MoveDown(self, timeInMilliseconds: int) -> Future[bool]: + """发出向下移动指令 + + :param timeInMilliseconds: 期望移动的毫秒数 + :return: 移动是否成功, 通过 `.result()` 方法等待获取 `bool` + """ pass @abstractmethod def Attack(self, angleInRadian: float) -> Future[bool]: + """发出攻击指令 + + :param angleInRadian: 期望攻击的弧度值, 向下为x轴正方向, 向右为y轴正方向 + :return: 攻击是否成功, 通过 `.result()` 方法等待获取 `bool` + """ pass @abstractmethod def Recover(self, recover: int) -> Future[bool]: + """发出回复指令 + - 需要接近可用的 `Home` 或 `Community`(`Construction`) + + :param recover: 期望回复生命值 + :return: 回复是否成功, 通过 `.result()` 方法等待获取 `bool` + """ pass @abstractmethod def Produce(self) -> Future[bool]: + """发出生产指令 + - 需要接近未采集完的 `Resource` + + :return: 进入生产状态是否成功, 通过 `.result()` 方法等待获取 `bool` + """ pass @abstractmethod def Rebuild(self, constructionType: THUAI7.ConstructionType) -> Future[bool]: + """发出重建指令 + - 需要接近待重建 `Construction` + + :param constructionType: 建筑类型 + :return: 进入建造状态是否成功, 通过 `.result()` 方法等待获取 `bool` + """ pass @abstractmethod def Construct(self, constructionType: THUAI7.ConstructionType) -> Future[bool]: + """发出建造指令 + - 需要接近待建 `Construction` + + :param constructionType: 建筑类型 + :return: 进入建造状态是否成功, 通过 `.result()` 方法等待获取 `bool` + """ pass @abstractmethod def GetSelfInfo(self) -> THUAI7.Ship: + """获取本舰船信息 + + :return: 舰船信息, 详见 `THUAI7.Ship` 定义 + """ pass @abstractmethod def HaveView(self, gridX: int, gridY: int) -> bool: + """检测是否拥有视野 + + :param gridX: 待检测X坐标, 单位Grid + :param gridY: 待检测Y坐标, 单位Grid + :return: 是否拥有视野 + """ pass class ITeamAPI(IAPI, metaclass=ABCMeta): @abstractmethod def GetSelfInfo(self) -> THUAI7.Team: + """获取本队伍信息 + + :return: 队伍信息, 详见 `THUAI7.Team` 定义 + """ pass @abstractmethod - def InstallModule( - self, playerID: int, moduleType: THUAI7.ModuleType - ) -> Future[bool]: + def InstallModule(self, playerID: int, moduleType: THUAI7.ModuleType) -> Future[bool]: + """安装模块 + + :param playerID: 待安装模块的舰船编号 + :param moduleType: 模块类型 + :return: 安装是否成功, 通过 `.result()` 方法等待获取 `bool` + """ pass @abstractmethod def Recycle(self, playerID: int) -> Future[bool]: + """回收舰船 + + :param playerID: 待回收舰船编号 + :return: 回收是否成功, 通过 `.result()` 方法等待获取 `bool` + """ pass @abstractmethod def BuildShip(self, shipType: THUAI7.ShipType, birthIndex: int) -> Future[bool]: + """建造舰船 + + :param shipType: 舰船类型 + :param birthIndex: 出生点 (可用的 `Home` 与 `Community`(`Construction`)) 编号 + :return: 建造是否成功, 通过 `.result()` 方法等待获取 `bool` + """ pass diff --git a/CAPI/python/PyAPI/logic.py b/CAPI/python/PyAPI/logic.py index 707bbfd1..4fbb56ad 100644 --- a/CAPI/python/PyAPI/logic.py +++ b/CAPI/python/PyAPI/logic.py @@ -155,7 +155,7 @@ def GetConstructionState(self, cellX: int, cellY: int) -> tuple: ) else: self.__logger.warning("GetConstructionState: Out of range") - return (-1,-1) + return (-1, -1) def GetWormholeHp(self, cellX: int, cellY: int) -> int: with self.__mtxState: From e6b54d1ce6a1105b4d7603c029c71bd4450e9d0b Mon Sep 17 00:00:00 2001 From: 964293341 Date: Sat, 11 May 2024 21:30:07 +0800 Subject: [PATCH 2/2] docs(PyAPI): :memo: add docs for structures in PyAPI --- CAPI/python/PyAPI/Interface.py | 60 ++++++++++++++++++--------------- CAPI/python/PyAPI/structures.py | 52 +++++++++++++++++++++++++++- 2 files changed, 83 insertions(+), 29 deletions(-) diff --git a/CAPI/python/PyAPI/Interface.py b/CAPI/python/PyAPI/Interface.py index dbe92363..ca381a70 100644 --- a/CAPI/python/PyAPI/Interface.py +++ b/CAPI/python/PyAPI/Interface.py @@ -149,7 +149,7 @@ def HaveMessage(self) -> bool: """检查是否拥有待接收消息 :return: 是否拥有待接收消息 - """ + """ pass @abstractmethod @@ -157,7 +157,7 @@ def GetMessage(self) -> Tuple[int, Union[str, bytes]]: """接收消息队列的第一个消息 :return: 消息发送方的队内编号与消息, 如无消息发送方编号为-1 - """ + """ pass @abstractmethod @@ -174,7 +174,7 @@ def Wait(self) -> Future[bool]: - 在 `Setting.Asynchronous() == True` 下 :return: 等待是否成功, 通过 `.result()` 方法等待获取 `bool` - """ + """ pass @abstractmethod @@ -182,15 +182,15 @@ def EndAllAction(self) -> Future[bool]: """发出停止一切行动指令 :return: 是否进入无行动状态, 通过 `.result()` 方法等待获取 `bool` - """ + """ pass @abstractmethod def GetShips(self) -> List[THUAI7.Ship]: """获取本队所有舰船 - :return: 本队所有舰船 - """ + :return: 本队所有舰船, 详见 `THUAI7.Ship` 定义 + """ pass @abstractmethod @@ -198,8 +198,8 @@ def GetEnemyShips(self) -> List[THUAI7.Ship]: """获取敌方舰船 - 需要敌方舰船处于视野内, 对于 `TeamAPI` 指所有舰船视野 - :return: 视野内敌方所有舰船 - """ + :return: 视野内敌方所有舰船, 详见 `THUAI7.Ship` 定义 + """ pass @abstractmethod @@ -207,9 +207,9 @@ def GetBullets(self) -> List[THUAI7.Bullet]: """获取敌方子弹 - 需要子弹处于视野内 - :return: 视野内敌方所有子弹 + :return: 视野内敌方所有子弹, 详见 `THUAI7.Bullet` 定义 :raise: `NotImplementedError` 对于 `TeamAPI` - """ + """ pass @abstractmethod @@ -217,7 +217,7 @@ def GetFullMap(self) -> List[List[THUAI7.PlaceType]]: """获取地图 :return: `THUAI7.PlaceType` 的二维数组 - """ + """ pass @abstractmethod @@ -225,7 +225,7 @@ def GetGameInfo(self) -> THUAI7.GameInfo: """获取当前游戏信息 :return: 当前游戏信息, 详见 `THUAI7.GameInfo` 定义 - """ + """ pass @abstractmethod @@ -235,7 +235,7 @@ def GetPlaceType(self, cellX: int, cellY: int) -> THUAI7.PlaceType: :param cellX: X坐标, 单位Cell :param cellY: Y坐标, 单位Cell :return: 该坐标的区域类型 - """ + """ pass @abstractmethod @@ -245,7 +245,7 @@ def GetConstructionState(self, cellX: int, cellY: int) -> Tuple[int, int]: :param cellX: X坐标, 单位Cell :param cellY: Y坐标, 单位Cell :return: 该建筑当前的所属队伍编号与血量 - """ + """ pass @abstractmethod @@ -255,7 +255,7 @@ def GetWormholeHp(self, cellX: int, cellY: int) -> int: :param cellX: X坐标, 单位Cell :param cellY: Y坐标, 单位Cell :return: 当前虫洞血量 - """ + """ pass @abstractmethod @@ -265,7 +265,7 @@ def GetResourceState(self, cellX: int, cellY: int) -> int: :param cellX: X坐标, 单位Cell :param cellY: Y坐标, 单位Cell :return: 当前资源剩余可开采量 - """ + """ pass @abstractmethod @@ -273,7 +273,7 @@ def GetHomeHp(self) -> int: """获取当前大本营血量 :return: 当前大本营血量 - """ + """ pass @abstractmethod @@ -281,7 +281,7 @@ def GetEnergy(self) -> int: """获取当前经济 :return: 当前经济 - """ + """ pass @abstractmethod @@ -289,7 +289,7 @@ def GetScore(self) -> int: """获取当前得分 :return: 当前得分 - """ + """ pass @abstractmethod @@ -297,33 +297,37 @@ def GetPlayerGUIDs(self) -> List[int]: """获取本队所有舰船GUID :return: 本队所有舰船GUID - """ + """ pass @abstractmethod def Print(self, string: str) -> None: - """(DEBUG)打印字符串 + """ + (DEBUG)打印字符串 :param string: 待打印字符串 - """ + """ pass @abstractmethod def PrintShip(self) -> None: - """(DEBUG)打印所有舰船 - """ + """ + (DEBUG)打印所有舰船 + """ pass @abstractmethod def PrintTeam(self) -> None: - """(DEBUG)打印队伍信息 - """ + """ + (DEBUG)打印队伍信息 + """ pass @abstractmethod def PrintSelfInfo(self) -> None: - """(DEBUG)打印自身信息, `ShipDebugAPI` 打印舰船信息, `TeamDebugAPI` 打印队伍信息 - """ + """ + (DEBUG)打印自身信息, `ShipDebugAPI` 打印舰船信息, `TeamDebugAPI` 打印队伍信息 + """ pass diff --git a/CAPI/python/PyAPI/structures.py b/CAPI/python/PyAPI/structures.py index f65e9512..7e261c05 100644 --- a/CAPI/python/PyAPI/structures.py +++ b/CAPI/python/PyAPI/structures.py @@ -162,6 +162,27 @@ class NewsType(Enum): class Ship: + """ + :attr x: X坐标, 单位Grid + :attr y: Y坐标, 单位Grid + :attr speed: 速度, 单位Grid/s + :attr hp: 生命值 + :attr armor: 装甲值 + :attr shield: 护盾值 + :attr playerID: 舰船编号, 1~4 + :attr teamID: 所属队伍编号 + :attr guid: GUID + :attr shipState: 行为状态 + :attr shipType: 舰船类型 + :attr viewRange: 视距 + :attr producerType: 采集器类型 + :attr constructorType: 建造器类型 + :attr armorType: 装甲类型 + :attr shieldType: 护盾类型 + :attr weaponType: 武器类型 + :attr facingDirection: 面朝方向的弧度数, 向下为x轴正方向, 向右为y轴正方向 + """ + def __init__(self): self.x: int = 0 self.y: int = 0 @@ -184,6 +205,13 @@ def __init__(self): class Team: + """ + :attr playerID: 队内编号, 应当为0 + :attr teamID: 所属队伍编号 + :attr score: 得分 + :attr energy: 经济 + """ + def __init__(self): self.playerID: int = 0 self.teamID: int = 0 @@ -201,6 +229,19 @@ def __init__(self): class Bullet: + """ + :attr x: X坐标, 单位Grid + :attr y: Y坐标, 单位Grid + :attr facingDirection: 运动方向的弧度数, 向下为x轴正方向, 向右为y轴正方向 + :attr guid: GUID + :attr teamID: 所属队伍编号 + :attr bulletType: 子弹类型 + :attr damage: 伤害 + :attr attackRange: 射程 + :attr bombRange: 爆炸半径 + :attr speed: 运动速度, 单位Grid/s + """ + def __init__(self): self.x: int = 0 self.y: int = 0 @@ -211,7 +252,6 @@ def __init__(self): self.damage: int = 0 self.attackRange: int = 0 self.bombRange: int = 0 - self.explodeRange: float = 0.0 self.speed: int = 0 @@ -226,6 +266,16 @@ def __init__(self): class GameInfo: + """ + :attr gameTime: 当前游戏时间 + :attr redScore: 红队当前分数 + :attr redEnergy: 红队当前经济 + :attr redHomeHp: 红队当前基地血量 + :attr blueScore: 蓝队当前分数 + :attr blueEnergy: 蓝队当前经济 + :attr blueHomeHp: 蓝队当前基地血量 + """ + def __init__(self): self.gameTime: int = 0 self.redScore: int = 0