Symbiotica Grid Layout

Symbiotica Grid Layout is a small node with a specific job: it loads the layout image an asset type is drawn on, from <project>/datasets/layouts/. In a game-asset pipeline, a "layout" is the grid - the composition of the sheet that tells the image model where things go. Different asset types (Food, Decorations, UI icons) live on different layout grids, and those grids get versioned as the client iterates. This node finds the right one for the category you're working on, newest version first, and hands it to the model as the first image input.

It's the kind of node that's trivial in isolation and quietly essential in a lane. The layout is the spatial spec: every render for a Food sprite stands on the Food grid, and if the client bumped the grid to version 7, every render should silently start standing on version 7. This node makes that automatic.

How it works

Wire in the order (which carries the project), plus Asset Focus's category and bucket, and it resolves the layout file through a naming ladder: it tries <category> - <bucket> first, then falls back to plain <category>, newest version first. The pack calls this "the same ladder the Prompt Recipe climbs, so one naming rule covers the prompts and the grid" - same file-naming convention, two consumers, no drift.

Versioning is by new file, never a rename: Food - 3 stages-7.png is a new version, not an overwrite. That's a deliberate convention so nothing in a render's provenance ever has to guess whether a renamed file is the same grid.

The inputs that matter

• project_path - the client project folder; unneeded when order is wired (the order carries the project).
• layout - pin one file by name and it wins over the category ladder. Empty follows the category; the panel's picker fills this in.
• order - any order from the pipeline; carries the project.
• category - Asset Focus's category. Names the layout the same way it names the recipe.
• bucket - Asset Focus's bucket. Narrows to <category> - <bucket> when the folder holds one, falls back to the plain category when it doesn't.

Outputs: image (the layout, ready for the image model's first input), mask (its alpha, opaque where the layout has pixels - fully opaque for a layout saved without transparency), and name (which file was used - the answer to "which grid did that render stand on"). That name output is a quiet provenance gem: it makes renders auditable against the layout version.

Install

ComfyUI Manager → search Symbiotica → install, or:

cd ComfyUI/custom_nodes
git clone https://github.com/symbiotica-ai/comfyui-nodes.git symbiotica
pip install -r symbiotica/requirements.txt

Restart ComfyUI. No keys, no models - local image loading.

Common issues

• No layout found - the layouts folder doesn't have a file matching the category (or category-bucket) ladder. Check <project>/datasets/layouts/ naming: Food - 3 stages-7.png style, newest version first.
• An old layout keeps coming back - if the version is embedded in the filename (-7), the "newest first" sort only helps if the number increments. A file named just Food.png never loses to Food - 3 stages-7.png if the category names differ - check the bucket wiring.
• Wrong grid for a sub-kind - you wanted the Drinks bucket but didn't wire Asset Focus's bucket, so it fell back to plain Food. Wire the bucket in.
• Layout renders fine but provenance says a different file - read the name output; that's the source of truth for which grid was used.

It's an output node, so you can queue it alone to eyeball a layout. For anyone building a per-category render lane, wiring this before the image node's first input is the difference between grids that stay current and grids that quietly go stale.