misskey/src/docs/en-US/reversi-bot.md

Development of Misskey Reversi Bots

This page will explain how to develop an interactive bot for Misskey's Reversi function.

1. Connect to the games/reversi stream with the following parameters:

   • i: API key of the bot account

2. When an invitation to a game arrives, an invited event is emitted from the stream.

   • Information about the user who sent the invitation is included in the event as parent.

3. Send a request to games/reversi/match including the id of the parent as user_id

4. If the request suceeds, information about the game will be returned. Then, send a request to the games/reversi-game stream with the following parameters:

   • i: API key of the bot account
   • game: The id of the game

5. In the meanwhile, the opponent can modify the game's settings. Each time this happens, a update-settings event is emitted, so implement logic to handle these events if necessary.

6. Once satisfied with the settings, send a { type: 'accept' } message to the stream.

7. When the game starts, a started event is emitted.

   • Information about the game's state is included in this event

8. To place a stone, send { type: 'set', pos: <Position> } to the stream (how to calculate positions will be explained later).

9. When the opponent or you place a stone, the set event is emitted.

   • Contains the color of the placed stone as color
   • Contains the position the stone was placed at as pos

Calculating positions

In the case of an 8x8 map, the squares on the board are arranged like this (squares are marked with their respective index):

+--+--+--+--+--+--+--+--+
| 0| 1| 2| 3| 4| 5| 6| 7|
+--+--+--+--+--+--+--+--+
| 8| 9|10|11|12|13|14|15|
+--+--+--+--+--+--+--+--+
|16|17|18|19|20|21|22|23|
...

Find indices from X, Y coordinates

pos = x + (y * mapWidth)

mapWidth can be acquired from the map information as follows:

mapWidth = map[0].length

Find X, Y coordinates from indices

x = pos % mapWidth
y = Math.floor(pos / mapWidth)

Map information

Map data is included within map of the game data. As the data is represented as an array of strings, each character represents a piece. Based on this data, you can reconstruct the map state:

• (Space) ... No piece
• - ... Piece
• b ... Piece placed first was black
• w ... Piece placed first was white

For example, suppose a situation with the following 4*4 board:

+---+---+---+---+
|   |   |   |   |
+---+---+---+---+
|   | ○ | ● |   |
+---+---+---+---+
|   | ● | ○ |   |
+---+---+---+---+
|   |   |   |   |
+---+---+---+---+

In this case, the map data look like this:

['----', '-wb-', '-bw-', '----']

Creating an interactive bot showing a form to the user

To communicate with the user, you can show them a form in the settings screen. For example, to let the user select the strength of the Bot.

To display a form, send the following message to the reversi-game stream:

{
  type: 'init-form',
  body: [Array of form control fields]
}

From here on, the structure of form control elements will be explained. Form controls are objects arranged as follows:

{
  id: 'switch1',
  type: 'switch',
  label: 'Enable hoge',
  value: false
}

id ... The ID of the control element. type ... The type of the control element.Explained later. label ... Text displayed alongside the control element. value ... Default value of the control element.

Handling form interactions

When the user interacts with the form, an update-form event is emitted. Included in this event is the control element's ID as well as the value of the setting the user changed. For example, if the user flipped the switch from above to on, the following event would be emitted:

{
  id: 'switch1',
  value: true
}

Types of form control elements

Switch

type: switch Shows a slider.These can be helpful for functions that can be turned either on or off.

Properties

label ... The text written on the switch.

Radio button

type: radio Shows a radio button.These can be useful for choices.For example to choose the strength of the Bot.

Properties

items ... The options of the radio button.E.g.:

items: [{
  label: 'Weak',
  value: 1
}, {
  label: 'Moderate',
  value: 2
}, {
  label: 'Strong',
  value: 3
}]

Slider

type: slider Shows a slider.

Properties

min ... The minimum value of the slider. max ... The maximum value of the slider. step ... The step between each value on the slider.

Textbox

type: textbox Shows a textbox.These can be used for all general purposes which require user input.

Showing a message to a user

This is another way to interact with the user from the settings screen, separate from showing them a form.It's possible to display a message to the user. For example, when the user selects a map that the bot does not support, a warning can be displayed. To display a message, send the following message to the stream:

{
  type: 'message',
  body: {
    text: 'Message contents',
    type: 'Message type'
  }
}

Message types: success, info, warning, error。

Give up

To give up, send a request to this endpoint.