What's New

support Docker
support Aliyun FC
support VScode DevContainer

Install Docker

Clone

将本项目克隆到本地，并进入项目目录

git clone https://gitee.com/warai/starter-kit.git
cd ./starter-kit

Quick Start

支持三种开发方式, 选择一种即可，都需要安装Docker,并启动Docker服务

VScode DevContainer

将代码映射到容器中，在容器环境中开发调试

详细参见: Developing inside a Container

使用 VSCode 打开本项目: code ./
安装插件：Dev Containers
安装完会弹出提示：在Dev Container打开，如果没有可以使用快捷键Shift+Ctrl+P,选择Dev Containers: Reopen in Container
等待初始化Dev Container，成功后即可正常开发
如需调试：设置好断点，在调试Tab页选择：Debug In DevContainer, 按F5启动调试即可

VScode Local

本机开发，容器中运行

使用 VSCode 打开本项目: code ./
执行Build任务(Menu -> Terminal -> Run Build Task... ),快捷键: Ctrl+Shift+B(只需执行一次，SDK更新后需再次执行)
设置好断点，在调试Tab页选择：Debug Attached Docker Container, 按F5启动调试即可

CommandLine

在命令行中手动执行，自由度最高

Build Image

使用docker build基础镜像

docker build --no-cache --platform linux/amd64 -t starter-runtime .

Run

在 Docker容器中运行

Mac、Linux 或 Windows PowerShell中执行如下命令

docker run -it --rm --name starter-test -v ${PWD}:/usr/src/app starter-runtime python ./play_competitions.py

Windows CMD执行如下命令

docker run -it --rm --name starter-test -v %cd%:/usr/src/app starter-runtime python ./play_competitions.py

注意: 修改代码后不用重新Build Image, 直接 Run即可

Update Deps

如果官方SDK有更新，需重新执行 Build Image 步骤

先知2024兵棋AI选拔赛 Starter Kit

本项目用于先知2024兵棋AI选拔赛，主要介绍了任务型智能体开发方法。详细的数据结构可以参考：

本项目仍处于积极完善阶段，请保持关注以便及时更新。

前期准备

一台能够联网的 Linux 机器，推荐使用 Ubuntu 20.04 及以上
Python 3.10 环境，推荐使用 conda 创建一个新的环境（Miniconda官网）

安装

克隆本项目

使用以下命令将本项目克隆到本地。

git clone http://wargame.ia.ac.cn/gitlab/xz2024/starter-kit.git

当前路径下会创建 starter-kit 文件夹，其中内容与本项目一致。

安装依赖

使用以下命令在 Python 3.10 环境中安装本项目所需的依赖。

python -m pip install -U -r requirements.txt

终端显示 Successfully installed ...，没有报错信息，则表示安装成功。

使用

目录结构

starter-kit
├── ai                       # 智能体的代码与所需数据应放在此文件夹
│   ├── executors            # 任务的具体执行策略
│   │   ├── cross_fire.py    # 集结任务
│   │   ├── defend.py        # 防守任务
│   │   └── scout.py         # 侦察任务
│   ├── action.py            # 动作数据结构的生成器
│   ├── agent.py             # 在此文件的 Agent 类中实现智能体算法
│   ├── const.py             # 自定义的一些常量
│   └── map.py               # 一些简单的地图使用函数
├── replays                  # 默认的复盘生成文件夹
├── README.md                # 说明文件
├── play_competitions.py     # 入口脚本，智能体与环境交互的样例
└── requirements.txt         # 项目所需依赖

ai/ 文件夹内的所有目录结构与文件内容均可由开发者自行修改。

基本用法

要使用当前的智能体与环境交互，可以运行以下命令。

python play_competitions.py

终端持续显示交互信息，无报错信息，停止后 replays/ 文件夹中生成复盘文件，则表示运行成功。

赛道详情

“穿越火线”赛道

任务设定

任务目标：控制多个算子，以最快的速度、最大化保留有生力量的方式从任务起点达到任务终点；
任务开始时间：兵棋推演开始，任务启动；
任务终止时间：终止时间约为车辆算子按照最快路径以机动速度达到终点所需时间的3倍。

环境设定

