103 lines
4.1 KiB
Markdown
103 lines
4.1 KiB
Markdown
|
# Battlesnake Game Board
|
||
|
|
|
||
|
|
 
|
||
|
|
|
||
|
|
The board project is used to visualize and replay Battlesnake games on [play.battlesnake.com](https://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](https://code.visualstudio.com/docs/devcontainers/containers) or [GitHub Codespaces](https://github.com/features/codespaces) for development.
|
||
|
|
|
||
|
|
Commands to start dev server:
|
||
|
|
|
||
|
|
```sh
|
||
|
|
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](src/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:
|
||
|
|
|
||
|
|
```html
|
||
|
|
<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.
|
||
|
|
|
||
|
|
```html
|
||
|
|
<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:
|
||
|
|
|
||
|
|
```javascript
|
||
|
|
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.
|