Skip to content
Battlesnake Game Engine
Go HTML JavaScript Other
Branch: master
Clone or download
Latest commit 8943c2c Dec 30, 2019
Type Name Latest commit message Commit time
Failed to load latest commit information.
cmd/engine Require fmt for docker build check. Dec 24, 2019
controller Record snake latency on frame. (#104) Dec 19, 2019
rules Record snake latency on frame. (#104) Dec 19, 2019
version Engine Command and E2E Testing (#19) May 1, 2018
worker Merge pull request #65 from ColDog/prometheus-metrics Dec 13, 2018
.codecov.yml Engine Command and E2E Testing (#19) May 1, 2018
.gitignore Update .gitignore. Nov 30, 2019
.gometalinter.json TW: Remove exclude for err check and add in specific line ignores. May 21, 2018
.goreleaser.yml adjust script path Oct 10, 2018
.travis.yml Create May 12, 2018
LICENSE Create LICENSE Mar 28, 2018
Makefile finish off the pg store (#62) Nov 29, 2018 update to include details about engine dev mode. (#70) Jan 15, 2019 add tests comment Feb 12, 2019
go.mod convert to modules (#2) Dec 24, 2019
go.sum convert to modules (#2) Dec 24, 2019

Battlesnake Engine

Build Status Maintainability Test Coverage

API and game logic for Battlesnake.

NOTE: If you just plan on running the engine by itself, it's recommended to skip to the running a release binary section.

Install and Setup

  1. Install Golang if you haven't already here
  2. Set your GOPATH, here
  3. Add Go's bin folder to your paths. More on that here, or you can use: export PATH="$PATH:$GOPATH/bin"
  4. Git clone the project into $GOPATH/src/ Note, the docs for GOPATH and project directory layouts can be found here.

Running the engine

Build an executable via make install and then run engine server to run a local version of the server.

Better command: make run

Note: if you use the Makefile, you'll want JQ installed, here

Running a game with the CLI

Using Make

  1. Setup a snake-config.json, by default the engine looks in the HOME directory (see make run-game in the Makefile).

    Here's an example:

      "width": 20,
      "height": 20,
      "food": 10,
      "snakes": [
          "name": "Snake 1",
          "url": "http://localhost:8080"
          "name": "Snake 2",
          "url": "http://localhost:3001"
  2. Start the engine (refer above)

  3. Start a game with make run-game Example Output:

    $ make run-game
    go install
    engine-cli run -g "d151fe9d-8c15-4d31-a932-e7b4248d5586"
  4. To replay a game, run: engine replay -g <game id>

Using a release binary

NOTE: This section is recommended if you don't want/need to setup a GO environment.

  1. Download the latest engine release for your architecture to a folder somewhere on your machine
  2. Unpack/unzip the downloaded release. You should have an engine binary, the LICENSE, and the README available in the unpackaged folder
  3. Follow the snake-config.json setup from the previous section
  4. Open a terminal window and run the engine server with ./engine server and keep this tab running for the next few steps
  5. Open another terminal window and navigate to the engine binary folder
  6. Start a game with ./engine create -c ~/.snake-config.json which will yield a JSON response with `{"ID": "some id here"}
  7. Use the game ID from the previous step to run the game with ./engine run -g <game ID>

Protip: Provided you have the board setup and running, and have jq installed, you can create a game then run it in your browser you can run this one-liner:


./engine create -c ~/.snake-config.json \
  | jq --raw-output ".ID" \
  | xargs -I {} sh -c \
      "echo \"Go to this URL in your browser http://localhost:3000/?engine=${ENGINE_URL}&game={}\" && sleep 10; \
        ./engine run -g {}"

On macOS/OS X, you can tweak the above command and automatically open your browser to the correct game and run it, all in on go:


./engine create -c ~/.snake-config.json \
  | jq --raw-output ".ID" \
  | xargs -I {} sh -c \
      "open -a \"/Applications/Google Chrome\" \
          \"http://localhost:3000/?engine=${ENGINE_URL}&game={}\" \
        && ./engine run -g {}'

For more information about the engine:

$ engine --help
> engine helps run games on the battlesnake game engine

  engine [flags]
  engine [command]

Available Commands:
  create      creates a new game on the battlesnake engine
  help        Help about any command
  load-test   run a load test against the engine, using the provided snake config
  replay      replays an existing game on the battlesnake engine
  run         runs an existing game on the battlesnake engine
  server      serve the battlesnake game engine
  status      gets the status of a game from the battlesnake engine

      --api-addr string   address of the api server (default <http://localhost:3005>)
  -h, --help              help for engine
      --version           version for engine

Use "engine [command] --help" for more information about a command.

Running the engine in dev mode

Dev mode means that the engine will run a simple browser application that you can connect to your snake.

./engine dev

Open a browser and go to http://localhost:3010/

This will give you a web based environment to test the engine & the snake locally before you put it on the Internet.

Backend configuration

Storage options:

  • inmem - This is the default. All game data is erased when the engine restarts.
  • file - Stores one file per game. Games can be resumed or replayed after restart.
  • redis - Stores game data in a redis key. Games can be resumed or replayed after restart.

Backend configuration examples


Save games as files in ~/battlesnake/

engine server --backend file --backend-args ~/battlesnake


Save games as keys in redis

engine server --backend redis --backend-args 'redis://localhost:6379'

Battlesnake API

Refer to the docs repository or website, specifically the snake API.

You can’t perform that action at this time.