1.目的

该手册有助于了解机器人世界杯救援模拟服务器，并帮助有兴趣参加机器人世界杯救援代理模拟比赛的人。

2.安装

本手册假定代理将在 Linux 机器中运行，即使它们可以在 Microsoft Windows 或 Apple macOS 中运行。 我们推荐使用 Linux，因为它是开源的，并且大多数发行版都得到了用户社区的良好支持。 如果您以前从未使用过 Linux 并打算使用，我们建议您从用户友好的发行版开始，例如 Ubuntu or Fedora

2.1 软件要求

• JDK 17
• Git
• Gradle

2.2 下载

您可以通过克隆 https://github.com/roborescue/rcrs-server 存储库来下载带有 ADF 的示例代理。

使用此命令克隆存储库

$ git clone https://github.com/roborescue/rcrs-server.git

2.3 目录

rcrs-server 包含多个目录。 重要的目录是：

• boot: scripts to run the simulation server
  • boot/config/: default configuration files
  • boot/logs/: text log files
  • boot/records/: JSON log files
• build/: compiled Java classes
• docs/: documentation
• jars/: simulator JAR files
• lib/: external libraries
• maps/: maps and scenarios
• modules/: simulator source code
• oldsims/: old simulator source code

2.4 编译

必须在您的机器上编译模拟服务器，以生成运行模拟器所需的 JAR 文件。执行以下步骤来编译模拟服务器。

1. 切换到目录 rcrs-server
2. 使用命令编译项目

$ ./gradlew completeBuild

2.5 示例

在 Ubuntu 中，安装根据以下命令进行：

$ git clone https://github.com/roborescue/rcrs-server.git
$ cd rcrs-server
$ ./gradlew completeBuild

3.运行

模拟服务器有两种执行模式：预计算模式（Precomputation）和正常模式（Normal）。

3.1 预计算模式

在预计算模式下，模拟器连接每种类型的一个代理，并允许它们写入计算结果。

在预计算模式下运行模拟服务器的命令序列是：

$ cd rcrs-server
$ cd boot
$ bash start-precompute.sh

在为预计算运行模拟服务器后，移动到另一个终端窗口上的 ADF 目录并运行执行以下命令：

$ bash launch.sh -t 1,0,1,0,1,0 -h localhost -pre 1 & APID=$! ; sleep 120 ; kill $APID

预计算完成后，按下 Ctrl + C 并键入 bash kill.sh 以停止运行的模拟服务器。

$ bash kill.sh

3.2 正常模式

在正常模式下，模拟器连接场景中定义的所有代理，并允许它们使用预计算输出。

在正常模式下运行模拟服务器的命令序列是：

$ cd rcrs-server
$ cd boot
$ bash start-comprun.sh

运行模拟服务器后，运行代理。一旦模拟完成，服务器将自动停止。

3.3 更多选项参数说明

可通过以下参数运行仿真服务器:

