Project file reference

A BGI project is a YAML file with schema_version: 1. Describe contents and storage explains how to make one for your game; Full example provides a complete automatic project to copy. This page is a field reference.

Use spaces for indentation. Unknown fields, duplicate keys, aliases, anchors, executable tags, and multiple YAML documents are rejected. IDs start with a lowercase letter and use lowercase letters, digits, -, or _; they must be unique. Write lengths as unquoted millimetre numbers with up to three decimals.

Root map

Field	Role
schema_version, project	Required version and {id, name}.
box	Required inner_mm: [x, y, z]; optional four side clearances and top reserve.
material	Required bundled profile; optional overrides, including measured thickness and kerf.
components	Storage descriptions. Required for automatic compartment design; optional for manual geometry without contents assignments.
groups	Optional arrangements of requirements that share one compartment.
assemblies	Required array of constructed grids or trays. It may be empty for a container-only manual project.
containers	Optional existing closed boxes, placed by outside size.
layout	Required manual placements or auto search.
manufacturing	Optional sheet stock and spacing for arranging cut parts.
readme, preview, reference_data	Optional bundle description, display colors/textures, and explicit research provenance bindings.

Components and groups

Every component has an id and a kind. Choose the kind from the information you have:

Kind	Fields and meaning
explicit	clear_min_mm gives minimum usable space; orientations: [xy, yx] allows either footprint direction.
cards	count, card_outer_mm, split_counts, allowance_total_mm, and orientations. Use either effective_thickness_mm or stack_measurements_mm, one height for each split. Split counts must total the deck count.
objects	count, object_outer_mm, three-axis arrangement, object_gap_mm, allowance_total_mm, and permitted axis permutations in orientations. The arrangement reserves one space; it does not create individual pockets.
loose	Either measured_bulk_volume_cm3 or solid_volume_cm3 with fill_fraction; also footprints_mm, allowed_heights_mm, and allowance_total_mm. Volume is in cm³; lengths remain in mm.

Card orientations are flat_xy, flat_yx, upright_x, and upright_y. Object orientations use axis permutations such as xyz or yxz. Allowance vectors add a total amount on each axis, not that amount on each side. See dimensions and clearances.

Every component kind can use instances to name separate copies of a template. A split deck creates requirement IDs such as cards-1 and cards-2; a single stack keeps cards. An assembly’s members can name the source component to include all its requirements.

groups[] combines two to twenty requirements into one shared storage space:

layout	Arrangement
row	Members in order along X or Y, with a stated gap.
positioned	Each member at an explicit origin.
stack	Compatible members in a vertical stack.
bulk	Loose pieces sharing an explicitly measured mixed volume.

A group ID replaces its member IDs in the assembly’s members and the compartment’s contents. A group creates no dividers. Project setup shows a card-group example; storage and construction explains the relationships.

Existing containers

Each containers[] entry requires id, outer_mm, four side_clearance_mm values in left/right/front/back order, and top_clearance_mm. Supply measured removal clearances, even if a value is zero. Omitted box side clearances and top reserve, by contrast, default to zero.

Container rotations_deg may list 0 and/or 90; when omitted, both are allowed. An optional inventory records contents already inside. Those records do not create new compartments or establish that the contents fit. Use the outside envelope of a self-contained container; BGI does not construct its walls.

Assemblies and compartment trees

A constructed assembly uses kind: grid or kind: tray, construction: open_grid_box, and assembly: glue_allowed. Its interior is either a compartment tree or, for a supported automatic grid or single tray, {id, kind: auto}. members identifies the storage requirements assigned to it.

Tree node	Fields
Compartment	{id, kind: compartment, clear_mm}; may name contents and an outer-wall access_cutout.
Split	id, kind: split, axis: x or y, clear_mm, first, and second.

Parent dimensions include the divider between children. Clear dimensions exclude outer walls and floor. See the manual layout guide for a complete replacement tree and the size calculation. Supported trees produce straight splits, T junctions, and aligned crossings; arbitrary divider networks are not supported.

Automatic and manual layouts

layout.mode chooses one workflow. An automatic project can retain fixed parts; it need not leave every decision open.

