@acmucsd/hide-and-seek-ai 中文文档教程

Question

Hide and Seek AI Competition ????

欢迎来到捉迷藏 AI 竞赛！ 这是 ACM AI 的第一个竞赛原型，所以会出现许多错误，但也会很有趣！ 在 5 月 26 日至 7 月 6 日晚上 11:59 的比赛期间，您可以参加比赛并提交任意数量的机器人。 现在是什么游戏？

这就像捉迷藏和标签。 您的 AI 需要能够同时扮演寻找者和隐藏者的角色。 作为搜寻者，您的 AI 的目标是找到隐藏者并标记它们。 您的 AI 作为躲藏者的目标是躲避搜寻者并躲避他们，直到游戏结束。

阅读规范，了解有关比赛运作方式的具体信息。 您可以自己竞争或与他人合作并提交一个机器人。 此外，我们正在执行一套规则，我们要求每个参赛者都遵守。

继续阅读以了解如何快速入门并在 https://ai.acmucsd.com/ 上与您的机器人竞争。 请记住，您不需要任何机器学习就能获胜（但如果您愿意，可以这样做）

一旦您拥有了机器人，请务必前往 https://ai.acmucsd.com/ 注册一个帐户并上传您的机器人在那里！ 您可以上传任意多次，看看它对其他机器人的表现如何！ 请务必按照上传说明进行操作，并查看this 以获取有关如何正确压缩文件和上传文件的帮助。 我们将在截止日期 6 月 23 日晚上 11:59 之后通过运行大量比赛来计算最终排名。

如果您在编写机器人、上传机器人、引擎错误方面遇到问题，请随时向此存储库提交问题或在 discord 上的#competitions 频道中联系我们，我们会尽快与他们联系。 这里还有一个常见问题解答部分，用于一些常见错误。

注意，Windows 不受支持，您必须使用 WSL，有关 WSL 的安装说明转到此处（谢谢 Aaron）

Getting Started

首先确保您正在运行 Node v12 或更高版本并安装了 npm。 通过运行 node -v 和 npm -v 检查这一点。 如果您没有它们，请参阅本节以设置您的环境以开始运行捉迷藏游戏。

首先安装所有必要的文件，运行以下

npm install dimensions-ai
sudo npm install -g @acmucsd/hide-and-seek-ai

命令 现在，您可以使用 hide-and-seek 命令，它可用于观看比赛和运行比赛。

