Symbiotica Asset Refs

Symbiotica Asset Refs answers a deceptively simple question: what art did the client actually send for this asset? Not the dataset's house style, not the pack's seed-picked reference - the client's own reference files, in the order the order sheet pairs them. For a game-asset order, that's the difference between matching the client's intent and matching the client's neighbor. This is the node you wire when the reference art is the spec.

The ordering matters more than it looks. The pack's description spells out why: "for a type packed in stages that is prep, ready, serving, so the same index that picks a cell out of Slice Cells picks the reference that belongs to it." In other words, if you're rendering a food item through its stages, the reference index and the sliced-cell index line up, so a cell and its reference stay paired without any lookup table. Index alignment is the pack's whole philosophy, and this node is where references plug into it.

How it works

Wire in the order and (optionally) an asset_name, and it reads that asset's references from the order's references folder, in the order the sheet pairs them. Two behaviors make it pipeline-ready:

• Transparency handling. References with alpha are composited onto a chosen background (grey #808080 by default - matching the packed sheets, so a reference and its neighbor cell share a backdrop) rather than flattened. If you'd rather keep the transparency, keep_transparency leaves the background alone and hands the alpha out as masks instead. The pack's advice: composite for image models ("these files hide real pixels under their transparent areas"), keep transparency when you're going to composite elsewhere.
• output_size. Send a smaller reference when the detail isn't worth the tokens, using the same Lanczos resample Slice Cells uses - so a reference and the cell it pairs with are treated identically.

The inputs that matter

• order - required. The pipeline's order wire (from Order Specs or Asset Focus).
• asset_name - which asset, by name. Wire Order Assets' asset_names or Asset Focus's asset_name. Leave unwired when the order comes from Asset Focus - a focused order names one asset already.
• background - what a transparent reference sits on. Grey by default; set it to your generations' background to compare like for like.
• keep_transparency - off by default (composites onto background); on hands alpha out as masks.
• output_size - native by default, or downscaled for token savings.

Outputs: images (one per reference, in sheet order), asset_names (filenames, for traceability - wire into a Pick node's names to list only this asset's files), masks (each reference's alpha, emitted whether or not transparency is kept), and refs_path (the folder they came from - wire into a Pick node's input_path to tick the client's references by eye instead of taking every one).

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 file reading.

Common issues

• References come out as black rectangles - a transparent PNG landed on the graph with its alpha already flattened over black (ComfyUI's Load Image does this). That's the pack's warning about hidden pixels: composite onto the grey background or keep transparency and use masks.
• The wrong asset's references appear - asset_name isn't wired, or is wired from a list that's misaligned with the order. Asset Focus's focused order already names one asset, so leave asset_name empty in that setup.
• Index mismatch with Slice Cells - if the refs aren't in prep/ready/serving order, the cell/reference pairing breaks. Check the order sheet's reference ordering; the node emits them exactly as the sheet pairs them.

The trap to avoid: this is the client's art, not the style reference. If you wire this into the "style" socket you'll be matching the client's existing sprite rather than the catalog's house look. Keep it where the brief's art belongs, and let Dataset Reference handle style.