企鵝搶地 AI instruction

[noracami]

Summary

Backend provides the bots integration, so that anyone can host their bot to play the game.

TODOs

• Register bot
• Look up bots has registered
• Update bot
• Remove bot
• pick event
• kick event
• to_place event
• to_split event
• game_over event

Flow

When the room owner invoke add ai
Server will check how many bots are available, random choose 1 to join the room
The chosen bot service will get the request includes bot_id, player_id

When the bot's turn, the bot will be asked to play the game with current board info

When been kicked, the bot service will get the request includes bot_id, player_id

When the game is over, the bot service will get the latest board info

Requirement

• The bot service should response the request through webhook_url until been kicked or game over.
• The bot maintainer can choose the bot's max concurrent_number.

How to manage bots

0. Get the JWT

POST /api/v1/users
Content-Type: application/json

{
  "name": "your account name",
  "password": "p@$$w0rd"
}

1. Register bot

POST /api/v1/bots
Content-Type: application/json
Authentication: Bearer $token

{
  "name": "used as nickname in game",
  "webhook_url": "the bot service endpoint",
  "concurrent_number": 1
}

2. Look up bots has registered

GET /api/v1/bots
Content-Type: application/json
Authentication: Bearer $token

3. Update bot

PUT /api/v1/bots/{bot_id}
Content-Type: application/json
Authentication: Bearer $token

{
  "name": "used as nickname in game",
  "webhook_url": "the bot service endpoint",
  "concurrent_number": 1
}

4. Remove bot

DELETE /api/v1/bots/{bot_id}
Content-Type: application/json
Authentication: Bearer $token

---

What actions the bot should implement

GET "$webhook_url"

• expect response: 204 or 200 with any body

the game server send requests to bot's webhook_url, with following payload
event_name: pick, kick, to_place, to_split, game_over

POST "$webhook_url"
Content-Type: application/json

{
  "event_name": "event_name",
  "bot_id": 1,
  "game_id": 1,
  "player_id": 1,
  "game_config": {}
  "game_data": {}
}

1. pick: the room owner pick bot to join game, the request body includes:
   1. bot_id: int (check from GET /api/v1/bots)
   2. player_id: int (allow bot can join multiple rooms or same room at the same time)
   3. expect response: 204 or 200 with any body
2. kick: the room owner kick the bot, the request body includes:
   1. bot_id
   2. player_id
   3. expect response: 204 or 200 with any body
3. to_place: given the board, ask the bot to place
   1. bot_id
   2. player_id
   3. game_id: int
   4. game_config: provide the player order
   5. game_data: provide the board information
   6. expect response: 200 with coordinate to place

{ "x": 1, "y": 1 }

4. to_split: given the board, ask the bot to split
   1. bot_id
   2. player_id
   3. game_id: int
   4. game_config: provide the player order
   5. game_data: provide the board information
   6. expect response: 200 with the origin coord. and target coord. (and amount)

{
  "origin_x": 1,
  "origin_y": 1,
  "target_x": 2,
  "target_y": 2,
  "target_amount": 1
}

5. game_over: notify the game is over
   1. bot_id
   2. player_id
   3. game_id: int
   4. game_config
   5. game_data: provide the board information in the end
   6. expect response: 204 or 200 with any body