Add Standard Game Mode specification and RFC by coreyja · Pull Request #1 · BattlesnakeOfficial/rfcs

coreyja · 2026-01-13T12:12:02Z

In order to help standardize the Battlesnake rules, and allow for alternate engine implementations, this is a first draft of a spec document for the Standard Game Mode!

Its goal is to be the source of truth for how to run a Battlesnake game. It should cover all edge cases and be sufficiently detailed that it alone can be used by future implementations.

This is based off the Go rules repo, but we have NOT yet gone through and documented where each specification item is implemented and tested. I'd like to do this in follow ups after we agree on this initial spec!

nosnaws · 2026-01-15T21:28:41Z

Hey @coreyja, what kind of feedback are you looking for?
I gave it a quick read and it looks fantastic! I’ll plan to do a deep read of it this weekend.
Cheers!

bvanvugt · 2026-01-16T00:42:47Z

specs/game-modes/standard.md

+
+### 1.2 Board Dimensions
+
+Standard board sizes are:


Unsure if it's worth mentioning here - standard board sizes are all odd dimensions for competitive purposes:

Head-to-head collisions are only possible when all players start on all "black" or all "white" checker board spaces.

Applying that to even dimension game boards creates asymmetry in starting positions

Visually, having a single center coord makes for dramatic gameplay

Ahh yes love this added color!

Visually, having a single center coord makes for dramatic gameplay

Ahh hadn't thought of this before personally, thats cool!

bvanvugt · 2026-01-16T00:45:15Z

specs/game-modes/standard.md

+
+- `body[0]` is the snake's **head**
+- `body[length-1]` is the snake's **tail**
+- Adjacent body segments MUST be orthogonally adjacent (Manhattan distance of 1)


Manhattan distance of 1 or 0 (to account for next bullet point)

bvanvugt · 2026-01-16T00:47:42Z

specs/game-modes/standard.md

+
+| Constant     | Value | Description                 |
+| ------------ | ----- | --------------------------- |
+| `MAX_HEALTH` | 100   | Maximum and starting health |


Maybe not list starting health here - that's a function of board initialization using MAX_HEALTH, not necessarily a constant

Ahh ya fair! I do think its true that for Standard mode starting == max, but I think its worth touching up the wording since other game modes are coming soon enough anyways 😆

bvanvugt · 2026-01-16T00:49:20Z

specs/game-modes/standard.md

+Each turn executes the following phases **in order**:
+
+1. **Game Over Check** - Determine if the game has ended
+2. **Movement** - Apply snake moves


Is it worth including that snake moves are requested, either before or as part of this step? Just to be super clear what state snakes receive.

Ya good callout! This was too focused on just the rules eval, but does need that context to make sense as a spec I think

bvanvugt · 2026-01-16T00:50:33Z

specs/game-modes/standard.md

+### 2.2 Turn Numbering
+
+- Turn 0 is the **initial state** before any moves
+- The first move request is sent during turn 0


Worth saying that start request gets turn 0 too?

Oh yes, probably! In general this spec could probably talk about the actual Snake requests a bit more 🤔

bvanvugt · 2026-01-16T00:54:15Z

specs/game-modes/standard.md

+
+If a snake does not provide a valid move (timeout, invalid response, etc.), the implementation MUST apply a **default move**.
+
+The default move is determined by the relationship between the head and neck:


Probably worthwhile stating that the intent of the default move algorithm is to "maintain the intent of the previous move", ie; keep moving forward.

The algorithm exists purely because the previous move can be deduced from body state. But the result could also be achieved by storing and applying the move from turn N-1.

Yes I actually made a similar edit this morning before realized you left such great comments 😆

I also like adding the note that its re-producible from board state, but could just be implemented by remembering the last move too!

bvanvugt · 2026-01-16T00:56:00Z

specs/game-modes/standard.md

+If neck.Y == 0 AND head.Y > 0: default = "down"
+```
+
+If the snake has fewer than 2 body segments, or no direction can be determined, the default move is `"up"`.


It might be worth abstracting out a MIN_SIZE constant of 3, and applying it in these cases. I don't think that actually exists in my code, but could.

Oh yes, no reason to have hard-coded "magic numbers" in the spec 👍

bvanvugt · 2026-01-16T00:57:00Z

specs/game-modes/standard.md

+
+### 3.4 Simultaneous Movement
+
+All snake moves are applied **simultaneously**. The order in which snakes are processed during movement MUST NOT affect the outcome. Each snake's new position is calculated based on the state at the **start** of the movement phase.


The order in which snakes are processed during movement MUST NOT affect the outcome.

This is good wording!

bvanvugt · 2026-01-16T00:59:41Z

specs/game-modes/standard.md

+snake.health = snake.health - 1
+```
+
+### 4.2 Starvation Elimination


Small detail but we've intentionally moved away from "starvation" language (it likely still exists in some places) - both for social impact reasons, and because food is not the only source of health, and movement is not the only source health reduction.

Oh yes, great point! Changing now!

bvanvugt · 2026-01-16T01:02:18Z

specs/game-modes/standard.md

+If multiple snakes' heads occupy the same food position:
+
+- **All** snakes consume the food (health restored, growth applied)
+- The food is removed once


This could also be described as two distinct phases:

Food Consumption: Grow any snakes whose head shares the coordinates of food

Food Removal: Remove any food whose coordinates are shared with the head of a snake

Ahh yes I think that matches the impl closer, and I think makes it clearer how things happen.

bvanvugt · 2026-01-16T01:03:57Z

specs/game-modes/standard.md

+
+### 5.1 Food Consumption
+
+A snake consumes food when its **head** occupies the same position as a food item.


