| description |
|---|
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:
- A free Battlesnake Account
- A free Replit Account
If you do not wish to use Replit, you are welcome to use your own IDE, or any hosting solution of your choosing.
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.
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.
{% hint style="info" %} 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. {% endhint %}
- Open the Python Starter Project in Replit
- NOTE: Importing Python projects from Github in Replit is currently not working, so you'll need to fork the template above to get started.
- Open the Go Starter Project in Replit
- Open the JavaScript Starter Project in Replit
- Open the TypeScript Starter Project in Replit
- Open the Rust Starter Project in Replit
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.
{% content-ref url="../references/starter-projects.md" %} starter-projects.md {% endcontent-ref %}
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.
- Python Starter Project Customization
- Go Starter Project Customization
- JavaScript Starter Project Customization
- TypeScript Starter Project Customization
- Rust Starter Project Customization
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).
{% content-ref url="../references/personalization.md" %} personalization.md {% endcontent-ref %}
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.
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.
{% hint style="info" %} You will need your Battlesnake server URL later in Step 3 when registering your Battlesnake! {% endhint %}
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:
{"apiversion": "1", "author": "", "color": "#ff0000", "head": "default", "tail": "default"}
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.
{% hint style="success" %} 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. {% endhint %}
{% content-ref url="../references/hosting-suggestions/" %} hosting-suggestions {% endcontent-ref %}
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.
{% hint style="warning" %}
If you get an SSL error when loading your Replit Battlesnake server URL, try changing the https:// to http://.
{% endhint %}
Click here to create a new Battlesnake in your account.
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.
{% hint style="warning" %} 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. {% endhint %}
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:
- Go to play.battlesnake.com
- From the navigation menu, choose Create Game
- Click the ➕ next to your Battlesnake to add it to the game
{% hint style="info" %} 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. {% endhint %}
- 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!
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.
Congratulations, you've built and deployed your first Battlesnake! 🎊
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.
- Avoid colliding with walls
- Avoid colliding with yourself
- Avoid colliding with other snakes
- Try to move towards food
Typical Battlesnake development cycles look like this:
- Decide how you want your Battlesnake to move in a specific situation
- Program your Move Command accordingly
- Deploy your changes to your web server
- Create new games and test your new behavior
- 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:
- Python Starter Project -
handle_move()function inside of server.py - Go Starter Project -
HandleMove()function inside of main.go - JavaScript Project -
move()function inside of logic.js - TypeScript Starter Project -
move()function inside of logic.ts - Rust Starter Project -
get_move()function inside of logic.rs
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.
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.
{% content-ref url="../references/api/" %} api {% endcontent-ref %}
{% content-ref url="../references/api/sample-move-request.md" %} sample-move-request.md {% endcontent-ref %}
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.
{% content-ref url="../references/rules.md" %} rules.md {% endcontent-ref %}
{% content-ref url="../references/game-modes.md" %} game-modes.md {% endcontent-ref %}
{% content-ref url="tips.md" %} tips.md {% endcontent-ref %}
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!
****