battlesnakeofficial / board

Battlesnake Game Board and Playback Control

Battlesnake Game Board

The board project is used to visualize and replay Battlesnake games on play.battlesnake.com, as well as live streams and competitions. It uses SvelteKit to orchestrate playback and renders the board with dynamic SVGs.

Development Server

We recommend using a VSCode Devcontainer or GitHub Codespaces for development.

Commands to start dev server:

npm install
npm run dev

Required Parameters

A valid game ID is required to be passed as a URL parameter. For example: http://127.0.0.1/?game=ASDF-1234-QWER-6789.

Playback Settings

Playback settings are used to control playback speed, visual theme, media controls, etc. Some settings are persisted in local storage, and all settings can be overridden using URL parameters.

See lib/settings for more details.

Persisted Settings

These values are configurable in the UI and persisted in local storage. They can also be overridden using URL parameters.

• autoplay: boolean - Start playback as soon as game is loaded. Defaults to false.
• fps: number - Playback speed, defined in 'frames per second'. Defaults to 6.
• showCoords: boolean - Display coordinates on game board. Defaults to false.
• theme: string - Display theme. Defaults to 'system'.

Other Settings

These values can be set with URL parameters and are not persisted between games.

• engine: string - Stream game data from an alternate game engine.
• loop: boolean - Loops playback when game is finished. Defaults to false.
• showControls: boolean - Displays playback controls under the game board. Defaults to true.
• showScoreboard: boolean - Displays scoreboard to right of game board. Defaults to true.
• title: string - Display a title above the board. Defaults to empty string.
• turn: int - Start playback on a specific turn. Defaults to 0.

Tests & Linting

Formatting is enforced with prettier, and linting is enforced with eslint.

Playwright is included in the repo but not yet in use.

Usage

The board project is intended to be embedded into other webpages using an <iframe>. For example:

<iframe scrolling="no" style="width:1280px" src="https://board.battlesnake.com/?game=1234"></iframe>

If you want specific settings to be used, add their values to the src URL as additional parameters.

Sizing

It's expected that the iframe element will have a width and height of 100%, and be contained by a parent with a fixed width. Board will react to the width of the container and size accordingly, with a maximum width of 1280px and a perferred aspect ratio of 16x9 on larger screens.

If you know you're viewing on a larger screen, you can safely set the aspect ratio to 16x9, or fix both dimensions.

<div style="width: 1280px; aspect-ratio: 16 / 9;">
    <iframe style="width: 100%;height: 100%" src="..."></frame>
</div>

Otherwise you should listen for the posted 'RESIZE' message from the iframe to know what height the board has chosen to render (see below).

Cross-Origin Messages

The board will post messages to the parent frame to signal major playback events, such a new frame being displayed and playback ending.

These messages are useful for loading new games, triggering surrounding UI, and properly sizing the embedded iframe.

Example code for listening to these messages:

window.addEventListener("message", (e) => {
  if (e.origin !== "https://board.battlesnake.com") {
    return;
  }
  console.log(e.data);
});

Messages

RESIZE: Signals the board has drawn at a new size and includes sizing information. Useful for rendering a responsive iframe.

TURN: Sent every time a new game state is displayed, and includes full game state information.

GAME_OVER: Signals that playback has concluded and the final frame is being displayed.

board's Issues

Board seems to not handle invalid tails

If there is a typo in a snake's tail type the board does not render.

Sample broken game
https://play.battlesnake.com/g/51dac76c-0f38-4798-85c8-eb375ba745e7/
The tail type for Zombie snake was tailType = 'flecked' which is not correct. The moment you press play of forward with this game the entire board disappears.

Once the tailType is corrected to 'freckled' then everything works again

Games that no longer exist constantly try to connect to the engine's web-socket

How to replicate:
Head to https://play.battlesnake.com/g/71638e34-6659-420e-9d01-658a00a42e80/ with your network tab open.

What should happen:
When the request to get the game engine comes back as a 404, the board should show some info on the front-end telling the end user that the game is no longer stored in the battlesnake backend, and not try and connect to the engine's websocket.

What happens:

As long as the browser is open, the board will keep trying to connect to the websocket, once a second.

Create an endpoint for retrieving Board version.

What is the problem?
We're not sure what version of board is live in the wild.

What is the solution?
Other apps provide a /version endpoint that dumps the APP_VERSION environment variable.
Example: engine.battlesnake.com/version -> 0.0.8.
Let's add this to board as well.

Other Notes

• Endpoint should return the APP_VERSION environment variable if set.
• If not set, return 'unknown'.
• Here's the go code we use in engine:

func versionHandler(w http.ResponseWriter, r *http.Request, _ httprouter.Params) {
	version := os.Getenv("APP_VERSION")
	if len(version) == 0 {
		version = "unknown"
	}
	fmt.Fprint(w, version)
}

Feature Request: Permalink to a specific turn on a game board

Hi,

Currently on one can link to play.battlesnake.com/g/{game_id} to share a game board with friends. I would love to be able to link to something like play.battlesnake.com/g/{game_id}?turn=123 which would load the exact same page, but skip to turn 123 in the view.

Very minor, just would make it easier to share key positions 👍

Board fails to load when a snake has a freckled tail

The media server appears to have permissions misconfigured for the freckled tail. If a snake has this tail, the board fails to load at all, reporting the following error in the console:

Access to fetch at 'https://media.battlesnake.com/snakes/tails/freckled.svg' from origin 'https://board.battlesnake.com' has been blocked by CORS policy: No 'Access-Control-Allow-Origin' header is present on the requested resource. If an opaque response serves your needs, set the request's mode to 'no-cors' to fetch the resource with CORS disabled.

All other tails seem to load properly.

Sweep: Add a new setting to settings/store.ts to control a dark more preference