Is it worth mentioning that by this spec, food can only exist where a snake body or tail is not (but can share head coords)

Yup I think so! I'm also thinking about how much the food spawning needs to be defined as part of this spec... Starting to think it really should be cause can't impl a standard game without it really.

Which we can def do! And likely just leave a note that randomness is 'unspecced' for now, and we can follow up with a deterministic randomness RFC after this (which I have a draft of too somewhere)

bvanvugt · 2026-01-16T01:05:03Z

specs/game-modes/standard.md

+Elimination checks MUST be performed in this order:
+
+1. **Out of Health**: Check if `health <= 0`
+2. **Out of Bounds**: Check if any body segment is outside board boundaries


Ooo nice callout on any body segment.

bvanvugt · 2026-01-16T01:08:03Z

specs/game-modes/standard.md

+
+When a snake collides with another snake's body, the collision is attributed to the **other** snake.
+
+When multiple snakes could be credited for a body collision (in edge cases), the elimination MUST be attributed to the **longest** snake involved.


What if multiple snakes are tied for longest?

Ahh yes, I was too Duels brained here lol

bvanvugt · 2026-01-16T01:09:21Z

specs/game-modes/standard.md

+The game ends when **one or fewer** non-eliminated snakes remain:
+
+```
+count = 0


might be cleaner if named 'num_non_eliminated_snakes' or similar.

bvanvugt · 2026-01-16T01:10:25Z

specs/game-modes/standard.md

+### 8.2 Winner Determination
+
+- If exactly 1 snake remains: that snake wins
+- If 0 snakes remain: no winner (draw or mutual elimination)


I'd probably remove the "mutual elimination" here and just go with "draw", which can then be defined cleanly.

Oh ya no need for a fancy term here, that's just a "draw" lol

bvanvugt · 2026-01-16T01:11:14Z

specs/game-modes/standard.md

+
+### 8.3 Game Over Check Timing
+
+The game-over check is performed at the **beginning** of each turn, before movement. This means:


This probably makes it important to know when move requests are sent to snakes.

coreyja · 2026-02-04T15:41:55Z

@nosnaws thanks for taking a look! Any comments or feedback you have is great.
My goal here is that someone could take this spec file, and fully implement a Battlesnake game engine from it 😆

Which is a lofty goal, so there are definitely things that are under-specced for that. And I think there are likely parts of that we won't spec here (for example how randomness works), but ideally I think it would be cool to have a 'formal' spec for basically everything we reasonably can!

coreyja · 2026-02-04T15:42:19Z

@xtagon to continue our Discord convo from a few weeks ago here if you don't mind.
I'm definitely interested in a more formal language to define the rules in! But I think I want to do this first, but down to do that eventually and assuming it goes well call that the 'canonical' version.
I want to do the English speccing cause:

It seems like a fun excersice, since I'm not used to writing formal specs
Battlesnake seems simple enough to formally spec in English

But I'm happy to be proven wrong on both those fronts 😆

Also I do agree I was using pseudo-code here as a crutch so tried to cleanup up most/all of it. And will continue on my next passes!

Introduces formal specification for Battlesnake Standard mode, enabling alternative implementations to achieve compatibility with the official rules engine. RFC (rfcs/2026-01-standard-mode-spec.md): - Motivation for formalizing existing rules into a spec - Scope and relationship to future PRNG spec Spec (specs/game-modes/standard.md): - Coordinate system and board state representation - Turn phase ordering (game over, movement, starvation, hazards, feeding, elimination) - Movement mechanics including default move logic - Elimination rules with exact priority ordering - Head-to-head collision resolution - Examples in appendix Note: Full reproducibility requires upcoming PRNG specification for randomness in initialization and food spawning.

coreyja · 2026-02-04T15:43:32Z

@bvanvugt Thanks for all the detailed feedback!!

Folded it in a bit quickly this morning, and want to take a fuller pass on my train home today

xtagon · 2026-02-05T01:30:06Z

@coreyja Makes sense! We could also link to specific lines (github permalinks can highlight lines) of the Go rules in reference to certain rules in the spec. It might help not just with readers of the spec, but help with the process of us defining it. I know I pour through the Go code a lot when implementing my own engines.

bvanvugt reviewed Jan 16, 2026

View reviewed changes

coreyja force-pushed the push-swtnvzzkuxyu branch from b5bea70 to 5362298 Compare February 4, 2026 15:42


		If a snake does not provide a valid move (timeout, invalid response, etc.), the implementation MUST apply a default move.

		The default move is determined by the relationship between the head and neck:


		### 3.4 Simultaneous Movement

		All snake moves are applied simultaneously. The order in which snakes are processed during movement MUST NOT affect the outcome. Each snake's new position is calculated based on the state at the start of the movement phase.


		### 5.1 Food Consumption

		A snake consumes food when its head occupies the same position as a food item.


		When a snake collides with another snake's body, the collision is attributed to the other snake.

		When multiple snakes could be credited for a body collision (in edge cases), the elimination MUST be attributed to the longest snake involved.


		### 8.3 Game Over Check Timing

		The game-over check is performed at the beginning of each turn, before movement. This means:

Conversation

coreyja commented Jan 13, 2026

Uh oh!

nosnaws commented Jan 15, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

bvanvugt Jan 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

bvanvugt Jan 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

coreyja commented Feb 4, 2026

Uh oh!

coreyja commented Feb 4, 2026

Uh oh!

coreyja commented Feb 4, 2026

Uh oh!

xtagon commented Feb 5, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

bvanvugt Jan 16, 2026 •

edited

Loading

bvanvugt Jan 16, 2026 •

edited

Loading