Help & Guide

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.

Quick start

1. Add your games — My Games tab → import from BGG (cookie), or a CSV / XML file, or add manually.
2. Add box dimensions — needed for packing. Import them (see below) or type them in.
3. Define your shelves — Shelves tab (or use a Kallax / Billy / Detolf preset).
4. Pack — Packing Results tab → see what fits where, with a visual layout.
5. 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 token (separate, optional) enables search and auto-fetch of dimensions. 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 token — 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).

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:

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

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>.

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 token (register on the BGG site).

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=...

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