README

About

Framework to build bots for PiwPew

Installation

npm install piwpew-bot

Usage

Use the piwpew-bot tool to run a bot writen with this framework. It works for bots written both in JavaScript or TypeScript.

$ piwpew-bot -h
Options:
  --help        Show help                                              [boolean]
  --version     Show version number                                    [boolean]
  -i, --id      Bot id                                       [string] [required]
  -m, --module  Module implementing the BotAPI               [string] [required]
  -r, --replay  Log file to be replayed                                 [string]
  -s, --server  Address of the game engine
                                     [string] [default: "wss://game.piwpew.com"]

For example:

npx piwpew-bot -i my-amazing-bot -m ./handler.ts

The framework will write a log file with all the messages sent and received by the bot. The log file will be named <bot-id>-messages.log.

About the game

Piwpew is a game where bots, coded by you and others, fight against each other. The game dynamics are quite simple:

Your bot registers in the game. This is automatically done for you by the framework.
The game engine notifies the bot when the game starts.
Your bot sends requests to the game engine. Requests can be: move forward, move backward, shoot, etc.
The game engine takes all the requests received from the different players in one tick, evaluates the requests with the current game state and sends the appropiate responses and notifications.
Your bot receives responses and notifications and decides what to do next.

Steps 1 and 2 happen only once per game. 3, 4 and 5 repeat until the game ends or your bot is destroyed.

Game protocol

Following is a summary of the game protocol, check out the piwpew-docs for a reference documentation about requests and notifications.

Bots interact with the game engine by sending requests. The game engine validates the requests, executes them and updates its internal state. If the request was successful the response includes data that describes how the bot state changed as a consequence of it. Responses are sent at the end of each game tick.

Bots can only have one in-flight request per game tick. That is, they shouldn't send a request before receiving the notification that signals a new tick, as later requests will overwrite previous ones.

The game engine sends notifications to bots in response to game events that happen asynchronously to requests.

Writing a bot

To write a bot all you have to do is implement the parts you want from the following interface and export it with the name bot in the module that is passed to piwpew-bot. The methods in the interface map to the request's responses and notifications sent by the game engine. You can find example implementations in the examples/ folder.

interface BotAPI<S> {
  initState?: () => S

  handlers: {
    radarScanNotification?: (
      data: RadarScanNotification,
      state: S
    ) => { state: S }

    registerPlayerResponse?: (
      data: SuccessfulRegisterPlayerResponse | FailedRegisterPlayerResponse,
      state: S
    ) => { state: S }

    rotatePlayerResponse?: (
      data: SuccessfulRotatePlayerResponse | FailedRotatePlayerResponse,
      state: S
    ) => { state: S }

    movePlayerResponse?: (
      data: SuccessfulMovePlayerResponse | FailedMovePlayerResponse,
      state: S
    ) => { state: S }

    shootResponse?: (
      data: SuccessfulShootResponse | FailedShootResponse,
      state: S
    ) => { state: S }

    deployMineResponse?: (
      data: SuccessfulDeployMineResponse | FailedDeployMineResponse,
      state: S
    ) => { state: S }

    hitNotification?: (
      data: PlayerHitNotification,
      state: S
    ) => { state: S }

    tickNotification?: (
      state: S,
      context: { inFlightRequest?: Request }
    ) => { state: S, request?: Request }

    startGameNotification?: (
      state: S
    ) => { state: S }

    joinGameNotification?: (
      data: JoinGameNotification,
      state: S
    ) => { state: S }
  }
}

For a list of all the types mentioned in this interface check: types and requests. The npm package exports the required type definitions to build a bot in TypeScript.

Notice that you can only return a request to be sent to the server from the tickNotification handler.

Helpers

The library includes some helpers that can facilitate writing a bot. These helpers are:

declare function radiansToDegrees (radians: number): number

radiansToDegrees converts a angle in radians to its value in degrees

declare function calculateAngleBetweenPoints (pointA: Position, pointB: Position): number

calculateAngleBetweenPoints calculates the angle between two points. The returned value is an angle in degrees.

declare function calculateDistanceBetweenTwoPoints (pointA: Position, pointB: Position): number

calculateDistanceBetweenTwoPoints return the distance between two points in the arena.

The helpers can be imported directly from the library. For example:

import { calculateAngleBetweenPoints } from 'piwpew-bot'

Bot registration

You don't have to take care of registering the bot in the game, the library will take care of doing that for you.

Bot state

Each handler method takes as an argument the bot state that you can use to keep information between handler invocations. Each handler method must return the new state that will be passed in as an argument to the next handler invocation. You can init the state before receiving any message from the game engine by implementing the initState method. The default bot state is an empty object {}.

Logs playback

If you want to you can replay the logs by running bin/bot with the -r flag. When replaying the logs, you can pause the playback (for example because you want to set a breakpoint) by adding a line with the text [break] in the log file being replayed with -r.

License

MIT

Usage no npm install needed!