Get layout suggestions

By this stage, your game.bgi.yaml describes the box, material, contents, and which contents belong in each assembly. You have decided what stays together; now let BGI choose the compartment arrangement. If those inputs are not ready, start with Describe the contents and storage.

Leave the arrangement open

An automatic grid needs the IDs of its contents and an automatic interior. This is the assembly from Full example:

assemblies:
  - id: insert
    kind: grid
    construction: open_grid_box
    assembly: glue_allowed
    members: [cards, tokens]
    interior:
      id: compartments
      kind: auto

members assigns the storage requirements to this grid. kind: auto inside interior leaves their compartments for BGI to arrange. It does not ask BGI to decide which pieces should share a compartment: use a storage group for that.

BGI can turn a requirement only in the orientations you allow. A card stack might allow both flat orientations, for example, but upright storage needs an explicit choice. The declared allowances become part of the required space. BGI then adds floors, walls, dividers, and joints and checks the resulting outside size against the game box.

Set the scope of the search

For a single grid, add this top-level section:

layout:
  mode: auto
  construction_mode: full_box
  search:
    budget: 100
    top_k: 3

Setting	Decision it makes
mode: auto	Ask for candidate layouts before building.
construction_mode: full_box	Plan one grid. The name does not mean BGI expands every compartment to fill unused box space.
budget	Maximum number of candidate attempts, including rejected attempts. 100 is a starting point for this small project.
top_k	Maximum number of successful candidates to save. 3 gives you a few alternatives to compare.

Start with as few layout restrictions as the game needs. Allowed orientations and sensible compartment sizes give BGI flexibility. Fixing every position can remove useful alternatives. If one region really must stay in place, use manual and mixed layouts to express that constraint.

For several grids or a grid beside existing containers, use construction_mode: local_groups. You still assign the contents of each grid; BGI can size and place their automatic interiors together. Example 39 shows separate card and token areas beside a fixed dice area and an existing box. This is a placement of grids, not an automatic decision to turn them into removable trays or add layers. Arranging designed trays uses a separate workflow.

For one removable tray, set kind: tray on that assembly, add positive side_clearance_mm: [left, right, front, back], and use construction_mode: local_groups. BGI then searches for separate compartments inside the tray and leaves space to lift it out. Example 75 shows this limited workflow. You still specify the tray’s members; BGI does not yet decide how many trays to make or stack them from a list of components.

Run the search

Run this command from the folder containing your project:

bgi game.bgi.yaml

BGI calculates the required storage space, tries layouts, and builds every retained candidate. The default output is build/<project-id>; repeat the command after editing the YAML to refresh it.

Open build/<project-id>/README.md. It shows the top-down layout and rendered assembly for each candidate and links to its full cutting bundle and saved .json recipe. report.md retains the detailed search and rejection information. For automation that needs only the search artifacts, use bgi solve game.bgi.yaml --output layouts separately.

Continue with Choose and build a layout to compare the suggestions and inspect the generated design.

If no suggestion works

If the report contains no candidates, look at the rejection reasons before changing the search budget. Check the space reserved above the insert, material thickness, permitted orientations, and the size of each storage requirement. A card stack that could lie in either direction may have been restricted to one; an oversized token compartment may reflect an estimate rather than a measurement.

When a reported compartment size is surprising, the requirements command can show how BGI calculated it. For other errors, use diagnostics.

If all saved candidates fit but are awkward to use, change a storage decision: split a card deck, keep a player set together, or preserve a fixed region. Then search again. Increasing the budget only helps BGI try more arrangements within its supported patterns; it cannot introduce a new construction type.