Storage requirements and search

A component entry describes what you own; a storage requirement describes the clear space it needs. BGI calculates requirements before checking a manual compartment or searching for an automatic layout. When a compartment seems unexpectedly large, the requirements command shows the calculated IDs, counts, sizes, and permitted orientations.

From measurements to clear space

Input kind	How its requirement is formed	Useful check
explicit	Uses declared clear_min_mm and allowed XY orientations.	Confirm the figures are usable inside a compartment.
cards	Uses card size, count, effective thickness or measured stacks, split counts, allowance, and flat or upright orientations.	Check sleeve thickness and whether upright storage was allowed.
objects	Uses object size, a declared three-axis count arrangement, gaps between objects, outer allowance, and allowed axis permutations.	Check the arrangement, rather than assuming BGI will choose how many objects go in each row.
loose	Uses measured bulk volume, or solid volume and fill fraction, against explicitly listed footprints and heights.	Check that one of those shapes has enough capacity; an estimated volume is still an estimate.

Named instances make separate requirements from one component template. A groups[] entry can instead make one packing unit from several requirements: an ordered row, positioned arrangement, compatible stack, or explicitly measured mixed bulk volume. The group takes its members’ place in compartment assignments; its members remain identifiable in the result. Grouping is an instruction from you, not an automatic decision to combine pieces. See storage and construction and the project file reference for fields and examples.

assemblies[].members says which requirements a grid must store. In a manual tree, each compartment’s contents assigns its requirement. BGI checks assignment completeness and whether a permitted size and orientation fits the declared clear dimensions. A compartment holding multiple kinds of loose content needs a declared group. An existing closed container is different: containers[].outer_mm reserves its measured outside size plus removal clearance. Its inventory does not create a constructed compartment or prove that everything inside it fits.

What automatic search does

An automatic project gives BGI the storage requirements, permitted shapes, box and material dimensions, and a layout.search.budget. Search tries supported compartment arrangements and placements. Before returning a candidate, BGI checks its constructed outside size, box space, material rules, cut paths, and any requested sheets. The report ranks candidates that pass those checks.

The current search covers compact X or Y splits, some T arrangements, aligned crossings and grids, and declared fixed regions. fixed_order, fixed_slots, fixed_origin_mm, fixed_subtrees, and interior_template constrain parts of the search when you already know where they belong. It does not explore every conceivable tray, freeform compartment, or vertical stack. A search budget counts attempted candidates, including rejected ones.

Declared optional_groups let the same search compare a shared row with separate compartments. Fixed blocks and unrelated placements stay fixed. Order, slots, and allowed shapes continue to constrain each choice; BGI filters shapes by the resulting number of packing units. The current search does not invent group members or group geometry on its own.

bgi solve game.bgi.yaml --output search-results

Read search-results/report.md for the outcome, candidate list, and rejection reasons. no_candidate means BGI found no design within the patterns and attempt limit used. Check the calculated sizes, allowed orientations, fixed constraints, box reserves, and material thickness before increasing the budget. If a candidate suits your game, build its saved file:

bgi build game.bgi.yaml --solution search-results/candidate-001.json --output insert-bundle

Use the filename actually listed in the report. BGI reconstructs and checks the candidate against the project during build. Full example provides a complete worked project, and the diagnostics reference helps interpret failures.