Board game idea based on building and programming your own units
GAME_RULES.md states the rules the game plays by, in one place.
- Create your own unit types, and deploy units built from them
- Write the program a type's units run; every unit thinks for itself, once a turn, and pays for its thinking in energy
- Units that meet fight it out, and the last player whose flag still stands wins
Nobody orders a unit by hand. A player's whole game is the setup: the types,
their programs, where the units stand and which one carries the flag. When
the last setup is committed the game is resolved to its end at once, every
turn of it is written down, and what is left is a record to watch turn by
turn - at a prompt with show turn, or in a browser as a replay.
From the project root:
python3 -m venv venv
source venv/bin/activate
pip install .
That's it. Every dependency comes with the install, and four console
scripts land on your $PATH: bgcapiserver, bgcserver, bgcclient,
bgcobserver. On Ubuntu, sudo apt-get install python3-pip python3.12-venv first if you don't have them.
For working on the code, use pip install -e '.[dev]' — the -e
installs in place, [dev] pulls in the linter.
The three CLI roles talk to a REST server (bgcapiserver); with no
--server and no BOARD_GAME_SERVER set, the roles probe for one on
http://127.0.0.1:45678. Naming a --backend or --server explicitly
skips the probe.
$ bgcapiserver &
$ export BOARD_GAME_SERVER=http://127.0.0.1:45678
$ bgcserver -g 1 # admin: sets the board, registers players
# commits and exits
$ bgcclient 1 1 # player 1
$ bgcclient 1 2 # player 2
$ bgcobserver 1 # observer
Without BOARD_GAME_SERVER (or --server URL on a role), each binary
opens the game directory itself and runs its own local flow — the CLI
behaviour that pre-dated the HTTP tier is unchanged. The storage backend
is chosen by BOARD_GAME_BACKEND (or --backend); SQLite is the
default, YAML is the readable-file alternative.
Two backends behind the same GameRepository port:
- SQLite (default) — one file per game at
games/_<gameno>/game.sqlite3. Real tables;held()is a transaction;read_viewruns the visibility join. This is what a real deployment uses. - YAML — the readable-file backend. One YAML file per thing under
games/_<gameno>/data/andgames/_<gameno>/players/. Available for tests (byte-diff coverage), or for an operator who wants tocatthe game state. Pick with--backend yamlorBOARD_GAME_BACKEND=yaml.
Pick one at startup and stay with it: a game written by one backend is not readable by the other, and there is no migration between them.
Each player is registered with a point budget, which is what bounds the army they may deploy. The administrator names it as an optional second argument:
bgcserver> add player 1 150 # 150 points to spend
bgcserver> add player 2 # the default: 320
A budget is an integer from 1 to 1000 and is fixed for the life of the
game. A type costs the sum of its four statistics — add type Cross X 1 10 10 2 costs 23, the 2 being its compute — and every unit deployed
from it costs that again, so a 100-point budget buys four Crosses and
refuses a fifth. Defining a type is free; deploying is what spends, and a
destroyed unit is not refunded. The stock army a seat opens with costs
308 of the default 320. show types prints each type's COST and
show players prints your BUDGET, SPENT and LEFT.
A player file handed to load player may carry a budget: key; one
that leaves it out gets the default.
A game saved before budgets existed cannot be opened. A stored player record with no budget is refused rather than defaulted, because defaulting one would play the game by rules it was not set up under. Delete the game directory and start a new one.
Install it and start it. That is the whole of the setup:
$ pip install .
$ bgcapiserver
bgcapiserver: http://127.0.0.1:45678/
games and accounts in /home/you/games
/home/you/games/games/
/home/you/games/accounts.sqlite3
set $BOARD_GAME_HOME to keep them somewhere else
sign in as admin / admin, or observer / observer - each must change its
password before it can do anything
It says where it is serving, where it put your games and accounts, and how to get in, because a person who has just installed something should not have to read the source to find any of that out.
The directory you start it in, unless you say otherwise — games/ and
either accounts.sqlite3 or accounts/ beside each other.
That is fine when you run it in a directory you keep games in, and a trap when
you don't: an installed command is run from wherever you happen to be, so
starting it somewhere else tomorrow gives you a different, empty server,
handing out the default passwords again. Set $BOARD_GAME_HOME and it stops
mattering where you were:
$ export BOARD_GAME_HOME=~/board-games
$ bgcapiserver
One setting moves games and accounts together — a deployment with its games in
one place and its people in another would be worse than either. --base-path
overrides both.
One page, and it is a client of the same JSON API the command-line roles use — there is no route that exists only for the browser. Sign in, take a seat from the lobby, design your units, and play.
No build step and no package manager. Everything under
src/board_game_concept/http/static/ is a plain file served as it was
written: the board is one <svg> and a unit moves by a change of transform,
so the animation is a CSS transition rather than a library. The repository
stays one language with one toolchain.
The armoury is where a game is played. A type is designed with four statistics — attack, health, energy and compute — and its cost is shown as you type them. A type with compute has a controller, and the armoury has an editor for the program it runs: every line is priced in ticks as it is written, from the same tariff the server charges, and the total is held against the per-turn cap the type's compute buys, so a program that does not fit its type is seen before a turn says so. The server checks the program when it is set and names the line it refused.
The record tells you what every turn did. Every unit is drawn with the health it has left against the health its type was built with, so a unit a blow from destruction does not look like a fresh one. Under the board is an account of the turn in the order it happened — who engaged whom, every attack and the damage it dealt, and every unit destroyed — and, for your own units, what their controllers thought: the order each gave, the ticks it spent and the energy that cost it. The squares that were fought on are marked on the board itself, with what the fighting cost you there and where a unit fell.
That account is the server's, not the browser's. It is written for each seat when the turn resolves, out of what that seat could see while it was being fought: you are told what happened to your own units and what other people's did only where you could see them. A fight between two players you cannot see is not in your feed at all — being told it happened would give away that they are near each other, which is the thing visibility withholds.
Setting a game up is a thing you are still deciding: the administrator can size the board again and add or remove seats until the setup is committed, which is when both stand. A resize that would leave a unit off the board is refused, naming it. A setup with no board cannot be committed at all, and says so before the button rather than after it.
Committing publishes the board, and that is how the lobby tells a game with a setup still to do from one whose setup is done: both read as "setting up" until the last seat commits, because players are still deploying, but only the first is offered a setup screen.
Committing a setup is the last thing a player does. The page then says which seats are still being waited for, and the moment the last of them commits the whole game is resolved and the replay opens at its first turn. The lobby sends a seat that has committed to the replay rather than back to its armoury, and the armoury says the setup is committed rather than offering forms whose every answer would be refused.
One of your units carries your flag, designated during setup and fixed when you commit it. Every player can see which square each flag is on and whose it is, whoever they have met — and nothing else about the unit standing there, so you know where to go rather than what you will meet. Lose your carrier and you are out of the game: your units stay where they are as terrain, their controllers stopped and striking nothing, and the last player left wins. A setup without a carrier is refused, because a player who cannot lose a flag is playing a different game from everybody else at the table. A game set up before flags, or before controllers, existed cannot be opened, so finish one by starting it again.
Beside the board is a roster: your own units with what each has left against what it was built with, and every enemy design you have met with the statistics its owner built it with. That memory outlives the contact that taught it, and it is also what your army's map keeps: a square your units have stood on, and an enemy they fought where they fought it, each stamped with the turn. Only the design and the square: nothing of how an enemy thinks. The watching observer gets the same roster for every player.
The replay draws the whole board after every turn, because a replay is
watched once the game is over and nothing on it can still be acted on. What
it does not show is anybody's program: contact discloses a type's attack,
health and energy and nothing of how it thinks, and a trace is its owner's
and the observer's. Press K and the board is drawn instead as your army
knew it after that turn — the squares your units had stood on, the enemies
they had fought where they fought them, and everything else unknown — which
is the board your controllers were actually reading. Hovering a unit gives
its statistics, yours or an enemy's.
It is watched from the keyboard: ← and → step a turn, Space plays
and pauses, + and - change the speed, Home and End go to the first
and last turn, K toggles the known board, W A S D move the cursor
about the board, Enter selects the unit under it and Esc clears the
selection.
If the server stops answering — restarted under an open tab, a laptop closed, a network gone — the page says so and keeps trying, backing off as it goes, and picks up where it left off when the server comes back. Nothing committed is lost by it.
Everything the browser can do, a command line can do: the interface is a
client of the served contract and so are the roles. set program gives a
type the program the armoury's editor writes, read from a file; show program lists it with the ticks each line costs; show turn <n> is one turn
of the record as the replay draws it, show turn <n> known the board as your
army knew it, and next and prev step through the record. show events is
the account of what the turns did, show designs the enemy designs you have
met, show flags where every flag is, show units the statistics of every
unit you can see, set flag the designation the armoury makes with a button,
and remove player the seat the administrator's screen removes with another.
A test holds the two to each other, so a view added to one and not the other
fails the suite.
Everyone on the same Wi-Fi can play from their own phone. Start the server so it answers on the network rather than only on the machine it runs on:
$ bgcapiserver --host 0.0.0.0
bgcapiserver: http://192.168.1.23:45678/
games and accounts in /home/you/board-games
...
█████████████████████████████████
████ ▄▄▄▄▄ █ ▄ ▀ ██▄█ ▄▄▄▄▄ ████
...
The address it prints is the one other devices can reach — not 0.0.0.0,
which is what was bound and is not somewhere anybody can type — and the code
beneath it is that same address, to scan. A guest points their phone's camera
at your screen, opens the link, taps Register instead on the sign-in
screen, signs in, and takes a seat from the lobby. Nobody installs anything.
You sign in as admin, make the game and add the seats, as in
Accounts below.
A home network is the trusted one the TLS note exempts: tokens and passwords cross it in clear, which is fine among people you would hand your phone to and not fine beyond that. Do not put this on a network you do not control without TLS in front of it.
If the machine has several addresses — a VPN, a wired connection alongside the Wi-Fi — the banner names the one with the default route, which may not be the one your guests are on. Name the right one and it is printed as given:
$ bgcapiserver --host 192.168.1.23
Guest and public Wi-Fi often stop devices seeing each other (the router
calls it client isolation), and then no phone can reach the server however it
is bound. The way round it is to make the host's phone the network: turn on
its hotspot, have everyone join that, and name the hotspot's address with
--host — it is under Hotspot in the phone's settings — because the address
the banner finds on its own is the one facing the mobile network, not the
one your guests are on.
The server itself runs on a phone. Every dependency is pure Python, so it
installs without a compiler. Install Termux from
F-Droid — the Play Store build is abandoned and its pip no longer works —
then:
$ pkg install python git
$ git clone https://github.com/aburston/board_game_concept
$ cd board_game_concept
$ pip install .
$ export BOARD_GAME_HOME=~/board-games
$ bgcapiserver --host 0.0.0.0
The banner and the code appear on the phone's own screen, and that is what the other phones scan. If the code wraps on a narrow terminal, turn the phone sideways: a broken code does not scan.
Two things stop Android killing the server in the middle of a turn, and without both it will:
- Hold a wake lock. Run
termux-wake-lockbefore starting the server, or tap Acquire wakelock in the notification Termux shows while it runs. Otherwise the process is suspended as soon as the screen goes off. - Turn off battery optimisation for Termux, under Apps in Android's settings. Otherwise Android stops it anyway after a while in the background.
An iPhone cannot host this way — nothing keeps a Python server running in the background there — but it joins a laptop or an Android host like any other phone.
Android does not firewall a listening app and Termux has no firewall of its own, so "the phone is blocking it" is rarely the answer. Work through these on the host phone, in order, with Termux in the foreground; the first one to fail names the problem.
- Check the port. It is
45678, five digits, and the banner's first line prints it. A dropped digit gives a "site can't be reached" on every device, which looks exactly like a network problem and is not one. The code exists so that guests never type it; the host, who cannot scan their own screen, is the one who does. - Open
http://127.0.0.1:45678/in the phone's own browser. This proves the server is up at all. If it fails, the server is not running, or is on another port. - Open
http://<the banner's address>:45678/on the same phone. This proves the phone can reach itself through its Wi-Fi address. If 2 works and this fails, something on the phone is intercepting its own traffic — almost always a VPN, or an ad blocker that works as one (look for a key icon in the status bar). Turn it off while hosting, or exclude Termux in its settings. - Open the same address from another device. If 3 works and this fails, the problem is between devices: the router is isolating Wi-Fi clients from each other, as guest networks and some extenders do. A laptop on a cable can hide this, because isolation is usually between wireless clients only. The hotspot, above, is the way round it.
Also check the address itself against Settings, Wi-Fi, your network. If the
banner printed one starting 10. or 100., that is the mobile network's
address, not the Wi-Fi's; name the Wi-Fi address with --host instead.
bgcapiserver runs Flask's development server, which is fine for a laptop or
a club and not for anything else. Each player waiting for a turn holds a
server thread for the length of the long-poll budget, so a host serving more
than a few people wants gunicorn or uwsgi in front of the same app — and
TLS, as below.
The three CLI roles talk to a game by naming a number. A server does not take anybody's word for it: over HTTP an account signs in, and what it may do is decided by which seats it holds.
An account is who somebody is; a seat is which player number they hold in which game. The numbers themselves are unchanged — 0 is still the administrator, 1 to 999 the players, 1000 the observer — and what each is entitled to is unchanged too. What changed is that a number now has to be proved rather than asserted.
Accounts live beside the games/ tree rather than inside any game, because a
person outlives every game they play in. They are kept in the same backend
the games are, chosen by the same --backend or BOARD_GAME_BACKEND: a
SQLite deployment keeps them in accounts.sqlite3, a YAML one in three files
under accounts/. A deployment is one thing or the other; there is no mixture.
Under the YAML backend the password hashes are in a readable file. They are
scrypt and are not reversible, but a file walks off more easily than a table
does, so accounts/ is created 0700 and its files 0600 — keep them that
way, or run the SQLite backend, which is the default.
$ bgcapiserver & # creates accounts.sqlite3 if it is absent
The store is created with two accounts: admin with the password
admin, and observer with the password observer. Both must change
their password before they can do anything else — until they do, every
request is refused except the one that changes it. That is the whole point of
shipping with a known password: it is a way in, once.
# sign in, and change the password the account was created with
$ curl -s -X POST localhost:45678/sessions -H 'Content-Type: application/json' -d '{"username":"admin","password":"admin"}'
{"kind":"admin","must_change_password":true,"token":"...","username":"admin"}
$ curl -s -X POST localhost:45678/accounts/current/password -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' -d '{"current":"admin","new":"something-better"}'
A password is at least 8 characters and nothing else is required of it. The
administrator can set anybody's password without knowing it
(POST /accounts/<name>/password); an account changes its own by giving the
one it has now.
None of this needs a browser, or even a server. login at the prompt of
any role does the same thing, and against local storage it opens the account
store beside the games — so the first password can be changed on a machine
that has never run bgcapiserver:
$ bgcserver -g 1
bgcserver> login admin
password:
signed in as admin (admin)
signing in locally reads and changes an account; playing a local game needs
no account
admin must change its password before doing anything else
new password:
new password again:
password changed
The password is typed at a prompt that does not echo it and never as a word on the command line, so it reaches no shell history and no process listing.
The administrator sets a game up as it always did — set board, then
add player <number> [budget] for each seat. Anyone else registers an
account and takes an open seat:
$ curl -s -X POST localhost:45678/accounts -d '{"username":"ada","password":"secret12"}' -H 'Content-Type: application/json'
$ curl -s localhost:45678/games/1/seats -H "Authorization: Bearer $TOKEN"
$ curl -s -X POST localhost:45678/games/1/seats/2 -H "Authorization: Bearer $TOKEN"
admin and observer are reserved and cannot be registered, in any case.
A seat can be taken until a turn of that game has resolved — so a game that has been set up but not yet played is still joinable, which is when somebody looking for a game to join would arrive. It can be given up in that same window and not after.
One account may hold several seats in one game. That is deliberate: it is
how one person plays both sides to try the game out without needing a second
person. Each seat stays a separate identity — its own army, its own programs,
its own view, and its own setup to commit — so holding both is no way round
the fog of war. Because a seat is not implied by the account, it
stays in the address: /games/1/players/2/... is seat 2, and two browser tabs
can be two seats.
The observer is the one account that may hold no seat. It is 1000 of every game and sees every unit of every player, so a seat it held would be a seat played with the whole board in view — and the account is shared. A claim from it is refused.
The administrator may take a seat like anybody, and a seat it holds is an ordinary seat: it sees what that seat may see and no more, it spends that seat's budget, and the turn waits for it. Nothing about being the administrator reaches into it. So one person with one account can set a game up and play every side of it, which is the quickest way to try a rule change end to end:
$ curl -s -X POST localhost:45678/sessions -d '{"username":"admin","password":"admin"}' -H 'Content-Type: application/json'
$ curl -s -X POST localhost:45678/accounts/current/password -d '{"current":"admin","new":"admin-secret"}' -H 'Content-Type: application/json' -H "Authorization: Bearer $TOKEN"
$ curl -s -X POST localhost:45678/games -d '{"gameno":"1"}' -H 'Content-Type: application/json' -H "Authorization: Bearer $TOKEN"
# set board, add player 1, add player 2, commit — as player 0
$ curl -s -X POST localhost:45678/games/1/seats/1 -H "Authorization: Bearer $TOKEN"
$ curl -s -X POST localhost:45678/games/1/seats/2 -H "Authorization: Bearer $TOKEN"
admin starts with the password admin and must change it before it may do
anything else, which is the first call above. From there, drive each seat at
its own address — in two browser tabs, or as two bgcclient sessions carrying
the same token — and commit them one at a time; the turn resolves when the
last of them has. Playing every side means seeing each side's blind view in
turn, which is not the game the rules describe; it is a way to exercise them,
not a way to play.
A role talking to a server has to say who it is. Started at a terminal with no token, it asks:
$ export BOARD_GAME_SERVER=http://127.0.0.1:45678
$ bgcclient 1 2
signing in to http://127.0.0.1:45678
username: ada
password:
signed in as ada (player)
bgcclient>
An account that must change its password is asked for a new one there, before the session is opened. A token skips the asking, which is what a script or a bot uses, since it keeps a password out of a shell history:
$ export BOARD_GAME_TOKEN=... # or bgcclient --token ...
$ bgcclient 1 2
A role started against a server with no token and nobody at the terminal —
a pipe, a script, matches/ — says a token is needed and exits rather than
opening a session it cannot act through.
Playing locally needs no account at all. Without BOARD_GAME_SERVER the
roles open the game directory themselves, and there is no server to prove
anything to. The account commands still work there; they just are not needed
to play.
Every role offers the same four, whatever else they differ on — who you are is not a thing one role may ask and another may not:
| command | what it does |
|---|---|
login [<username>] |
sign in; the password is asked for at a prompt, never typed as an argument |
logout |
end the token this session signed in for |
whoami |
which account this session is signed in as, and its kind |
passwd |
change the password of the account you are signed in as |
A token lives in the process and nowhere else: a session signs in each run, or
is given a token with --token or $BOARD_GAME_TOKEN. Nothing writes a
credential to a file.
The observer account sees every unit of every player, on every game — that is what the rules grant the observer, and it is what makes watching a game worth doing.
It is one shared account, and nothing stops somebody who holds a seat in a game from also signing in as the observer to see the whole board. That is deliberate rather than an oversight: the enforcement that would work costs live spectating, and this is a game played among people who would rather play it than win it. Change the observer password to whatever your group is comfortable sharing, and tell people what it shows.
The account store — accounts.sqlite3 or accounts/, depending on the
backend — sits beside games/ and is worth backing up with it. Losing it
makes every game unreachable over HTTP while leaving the games themselves
perfectly intact — a membership names a seat rather than being part of one —
so the recovery is to recreate the accounts and claim the seats again.
- TLS. Tokens and passwords cross the wire in clear, and
bgcapiserverbinds127.0.0.1by default. A home or club Wi-Fi is a trusted network, and playing in the same room on one needs nothing more than--host 0.0.0.0; anything reachable beyond one wants TLS in front of it, and a real WSGI server rather than Flask's development one.
For an editable install (the commands run the source in src/ rather than
a copy of it) plus the linter used in CI:
pip install -e '.[dev]'
The test suite wants pytest:
pip install pytest
pytest # whole suite (YAML backend by default)
BOARD_GAME_BACKEND=sqlite pytest # same suite over SQLite
pytest tests/test_basic.py # or one file
The suite runs the installed commands when they are on your path and falls
back to the module files when they are not, so it passes either way — but
tests/test_cli_installation.py skips unless you have installed the package,
and that is the file that proves the commands work at all.
Install editable, not plain, while you are working. A pip install .
copies the source into site-packages, and the suites that drive the roles
as subprocesses — tests/test_cli_*_surface.py and
tests/test_server_client_integration.py — then run that copy rather than
what you have just edited. They go green against the code you replaced, which
looks exactly like passing. pip install -e points them at src/.
matches/ plays games between doctrines through the real roles - one
bgcserver that registers the seats and commits, one bgcclient per seat
that sets its army up and commits, and the record read back through the
same client once the game has resolved. A doctrine is a file under
matches/bots/: the types it fields with their four statistics, the
program each type's units run, where its units stand and which carries the
flag - or nothing but programs, for a doctrine that keeps the stock army
and only tells it how to think. Once both seats have committed there is
nothing left for anybody to decide: the game plays itself to its end, and
the harness writes down what the record says. A game is played on the
game's own defaults: nothing names a board size or a budget, so it is the
8 x 8 board, 320 points a seat, and the stock army each seat opens with.
python matches/arena.py --game 221 --p1 matches/bots/flag_hunt.yaml \
--p2 matches/bots/lancers.yaml # one game
matches/series.sh # games 221-240
PARALLEL=4 matches/series.sh 225 226 # some, at once
Each game writes matches/logs/game_<n>.log - each seat's setup, the
board after every turn, what every turn did, every refusal, the outcome and
the final units - beside the roles' transcripts and a turn-by-turn history
in JSON. The series are written up in matches/RESULTS-*.md; the current
one is matches/RESULTS-ARMY-THAT-PLAYS.md, and the earlier ones say at their
head which rules they were played under. tests/test_match_harness.py
checks every doctrine's army and programs against the game's own rules
without playing a game; pytest -m slow tests/test_match_harness.py plays
a short game through the real roles as well.
Installing the package puts one command on your path per role:
bgcclient <gameno> <player_number>→ runs the player client interfacebgcserver -g <gameno>→ runs the game server/admin interfacebgcobserver <gameno>→ runs the neutral game observer
The three roles are three identities: 0 is the administrator, 1 to 999
are the players, and 1000 is the observer. bgcclient takes a player's
number and refuses one outside that range.
Each resolves a game against the directory you run it in, as games/_<gameno>.
Inside a session, show board, show types, show units, show players,
show pending, show program <type> and show turn <n> print tables.
Ending the command in json — show units json — prints the same thing as
one JSON document instead, so a session can be driven by something other
than a person:
bgcclient> show types
PLAYER NAME SYMBOL ATTACK HEALTH ENERGY COMPUTE PROGRAM COST
1 Cross X 1 10 10 2 yes 23
A type's program is written in a file and given to the type with
set program <type> <file>, during setup. show program <type> lists it
back with the ticks each line costs and the per-turn cap the type's compute
buys; GAME_RULES.md R10 is the instruction set and the tariff, and
PROGRAMMING_GUIDE.md is the guide to writing programs, with a reference
for every instruction.
Inside a session, Tab completes what can be typed next. That is the commands
the role you are running accepts, the show subjects it may ask for, the
trailing json — and the names only the game knows: your own units for
remove unit and set flag, and the types you have defined for add unit,
set program and show program. A unit you deployed a moment ago completes
without a reload. load board, load player and set program complete
paths.
You get line editing and within-session history with it: arrow keys, Ctrl-A, and up-arrow to recall what you typed before.
None of this happens when a session's input is not a terminal. Driven by a pipe or a file — which is how the test suite drives every role — a session prompts and answers exactly as it always has, with no editing and nothing but its own output in the transcript.
For completing the commands themselves, source the script for your shell:
source completions/bgc.bash # bash
source completions/bgc.zsh # zsh, after compinit
Then bgcclient <TAB> offers the game numbers under games/, a second <TAB>
offers the players registered in that game, and bgcserver -g <TAB> offers
game numbers. They are files to source; installing the package still puts three
commands on your path and nothing else.
The standalone test harness has no command of its own — it is developer tooling rather than something an installed game needs, so run it as a module:
python -m board_game_concept.test_suite
- add and
initgame.pyscript to do the initial setup of the game, strip that out of the server - separate all the DB storage out of the
GameData.pyclass and rename, create dedicated objects for data returned from the DB.
Note to check my clone... -R