Setting	Meaning
construction_mode: full_box	One constructed grid, without existing containers. It does not expand compartments to fill all spare box space.
construction_mode: local_groups	Several constructed assemblies and/or existing containers, each with a placement.
mode: auto	Search for candidate layouts. Requires search: {budget, top_k}.
mode: manual	Use the declared compartment trees and placements.

Automatic search accepts a budget of 1–100,000 attempts and returns up to ten candidates. It supports fixed_order, one-based fixed_slots, fixed_origin_mm, fixed assembly/container origins, and allowed_shapes. Supported shapes include strips, T and crossing patterns, and selected aligned grids. fixed_subtrees preserves designed blocks; interior_template preserves a frame with automatic regions. See Get layout suggestions and Manual and mixed layouts for when to use each option.

layout.search.optional_groups and assemblies[].search.optional_groups offer up to four disjoint rows of two to four free requirements as choices between shared and separate compartments. Each row declares id, layout: row, axis, gap_mm, and explicitly oriented members. A fixed subtree may remain in that grid, but its contents cannot join a row. fixed_order names the separate packing units; a selected row takes the earliest member’s position. fixed_slots may pin only unaffected units and must fit every selection. allowed_shapes applies to each selection’s resulting number of units; a selection with no matching shape has no recipes. interior_template cannot be combined with these options.

Automatic local_groups can size and place multiple grids alongside fixed grids and existing containers. It can also divide one explicitly declared removable tray into compartments, but does not choose its members or invent a tray stack. Tray exploration starts from complete manual tray designs.

Each manual placement names an assembly or container id, origin_mm: [x, y], and rotation_deg. Existing containers may rotate through 0 or 90 degrees when permitted by their entry. Constructed assemblies require rotation_deg: 0. The origin locates the outside corner of the placed object inside the game box.

Removable trays and layers

A kind: tray assembly requires four positive side_clearance_mm values. These reserve removal space around its finished outside walls. Trays have their own floor and enclosing walls. One automatically divided tray is supported with local_groups; multiple trays and layers currently use manual layouts or exploration of already designed trays.

For a supported stack, add layout.layers. Each layer has an id, a bottom height z_mm, and a positive height_mm. Placements name their layer; an upper tray also names its supporting lower tray using supported_by.

# Partial layout for two trays whose outside height is 38 mm each.
layers:
  - {id: lower, z_mm: 0, height_mm: 38}
  - {id: upper, z_mm: 38, height_mm: 38}
placements:
  - {id: lower-tray, origin_mm: [2, 2], rotation_deg: 0, layer: lower}
  - {id: upper-tray, origin_mm: [2, 2], rotation_deg: 0, layer: upper, supported_by: lower-tray}

Layer starts must increase from zero, and each tray must fit the height budget at its start. Budgets may overlap for independent stacks, but the actual tray volumes and removal clearances must not collide. Supported stacks need matching outside footprints, continuous supporting rims, and contact at the correct height. BGI checks straight upward removal and records which trays must come out first. The tray layout guide explains how to compare supported arrangements automatically once two to four tray designs are complete.

Material and cutting sheets

Bundled material.profile IDs:

Profile	Sheet family
de-mdf-3mm	MDF
de-poplar-plywood-3mm	Poplar plywood
de-cellulose-board-3mm	Cellulose board
de-finnboard-3mm	Finnboard
custom-foam-board	Custom foam board

Starter profiles supply defaults; set thickness_mm and kerf_mm in material.overrides. Other overrides are fit_clearance_mm, min_web_mm, min_tab_mm, joint_edge_margin_mm, and compensation. Effective values follow profile → project → CLI. Prepare your material explains measurement and calibration.

To arrange flat cut parts on stock sheets, manufacturing names sheets with id, size_mm, and count, plus sheet_margin_mm, cut_gap_mm, and allowed rotations_deg. This is separate from arranging compartments inside the game box. Without it, the bundle still contains individual panel cutting files.

Complete schemas

Open the project schema, material profile schema, solution schema, or diagnostic schema for every structural variant.

Schemas describe the file structure. BGI also checks references, dimensions, assignments, and fit; full construction and manufacturing checks run during search or build. For a focused check while editing, see the diagnostic commands. From measurements to cut files explains the stages and diagnostics helps interpret failures.