Plugins — Software Bridges¶

alc/plugins/ contains one directory per software package. Each plugin provides a uniform interface so Alchemy can automate any software with a Python backend.

The create / edit / query contract¶

Every software plugin exposes three files:

File	Role
`create.py`	Initialize assets, scenes, or files in that software
`edit.py`	Modify existing work
`query.py`	Read state from that software

This uniform interface is what allows the cookbook to dispatch recipes to any software. Operations are addressed with the etymology convention {dcc}.{verb}.{task}.{op} and dispatched through a trampoline — the same address works in Maya, Blender, or any other bridged DCC that implements the op.

Current plugins¶

Plugin	Notes
`blender/`	Full bridge — headless + GUI, dashboard sidebar, MCP chat agent
`maya/`	Full bridge — mdl publish spine, turntables, farm render, mGear
`max/`	Full bridge (port 20263) — contract-first tasks, Qt Alchemy menu, GUI/`3dsmaxbatch` recipe runner, `3dsmaxcmd` farm render; `mdl` spine proven start→publish
`unreal/`	Perforce-routed; `/Game` paths grounded through PathObject
`premiere/`	UXP panel + local bridge server; cookbook-driven artist UI
`substance/`	Painter socket plugin (port 20260)
`alchemy/`	Alchemy's own internal automation (create / edit / query)
`shotgrid/`	ShotGrid / Flow sync
`perforce/`	Version control integration
`aws/`	Cloud storage
`elevenlabs/`	Voice synthesis
`huggingface/`	Model hub integration

Adding one¶

Every registry a new DCC must be entered in, the LocalSoftwareVersion surface, the bridge contract, the contract-parity gate, the five phases and the artist menu are written up as a checklist in Porting a DCC to Alchemy. Follow it rather than reading three existing plugins side by side — that is what it exists to replace.

Language routing¶

Plugins for JS-hosted environments (e.g. Premiere UXP) route by a language field on the recipe step: JavaScript steps run in the panel, Python steps run on the local bridge server. See the Premiere UXP plugin spec.

Software setup¶

Each plugin can carry a setup/ directory (requirements, bootstrap) driven by LocalSoftwareVersion.setup() — this is how farm bootstrap, TRELLIS, and other tool installs are handled as plugins rather than manual steps.

Verifying a bridge before you trust it¶

A bridge answering on its socket is not the same claim as a bridge that works, and the two have been confused often enough to be worth a standing check. The gap between them is where the expensive bugs live:

the exec can land on a worker thread, where the DCC's API is not thread safe — it looks fine and corrupts state under load;
an op can return {"ok": true} while the scene is unchanged, because an implicit undo rolled the change back out (first seen on the Blender bridge);
the client can reach a session and not the one you meant, because a second DCC bound the same port — on Windows SO_REUSEADDR lets it, which is why MaxBridgeServer asks for SO_EXCLUSIVEADDRUSE instead;
an op that raises inside the DCC can hang the caller rather than returning an error.

The rule that falls out of those: assert on scene state read back over a second, independent call — never on the return value of the mutating call.

3ds Max¶

venv\Scripts\python.exe -m alc.services.ai.max_bridge.verify

It launches its own 3ds Max on a free port (never 20263 — an artist's session owns that), waits for the bridge the deployed userSetup.py starts, drives real contract ops through the real trampoline, then stops the session it started. Exit code is 0 only if every check passed. Useful flags:

flag	why
`--keep-open`	leave the launched Max up so you can look at the scene
`--port N`	pin the bridge port instead of taking a free one
`--simulate not-running`	nothing listening — must report, not hang
`--simulate no-startup-script`	up but no bridge — the error must name the startup script
`--simulate op-error`	an op raises inside Max — must come back as an error dict

The simulations exist because a harness nobody has watched fail is not evidence. Run one after touching the bridge; if it still goes green when you break it, the green run means nothing either.

Bridge ports, for reference: Maya 20240, Substance 20260, Premiere 20261, After Effects 20262, 3ds Max 20263. A session Alchemy spawns never takes one of these — recipe runs get an ephemeral port (ALC_MAX_BRIDGE_PORT=0) and the verifier gets a free one, so a spawned DCC can never shadow an artist's.