BattleSnake 2017 API

Called when a new game is started.

Game IDs are guaranteed to be unique¹.

The purpose of this callback is for clients to report what their snake's name, colour, and other display properties should be for this game.

This callback should not be used to manage internal snake state it is not guaranteed that as you will be notified when the game ends, or when your snake dies.

All attributes the request are provided to maintain backwards compatibility with 2015 snake clients - it is strongly recommend that clients exclusively use the move callback for any and all game play logic.

The game server will issue a request for this callback on each turn to request the client's move.

This callback should be used for all game logic.

Below is a simple example snake. This is what the bare minimum implementation of a functional snake might look like.

This example is written in Ruby, but you are of course not limited in what technology you wish to use.

In the below example we create a basic Sinatra² web application. The app severs the two post callbacks, and provides a response containing only the required attributes for both.

# ./Gemfile
source "https://rubygems.org"
gem "sinatra", require: "sinatra/base"
gem "rack"

# ./ruby_snake.rb
require "json"

class RubySnake < Sinatra::Base
  post "/start" do
    {
      name: "simple-ruby-example-snake",
      color: "#123456"
    }.to_json
  end

  post "/move" do
    {
      move: "up"
    }.to_json
  end
end

This Snake only goes up, but it works!

A 2-dimensional vector.

x :: 0..infinity
y :: 0..infinity
Point :: [x, y]

[0, 1]

{
  "taunt": "git gud",
  "name": "my-snake",
  "id": "5b079dcd-0494-4afd-a08e-72c9a7c2d983",
  "health_points": 93,
  "coords": [
    [0, 0],
    [0, 0],
    [0, 0]
  ]
}

coords is a complete list of a snakes head and body segments. The first segment in coords is a snakes head.

When a snake moves its' head segment will move in the direction specified, and all it's tail segments will advance to space ocupied by the previous segment

Eating food extends your snake's tail, and restores your health points.

For example:

// before eating food
{
  "taunt": "git gud",
  "name": "my-snake",
  "id": "5b079dcd-0494-4afd-a08e-72c9a7c2d983",
  "health_points": 50,
  "coords": [
    [2, 0],
    [1, 0],
    [0, 0]
  ]
}
// moves right, (1, 0), into a space that occupies food (3, 0)
// the new state of the snake would be
{
  "taunt": "git gud",
  "name": "my-snake",
  "id": "5b079dcd-0494-4afd-a08e-72c9a7c2d983",
  "health_points": 100,
  "coords": [
    [3, 0],
    [2, 0],
    [1, 0],
    [1, 0]
  ]
}
// the tail has been extended by 1 and the health restored to 100

color :: hexcode | hsl | named_color | rbg

"gold"

"#ffffff"

"rgb(255, 255, 255)"

"hsl(255, 100%, 100%)"

A string matching one of the values listed below:

Value	Preview
"bendr"
"dead"
"fang"
"pixel"
"regular"
"safe"
"sand-worm"
"shades"
"smile"
"tongue"

A string matching one of the values listed below:

Value	Preview
"small-rattle"
"skinny-tail"
"round-bum"
"regular"
"pixel"
"freckled"
"fat-rattle"
"curled"
"block-bum"

BattleSnake is an adaptation of the classic video game "Snake", where the player maneuvers a snake around the play field to collect food pellets, which makes the snake grow longer. The main objective is to collect as much food as as possible, while avoiding hitting obstacles, such as walls and most importantly - your own snake.

In BattleSnake, each round X number of snakes is pitted against each other, and the goal is to be the last snake left alive at the end of the round.

• Runs into another snake's body.
• Runs into its own body.
• Runs into the walls of the play field.
• Collides head-to-head with a longer snake (both die if they are of the same size).
• Starves.

• Your snake starts out with 100 life and counts down by 1 each turn.
• When your snake's life total reaches 0, it dies of starvation.

• Food pellets spawn randomly around the play field.
• Each food pellet increases your snake's length by 1 and resets its life to 100.

• No DDoSing your opponents.
• No manual control of your snake.

Ruby Snake