A Billion Suns Companion
An unofficial mobile companion for the tabletop game A Billion Suns: a campaign tracker, an in-game battle tracker, and ship reference cards.
Open the GitHub Pages site on your phone and choose Add to Home Screen to install it. It works offline, and your campaign is saved on the device. Use Overview → Export backup to move a campaign between devices. To show your campaign to someone else, use Share demo copy instead: it leaves out your sign-in, Google account, team and campaign codes, and device names (photos are optional), and they load it with Import backup.
-
Overview: corporation details and campaign status, rivals and standings, notes and backup/import. Capital and reputation are calculated from the log and unlocks. Rivals can join an online campaign by code (see setup below) or swap files with Share my corporation; either way you can view each other's fleet stats.
-
Battle: in-game tracker with:
- the contracts in play and their full reference cards;
- round, scale and the opponents in this game (rivals or typed names);
- the command helm (Seize Initiative / Jump In / Tactical tokens, each with expandable rules);
- credits ledger;
- battlegroup requisitions with damage and ship-loss tracking. In an online campaign, damage can be credited to the opponent's battlegroup that dealt it, and Log attack records attacks with no damage, hits on contract objects and jump points, or damage to opponents not using the app.
Use "Finish game → Log" to record the result. A game's result is its final credits plus "I had the most credits" (ties count), which the app checks once every opponent has logged the game.
-
Stats: stat cards for your unlocked ships, or toggle to show all ships.
-
Unlocks: ship classes (tap a name for its stats) and competitive advantages (tap ⌄ for full rules). Can buy now hides what you can't afford or research yet.
-
Log: per-game log. Game summaries and campaign stats show damage dealt and attacks per battlegroup and ship class; tap Cost/Lost to switch between credits and ship counts.
The Rules button (top bar) searches glossary.js: short unofficial summaries with rulebook page numbers, for the group's own use alongside the rulebook. Battle also tracks contract cards left and exhaustion (with the game-end check) and keeps the screen awake during games. The Log has campaign stats and game photos (stored on the device and included in backups). Overview can print the campaign sheet or save it as a PDF.
Rules text in rules.js is paraphrased from the rulebook, with FAQ v1.2 and Warzone errata applied. It is not copied verbatim. Contract cards in contracts.js come from the group's contract reference cards.
Online campaigns (one-time setup)
Online campaigns use a free Google Firebase project that the group owns. Until it's set up, the app works the same but only offers sharing by file.
- Go to https://console.firebase.google.com, sign in with a Google account and Create a project (any name, e.g.
abs-companion). Google Analytics isn't needed.
- Build → Authentication → Get started → Sign-in method → Anonymous → Enable → Save.
- Build → Firestore Database → Create database → pick a location near you → Start in production mode.
- In Firestore, open the Rules tab, replace everything with the contents of
firestore.rules from this repo, and Publish.
- Project settings (gear icon) → Your apps → the web icon
</> → register an app (any nickname, no hosting). Copy apiKey and projectId from the config it shows into sync-config.js.
- Optional Google sign-in (cloud backup, keeping your corporation across phones): Authentication → Sign-in method → Google → Enable, copy the Web client ID into
googleClientId in sync-config.js, add your Pages domain under Authentication → Settings → Authorized domains, and add it (https://<you>.github.io) to Authorized JavaScript origins of the auto-created OAuth web client in Google Cloud → APIs & Services → Credentials.
Console menus move around; the direct pages are console.firebase.google.com/project/<projectId>/authentication/providers, /firestore, /firestore/rules and /settings/general.
Then commit and push. One player taps Overview → Rivals → Start online campaign and shares the code; everyone else taps Join with that code.
How it works: each corporation is one document under campaigns/{code}/corps/. Phones sign in anonymously, so nobody needs an account; signing in with Google is optional and links to that same account, adding a cloud backup under users/{uid}/backup/ (photos stay on the phone). Anyone who knows the code can read that campaign, but only the phone that created a corporation can change or remove it. The sign-in travels with Export backup, so moving to a new phone keeps your corporation. Firebase's free tier is far more than a gaming group needs.
Teams & devices: teammates can share one corporation, and one person can use the same corporation on several devices (phone + iPad). One device taps Overview → Team & devices → Share this corporation and shares the TEAM-XXXX-XXXX code; the others tap Join. Each device gives a name (changeable later); one person's devices are listed once. Signing in with Google does this automatically: the account remembers its shared corporation (users/{uid}/backup/link), so another device signed in with the same account joins it without a code (asking first if that device already has a different corporation). Any teammate's phone can log games, buy unlocks and edit notes; changes sync between phones (stored in teams/{code}) and are merged so simultaneous edits aren't lost. The Battle tab, photos and rivals stay on each phone. In an online campaign the team shows as one corporation with all its CEOs.
ABS_Campaign_Tracker.html is the printable tracker. A filled-in "Save a copy" file from it can be imported into the app.
When you change app files, bump the version (e.g. 0.11.0 → 0.12.0) in both sw.js (VERSION) and app.js (APP_VERSION) so installed copies update.
