Files
openclaw-dnd-city-visualiza…/SKILL.md
T

100 lines
8.6 KiB
Markdown

---
name: dnd-city-visualization
description: "Render map-true towns, cities, approaches, establishments and their weather/population matrices for a tabletop campaign: 3D block model from the map, template plates per camera, re-surface with an image-edit model, gate, deliver by effort tier. Use when a GM asks for a view of a mapped place, a first view from the road, an aerial, a gate, a shopfront, a tavern at a given hour, or a weather matrix."
license: see LICENSE
---
# City render workflow
The method: **geometry arrives as pixels, never as words.** Trace the map into a block model, ray-march a template
plate per camera, hand the plate to an image-edit model as IMAGE 1 with "re-surface this; move nothing", then gate the
frame against the plate. A correction is one edit to the model and a re-render of every camera. Details in
`references/pipeline.md`; run `scripts/smoke_test.py` once to see every tool work on a synthetic town.
## Before you start
- Read `references/effort-tiers.md` and assign the place a tier (= the chance it comes into focus at the table). The
tier fixes the deliverables, the budget and the matrix sizes. **Never exceed the tier's ceiling without the GM.**
- Copy `examples/citykit.example.json`, `views.example.json`, `scene.example.json`, `prompts.example.json` next to
the map and fill every value. Credentials only in the environment (`IMAGE_API_KEY`, `IMAGE_API_BASE`).
- Write down what is canon (on the map) and what you are about to PROPOSE (terrain, heights, walls, gates, the hour).
- Check the lane folder for a fresh REPORT.md: the same brief dispatched twice is re-verified, never re-rendered.
- **Done when:** config files exist, the tier and budget are in the brief, and REPORT.md exists with a Problem line.
## Steps
0. **Build district sheets when the city needs them.** Register each district bitmap to the whole-city map from
several roof patches; record the scale, translation and residuals; project established pins through that transform.
Fill unused template slots only with clearly **PROPOSED** establishments sited on real unoccupied roofs, each with
a name, tagline, wealth tier and effort tier. Never move a pin to escape the template veil. Most padded places are
T3/T4 until play promotes them. Route leaders without crossings or legend hits; see
`docs/walkthrough-district-map.md` and `references/pipeline.md` section 0.5.
**Done when:** registration is measured, canon and proposals are visually distinct, every pin is map-sited, label
routing passes, and the companion table carries both tier types.
1. **Segment the map.** `segment_map.py MAP --mpp M --out seg.npz --look look.jpg`. Eyeball `look.jpg`.
**Done when:** roofs, trees and water are right where you will put a camera; false trees removed.
2. **Mass the town.** `massing.py seg.npz --config citykit.json --out town.npz`. Heights come from wealth zones
(proposed); hand-modeled landmarks are cut out and rebuilt in `scene.json` with every dimension named.
**Done when:** separate houses are separate cells, no slivers, landmarks have their canon dimensions.
3. **Place cameras and proxies.** Cameras in `views.json`: eye-level views at ground + 1.65 m with a lens shift
instead of pitch; the camera that *presents* the defining feature; found from the heightfield, never by eye.
Proxies (1.60-1.80 m, carts, animals) in the scene, 10 m or more from an eye-level camera, off the frame edge.
**Done when:** every view has a visibility list (what it sees, what is occluded) written for step 5.
4. **Render plates.** `render_plate.py V1 V2 --config citykit.json` (parallel processes; 1-15 min each at 2048).
Gate the plate against the map's checkable facts (`references/gates.md` section 0) and fix the model, not the
prompt. **Done when:** every plate passes its facts by eye and the untextured plate shows no artifact.
5. **Write the prompts.** Fill `prompts.json` per `references/prompting.md`: resurface premise, per-view intro /
keep / FRAMING LOCK with measured band positions, the people block, the eye-line clause for eye-level views, the
setting and town blocks (with the big things the model invents for a town of this kind, negated), the light with
the sun relative to the camera, no-modern and no-text. Material references from a different camera than the plate.
**Done when:** `build_jobs.py day --config citykit.json --prompts prompts.json --takes 3 --out jobs_day.json`
writes the jobs and you have read `jobs_day_PROMPTS.md` for contradictions.
6. **Re-surface.** `render_batch.py jobs_day.json --out out_day --start 4 --max 8`. Three to four takes per view.
**Done when:** `out_day/calibration.md` reports the run and no quota or refusal stopped it (a refusal stops the
lane; report it, do not switch renderers).
7. **Gate and pick.** `gate.py out_day --config citykit.json`, then `qc_sheet.py`. Reject reframes (ECC scale off
1, shifts beyond a few px), low landmark correlation, any invented skyline structure on wide views, figures off
their brackets, anything in the corner sweep. Pick one plus an alternate per view into `picks.json`.
**Done when:** every pick has its gate numbers in REPORT.md and the plate-vs-pick sheet exists.
8. **Relight.** `build_jobs.py relight --light sunset V=out_day/V_day_t2.png ... --out jobs_sunset.json`, render,
gate with `--keepers`. Sunset, night and morning are light-only edits of the day pick; the sky in frame is named
(east or west). **Done when:** relights register to their day pick within 0.2 % scale and 2 px.
9. **Matrices (tier 1 and 2).** `matrix_jobs.py weather --tier T V=keeper ...` for Day/Sunset/Night x Dry/Rain/
Snow (light) and any storm or deep-snow cells; `matrix_jobs.py population --tier T V=empty_master ...` for every
venue with people. Chained cells (Sunset/Night of a weather) get their reference after the Day cell is picked. Gate
storms on the wall band, deep snow above the snow line, route clearance by class (`references/matrices.md`).
**Done when:** the matrix is complete for the tier, each cell's gate rung is recorded, fixed cells are disclosed.
10. **Character pass (several exteriors on one wealth rung).** Thumbnail the batch; if the houses are
interchangeable, one-change edits adding each house's emblem sign and visible trade, gated against their own source.
**Done when:** the contact sheet reads as different places.
11. **Deliver.** Canon file names per `references/naming.md`; picks plus alternates; the QC sheets; a README for
the GM (what to show when, PROPOSED items with "if you rule otherwise", open questions, known flaws). Gated work
goes straight to canon with a one-line note; a human review entry only for a story-critical face, a permanent
bake, or on request. Verify by fetching back and hashing. **Done when:** REPORT.md has Problem, two Whys, what
was built, picks with numbers, failures and fixes, PROPOSED, open questions, limits, **Cost** (`cost.py`), and the
re-render chain; the hand-off is its path and one headline line.
## Non-negotiables
- Fix geometry in the model, never by wording. The renderer photographs the plate's mistakes as faithfully as its truths.
- Per camera, from a visibility list; occluded features disowned positively.
- Overviews and wide aerials are gated for invented large buildings against the model's landmark list.
- Figures are proxies in the plate, gated by brackets (+-25 %).
- Signs are emblems, never lettering; a corner and edge sweep on every frame.
- Never re-export the map to fix a fit; move a pin or reuse an existing building.
- Every run reports its Cost. Cut spend by volume, never by switching to a weaker renderer.
- Play promotes a place's tier; never demote; nothing rendered is deleted, superseded files are moved aside.
## Reference
- `references/pipeline.md` — the method step by step, with the measured reasons.
- `references/gates.md` — every gate, its bands, and what it is blind to.
- `references/prompting.md` — prompt blocks, framing locks, scale by relation, wealth-tier vocabulary, glass.
- `references/matrices.md` — the 9-square, snow levels and route clearance, foliage, population x time, matrix traps.
- `references/effort-tiers.md` — tiers, deliverables, budgets, model-cost tiering, delivery policy (on trial).
- `references/naming.md` — file and folder names, the report shape.
- `references/failure-modes.md` — symptom, cause, fix, one line each.
- `docs/` — illustrated castle, interior, sign-lock, and district-sheet walkthroughs.
- `scripts/` — `segment_map.py`, `massing.py`, `scene_solids.py`, `render_plate.py`, `build_jobs.py`,
`render_batch.py` (+ `adapters/`), `gate.py`, `qc_sheet.py`, `matrix_jobs.py`, `cost.py`, `smoke_test.py`.