References
Quick Start Coding Guide
A guide to creating and deploying your first Battlesnake.
This guide will walk you through one way to get your first Battlesnake running, using a pre-built starter project and Replit as your development environment and web server host. You will need:
If you do not wish to use Replit, you are welcome to use your own IDE, or any hosting solution of your choosing.
How does it work?
Developers build and deploy a web server that implements the Battlesnake API. When a game is created, the game engine will make HTTP requests to your Battlesnake server, sending game board information and asking for your next move. Your Battlesnake's behavior is determined by how you program it to respond to these requests.
You can use any programming language, cloud platform, and strategy you want - from simple game logic to machine learning and AI.
Step 1: Select a Starter Project
There are several community-built and supported starter projects for popular languages and technologies. Each one is documented with detailed development and deployment instructions. It's possible to use most programming languages, but some will be easier than others.
You can choose from the complete list of Starter Projects, or use a Replit quick-link below to automatically clone an officially supported starter project and open it in your Replit account.
Tip: If you're unsure what language to choose, we suggest starting with JavaScript or Python as they're both widely supported and popular in the Battlesnake community.
All of the Official Starter Projects implement the full Battlesnake API with enough code to run a basic Battlesnake that moves in a random direction.
Step 2: Customize your Battlesnake (a little bit)
To make sure everything works correctly when you deploy and run your Battlesnake for the first time, make a small customization change, such as the color of your Battlesnake. The
README.md file in each Starter Project describes where the customization code can be found. Customizations are set in the root "GET /" command of the Battlesnake API.
Customizing the Battlesnake colour to 'red' #ff0000 for the Python Starter Snake
While color is a great place to start, Battlesnake also features an exciting collection of customizable heads and tails! All customization options are described in detail on the Personalization Reference page.
After making changes to your Battlesnake, you can restart your Replit to have the change take effect (or in many cases, your Replit will restart automatically).
Step 3: Deploy and run your Battlesnake
Replit can act as both our development environment and web server host. To run your Battlesnake within Replit, click the Run button at the top of the screen.
Run button located at the top of the screen on the Replit website.
After clicking the Run button, you should see all libraries and dependencies being installed in the Replit console window, which may take a few moments. Once installation is complete, your Battlesnake server will start. You should see the live output from your Battlesnake server and the URL at the top.
Sample Python Starter Project running, with URL and output
You will need your Battlesnake server URL later in Step 3 when registering your Battlesnake!
The output should match whatever configuration changes you made in Step 2. For example, if you changed your Battlesnake to be red, with the hex color value
#ff0000 then your output should look like this:1
{"apiversion": "1", "author": "", "color": "#ff0000", "head": "default", "tail": "default"}
Copied!
This means that your Battlesnake is up and running correctly on Replit!
Replit is a fast and free option for hosting your Battlesnake server, but you can use whatever you like to run your server. For more options and information about hosting, check out Hosting Suggestions.
Tip: Keeping Replit open in a second window while games are running is helpful for watching server activity and debugging any problems with your Battlesnake.
Step 4: Create your Battlesnake
Once your Battlesnake has a working URL, you can create it on the Battlesnake website and start playing games. You only need to create a Battlesnake once and can continue to update and change your Battlesnake code afterwards.
Battlesnake creation happens in your profile. Copy the Battlesnake server URL from Replit (see Step 2) and put it in the 'URL' field. You can also fill in extra details such as 'Description' and 'Tags' to tell us a bit about your Battlesnake.
Form for registering a Battesnake
If you want your Battlesnake available for games with other people, you will need to check the Allow anyone to add this Battlesnake to a game option. If you leave this unchecked, your Battlesnake will only be available for games that you create or are a part of an official Battlesnake Tournament or Arena.
If everything is set up correctly, your Battlesnake should show as operational with the color, head, and tail you set in your code. Some additional information will also be displayed about the latency of communication between the game engine and your Battlesnake server.
Battlesnake created screen, with color customization.
If there is a problem or error with your Battlesnake, you can make changes and then Refresh your Battlesnake on the main profile page, or via the gear icon on the Battlesnake page.
Refresh option via the gear icon the Battlesnake page
Refresh button on the Profile page
Step 5: Create your First Game
You are now ready to test your Battlesnake in live games! So far, your Battlesnake has a sharp new look but only moves in a random direction. This means that for your first game, your Battlesnake is most likely going to collide with a wall or turn back in on its own body. That's ok! We all have to start somewhere.
Here's how to create a new game:
Form for creating a new Battlesnake game
- Click the âž• next to your Battlesnake to add it to the game
Tip: You can also add other Battlesnakes to your game, either by searching for them by name or using the 'Add a Random Battlesnake' button. Only Battlesnakes that check off the Allow anyone to add this Battlesnake to a game option (Step 3) will appear in public search.
Ready to 'Start Game' with one Battlesnake on an 11x11 board in Standard mode
- Click on Start Game button to start the game
You will be rewarded with a view of the game board that includes your Battlesnake and any other Battlesnakes you added to the game. Click the â–¶ button to start the game and watch your Battlesnake in action. You can also use the |â—€ and â–¶| buttons or the arrow keys on your keyboard to step through the game, move by move. This can be very helpful when reviewing your server logs for each turn!
A fresh Battlesnake game with your first Battlesnake ready to go
At the bottom of the gameboard is extra information about the game and additional controls. To quickly create a new game with the same configuration, click the Create Rematch button. There are also other options **to share and save the game as a favorite.
Game details and controls to rematch, share, or favourite a game.
Congratulations, you've built and deployed your first Battlesnake! 🎊
Step 6: Better than Random
Now you're ready to start making your Battlesnake smarter. Here are some initial goals to help you develop your Battlesnake. Completing these will make your Battlesnake competitive against other Battlesnakes in multi-player games.
- 1.Avoid colliding with walls
- 2.Avoid colliding with yourself
- 3.Avoid colliding with other snakes
- 4.Try to move towards food
Typical Battlesnake development cycles look like this:
- 1.Decide how you want your Battlesnake to move in a specific situation
- 2.Program your Move Command accordingly
- 3.Deploy your changes to your web server
- 4.Create new games and test your new behavior
- 5.Repeat until undefeated
The /move command in the API is where your Battlesnake decides which direction it is going to move. This can be found in the following places for each of the Official Starter Projects:
On every turn of the game, the Battlesnake Engine makes a call to your Battlesnakes /move command with data that describes the current state of the board, including its size, the location of food, the locations of other Battlesnakes, and other important game data. The API Reference has a sample JSON object that contains this data.
A subset of JSON data received on calls to /move
In the unmodified Official Starter Projects, the /move command accepts this JSON data, and then with absolutely no regard for self-preservation, responds with a move in a random direction, one of 'left', 'right', 'up' or 'down'. By changing the code in your projects
move() function, you can better control how your Battlesnake behaves.We recommend starting simple - start by adding rules that prevent your Battlesnake from turning back on its own neck, or running head-first into a wall. There is a series of Training Program Challenges that can act as your guide and help you track progress as you train up your Battlesnake. The secret is to make small changes and then immediately test.
For details on how /move and other commands work, we recommend reading through the code in the Battlesnake API Reference.
Coding Resources
This guide has helped you build and deploy your first Battlesnake using Replit and an Official Starter Project, and has reviewed the steps necessary to get it registered in your Battlesnake account and running your very first games.
But this only scratches the surface!
Check out the Battlesnake Game Rules and Tips & Tricks guide to making sure you understand how to program your Battlesnake to win the most games possible. You may have also noticed there are different Game Modes to explore that provide different challenges for your Battlesnake.
You can also check out the Battlesnake Awesome List, built by Xtagon and maintained by the community for great Battlesnake resources. Anyone may contribute, so if you know of any interesting resources or wish to share your own creations, open a pull request.
Good luck, and happy programming!
****
Last modified 23d ago