• -m MAPDIR 或 --map MAPDIR, 其中MAPDIR是要运行的地图的目录的路径(默认为 ../maps/gml/test/map）。
• -c CONFIGDIR 或 --config CONFIGDIR, 其中 CONFIGDIR 是包含与 map 相关的配置的目录(默认为../maps/gml/test/config)。
• -l LOGDIR 或--log LOGDIR, 其中LOGDIR是日志文件存放的目录(默认为 ./logs)。

这些参数可用于运行预计算和正常模拟。要在预计算模式和正常模式下运行模拟服务器，必须为MAPDIR和CONFIGDIR使用相同的参数。如何使用这些参数运行仿真服务器的示例如下:

$ bash start-precompute.sh -m ../maps/gml/kobe/map -l logs2
# (预计算完成后)
# Control + C
$ bash kill.sh
$ bash start-comprun.sh -m ../maps/gml/kobe/map -l logs2

4.工具

模拟服务器附带了几个工具来支持新地图和场景的开发以及模拟的重放。

4.1 地图编辑器

打开终端窗口，进入到rcrs-server根目录并执行

$ ./gradlew gmlEditor --args=<map file path>

--args=<map file path> 是可选的。

例如：

$ ./gradlew gmlEditor

$ ./gradlew gmlEditor --args="../maps/gml/test/map"

4.2 场景编辑器

打开终端窗口，进入到rcrs-server根目录并执行

$ ./gradlew scenarioEditor --args=<scenario path>

--args=<scenario path> 是可选的。

例如：

$ ./gradlew scenarioEditor

$ ./gradlew scenarioEditor --args="../maps/gml/test/map"

4.3 随机场景

打开终端窗口，进入到rcrs-server根目录并执行

$ ./gradlew randomScenario --args=<map path>

--args=<map path> 是可选的。

例如：

$ ./gradlew randomScenario

$ ./gradlew randomScenario --args="../maps/gml/test/map -civ 10 100 -fb 1 50 -fs 0 1 -pf 1 50 -po 0 1 -at 1 50 -ac 0 1 -refuge 1 2 -fire 0 1"

4.4 日志查看器

打开终端窗口，进入到rcrs-server根目录并执行

$ ./gradlew logViewer --args='-c config/logviewer.cfg <log path>'

--args='-c config/logviewer.cfg <log path>' 是可选的。<log path> 定义了日志文件路径。 默认的日志文件路径为logs/rescue.log。

4.5 osm2gml

打开终端窗口，进入到rcrs-server根目录并执行

$ ./gradlew osm2gml --args='<osm map path> <gml map path>'

<osm map path> 是 OSM 地图文件的路径。 <gml map path> 是目标 GML 地图路径。

5.模拟器的设计

本节描述模拟器体系结构及其主要特性，以及组成仿真场景的实体。

5.1 架构

RoboCup 救援模拟服务器由下表中列出的几个模拟器组成。

这些模拟器建立连接到内核模拟器，负责协调模拟器的进程和集中他们生成的数据。这些连接在模拟器的体系结构中进行了说明。

RoboCup 救援模拟器旨在创建一个部分可观测的、离散时间的、动态的、随机的、多代理的环境。换句话说，在这种环境下：

• 不能通过单个智能体的感知来了解整个世界的当前状态(即使智能体有无限视野，它仍然无法透过建筑物的墙壁看到东西);
• 时间是按间隔划分的，而不是连续时间;
• 有随机元素影响它的状态转换;
• 有不止一个代理人在场，一个人的行为可能会干扰其他人的表现。

时间被分为时间步(timesteps);在每个时间步中，代理感知环境并判断它将执行什么动作。在每个时间步中，会发生以下事情：

• 内核更新所有代理的感知(视觉和通信)，并等待代理的命令。
• 代理更新它们的世界模型(world model)并做出决定，将它们的命令发送给内核。
• 内核将代理的命令发送给模拟器(simulators)。
• 模拟器处理代理的命令，并将环境所遭受的变化发送回内核(kernel)。
• 内核将环境变化发送给查看器(viewers)。

5.2 实体(Entity)

几个对象在模拟器中表现如下:

5.2.1 障碍物(Blockades)

障碍物阻塞了代理(Agent)和平民(Civilian)的道路;它们在道路上以黑色多边形表示。障碍物出现在模拟的开始，之后不会产生。他们必须由警察部队(Police Forces)清除(Clear)。

构成障碍物实体类的属性如下：

5.2.2 区域(Area)

区域实体代表建筑物和道路。

构成区域实体类的属性如下：

虽然Buildings和Roads都有 blockades 属性，但是 blockades 只在Roads中有效。

5.2.3 建筑物(Buildings)

Buildings 代表模拟器中的各种建筑物。有一些特殊类型的建筑物，如避难所(Refuges)、救护中心(Ambulance Centres)、消防站(Fire Stations)和警察局(Police Offices)，它们不会着火。下方显示了这些特殊建筑的标识图，它们将在本文档的后面部分进行描述。

构成建筑物实体类的属性如下：

1. brokenness: how structurally damaged the building is; does not change during the simulation(建筑物的结构损坏程度;在模拟过程中不会改变)
2. fieryness: the intensity of the fire and fire-related damage in the building(火灾的强度和火灾对建筑物造成的损害,火灾场景不用关心，已去除)

• UNBURNT - not burnt at all
• WATER_DAMAGE - not burnt at all, but has water damage
• HEATING - on fire a bit
• BURNING - on fire a bit more
• INFERNO - on fire a lot
• MINOR_DAMAGE - extinguished but minor damage
• MODERATE_DAMAGE - extinguished but moderate damage
• SEVERE_DAMAGE - extinguished but major damage
• BURNT_OUT - completely burnt out

3. floors: 大楼的楼层数
4. ground area: 每层的面积
5. ignition: 表明模拟器是否点燃了这栋楼(无需关心)
6. importance: unknown function; has equal values to all buildings
7. temperature: 建筑物温度;如果它达到阈值，大楼就会着火(无需关心)
8. total area: the total area of the building (floors x ground area)

常规建筑根据其状态用不同颜色的多边形表示，见下图;颜色越深，结构火灾或水损坏越大。

在模拟开始时，破碎的建筑物将在其内部的人类困在废墟下;这些碎片必须由警察部队(Police Force) 进行清除(Clear)，然后由消防队(Fire Brigade) 进行救援(Rescue)，最后由救护队(Ambulance Team) 运送(Load/Unload) 至避难所(Refuge)。

避难所是一种特殊的建筑：它代表着一个被指定为支持救援活动的地方，为伤员提供医疗护理，为消防队提供水。在模拟器中，避难所内的人类的 damage 属性为 0，这意味着他们在那里不会失去 HP;然而，当人类实体离开避难所时，若 damage 不为零，HP 将继续降低。

此外，当消防队在避难所内时，他们的供水在每个周期内都会得到一定数量的补充。(然而由于没有火灾，所以关于水的一切也并无意义，无需关心)

5.2.4 道路(Roads)

除了Area实体的属性外，表示道路的Area实体没有新的属性。

5.2.5 人类(Humans)

这些是代表人类的实体。在模拟器中，他们可以是平民(Civilian)，救护队(Ambulance Teams)，消防队(Fire Brigades)，或警察部队(Police Forces)。他们都用不同颜色的圆圈来代表，如果他们死了或被埋葬了，他们就不能自己移动。

构成人类实体类的属性如下：

模拟器中每个人的颜色由其类型和健康状况决定：健康状况越低，颜色越深。死亡的人用黑色表示。

5.2.6 平民(Civilians)

平民是人类实体，他们不是救援队的一部分;它们用绿色来表示。如果他们没有受伤或被埋，他们的标准行为是移动到最近的避难所;否则，他们必须由*救护队(Ambulance Team)*运送。

5.3 代理(Agent)

这些实体将组成你的救援队;换句话说，这就是您将要编程的内容。代理(Agent)分为两种类型:排级代理(Platoon Agents)和中心代理(Centre Agents)。

5.3.1 排级代理(Platoon agents)

排代理能够通过感知(perception)和执行动作(executing actions)与模拟环境进行交互。它们还可以通过声音或无线电通信与其他代理交换信息。他们由三个不同类别组成:救护队(Ambulance Team)、消防队(Fire Brigade)和警察部队(Police Force)。

5.3.2 中心智能体(Centre Agents)

中心智能体是一种仅通过无线电通信与外界互动的智能体。中央代理有三种类型:救护中心(Ambulance Centres)、消防局(Fire Stations)和警局(Police Offices)，并以建筑物表示。

5.4 感知(Perception)与命令(Commands)

该模拟器具有两种感知模式:标准感知模式和视线感知模式。

视线感知用来模拟代理的视觉感知:定义了一个视觉范围和一些光线，代理感知这些光线到达的任何事物。

代理当前可见实体的集合存储在名为ChangeSet的结构中;集合中的实体会在它的世界模型中自动更新;也就是说，如果一个智能体(agent)感知(perceive)到一个它以前不知道的障碍物(blockade)，这个障碍物就会自动添加到它的世界模型(world model)中。然而，相反的情况却不会发生：如果智能体不再感知到障碍物，即使它知道在之前那里有障碍物，它的世界模型也不会改变。在这种情况下，agent 仍然会认为那条路上有一个障碍物，即使这个障碍物已经被清除。因此，这需要智能体来弄清楚此处是否存在障碍物并相应地修改它的世界模型。

5.5 通讯(Communication)

在模拟器中有两种可用的通信形式：直接通信(Direct communication)和无线电通信(Radio communication)。

使用speak命令完成的直接通信是在发射器代理(emitter agent)半径范围内的人类(humans)可以听到的(audible)通信，就好像发射器发出了什么。

无线电通信是通过命令tell完成的，它将信息传输(transmit)到所有已注册(signed up)到当前无线电所属广播(broadcast)频道(channel)的代理。无线电通信频道的数量有限，每个信道的带宽也有限。

在这两种通信类型中，消息在发送之前都必须被编码成一串字节;接受者一旦接收到信息就必须解码。这两种类型都可能容易受到到消息丢失(message drop out)的影响，即消息未被其目标接收;无线电通信也容易受到消息失败(message failure)的影响，即接收到的消息是空的。