Use a custom external battle bot service

Showdown-ChatBot has the ability to play battles. However, it uses a very basic algorithm, trying to resemble the NPCs in the games.

If you wish your bot to use an external service that handles the decisions for the battles. This service must be an HTTP or HTTPS server, implementing the API specified by following SWagger / OpenAPI 3.0 specification:

• https://github.com/AgustinSRG/Showdown-ChatBot/blob/master/src/bot-modules/battle/battle-bot-service.swagger.yml

You can open this specification with Swagger Editor.

As an example of an implementation, you can check the following repository: https://github.com/AgustinSRG/ps-battle-bot-service-example

Battle bot service

The service must implement a single POST endpoint at the path /battle-bot, which will receive a JSON body containing, for each battle, its identifier, the log to update the battle status, and optionally, 2 flags to perform actions (decide in order to make decisions and clear in order to indicate the battle is finished)

[
  {
    "id": "battle-gen9randombattle-2432959576",
    "log": [
      "|rule|HP Percentage Mod: HP is shown in percentages"
    ],
    "decide": true,
    "clear": false
  }
]

The service must respond with 200 OK, and a JSON body containing, for each battle, its identifier, and, if requested, the decision in the form a command to send to the battle.

[
  {
    "id": "battle-gen9randombattle-2432959576",
    "decision": "/choose move 1"
  }
]

Notice that the service receives and returns arrays. This is because the service is expected to be able to handle multiple battles at once.

Authentication

The service should implement some form of authentication to prevent security issues.

The recommended authentication form is to use an authentication token shared between the service and Showdown-ChatBot, witch will be sent in the standard Authorization HTTP header.

Warning: When comparing an authentication token to check if it is correct, make sure to use hashing functions or time-safe comparing functions in order to prevent timing attacks to the service.

It is also recommended you also prevent access to the service from outside the network, using a firewall, so only Showdown-ChatBot can access the service.

Configuring Showdown-ChatBot

Once your setup the service, you must configure Showdown-ChatBot in order to use it.

Go to the control panel, under the Battle Bot section, External Service sub-section.

Add the URL of the service (without the /battle-bot path, it will be appended to the URL you provided), and the authentication details.

Once you save the changes, new battles will start using the service.

Note: If your service fails or do not provide a decision when asked, Showdown-ChatBot will default to using the internal algorithm, so users will not notice it. However, this failures will be logged to the Security Log.