This article assumes that you are developing in .NET Core and intend to use the NydusNetwork wrapper. I have attempted to front-load the article with general applicable knowledge such that it can provide value to users of other wrappers.

本文假定您在.NET Core中进行开发，并打算使用NydusNetwork包装器。 我尝试将文章的一般适用知识放在首位，以便它可以为其他包装的用户提供价值。

The StarCraft II API includes quite a few messages. They are all wrapped in the message, so that is the only message you will ever send — and the client will respond with message which wraps all the possible responses.

StarCraft II API包含许多消息。 它们都包装在消息中，因此这是您将发送的唯一消息-客户端将以包含所有可能响应的消息进行响应。

The diagram showcase a simply request message flow of an agent. These are the only necessary requests (step can even be omitted in realtime mode) to create a functioning bot — but it is beneficial understand all types;

该图展示了代理程序的简单请求消息流。 这些是创建可运行的bot的唯一必要请求 (甚至可以在实时模式下省略该步骤)，但是了解所有类型都是有益的。

• CreateGame

  创建游戏

  Setup a new game, equivalent to creating a lobby in the regular game. This message can only be sent in the

  设置一个新游戏，等同于在常规游戏中创建大厅。 此消息只能在

  launched state or ended state.

  启动状态或结束状态。

  -

  --

  Disable fog, if off will allow your bot to see everything (no fog of war).

  禁用雾，如果关闭，则您的漫游器可以看到所有内容(没有战争雾)。

  -

  --

  Realtime, tell the client not to wait for StepRequest to advance the game.

  实时，告诉客户端不要等待StepRequest进行游戏。

  -

  --

  PlayerSetup, list of race and ‘type’ (AI or Blizzard AI) of each player.

  PlayerSetup，种族列表和每个玩家的“类型”(AI或暴雪AI)。

  -

  --

  LocalMap, path to game map to play OR

  LocalMap，要玩的游戏地图的路径或

  -

  --

  BattlenetMapName, name of official SC2 map

  BattlenetMapName，官方SC2地图名称

• JoinGame

  加入游戏

  Starts the game you are hosting or joins another host. This message contains your

  开始您正在托管的游戏或加入其他主机。 此消息包含您的

  InterfaceOptions where you tell the client what information your agent needs. What is referred to as raw is a representation of the game state as a list of visible units, tiles, etc. which is easy (for a computer) to interpret. It equates to being able to see the entire map at once — which a human components would never be able to do. The alternative is feature layers — the game state represented through multiple color-coded images that more closely resemble the information available to a human (meant for Machine Learning).

  InterfaceOptions ，您可以在其中告诉客户代理需要的信息。 所谓的“ 原始”是游戏状态的表示形式，它是可见单位，磁贴等的列表，很容易(对于计算机)进行解释。 它等同于能够一次查看整个地图，而人工操作将永远无法做到。 替代方案是要素层 -通过多个颜色编码的图像表示的游戏状态，这些图像更类似于人类可用的信息(意味着机器学习)。

• LeaveGame

  离开游戏

  Empty message that leaves the match.

  离开比赛的空消息。

• QuickSave

  快速保存

  Empty messages that quick saves.

  快速保存的空消息。

• QuickLoad

  快速加载

  Empty messages that loads previous quick save.

  载入先前快速保存的空消息。

• Quit

  退出

  Empty message that closes the client (gracefully). Applies in all states.

  空消息(正常关闭)关闭客户端。 适用于所有州。

• ObserverAction

  观察者动作

  Actions that an observer can apply (non-player).

  观察者可以应用的动作(非玩家)。

• Step

  步

  Ask the client to advance the game simulation with x

  要求客户使用x推进游戏模拟

  steps. The client will per default wait for this message before advancing the game, unless playing in realtime which can be configured in CreateGame.

  脚步。 默认情况下，客户端将在游戏前进之前等待此消息，除非可以在CreateGame中配置的实时游戏。

• Query

  询问

  Request info on pathing, available abilities and building placement.

  索取有关路径，可用功能和建筑物位置的信息。

• SaveReplay

  保存重播

  Save the game as a replay — can be done

  将游戏另存为重播-可以完成

  in-game or in ended state.

  游戏中或处于结束状态。

