XB-llama - 🎬 角色场景调度器

Short-drama generation has a coordination problem: you've got a storyboard script where scene 3 needs 角色A (character A) against 背景B (background B), and your graph has separate character images and background images that must pair up with the right prompt, frame by frame. XB_RoleSceneDispatcher is the node that does the pairing. Give it the script text and the available character/background images, and it dispatches aligned lists - one prompt, one background, up to four characters per frame - so every downstream scene gets exactly its cast.

It lives in the pack's XB-llama family and is designed to sit after an LLM that wrote the storyboard: feed it the output of a llama/storyboard node (the text_input accepts any type via a forced input), and it parses the frame structure out of the text.

The parsing contract (the part to get right)

The dispatcher reads a specific format from the text: frames marked 分镜图_01 (or Scene_1) and, inside each frame, labels like 背景A and 角色B. Those labels are what it matches against your wired-up images. The optional image inputs are flexible - you connect them by name, e.g. an image port labeled 背景A or 角色C. So the workflow is: script → dispatcher → it pulls each frame's 背景/角色 label, grabs the matching wired image, and emits that frame's prompt + images as one row in the output lists.

Inputs and the "gacha" mode

• text_input - the storyboard script.
• draw_mode - the interesting one. Turn it on and the dispatcher caches the parsed frames on its first run, so later runs can re-dispatch from cache without feeding the text again - the pack calls this 抽卡 (gacha) mode. Useful when you're iterating on images while the script stays fixed.
• draw_range - "全部" (all) or a specific 分镜图_01–分镜图_16 to emit just one frame.

Outputs: 提示词 (prompts, STRING list), 背景图 (backgrounds, IMAGE list), and 角色01–角色04 (character images, IMAGE lists). They're list-aligned - element N of each list is frame N's full package, ready to feed a per-frame image-to-video or scene renderer. Missing labels get a black placeholder rather than a crash, which is forgiving but worth knowing: a frame that references a character you didn't wire up will happily produce a black rectangle.

The honest notes

It's a string-and-socket router, not magic - the matching only works if your script uses the 背景X/角色X label vocabulary and you label your image inputs to match. And because it's in the XB-llama family, some users assume it needs a local LLM running; it doesn't - it's pure parsing, and it works with text from any source. It also has no real dependency on llama-cpp-python (which the pack gates behind a try/except), so it's available even on installs where the llama nodes didn't register.

Install: Manager → XB_ToolBox, or git clone https://github.com/wjluoxiao/XB_ToolBox.git into custom_nodes, restart. Under "XB-llama". No extra pip deps for this node itself.