Help & Guide — Board Game Shelf Calculator

Everything you need to use the app and to import / export your data. The app runs entirely on your device — there is no account and nothing is uploaded unless you use Cloud Sync.

Jump to:
Quick start The tabs Getting your games in Box dimensions Backup & Restore Cloud sync Import / export formats Where data is stored BGG API notes

Quick start

Add your games — My Games tab → import from BGG (cookie), or a CSV / XML file, or add manually.
Add box dimensions — needed for packing. Import them (see below) or type them in.
Define your shelves — Shelves tab (or use a Kallax / Billy / Detolf preset).
Pack — Packing Results tab → see what fits where, with a visual layout.
Back up — My Games → 💾 Backup (save all), and/or ☁ Cloud sync to share across devices.

The tabs

Tab	What it does
📦 My Games	Import / add games, edit box dimensions, mark expansions, backup & cloud sync.
🗄️ Shelves	Define shelf / storage dimensions. Presets for IKEA Kallax, Billy, Detolf.
📊 Packing Results	3D bin-packs your collection across all shelves; shows an engineering 3-view and a visual map.
🚛 Moving House	Packs the whole collection into cardboard moving boxes; estimates how many boxes you need.
✏️ Layout Editor	Pin specific games to a shelf and auto-fill the rest.
📋 My Layout	Save any packing result as a named layout; move games between containers.

Getting your games in

1. From BoardGameGeek (Live API)

BGG now requires you to be logged in to use its API. So:

Paste your BGG session cookie in My Games → Live API → BGG session cookie. This loads your collection (public or private). See BGG API notes for how to get the cookie.
A BGG API key (separate, optional) enables search and auto-fetch of dimensions. Paste it in ⚙ Settings → 🔑 API key (name + value). Register at boardgamegeek.com/using_the_xml_api.

2. From a file (CSV or XML)

CSV — export your collection from BGG (Collection page → Export → CSV), then My Games → CSV tab.
XML — a BGG collection XML, or a "collection with dimensions" export. My Games → XML tab.

3. Manually

Use the "Add game" form to type a name and dimensions directly.

Box dimensions

Packing needs each game's box size (width × depth × height, stored in mm). Ways to get them:

A "collection with dimensions" XML (e.g. a bgg.xml export that has <width>/<depth>/<height> on each game) — import via the XML tab; sizes come in with the names.
A dimensions file (CSV or JSON) — import via 📂 Restore backup → "Dimensions only", which merges sizes into your existing games by BGG id / name.
BGG API key (⚙ Settings → 🔑 API key) — auto-fetch from BGG's version data (partial coverage — not every edition has sizes).
Manually — type them in the My Games list (the "Fix Missing Dimensions" panel helps focus on gaps).

Tip: any value imported in inches or cm is auto-converted to mm.

Backup & Restore

One JSON file holds everything — games, dimensions, shelves and saved layouts.

💾 Backup (save all) → downloads shelf-calculator-backup.json.
📂 Restore backup → pick a JSON backup; it then asks what to import:
1. Everything — replace games, shelves & layouts
2. Collection only — games + shelves
3. Dimensions only — merge box sizes into your current games (matched by BGG id / name)
4. Layouts only — just the saved layouts

Cloud sync

Move your data between your PC and phone without files. In My Games → ☁ Cloud sync:

On the first device, type a secret sync code (≥ 6 characters) and click ⬆ Save to cloud.
On the other device, type the same code and click ⬇ Load from cloud.

The sync code is the password — anyone who knows it can read or overwrite that data. Use something long and unique. Only board-game data is stored.

Import / export formats (reference)

Backup JSON

What 💾 Backup writes and 📂 Restore reads:

{
  "v": 2,
  "games": [
    { "id": 1, "bggId": "13", "name": "Catan",
      "w": 295, "d": 295, "h": 75, "qty": 1,
      "isExpansion": false, "inBaseBox": false }
  ],
  "shelves": [ { "id": 1, "name": "Kallax", "w": 330, "d": 380, "h": 330 } ],
  "nextId": 2,
  "layouts": [ /* saved layouts */ ]
}

Dimensions w/d/h are in millimetres. bggId is used to match games on a "Dimensions only" import.

Dimensions CSV

The importer is flexible: it auto-detects the delimiter (, ; or tab), the unit (inches / cm / mm), and these column names:

Meaning	Accepted column headers
BGG id	`bggid`, `objectid`, `id`
Name	`name`, `objectname`, `title`
Width	`w`, `w_mm`, `width`
Depth	`d`, `depth`, `thickness`
Height	`h`, `height`, `length`
Optional	`qty`, `isExpansion`, `inBaseBox`

Example:

bggId,name,w_mm,d_mm,h_mm
13,Catan,295,295,75
9209,Ticket to Ride,295,295,70

BGG XML

Both BGG shapes are accepted on the XML tab:

Collection — <item objectid="…"><name>Catan</name>…</item>. Dimensions only if the export includes <width>/<depth>/<height> (in inches).
Thing — <item id="…"><name type="primary" value="Catan"/>…<versions>…<width value="…"/>…</versions></item>.

BGG XML API URLs

The data is split across two endpoints (replace YOU with your username; the app fills these in for you in the XML tab and ⚙ Settings):

Owned base games — https://boardgamegeek.com/xmlapi2/collection?username=YOU&own=1
Owned expansions (a separate download — the default call excludes them) — https://boardgamegeek.com/xmlapi2/collection?username=YOU&own=1&subtype=boardgameexpansion
Add complexity "weight" + stats — append &stats=1 to a collection URL → adds <averageweight>, player counts, rating. (Note: BGG "weight" = rules complexity 1–5, not physical mass.)
Box dimensions are NOT in the collection feed — they live per-edition on the thing endpoint: https://boardgamegeek.com/xmlapi2/thing?id=13,926,…&versions=1 → <width>/<length>/<depth> in inches. The app fetches these automatically after an import (🔄 Fetch from BGG / auto), mapping width→W, depth→D, length→H, preferring your owned edition.

Where your data is stored

Web / installed app (PWA) — in the browser's localStorage for this site. It's per-device and per-browser — Chrome and Firefox don't share, and phone and PC don't share, unless you use Backup files or Cloud sync.
Windows desktop app — in files under %APPDATA%\shelf-calculator\.
Clearing your browser's site data, or uninstalling, removes the local copy — keep a Backup or use Cloud sync.

BGG API notes

Since late 2025 BGG locked its XML API behind authentication (the "XML API registration" change):

Your own collection works with just a logged-in session cookie — no registration needed.
Search and box-dimension lookup need a registered-app API key (register on the BGG site, then paste it in ⚙ Settings → 🔑 API key).

Getting your session cookie

In a desktop browser logged in to boardgamegeek.com: press F12 → Application → Cookies → https://boardgamegeek.com. Copy the values of bggusername, bggpassword and SessionID and paste them into the app as:

bggusername=YOU; bggpassword=...; SessionID=...

Treat the cookie like a password — it grants access to your BGG account until it expires. Don't share it. Re-paste a fresh one if loading stops working.

Board Game Shelf Calculator — local-first, no account required.