• ReplayInfo

  重播信息

  Load meta data about replay.

  加载有关重播的元数据。

• AvailableMaps

  可用地图

  Get a list of available maps. This list can be empty if your client has never downloaded the map.

  获取可用地图的列表。 如果您的客户从未下载过地图，则此列表可以为空。

  Download it manually or force it by creating a game using the regular client on the map you want.

  手动下载它或通过使用想要的地图上的常规客户端创建游戏来强制它。

• SaveMap

  保存地图

  Save the map data to a local path.

  将地图数据保存到本地路径。

• MapCommand

  MapCommand

  Manually execute a map trigger.

  手动执行地图触发器。

• Ping

  平

  Well… surprisingly not a true ping message. The client responds with game version, data version, data build version and base build version.

  好吧……令人惊讶的是，这不是真正的ping消息。 客户端以游戏版本，数据版本，数据构建版本和基本构建版本进行响应。

• DebugExecute a list of DebugCommand which allows you to draw on screen or manipulate the game by spawning units, killing units, updating their values etc.

  调试执行DebugCommand的列表，该列表允许您在屏幕上绘画或通过生成单位，杀死单位，更新其值等来操纵游戏。

安装API包装器 (Installing an API wrapper)

Using an API wrapper saves you a lot of hassle — a lot! This section assumes that you are writing in .NET Core and wish to use NydusNetwork as your API wrapper, but you can find many alternatives in other languages here. You can also always write your own from scratch, in which case this guide might prove useful;

使用API​​包装器可以为您节省很多麻烦-很多！ 本部分假定您正在使用.NET Core进行编写，并且希望将NydusNetwork用作API包装器，但是您可以在 此处 找到其他语言的许多替代方法 。 您也可以始终从头开始编写自己的内容，在这种情况下，本指南可能会有用。

NydusNetwork is a StarCraft II API wrapper written in .NET Core that was created as part of the Abathur framework, but has been written as a separate component that can be used independently of Abathur. I recommend cloning SC2Abathur if you intend to opt for the full framework experience — it comes pre-installed there.

NydusNetwork是用.NET Core编写的StarCraft II API包装器，它是作为Abathur框架的一部分创建的，但是被编写为一个独立的组件，可以独立于Abathur使用。 如果您打算选择完整的框架体验，我建议克隆SC2Abathur-它已预先安装在此处。

Alternatively, to proceed without Abathur, simply install it using the nuget package manager and start using it in your custom bot. This is the approach I will assume you chose as Abathur encapsulates NydusNetwork.

另外，要继续使用Abathur，只需使用nuget软件包管理器进行安装，然后在自定义bot中开始使用即可。 我将假设您选择这种方法，因为Abathur封装了NydusNetwork。

Install-Package NydusNetwork

Install NydusNetwork through Package Manager console

通过Package Manager控制台安装NydusNetwork

dotnet add package NydusNetwork

Install NydusNetwork through dotnet CLI

通过dotnet CLI安装NydusNetwork

使用NydusNetwork (Using NydusNetwork)

Importing NydusNetwork.Model gives you access to all message types supported by the official StarCraft II API. The most basic usage of the NydusNetwork is simply using the SendRequest(Request r) to send raw messages to the client.

导入NydusNetwork.Model可让您访问官方StarCraft II API支持的所有消息类型。 NydusNetwork的最基本用法只是使用SendRequest(Request r)将原始消息发送到客户端。

using NydusNetwork;namespace AdequateSource{  class Example  {    void QuitGame(GameClient client)      => client.QuitRequest();  }}

Basically all API wrappers will give you this direct raw interface to the client, but NydusNetwork comes with a few extra features than a thin API wrapper.

基本上，所有API包装器都会为您提供到客户端的直接原始接口，但是NydusNetwork具有比精简API包装器更多的功能。

速记 (Shorthands)

The most basic of these is shorthands for empty request. The API includes quite a few empty request messages, so it allows us to clean up the code a bit.

其中最基本的是空请求的简写。 该API包含许多空的请求消息，因此它使我们可以稍微清理一下代码。

using NydusNetwork;namespace AdequateSource{  class Example  {    void QuitGame(GameClient client)      => client.QuitRequest();  }}

完成游戏初始化 (Complete Game Initialisation)