为支持强化学习模型训练，环境可以随机生成任务并提供奖励反馈；
任务的起点、终点可以随机产生（任务起点和终点将不会出现在湖泊内），任务起点和终点的距离范围为20-35格；
我方控制算子类型包括无人机、重型坦克、重型战车、无人战车、步兵小队5种算子；
我方无人机算子数量为1，步兵小队数量为1，车辆类型算子在特定范围内随机生成，算子最大数量为7；
任务开始时，我方算子随机部署在以任务起点为圆心、半径为2格的圆形区域内；
任务过程中，我方算子可以采取当前环境条件允许的任意动作；
敌方可能出现的算子包括重型坦克、重型战车、步兵小队、远程火炮4种类型；
敌方火炮算子数量为1，重型坦克、重型战车、步兵小队算子数量和位置将随机生成；
敌方算子无法移动，但具备打击能力。敌方算子火力不会覆盖任务起点和目标终点，但有概率覆盖部分我方地面算子的行进路径。

奖励计算

单局得分计算方式为，在任务$m$中，每个算子到达时间分别为$t_1, t_2, ..., t_K$，到目的地的后剩余价值分别为$v_1, v_2, ..., v_K$，任务终止时间$T$：

$$ r_m = \sum_k^K \delta_k v_k[1 + (\frac{T-t_k}{T})] $$

其中，

$$ \delta_k = \begin{cases} & 1, &t_k \le T \\ & 0, &t_k > T \end{cases} $$

“协同侦察”赛道

任务设定

任务目标：控制多个算子，躲避敌方火力的干扰，以最快的速度完成对敌方全部阵地区域的侦察；
任务开始时间：兵棋推演开始，任务启动；
任务终止时间：推演2800步；
任务结束条件：超过任务终止时间或发现敌方全部算子。

环境设定

为支持强化学习模型训练，环境可以随机生成任务并提供奖励反馈；
任务起点、待侦察区域随机生成，待侦察区域为圆形，半径范围为20-30格，任务起点和待侦察区域中心距离范围为30-40格；
我方算子类型包括无人机、重型坦克、重型战车3种算子；
我方算子数量为3-5个，其中至少包括1架无人机、1辆重型战车；
任务开始时，我方算子随机部署在以任务起点为圆心、半径为4格的圆形区域内；
任务过程中，我方算子可以采取当前环境条件允许的任意动作；
敌方待侦察算子包括重型坦克、重型战车2种类型；
敌方算子随机放置在待侦察区域内，算子数量随机生成，最大数量为3；
敌方算子无法移动，但具备打击能力。

奖励计算

单局得分包括侦察得分和任务完成得分两部分。假设任务$m$的侦察得分为$r_{m,1}$、任务完成得分为$r_{m,2}$，则单局得分为：

$$ r_m = r_{m,1} + r_{m,2} $$

在任务$m$中，假设存在$K$个敌方算子，任务时间限制为$T$，每个敌方算子的价值分别为$v_1, v_2, ..., v_K$，每个敌方算子被发现时的时间消耗分别为$t_1, t_2, ..., t_K$则侦察得分为：

$$ r_{m,1} = \sum_k^K \mathbb{I}_kV_k\times(1-\frac{t_k}{T}) $$

其中$\mathbb{I}_k$是指示函数，当第$k$个敌方算子被发现后为1，否则为0。

任务完成得分是对发现全部敌方算子的奖励。在任务$m$中，假设存在$K$个敌方算子，任务时间限制为$T$，被发现的敌方算子的个数为$C$,任务总耗时为$t$,为则任务完成得分为：

$$ r_{m,2} = \begin{cases} & 10+10 \times(1-\frac{t}{T}), &C = K \\ & 0, &C < K \end{cases} $$

“一夫当关”赛道

任务设定

任务目标：控制多个算子，守卫尽可能多的要点，抵御敌方的激烈争夺；
任务开始时间：兵棋推演开始，任务启动；
任务终止时间：推演1000步；
任务结束条件：到达任务终止时间或己方全部算子（不包括工事）被消灭且己方没有控制任何夺控点。

环境设定

