Help & Guide

← Back to app

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 Finding games (filters) Shelves & boxes How packing works Layout Editor & hand-arranging Backup & Restore Cloud sync Import / export formats Where data is stored BGG API notes

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, auto-fetch from BGG, or type them in the πŸ“ Fix Dimensions tab.
  3. Define your shelves β€” My Shelves tab (or use a Kallax / Billy / Detolf preset).
  4. Pack β€” Packing Results tab β†’ see what fits where, with a 2D map and a 3D view.
  5. Save & fine-tune β€” πŸ’Ύ Save as Layout, then open it in the ✏️ Layout Editor to hand-arrange the last boxes.
  6. Back up β€” My Games β†’ πŸ’Ύ Backup (save all), and/or ☁ Cloud sync to share across devices.

The tabs

TabWhat it does
πŸ“¦ My GamesImport / add games, filter & sort the collection, edit a game's profile (size, expansion flag, note), backup & cloud sync.
πŸ“ Fix DimensionsFocused side-by-side editor for typing box sizes β€” list of games on the left (⚠ Missing only / All games), entry panel on the right.
πŸ—„οΈ My ShelvesDefine shelf / box dimensions β€” outer size, wall thickness, type, and the wider rim of a tapered plastic tote. Presets for IKEA Kallax, Billy, Detolf.
πŸ“Š Packing Results3D bin-packs your collection across all shelves; per-shelf fill %, 2D map, 3D view, ↔ Swap / πŸ—‘ Make room, and πŸ’Ύ Save as Layout.
πŸš› Moving HousePacks the whole collection into cardboard moving boxes and estimates how many boxes you need. Box types here are session-only β€” they are not saved to My Shelves.
✏️ Layout EditorFull editor for one layout: move games between boxes, resize a box, choose a packing strategy, and βœ‹ Arrange each game by hand in 2D and 3D.
πŸ“‹ My LayoutsYour saved layouts β€” container cards (A–Z, with expansions stored inside a base-game box listed under it), 🏠 Rooms β€” tabs under the Saved Layouts title (All / each room / Unsorted / οΌ‹ Add room); picking a room lays the same layout list out on that room grid (columns Γ— stacking levels, bottom row = the floor). βš™ Room setup picks which layouts are in the room, ✏️ Arrange drags them into place, a big 3D view, unassigned games, rename / note / open in the editor.

Getting your games in

1. From BoardGameGeek (Live API)

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

2. From a file (CSV or XML)

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:

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

Which games "need" dimensions

A game is only counted as missing dims when the packer actually needs its size. Expansions marked stored in the base game's box and games you have excluded are skipped β€” they are never packed on their own, so they don't need a size and they don't appear in the ⚠ counter.

Measuring boxes to submit to BGG? Use My Games β†’ Missing dims β€” incl. in-box. It ignores that rule and lists every game and expansion with no numbers on record, in-box and excluded included, so you can measure them anyway. It also overrides the ☐ Hide in-box exps checkbox.

Finding games (filters & sorts)

The filter bar above the My Games table. β†Ί Reset clears search, every filter and the sorting.

ControlOptions / what it does
SearchMatches the game name.
TypeAll / base games only / expansions only.
DimensionsAll dims Β· Has dimensions Β· Missing dims (what the packer needs) Β· Missing dims β€” incl. in-box (raw: anything with no W/D/H at all).
BGG infoβŒ› BGG info missing / βœ“ loaded β€” whether the full BGG details (players, time, categories, edition languages) have been pulled for that game.
Edit stateHand-edited dims β€” every size you typed yourself (the ✎ games). Use this to review your own numbers, e.g. before submitting them to BGG. Or Not hand-edited for everything still on BGG's values.
EditionFilter by a BGG edition language recorded on the game.
☐ Hide in-box expsHides expansions stored inside a base game's box.
SortName, size, volume, group by exact / similar size, and recently hand-edited first. Clicking the W / D / H column headers sorts by that dimension.

The app records that you edited a size, but not what BGG originally said β€” so it can list your hand-edited games, not the difference from BGG's value.

Shelves & boxes

You enter outer dimensions plus a wall thickness; the usable interior is computed as outer βˆ’ 2Γ—wall on each axis. That inner size is what the packer fills, and it's the big number on the shelf card (the outer size and wall are shown underneath).

Using a shelf in a layout does not consume it β€” the layout takes a copy. Your shelves stay in πŸ—„οΈ My Shelves. (Two consequences: an empty box is dropped from a layout when you save it, and resizing a shelf later does not resize boxes in layouts you already saved.)

How packing works

  1. Every game is expanded by its quantity. Games with no dimensions, games in a base box, and excluded games are skipped β€” and reported in the summary rather than silently dropped.
  2. Shelf 1 is packed with everything, then shelf 2 with what's left, and so on. Shelf order matters β€” the first shelf gets first pick. Whatever survives every shelf is listed under Games that didn't fit.
  3. Inside one box, all 6 orientations are tried per game, biggest first, each placed at the lowest position it fits. Tapered totes use a separate packer that can stand boxes on edge against the slanted wall.

Store as changes which orientations are allowed:

The gap is applied once between neighbours, not around every face β€” two 60 mm boxes at a 5 mm gap sit at 0–60 and 65–125.

Fill % is volume-based, so 60 % can already be physically full β€” boxes don't tessellate. 3D packing is a hard problem and a careful human still beats the algorithm on the last box or two; that's what βœ‹ Arrange is for.

Layout Editor & hand-arranging

Open a saved layout in the ✏️ Layout Editor (or from πŸ“‹ My Layouts β†’ ✏️ Open in Layout Editor). Per box you can rename/resize it (πŸ“ Edit box), move games in and out, set the packing strategy, and open βœ‹ Arrange to place each game yourself.

In βœ‹ Arrange

If you change a game's box size after saving a layout, reopening the layout updates that game inside the arrangement automatically (keeping its orientation) and tells you how many games changed. Check the overlap banner afterwards β€” a box that grew may now clash with its neighbours.

Backup & Restore

One JSON file holds everything β€” games, dimensions, shelves and saved layouts.

Cloud sync

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

  1. On the first device, open βš™ Settings, press 🎲 Generate for a strong secret sync code (or type your own, β‰₯ 6 characters) and click β˜β¬† Save.
  2. On the other device, enter the same code in βš™ Settings and click β˜β¬‡ Load.

If the cloud copy was saved from another device since this one last loaded or saved it, β˜β¬† Save asks before overwriting it. Each save also keeps the one before it β€” βš™ Settings β†’ ↩ Load previous cloud save brings it back.

The sync code is the password β€” anyone who knows it can read or overwrite that data. Use 🎲 Generate rather than a word you picked. 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:

MeaningAccepted column headers
BGG idbggid, objectid, id
Namename, objectname, title
Widthw, w_mm, width
Depthd, depth, thickness
Heighth, height, length
Optionalqty, 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:

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):

Where your data is stored

BGG API notes

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

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.