# 15 Puzzle game with Go

🚀 [Play in Telegram](https://t.me/puzzle_15_bot?startapp).
Game has [simple rules](https://en.wikipedia.org/wiki/15_puzzle).

## Description

The intentions of the project is to create a simple proof-of-concept demonstrating that a [Telegram Mini App](https://core.telegram.org/bots/webapps) can be developed with Go and [WebAssembly](https://go.dev/wiki/WebAssembly).

✨ Graphics are made with [Ebitengine](https://github.com/hajimehoshi/ebiten).

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](https://core.telegram.org/bots/webapps#validating-data-received-via-the-mini-app).

## Running game

Local gameplay can be initiated using the following command:

```shell
go run ./cmd/ui
```

A fully functional Mini App requires a web server.
You can use [`Dockerfile`](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](https://core.telegram.org/bots/tutorial). |
| **`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](https://docs.gitea.com/usage/actions/overview)
workflow ([`.gitea/workflows/ci.yaml`](.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`](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](https://github.com/hajimehoshi/ebiten) game engine by Hajime Hoshi.
- Font by [VileR](http://int10h.org) and [fly_indiz](http://old-dos.ru/index.php?page=files&mode=files&do=show&id=102798).
- ASCII Gopher by [gheimifurt](https://www.reddit.com/r/golang/comments/xdxb9a/gopher_ascii_art_for_bashrc/).