novel-staging
Set for every scene of an AI short dramathe opening blocking: at the start of this scene, where each person appearing is relative to which object, sitting or standing, facing where.
Why block it separately: each video segment of a short drama is generated independently, and each segment decides on its own who sits where. In a group scene with six people around a long table, the first segment has five unnamed guests extra at the table, and in the third segment the person sitting with a drink is wearing the protagonist's clothes. The storyboard's blocking sentences hand off from one segment to the next, but each scene'sfirst segmentsentence is made up by the storyboard itself, and no one can see or change it. So before the storyboard, each scene first fixes a set of blocking, and the storyboard copies it verbatim.
| Delivery | What it solves |
|---|---|
| Image recognition result (4–20 objects per location) | Blocking only lands next to objects that actually exist in the image—a raised platform written in the prompt but not drawn in the image, with people sitting on it, will differ in every video segment |
| Top-down plane | On a perspective scene image, "north side of the table" is just a thin strip behind the table, and front-back depth is unclear; flattened and viewed from above, directions are obvious at a glance |
| Opening blocking (per scene) | Who is present at the opening and who enters later; sitting or standing follows the script; the main seat, opposition, and isolation are expressed through position |
| Opening blocking sentence | The program writes it according to the blocking and hands it to the storyboard word for word: "Hu Er Ye sits on the seat board in the third row, facing north; the remaining seats are empty, with no one else." |
| Adjustable report | People drag on the page, change sitting/standing and facing, and the export is the new staging.json, with no need to edit JSON by hand |
{baseDir} = the directory containing this file. Script {baseDir}/scripts/novel-staging.mjs, zero dependencies,node run directly.
Boundaries (what it does not do): it does not write storyboards, does not write scripts, and does not produce images. It only handlesthe moment of the opening—who stands up midway and where they walk is the storyboard's business, and the storyboard continues writing from this moment onward.
Step 0 — Define inputs
- script.json(output of novel-script)—hard prerequisite: which scenes there are, which location each scene is in, who appears, and how the script is written
- art.json(output of novel-art)—the names of the locations; when there is no image yet, infer from its anchors and main-view prompt
- outline.json(output of novel-outline)—the names corresponding to character numbers (C01 → Shen Zhiwei)
- Scene image—one per location, placed in
images/<地点名>-sheet.png(the setting-image layout of novel-art, with the main view at the upper left).Best to have: blocking must land next to objects that actually exist in the image. It can also be blocked first without an image, but that is only a draft (see Step 2)
Step 1 — seed skeleton
node {baseDir}/scripts/novel-staging.mjs seed <script.json> --art <art.json> --outline <outline.json> > <workdir>/staging.json
Deterministic transfer: locations (in order of first appearance), each scene's episode number and scene number, which location it is in, lighting period, characters appearing, and one empty blocking entry for each person.Do not make the model rethink these facts. Just a few episodes of it, add --eps 1-3。
Step 2 — Identify objects (once per location)
One task per location; parallelize if possible. Read {baseDir}/references/read-pass.md, and follow it: look at the main viewpoint of the scene image, identify the things a person would stand next to or sit on, and for each write the name, another language, the box on the image (box), the position on the plane (plan), whether it can be sat on (on), whether it is round (round), 4–20 items,readFrom write picture。
The two most important:Do not write what is not visible in the image(anything in the prompt but not in the image must not be written);plan infer by perspective, not copy box。
No image yet: infer from the anchors and main-viewpoint prompt in art.json,readFrom write prompt, do not write box. The report will mark it; once the image is out, identify again and verify the positions.
Step 3 — Arrange positions (once per scene)
One task per scene; parallelize if possible (for several consecutive scenes at the same location, arrange them in order to keep positions consistent). Read {baseDir}/references/staging-pass.md, take this scene's script, characters present, and the things identified at this location, and for each person in places fill in: whether present at the start (present), which side (item) of which object (side), how far along that side (along), sitting or standing (posture), facing which way (facing); then fill in extras (extras / extrasWhere) and one sentence why。
The three most important:People who come in later are not present at the start；If the script does not say there are others, there are no extras；Only use the things that were identified。
Step 4 — Validation ⛔ Cannot be skipped
node {baseDir}/scripts/novel-staging.mjs validate <staging.json> --script <script.json> --art <art.json>
The 8 quality gates are all code: each location has an identified image and 4–20 items, the names of the things are not duplicated and the boxes are valid (those identified from the image must have box), every scene's location has an identification result, the characters present are exactly right (if --script is given, also verify it matches the script), every person has presence determined and at least one person is present, present people land on identified things and their side/sit-stand/facing are valid, no stacking on the same side, and the number of extras is an integer and states where they are.
Fix violations one by one, rerun after fixing, until it passes.
Step 5 — Default delivery is the HTML tool report
cd <输出目录>
node {baseDir}/scripts/novel-staging.mjs render staging.json > staging-report.html
The default main deliverable is staging-report.html; after completion, give the user the report link or path directly, do not return only JSON, Markdown, or a chat summary. render When no format is specified, output HTML directly; explicit --html is still supported.staging.json Save as working data for validation, re-rendering, and later handoff; only run render staging.json --md > staging.md。
staging-report.html Double-click to open, one top-down plan per scene:
- Draga person to change position; on release they land on the nearest side of the nearest thing; dragging back to the tray below means not present at the start, dragging in from the tray means present
- Clicka person to adjust sitting/standing and facing (eight directions)
- Add/remove extras and write where they are; the opening blocking sentence and this scene's checks update in real time
- Changes are stored in the browser and survive refresh; **"Export JSON"** downloads the modified staging.json
Overwrite the exported file back to staging.json，and run Step 4 again. The report interface is in Chinese by default,--lang en switch to the English interface (for blocking sentences, use the other language's names written at image-recognition time). If the image is elsewhere, use --images <目录> to point over there.
The user can also request an adjustment in one sentence ("Move Hu Erye to the bow"): follow staging-pass.md"Adjust by one sentence" to make the change, touching only the person mentioned, then validate again.
Step 6 — Hand off to storyboard
node {baseDir}/scripts/novel-staging.mjs blocking staging.json # 每场一行：场次 + 开场走位句
node {baseDir}/scripts/novel-staging.mjs blocking staging.json --lang en # 英文
When the storyboard writes the opening blocking for each scene'sfirst segment(novel-storyboard's blocking), copy this sentence verbatim; afterward each segment continues as usual from the previous segment's end-of-segment blocking.
First provide the HTML tool report link or path, then state clearly in one sentence: how many locations (how many recognized by image, how many inferred from prompts), how many scenes, how many scenes have someone not present at the opening, how many extras; explicitly state any gates not passed. JSON is the accompanying working data; Markdown is not a default deliverable.
Final delivery:
<输出目录>/
├── staging-report.html ← 默认主交付，双击打开，拖动调整并导出 JSON
├── staging.json ← 工作数据，供校验、渲染和后续交接
└── images/ ← 本 skill 不写这个目录
└── <地点名>-sheet.png ← novel-art 的场景设定图放这儿，认图和报告都使用它
Position in the pipeline
novel-outline → outline.json （人物名字）
novel-art → art.json （地点 + 场景图）
novel-script → script.json （每一场谁出场、怎么演）
novel-staging → staging.json （每一场开场谁在哪）
novel-storyboard → storyboard.json（每一场第一段的开场走位照抄 staging）
seed takes script.json,--art provides location names,--outline provides character names. novel-storyboard currentlydoes not automatically read staging.json: use the sentences produced by the blocking command, write them into the blocking。
Boundaries
- Only arrange the moment of the opening; changing positions mid-way is up to the storyboard
- This skill does not produce images; scene images are produced by novel-art's setting images and then placed into
images/ - Directions are always stated by scene (east, south, west, north, next to which object), not by frame (left, right) — frame left/right is derived from the camera position, and flips when the camera position changes
Self-test
node {baseDir}/scripts/selftest.mjs
99 assertions, no model calls, no quota spent. Each of the 8 quality gates has a breaking test case; planar geometry, drag drop points, blocking sentences, seed, and report (Chinese/English interface, escaping, embedded images) are all covered; it also separately rebuilds a copy using the source code of the algorithm embedded in the page, and verifies it matches the command-line calculation. After changing the script, run this first.
Built-in sample
{baseDir}/examples/渡口-staging.json: "The Ferry Crossing" three locations (ferry pier, ferry cabin, far-bank reed shoal), opening positions for nine scenes, all quality gates passed (against the sample script and art). The sample has no scene images; all three locations are inferred from setting prompts (readFrom: prompt). Serves as a quality baseline and also as a self-test fixture.