NydusNetwork also aids in game creation. The initialise method will connect to the client based on the supplied settings — and launch it if an the client application is not running. After connection is confirmed simply called CreateGameRequest() and JoinGameRequest() and you are up and running. Local multiplayer (bot vs bot) is also supported by these methods.

NydusNetwork还有助于创建游戏。 初始化方法将基于提供的设置连接到客户端-如果客户端应用程序未运行，则启动该方法。 确认连接后，只需调用CreateGameRequest()和JoinGameRequest()即可启动并运行。 这些方法也支持本地多人游戏(机器人与机器人)。

using NydusNetwork;using NydusNetwork.API.Protocol;using NydusNetwork.Model;using System.Collections.ObjectModel;namespace AdequateSource{  class Example  {    void Initilize() {      var client = new GameClient(        new GameSettings        {          FolderPath = @"C:\Program Files (x86)\StarCraft II",          ConnectionAddress = "127.0 0.1",          ConnectionServerPort = 8165,          ConnectionClientPort = 8170,          MultiplayerSharedPort = 8175,          InterfaceOptions = new InterfaceOptions {            Raw = true, Score = true          },          Fullscreen = false,          ClientWindowWidth = 1024,          ClientWindowHeight = 768,          GameMap = "Cloud Kingdom LE",          Realtime = false,          DisableFog = false,          ParticipantRace = Race.Random,          Opponents = new Collection<PlayerSetup> {            new PlayerSetup {              Type = PlayerType.Computer,              Race = Race.Random,              Difficulty = Difficulty.VeryEasy            }          }        }      );      client.Initialize(asHost: true);      client.CreateGameRequest();      client.JoinGameRequest();    }  }}

得到回应 (Getting a Response)

Two ways of getting a response from the client are supported. The simplest is TryWait{Type}Request where you block execution flow until the request is received or fails. This method supports optional timeouts.

支持两种从客户端获取响应的方法。 最简单的是TryWait {Type} Request ，您可以在其中阻止执行流，直到接收到请求或该请求失败为止。 此方法支持可选超时。

The second method is by registering a handler that listens to specific response types. The handler will be called each time that type of response is received until you deregister the handler. This is how the TryWait{Type}Request is implemented behind the scene.

第二种方法是注册一个侦听特定响应类型的处理程序。 每当您收到该类型的响应时，都将调用该处理程序，直到您注销该处理程序为止。 这就是在后台实现TryWait {Type} Request的方式。

using NydusNetwork;using NydusNetwork.API.Protocol;using System;namespace AdequateSource{  class Example  {    void Ping(GameClient client) {      if (client.TryWaitPingRequest(out var r, wait: 3000))        Console.WriteLine(r.Ping.GameVersion);    }    void ListenForPing(GameClient client)    {      var action = new Action<Response>(r => {        Console.WriteLine($"Heard ping! {r.Ping.GameVersion}");      });      client.RegisterHandler(Response.ResponseOneofCase.Ping, action);    }  }}

为什么选择处理程序？ (Why Handlers?)

The client is not a neat little rest API that answers when you call it, it is a web socket that answers you when it please. Some requests will not be answered immediately by the client. The StepRequest for example is answered once the client has received it from everyone in the game — which in single-player means immediately, but in multiplayer can be whenever.

客户端不是一个整洁的小休息API，它会在您调用时回答，而是一个Web套接字，它会在您需要时回答您。 客户端将不会立即答复某些请求。 例如，一旦客户端从游戏中的每个人都收到了StepRequest ， 便会对其进行响应-在单人游戏中，这意味着立即开始，但在多人游戏中，则可以随时进行。

This means that requests might not receive responses in the same order. The client does however make sure to handle requests of the same type sequentially so ActionsRequests for example will always be processed in order (the alternative could alternate the game). Note that multiple actions for the same unit will override it’s action.

这意味着请求可能不会以相同的顺序收到响应 。 但是，客户端确实确保按顺序处理相同类型的请求，因此，例如，始终会按顺序处理ActionsRequests (替代方案可能会替代游戏)。 请注意，同一单位的多个操作将覆盖其操作。

Originally published at https://adequatesource.com on August 30, 2020.

最初于 2020年8月30日 在 https://adequatesource.com 上 发布 。