15 Puzzle game with Go
🚀 Play in Telegram. Game has simple rules.
Description
The intentions of the project is to create a simple proof-of-concept demonstrating that a Telegram Mini App can be developed with Go and WebAssembly.
✨ Graphics are made with Ebitengine.
Basic "features" include: a splash screen, game move sound, a switchable silent mode without moves count, a players' rating table, a congratulations screen for achieving 1st place, a pin-code protected game statistics screen, and backend API requests secured through data validation.
Running game
Local gameplay can be initiated using the following command:
go run ./cmd/ui
A fully functional Mini App requires a web server.
You can use Dockerfile to build a Docker Image
containing all necessary artifacts: the server binary, the WebAssemply (wasm) binary, and html page.
Certain environment variables should be set for the server to start:
| Env | Description |
|---|---|
BOT_TOKEN |
Telegram Bot API Token. |
DATA_FILE |
Path to the file where games data will be stored. |
ACCESS_CODE |
Pin-code to access the Statistics Screen. |
PROJECT_LINK |
URL to the project's source code. |
SERVER_PORT |
Port for the server to listen for API requests, defaulting to 8080 if not set. |
CONTEXT_ROOT |
Server requests URI root path, defaulting to / if not set. |
STATIC_DIR |
Directory where static files are located, defaulting to the current directory if not set. |
Deployment
The repository ships a Gitea Actions
workflow (.gitea/workflows/ci.yaml) that runs the
server test suite on every pull request to master, and on every push to
master additionally rebuilds the Docker image and (re)deploys the container on
the host Docker daemon through deploy/docker-compose.yml.
The deploy job runs in host mode: it builds the image locally (no registry) and
recreates the 15-puzzle container attached to the external edge Docker
network, so a host reverse proxy can route to 15-puzzle:8080.
Required Actions secrets and variables
Configure these under the repository's Settings → Actions:
| Kind | Name | Example / note |
|---|---|---|
| Secret | BOT_TOKEN |
Telegram Bot API token. |
| Secret | ACCESS_CODE |
Pin-code for the Statistics Screen. |
| Variable | PROJECT_LINK |
URL to the project's source code. |
| Variable | DATA_FILE |
/data/data.json (lives on the persistent volume). |
| Variable | SERVER_PORT |
8080. |
| Variable | CONTEXT_ROOT |
/. |
STATIC_DIR is intentionally left unset: the static assets (HTML, game.wasm,
wasm_exec.js) are baked into the image and served from the working directory.
Persistence
Game data is stored on the named Docker volume 15-puzzle-data mounted at
/data, so player ratings survive container recreation. The image creates
/data owned by the unprivileged app user so the volume is writable.
Credits
- Ebitengine game engine by Hajime Hoshi.
- Font by VileR and fly_indiz.
- ASCII Gopher by gheimifurt.