为支持强化学习模型训练，环境可以随机生成任务并提供奖励反馈；
守卫要点数量为3个，要点位置随机生成，要点之间距离范围为3-7格；
我方非工事算子数量为3个，包括重型坦克、步兵、重型战车3种算子；工事算子数量与步兵算子数量相同，包括人员隐蔽工事、人员战斗工事；
我方步兵算子数量范围为1-2个，重型坦克算子数量≤2个；
我方非工事算子和人员战斗工事算子均随机部署在距要点1格的区域内，人员隐蔽工事随机部署在距要点2格的区域内；
我方非工事算子初始血量（班数）均为2；
任务过程中，我方算子可以采取任意环境条件允许的动作，包括移动、射击、夺控、进出工事、解聚、聚合等；
敌方算子数量为3-5个，包括重型坦克、步兵、重型战车 3 种算；敌方坦克算子数量范围为2-3个，步兵算子数量≤2个；
敌方重型坦克、重型战车随机部署在距要点8-10格的区域内，敌方步兵算子随机部署在距要点4-6格的区域内；
敌方算子初始血量（班数）均为2；
环境提供敌方AI，封装在 defend_env.py 中，敌方AI共有三种策略：1）在要点之间随机游走；2）优先与我方算子同格交战，择机占领要点；3）优先占要点，择机与我方算子同格交战。

奖励计算

单局得分包括单步得分和任务结束得分两部分。假设任务$m$中，$i$时刻单步得分为$r_i$、任务结束得分为$r_{final_ step}$，则单局得分为：

$$ r_m = \sum_i^{T-1}r_{i} + r_{final_ step} $$

其中，$T$为最大推演时长。

$i$时刻单步得分计算方式如下：

$$ r_i = \sum^{city_num}j \delta{ij} v_j/T $$

其中，$city_num$为要点数，$\delta_{ij}$为指示函数，当我方第$i$时刻占据了第$j$个夺控点为1，否则为0。

任务结束得分计算方式如下：

$$ r_{final_ step} = \sum^{city_num}j \delta{j} v_j $$

其中，$\delta_{j}$为指示函数，当我方在推演结束时占据了第$j$个夺控点为1，否则为0。

代码提交

打包方式

将 ai/ 文件夹打包压缩为 ai.zip 文件，其结构如下所示。

ai.zip
└── ai
    ├── agent.py
    └── ...

注意：ai/ 文件夹中必须包含一个名为 agent.py 的文件，该文件中必须包含一个名为 Agent 的类，参赛团队需提交源代码。

可以尝试使用以下命令。（已安装 zip 的前提下）

zip -r ai.zip ai/ -x "**/__pycache__/*"

提交方式

具体提交测试及排名方式请关注后续赛事通知。

线上运行

智能体代码提交后将在平台上统一调度运行，平台提供的运行条件如下，请在本地开发时注意资源使用量和软件依赖，避免运行异常。

硬件资源

CPU：4 核
内存：4 GB

软件依赖

操作系统：Ubuntu 20.04
解释器：Python 3.10.13
可用依赖：
- gymnasium==0.28.1
- numpy==1.26.2
- pandas==1.5.3
- ray==2.9.0
- scikit-learn==1.0.2
- scipy==1.10.1
- tensorflow==2.11.0
- torch==2.0.1

常见问题

Q: 终端显示 did not pass authentication。

A: 删除已安装的 xz_env_2024 并重新安装。

本项目及相关文档最终解释权归大赛组委会所有。

warai / starter-kit .gitee-modal { width: 500px !important; }

What's New

Install Docker

Clone

Quick Start

VScode DevContainer

VScode Local

CommandLine

Build Image

Run

Update Deps

先知2024兵棋AI选拔赛 Starter Kit

前期准备

安装

克隆本项目

安装依赖

使用

目录结构

基本用法

赛道详情

“穿越火线”赛道

任务设定

环境设定

奖励计算

“协同侦察”赛道

任务设定

环境设定

奖励计算

“一夫当关”赛道

任务设定

环境设定

奖励计算

代码提交

打包方式

提交方式

线上运行

硬件资源

软件依赖

常见问题

简介

发行版

贡献者

近期动态

搜索帮助

warai / starter-kit