从此存储库的 kits 文件夹中下载您选择的初学者工具包，或单击以下按钮下载不同语言的工具包。 C++，Javascript, [Java]( https://storage.cloud.google.com/hideandseek_olbptg/kits/javastarter.zip），Python

我们将使用 JS 套件作为示例。 假设在同一个文件夹中有一个 kits 文件夹，目录 ./kits/js/bot.js 中有 js 机器人。 bot.js 文件是一个主文件，每个机器人都需要在机器人的根目录中。 要运行匹配，请运行以下命令

hide-and-seek ./kits/js/bot.js ./kits/js/bot.js --live=true

这将在您的终端中实时运行匹配。 设置 --live=false 使匹配跳过实时视图并尽可能快地运行。 此外，确保您拥有运行机器人的正确工具。 例如，如果您有一个 java 机器人，请确保 javac 可以正常工作。 请参阅this 了解每种机器人语言需要哪些工具以及如何匹配服务器的信息。

Matches 将在 replays 文件夹中创建一个格式为 match_.json 的 replay 文件。 要观看回放，请运行

hide-and-seek -w ./replays/match_<some long id>.json --delay=0.2

Set --delay 等于任意秒数，代表比赛每一帧之间的延迟。 0.2 例如表示 1/0.2 = 5 FPS。

运行

hide-and-seek --help

以获得完整的选项列表。

现在您已准备好开始开发您的机器人！ 阅读入门工具包中提供的注释，了解有关哪些数据可用以及如何开始开发机器人的信息。 您还可以查看通用 API。 此外，确保永远不要打印到标准输出（除了你的命令）。 为了帮助调试，改为打印到标准错误。

如果您想通过 JS/TS API 运行和观看比赛，请参阅 this

Specs

这是一个捉迷藏（和标记）游戏。

这是一个两人代理人/玩家游戏，一名玩家将成为 Seeker 队，另一名将成为 Hider 队。 AI 将在尺寸从 16x16 到 24x24（不一定是正方形）的二维地图上播放。 地图由空地块（0s）和墙地块（1s）组成，其他数字代表该地块上的单位ID。

Seekers 和 Hiders 都被称为 Units，它们只能做两件事，向北、东北、东……西、西南方向移动一个单位，或者留在原地什么都不做。 如果躲藏者与寻找者相邻，隐藏者将被视为已被寻找者标记，现在将从游戏中移除。 在每一轮中，AI 可以发送命令来移动他们的搜索者（如果他们是搜索者团队）或将他们的隐藏者（如果他们是隐藏者团队）移动到一个方向并且只能移动一次。 （如果您尝试多次移动一个单元，您将收到警告）。 我们基于按单元 ID 排序的轮流队列运行命令。

当达到最大回合限制 200 或地图上没有更多躲藏者时，游戏结束。 如果地图上没有更多的藏身者，则探索者获胜。 如果达到回合限制并且他们仍然有未标记的躲藏者，则隐藏者获胜。 就这么简单。

该游戏还为所有玩家使用战争迷雾。 两支队伍都会得到地图布局，其中包括空白和墙砖、他们自己的单位，以及他们的单位所在的位置。 但是，如果您的至少一个单位可以看到对方球队的单位，您只会得到对方球队单位的 x、y 坐标。

单位视野最远可达 48R^2。 R^2 是欧几里德距离但平方。 此外，地图上的墙壁会阻挡单位的视线，单位无法看到墙后的情况。 这里有一些简短的例子来证明这一点

。绿色圆圈标记了单元#4 的视野范围。 红色数字是隐藏者，蓝色数字是寻找者。 与绿色圆圈相交并在其中的所有内容都在 48R^2，即单元 #4 的视野范围内

黄色方块是墙壁。 由于墙壁，单元#4 的视线被阻挡，我们用红圈标记单元看不到的地砖。 例如，紫色线表示视线与黄色墙壁相交，因此无法看到其中一块瓷砖。 视线是从瓷砖中心到目标瓷砖中心的线，如果这条线与作为墙的方形瓷砖相交，则视线被阻挡。

此外，比赛引擎还会将每个单位与最近的对手单位的 R^2 距离发送给每个单位，这些数据可以帮助您捉迷藏！

请务必阅读入门工具包主要文件（例​​如 bot.js bot.cpp 等）中的注释，以了解有关可用变量及其含义的信息。 您还可以查看此部分，了解有关机器人 API 的文档。

Submission

比赛只接受最大 200mb 的 zip 文件。 确保遵循 kits 中提供的初学者工具包结构/a> 这个存储库的文件夹。 确保递归压缩你的机器人。 根据您的系统，阅读有关如何提交机器人的帮助说明

Linux / MacOSx

在 Mac 上，只需选择与您的 bot.js 文件位于同一文件夹中的所有文件，然后右键单击并单击压缩并提交。 对于提交表单上的 Bot Path 字段，确保将 bot.js 作为输入。 如果您的主文件名为其他名称，请将其放在表单的两个路径字段中。

要在命令行上压缩，请导航到包含主文件 bot.js 或您为其设置的任何名称的文件夹/目录，然后运行以下

zip -r bot.zip .

命令提交 bot.zip 文件并传入 bot.js 或您的主文件在表单的 Bot Path 字段中的名称。

Windows

选择包含主文件（例如 bot.js）的文件夹中的所有文件和文件夹，右键单击，然后单击压缩。 提交并传入您的主文件名，例如 bot.js 作为提交表单上的 Bot Path 字段。

How do we run your bots?

对于 JS，我们运行 NodeJS v12，并调用 node.js

对于 Python，我们运行 Python 3.5.3，并调用 python.py

对于 Java，我们使用的是 OpenJDK 11.0.7，我们正在通过调用 javac.java 并运行 java 来编译您的代码

对于 C++ ，我们通过调用 g++ -std=c++11 -O3 -o.out 用 g++ 编译你的代码并运行 ./.out

Computation Limits

每个机器人的计算时间最多为 1000 毫秒，与语言无关。 （即便如此，与 C 语言相比，您可能可以用 Python 编写一个非常好的机器人）。 这个时间是在我们的谷歌云计算引擎实例（4 cpu，4 GB RAM）上运行时计算的。

此外，每个机器人的 RAM 限制为 100MB。 这通常应该是足够的内存。 我们将根据需要扩展它。

Rules

1. 我们互相尊重。 ACM 是一个包罗万象的社区。 我们接受并欢迎各种背景和技能水平的人。 严格禁止骚扰、仇恨言论和辱骂，否则将立即被禁止参加比赛。

2. 任何黑客攻击，虽然鼓励寻求，但不得实际执行。 我们要求您演示它是可能的，但不要实际执行上述 hack，您将演示和代码发送到 ai@acmucsd.org 给我们。 此外，您不得提交对比赛进行黑客攻击的机器人，我们不容忍恶意活动。 这包括但不限于关闭我们的服务器、删除我们的文件、阅读其他竞争对手的代码等。

3. 在本文档和网站 ai 中说明的比赛结束之前，您不得开源您的机器人代码.acmucsd.com。 您可以与其他竞争对手谈论它，但我们要求您不要分享它的竞争完整性。

4. 玩得开心！

Languages

我们支持 Javascript、Python、C++ 和 Java。 如果您想要另一种语言并且有足够的需求，请在此处提交问题，我们将添加它。

Bot API

因为可能有多种语言，您需要阅读入门工具包中的文档以了解 api 的确切语法。

agent.round_number 是当前轮数。

agent.map 是一个二维动态数组。 agent.map[y][x] 是坐标(x, y) 处的值。 它可以有以下值

• 0: Represents an empty tile a unit can move on
• 1: Represents a wall tile a unit cannot move on or see past
• Other: Represents an ID of a unit, which can be your own team's unit ids or the other team's (if in vision)

agent.units 和 agent.opposingUnits 是 Unit 类的动态数组。 数组中的每个元素都是 Unit 类型。 agent.units 包含您团队中的单位，agent.opposingUnits 包含其他团队中视野中的所有单位。

Unit 是代表比赛中的 Unit 的类。

• Unit.id is the id of the unit
• Unit.x is the x coordinate of the unit's position
• Unit.y is the y coordinate of the unit's position
• Unit.distance is the distance away the unit is from the nearest opposing unit. This is always -1 if you don't own this unit

applyDirection 或 apply_direction 将方向应用于坐标 x, y。 例如，applyDirection(0, 1, Direction.NORTH) 返回 [0, 0]，因为向北移动会导致 y 减 1。

Setup

请参阅此：https://nodejs.org/en/download/

Javascript API

如果您更喜欢编写代码来运行比赛（和锦标赛）而不是命令行方法，请继续阅读！

Running a Match

创建一个名为 run.js 的文件并添加以下内容

const HideAndSeekDesign = require('@acmucsd/hide-and-seek-ai').default;
const Dimension = require('dimensions-ai');
let hideandseekdesign = new HideAndSeekDesign('hide-and-seek');
let hideandseek = Dimension.create(hideandseekdesign, {
  activateStation: false,
  observe: false,
  name: "Hide and Seek",
  defaultMatchConfigs: {
    agentOptions: {
      runCommands: {'.py': ['python3']}
    }
  }
});

这将初始化一个 Dimension，您可以通过它自己运行比赛（和锦标赛）。

要运行比赛，您首先需要一些 AI 来运行它。 现在，我们将只使用 kits/js/bot.js 中的入门工具包机器人

添加以下代码

hideandseek.runMatch(['./kits/js/bot.js', './kits/js/bot.js'], {
  delay: 0.2,
  liveView: true,
  seed: 123
}).then((res) => {
  console.log(res);
});

将 liveView 设置为 true 作为与 false 相反，比赛将在您的终端上直播，您可以观看。 将其设置为 false，它会运行得更快，但您必须通过重播文件观看它

delay: 0.2 将实时查看器的速度设置为每帧 0.2 秒(1/0.2 = 5 FPS)

seed: 123 设置匹配种子。 删除此字段将使种子随机。

Watch Replays

默认情况下，回放以 .json 文件的形式存储在 replays/ 文件夹中。 要观看回放，请运行以下

HideAndSeekDesign.watch('./replays/your_replay_file.json', 0.2);

命令 这将以每帧 0.2 秒（5 FPS）的速度运行之前在终端中显示的 liveViewer

Known Quirks/Issues

已知 Java 有点不稳定，有时它可能无法与匹配引擎正确并超时。 但是，这种情况很少见（在服务器上每 10,000 个匹配项中就有一次）

FAQ

如果您无法安装某些东西，请尝试 sudo npm install。

如果在提供运行匹配的路径时提示代理目录错误，请尝试在路径前加上 ./。 修复了您传入类似 bot.py 或 bot.js 的错误，因此您应该运行 hide-and-seek ./bot.py ./bot .js。