jormungandr-bite/src/docs/de-DE/reversi-bot.md

Entwicklung eines Misskey Reversi-Bots

Auf dieser Seite wird die Entwicklung eines Bots für Misskey Reversi erläutert.

1. Verbinde dich unter Verwendung folgender Parameter mit dem games/reversi-Stream:

   • i: API-Schlüssel des Bot-Kontos

2. Sobald den Bot eine Spieleinladung erreicht, wird das invited-Event vom Stream gesendet

   • Der Inhalt dieses Events ist ein parent-Attribut, was Daten über den Benutzer, der die Einladung verschickt hat, beinhaltet

3. Sende eine Anfrage an games/reversi/match, wobei der Wert des user_id-Parameters das id-Attribut des vorher erhaltenen parent-Objekts ist

4. Gelingt die Anfrage, werden die Spieldaten als Rückgabewert geliefert. Nutze diese dann, um die unten gelisteten Parameter an den games/reversi-game-Stream zu senden:

   • i: API-Schlüssel des Bot-Kontos
   • game: id-Attribut des game-Objekts

5. Währenddessen kann der Spielgegner die Spieleinstellungen verändern. Jedes mal, wenn eine Einstellung verändert wird, sendet der Stream ein update-settings-Event, weswegen möglicherweise Logik, um solche Events verarbeiten zu können, notwendig ist.

6. Sobald du mit den Spieleinstellungen zufrieden bist, sende die Nachricht { type: 'accept' } an den Stream

7. Sobald das Spiel startet, wird das started-Event gesendet

   • Der Inhalt dieses Events sind die Spieldaten

8. Um einen Stein zu setzen, sende die folgende Nachricht an den Stream: { type: 'set', pos: <Position> } (Positionsberechnungen werden später erläutert)

9. Setzt der Gegner oder du einen Stein, wird das set-Event vom Stream gesendet

   • Die Farbe der Spielfigur ist als color enthalten
   • Die Position der Spielfigur ist als pos enthalten

Positionsberechnungen

Im Falle eines 8x8 Spielbrettes sind die Felder wie folgt aufgestellt (jeweils mit ihrem Index versehen):

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

Berechnung von Indizes durch X und Y Koordinaten

pos = x + (y * mapWidth)

Bei mapWidth handelt es sich um wie folgt aus map entnommene Spielbrettdaten:

mapWidth = map[0].length

Berechnung der X und Y Koordinaten durch Indizes

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

Spielbrettdaten

Die Spielbrettdaten sind innerhalb vom in den Spieldaten enthaltenen map-Attribut gespeichert. Da das Spielbrett als Array von Zeichenketten representiert wird, steht jedes Symbol für ein Spielfeld. Basierend auf diesen Informationen lässt sich der Spielbrettzustand rekonstruieren.

• (Leer) ... Kein Spielfeld
• - ... Spielfeld
• b ... Spielfeld auf dem zuerst platzierter Stein schwarz war
• w ... Spielfeld auf dem zuerst platzierter Stein weiß war

Sei folgendes simple 4*4 Spielbrett als Beispiel gegeben:

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

In diesem Fall sehen die Spielbrettdaten wie folgt aus:

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

Erstellen eines Bots, der mit dem Benutzer durch das Zeigen von Fenstern kommunizieren kann

Das Kommunizieren mit dem Spieler kann durch das Anzeigen von Fenstern während der Vorbereitungsphase des Spiels umgesetz werden. Beispielsweise kann so die Schwierigkeit des Bots durch den Benutzer konfiguriert werden.

Um ein Fenster anzuzeigen, sende folgende Nachricht an den reversi-game-Stream:

{
  type: 'init-form',
  body: [Array an Fenster-Elementen]
}

Details bezüglich des Arrays an Fenster-Elementen werden nun erklärt. Ein Element eines Fensters ist wie das folgende Objekt aufgebaut:

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

id ... Die ID des Elements. type ... Der Typ des Elements.Diese werden später erläutert. label ... Text der zusammen mit dem Element angezeigt wird. value ... Standardwert des Elements.

Verarbeitung von Interaktionen mit Elementen

Interagiert der Benutzer mit einem der Elemente eines Fensters, so wird ein update-form-Element vom Stream gesendet. Die Inhalte dieses Events sind die ID des Elements sowie der Wert des Elements, der vom Benutzer eingestellt wurde. Wird beispielsweise der obige Beispielschalter eingeschaltet, wird das folgende Event gesendet:

{
  id: 'switch1',
  value: true
}

Arten von Form-Elementen

Schalter

type: switch Zeigt einen Schalter an.Eignet sich für Fälle, in denen etwas entweder ein- oder ausgeschaltet werden kann.

Attribute

label ... Auf dem Schalter anzuzeigender Text.

Optionsfeld

type: radio Zeigt ein Optionsfeld an.Eignet sich für Fälle, in denen verschiedene Optionen angezeigt werden.z.B. zur Einstellung der Stärke des Bots.

Attribute

items ... Die verfügbaren Optionen.z.B.:

items: [{
  label: 'Schwach',
  value: 1
}, {
  label: 'Mittelmäßíg',
  value: 2
}, {
  label: 'Stark',
  value: 3
}]

Schieberegler

type: slider Zeigt einen Schieberegler an.

Attribute

min ... Der minimale Reglerwert. max ... Der maximale Reglerwert. step ... Der Abstand zwischen zwei Stufen des Reglers.

Textbox

type: textbox Zeigt eine Textbox an.Für verschiedene Fälle, in denen Texteingabe des Benutzers gefragt sind, verwendbar.

Dem Benutzer Nachrichten zeigen

Dies ist eine alternative Methode, um mit dem Benutzer zu kommunieren, abgesehen vom Anzeigen eines Fensters während der Vorbereitungsphase des Spiels.Hierdurch kann dem Benutzer eine Nachricht angezeigt werden. Beispielsweise kann eine Warnung angezeigt werden, falls ein Spielmodus oder eine Spielkarte ausgewählt wird, mit der der Bot nicht kompatibel ist. Um eine Nachricht anzuzeigen, muss folgende Nachricht an den Stream gesendet werden:

{
  type: 'message',
  body: {
    text: 'Nachrichteninhalt',
    type: 'Nachrichtenart'
  }
}

Nachrichtenarten: success, info, warning, error.

Aufgeben

Um aufzugeben, sende eine Anfrage an diesen Endpunkt.