Super Auto Pets: The Board Game — Online
A web app for playing the Super Auto Pets board game remotely, at 2, 4, or 6 players. Play friends by room code, fill any empty seat with a computer opponent (easy / medium / hard), or play solo against a table of them.
Stack
- Backend: Go (stdlib-first). Pure game engine in
internal/game, WebSocket sync viacoder/websocket, persistence as JSON blobs in SQLite (modernc.org/sqlite, no cgo). - Frontend: React + Vite + TypeScript in
web/. DOM/CSS card rendering and battle animations. - Tasks: mise (
mise.toml).
Quick start
mise run install-web # once: npm install
mise run serve # build frontend + server, run on :8080
Open http://localhost:8080, host a game, and join from another browser (or incognito window) with the 5-letter code.
Development
mise run dev # Go server on :8080 + Vite hot reload on :5173
mise run test # Go tests (game engine)
mise run check # go vet + frontend type-check
During development open the Vite URL (http://localhost:5173); it proxies
/api (including the WebSocket) to the Go server.
Configuration
Set via environment or a .env file (see .env.example):
| Variable | Default | Purpose |
|---|---|---|
DATA_DIR |
data |
Directory holding the SQLite DB |
PORT |
8080 |
HTTP port |
STATIC_DIR |
web/dist |
Built frontend to serve |
DEBUG |
off | Unlocks the in-game buy-any-card panel |
Debugging a game that went wrong
Any game can be dumped as a debug report: the full state (every deck card by card, the shop row and the order of the remaining tier decks, discards, pending choices, each player's banked Mana/Trumpets/apples), the round's battles with their lineups and the dice they rolled, and the entire event log.
In game, the ⋯ menu has 🐛 Report a bug: a note field, a
Download report button, and Copy as text. It works on any server, DEBUG
or not, so a bug hit in a real game can actually be reported. That does hand the
player their opponents' hands and the shop deck order — an accepted trade, since
a report only ever goes to someone seated at that table (GET /api/debug/report, same credentials as the WebSocket).
From the command line, against the server's database:
mise run report # list recent games
mise run report -- QWERT # the report, as text, for reading
mise run report -- -json -out internal/game/testdata/bug.json QWERT
The JSON form is the useful one, because it replays. Drop it in
internal/game/testdata/ and the battle re-runs exactly — same lineups, same
dice, same events, right down to the log text:
rep, err := LoadDebugReportFile("testdata/bug.json")
res, err := rep.ReplayBattle(0) // 0 = the round's first pairing
if res.WinnerSeat != 1 { // assert what *should* have happened
t.Fatalf("expected seat 1 to win, got %d", res.WinnerSeat)
}
That works because every battle records the randomness it consumed
(BattleResult.Draws) alongside what it started from (Lineups, Inputs), so
a result is replayable long after the round cleared those banks. rep.Game()
hands back the whole game if the bug wasn't in the battle — carry on from the
shop, replay a different pairing, or read a deck card by card. The text form of
the report ends with a paste-ready version of the test above.
Rules implemented
Six rounds, each with its own shop tier deck. Per round:
- Shop — each player has 3 gold and players alternate actions: buy one of 4 face-up cards (1 gold — the only action that costs anything); sell any number of hand cards for free (each becomes an 🍎 apple, +1 power food, and Sell effects fire); or trade in 3 same-suit pets (the Triple action, also free) to pick 1 of the top 2 cards of the next tier's deck — Triple effects fire on the traded cards and the received pet's Buy effect fires. Passing is a final action, only legal at 5 pets or fewer: it forfeits remaining gold and ends that player's shopping for the round. The shop closes once everyone has passed.
- Arrange — Battle Prep effects fire first (e.g. Giraffe hands out apples), then players secretly order their decks. Food cards apply to the next pet after them; trailing foods are wasted. A pet only benefits from its last-applied perk (e.g. Honey, Garlic).
- Battle — automatic stack machine. Cards reveal off the top of each deck until a pet is in play. Play effects fire on reveal (rocks roll a d6 with faces 0/0/1/1/2/2 and hit the opposing pet before the clash; Skunk strips foods; Wolverine steals apples; Chili mills the enemy deck). The two pets simultaneously deal their full power to each other as damage markers; a pet with markers ≥ power faints (attack never drops while wounded). Faint effects push summons onto either deck, recycle apples (Dodo), set aside delayed/recurring/conditional rock volleys (Badger, Blowfish, Snake, Crocodile), raise auras (Turkey, Mammoth), or arm a team shield (Turtle). Survivors that took damage fire Hurt effects (Peacock, Camel, Gorilla). Shields (Turtle/Gorilla/Melon) block whole hits, Garlic shaves 1 per attack, and Scorpion KOs anything its clash attack manages to hurt. Hippo heals when enemies faint; Rhino rocks each enemy pet as it's played. A clash that changes nothing is a stalemate: both pets faint so the ones behind them can settle it. Last player able to field a pet wins: 1 trophy for rounds 1–5, 2 for round 6. A battle that runs both sides out is a draw, and draws award nothing.
Apples and bees are temporary: they leave your deck after the battle. Most trophies after round 6 wins.
4 & 6 player mode
A game seats an even number of players — 2, 4, or 6 — so everyone has an opponent every round. A lobby with an odd number of humans fills the gap with a bot; any seat can be a bot, so a table of one human and five computers is just as valid as six humans.
Above two players the shop is shared but the battles are not: each round
splits the table into pairs, and every pair fights its own battle
simultaneously. The pairings come from the fixed table printed in the rulebook
(internal/game/schedule.go) — a round-robin that runs everyone past everyone
before replaying earlier rounds to fill out the six. All of it is public: you
can replay any table's battle, not just your own, and peek at any player's
lineup afterwards.
Two rules change with the bigger table:
- First shopper — at two players the priority token does double duty (shops first, acts first in battle) and passes from a winner to the loser. With more players it's a separate token that starts at seat A and walks one seat along each round, while every battle flips its own first player.
- Packs — the rulebook asks for one pack per pair (2 packs for 4 players, 3 for 6). The host picks them in the lobby and their tier decks shuffle together: all the tier 1 cards into one tier 1 deck, and so on. Two players may combine packs too, for a deeper shop.
Ties on trophies are settled by counting back from the last round: whoever won round 6 takes it, else round 5, and so on. Players with identical records share the victory.
Packs
Three card packs are playable, and the host combines one or more of them in the lobby. Each pack is six tiers, one per round, and every pet ships as two copies.
Turtle pack
| Tier | Pets | Food |
|---|---|---|
| 1 | Ant, Cricket, Duck, Otter, Mosquito, Fish | — |
| 2 | Worm, Flamingo, Peacock, Swan, Rat, Spider | Honey |
| 3 | Dog, Dolphin, Giraffe, Camel, Sheep, Dodo, Badger | Garlic |
| 4 | Squirrel, Turtle, Rooster, Bison, Blowfish, Skunk, Hippo | Pineapple |
| 5 | Monkey, Rhino, Crocodile, Scorpion, Seal, Shark, Turkey | Chili |
| 6 | Gorilla, Fly, Leopard, Mammoth, Cat, Snake, Wolverine | Melon |
Golden pack
| Tier | Pets | Food |
|---|---|---|
| 1 | Groundhog, Pied Tamarin, Chipmunk, Cone Snail, Bulldog, Opossum | — |
| 2 | Black-Necked Stilt, Lizard, Hercules Beetle, Stoat, Desert Rain Frog, Honduran White Bat | — |
| 3 | Guinea Fowl, Surgeon Fish, Osprey, Anteater, Bear, Royal Flycatcher, Flea | Avocado |
| 4 | Saiga Antelope, Vaquita, Poison Dart Frog, Manta Ray, Slug, Cockatoo, Manatee | Potato |
| 5 | Nyala, Nurse Shark, Giant Isopod, Blue-Ringed Octopus, Raccoon, Fire Ant, Macaque | Durian |
| 6 | Highland Cow, Wildebeest, Grizzly Bear, Catfish, Komodo, Bird of Paradise, German Shepherd | Tomato |
The Golden pack adds mechanics the Turtle pack doesn't have:
- Trumpets — an ephemeral battle resource pets earn and spend mid-fight.
- Golden Retriever — once per battle, a side that runs out of cards but still holds Trumpets fields one, its power equal to those Trumpets.
- Avocado — a persistent set-aside token you can discard in place of gold.
- Nurse Shark — on entry it spends every Trumpet it can (up to 3), throwing two rocks at the enemy per Trumpet spent.
- Cockatoo — a shop-time reveal, plus Manta Ray's free first buy, Blue-Ringed Octopus' per-buy apples, and more.
Unicorn pack
| Tier | Pets | Food |
|---|---|---|
| 1 | Alchemedes, Cuddle Toad, Pengobble, Barghest, Basilisk, Baku | — |
| 2 | Thunderbird, Gargoyle, Frost Wolf, Mothman, Nightcrawler, Bigfoot | Fairy Dust |
| 3 | Fur-Bearing Trout, Calygreyhound, Tatzelwurm, Skeleton Dog, Mandrake, Lucky Cat, Slime | Water of Youth |
| 4 | Roc, Chimera, Kraken, Unicorn, Abomination, Rootlin, Fairy | Health Potion |
| 5 | Kitsune, Pixiu, Red Dragon, Amalgamation, Vampire Bat, Werewolf, Loveland Frogman | Big Mana Potion |
| 6 | Sleipnir, Sea Serpent, Bakunawa, Manticore, Team Spirit, Behemoth, Quetzalcoatl | Cornucopia |
The Unicorn pack adds two mechanics the others don't have:
- Mana — a persistent resource (unlike ephemeral Trumpets): pets earn it in the shop (Cuddle Toad, Thunderbird, Roc) and in battle (Alchemedes, Fur-Bearing Trout, Kitsune, Tatzelwurm per rock blank), and spend it to power abilities (Pengobble, Gargoyle, Sea Serpent, Bakunawa; Sleipnir's very Power equals your Mana). It carries over between rounds until spent, so you can bank it up.
- Ailments — temporary debuff cards attached to a pet during battle, removed at round end like apples. Spooked lowers the pet's clash attack (−1 each, min 0); Exposed raises the damage it takes per hit (+1 each). They stack, can be added to the enemy pet or dropped on top of the enemy deck (Frost Wolf, Slime, Kraken, Red Dragon). Baku shrugs off the first one it takes, Unicorn turns the next friendly one into apples, and Manticore makes enemy ailments count for more.
- Plus a game-wide discard pile the higher tiers reach into (Chimera, Abomination), pet-recycling (Fairy, Loveland Frogman's bounce), and shop tricks — Bigfoot's deck peek, Water of Youth's upgrade, Quetzalcoatl's reveal.
Layout
cmd/server/ entrypoint
cmd/report/ debug report dumper (reads the DB directly)
internal/game/ rules engine (pure, fully tested)
internal/ai/ computer opponent (decides from a player View only)
internal/server/ HTTP + WebSocket rooms; drives bot turns
internal/store/ SQLite persistence
internal/env/ .env loading
web/ React frontend
The computer opponent
Any seat can be a bot (Player.IsBot); humans and bots are interchangeable
to the engine, so a table can mix them freely. The AI in internal/ai never
touches the Game — it decides from a game.View, the same per-player state
a human client is sent, plus a persisted memory of public observations
(battle lineups, the event log, shop row changes). It cannot see your deck
order, hidden trade picks, or the shuffled shop decks. It scores candidate
moves by Monte-Carlo battle rollouts (game.SimulateBattle) against sampled
guesses of your deck and ordering, blended with a long-term deck-value
heuristic; difficulty tunes a softmax over the scored moves plus the rollout
budget.
At a bigger table it keeps a model of every seat, not just one rival — it will face each of them eventually, and every battle is fought in the open — but plans each round against the specific opponent the schedule pairs it with. Its card counting spans the whole table's known cards and the combined contents of the packs in play.