- name
SKILL.md
Die Skill-Datei bleibt im Repository des Herausgebers.
Fügen Sie den kopierten Befehl in ein Terminal ein. Er installiert diese SKILL.md in dem jeweiligen Agenten.
npx skills add sloemo01/diorama -a cursor -yFügen Sie den kopierten Befehl in ein Terminal ein. Er installiert diese SKILL.md in dem jeweiligen Agenten.
npx skills add sloemo01/diorama -a claude-code -yFügen Sie den kopierten Befehl in ein Terminal ein. Er installiert diese SKILL.md in dem jeweiligen Agenten.
npx skills add sloemo01/diorama -a codex -yFügen Sie den kopierten Befehl in ein Terminal ein. Er installiert diese SKILL.md in dem jeweiligen Agenten.
npx skills add sloemo01/diorama -a grok -ySenden Sie die kopierte Nachricht in einem Grok Bot-Chat. Der Bot ruft diese SKILL.md von GitHub ab und fügt sie den Skills hinzu, die alle Ihre Bots gemeinsam nutzen.
Install this skill: https://github.com/sloemo01/dioramaVom Herausgeber
For a new commission, ask look first, model sourcing second, using the two gates below. These gates override older three-preset lists, automatic internet-first instructions and one-prompt assumptions elsewhere in this long guide and its references. Do not ask setup questions when merely editing the skill. Explicit answers in the brief skip the corresponding question; existing-project repairs retain recorded choices. An unanswered question is pending, not consent. Rendering and sourcing are independent of narrative/educational purpose.
Three looks are available: pixel (Classic Pixel Art; recommended), stroked-toon, pixel-stroke. Generic “pixel art”, “classic”, “old pixel style” and explicit delegation (“you choose”) resolve to pixel. All looks preserve free orbit. An unanswered style gate waits.
Three sourcing modes are available: internet-full, hybrid (recommended), authored-only. Generic “use internet models” resolves to hybrid unless the user requests downloaded models throughout. Older internet-first records map to hybrid on repairs. Sourcing requirements below apply only to modes that acquire external assets; authored-only skips model acquisition, not subject research, quality or geometry/contact checks.
This is the restored full-length guide, not the compact 4.x replacement. Keep its detailed composition, subject recipes, scene furniture, cast, animation, service/queue, vehicle, effects, framing and craft guidance. The following profile/sourcing updates override older wording only where explicitly stated.
Default sceneProfile: narrative. A place, landscape, amusement park, town, fantasy scene or interactive scene is not an educational mechanism. Pixel, stroked-toon and pixel+stroke choose the renderer, NOT the profile. Asset choice, a working ride or click interactions do not make a scene educational. Choose educational when the user asks to explain/teach how something works, its anatomy or causal sequence. If intent is genuinely mixed, ask once; otherwise infer and record it without another forced setup question.
Narrative has no educational UI by default. Do not import or instantiate education-v8.css, education-dock.mjs, an Explore/How it works panel, lesson steps, part picker, explanatory dashboard, floating callout labels or scattered teaching text for an ordinary diorama. This exclusion applies in ALL three render presets. Leave the scene/page visually clean. Free orbit and discreet functional pause/reset/accessibility controls remain permitted; diegetic park signs and shop names are scene geometry, not a teaching overlay. Optional title/readout furniture mentioned later is opt-in, not a toon/hybrid default. No debug panel in delivery.
Educational only: canonical V8 right card/mobile dock, causal lessons, part inspection and connected explanatory callouts apply to explanatory commissions, not to all scenes. Explicit UI-free requests still override the panel default: explanation can be delivered through the requested scene behavior and accompanying prose. Narrative scenes with explicitly requested ride/part inspection get the requested scoped interaction, not an automatic lesson dashboard. Explicit requested informational labels are allowed, but do not add unrelated teaching surfaces. Record uiMode: none | minimal-controls | requested-inspection | educational and why; never satisfy a UI test by adding unwanted UI.
Regression examples: “amusement park in pixel + stroked toon” → narrative + pixel-stroke + no education UI. “Interactive amusement park” → narrative; interaction alone adds no lessons. “Explain a roller coaster's operation” → educational, chosen style independently. “Amusement park with inspectable rides” → narrative + requested inspection only. A scene with no educational intent must not fail QA for lacking V8, lessons, labels or a card column.
Prevent intersections before adding detail or spawning copies, for people, animals, imported rigs, buildings, props and rides in BOTH profiles/all presets. Use references/action-clearance.md, templates/action-clearance.mjs and templates/pose-bounds.mjs with the actual production evaluator; this adds no educational UI.
requiredIds; missing actors/proxies or unverified coverage cannot pass. Test nonadjacent self-parts too, while explicitly declaring valid anatomical/structural joints. Proxy overlap is not automatically actual mesh penetration.sampledOnly:true is bounded sampled evidence, not continuous collision freedom. Move a real wrist/tail/knee into an obstacle, overlap building parcels and synchronize a crossing; the SAME production predicate must flag the fault and pass after repair. Review worst-contact side/back/top crops plus an action strip. Never hide bodies, shrink proxies, fade through walls or freeze the requested action to claim a pass. One source-driven QA runner, cached static obstacles, nearby-pair broad phase and worst-few reporting keep this practical.Ask the Model Sourcing Gate after the look is resolved, for BOTH profiles. Follow the recorded internet-full, hybrid or authored-only choice; do not silently impose internet-first. In the first two modes, reuse valid local assets but still search for missing major roles. The acquisition requirements in this section apply to those two modes; authored-only intentionally builds geometry and does not need a failed model search to justify it.
A search is not the deliverable. Before detailed hand-modelling, find candidates for the hero and major supporting roles, review the actual per-asset terms and appearance, download the chosen permitted model/dependencies, inspect an actual import, and USE it in the scene when it fits. A fitting, licensed asset must not be ignored in favour of primitive-only reconstruction merely because hand-building is familiar. Nor does importing one token tree satisfy sourcing a park's otherwise hand-built rides/buildings/cast. Record decisions for the main roles in the existing SOURCES/CREDITS/design ledger.
Fit means diorama-quality, not merely downloadable: correct subject/representation and silhouette, coherent kit/palette/proportions, adequate construction detail, usable parts/rig/clips for the requested motion or inspection, viable triangle/draw-call/texture budget, and compatibility with the chosen pixel/toon/hybrid rendering. Judge the real model from more than a thumbnail. Normalize scale/axes/origin, adapt colours/materials without losing important markings, preserve rigs/part identity, fit to the scene and review a rendered close-up. A realistic/PBR asset is not automatically disallowed if it can be adapted well; an unrelated low-poly substitute is not automatically suitable. Follow the original long-form craft, composition and motion standards after importing.
Rights remain mandatory: prefer FREE assets whose explicit terms permit commercial use, modifications and redistribution/embedding in the delivered scene. Read original asset/license evidence; retain credits/license/change notices where required. NC, ND, editorial, personal/educational-only and missing rights do not pass. Custom/ShareAlike/other terms require compatibility review, not a fake CC0 label. No purchases, subscriptions or paid downloads without explicit user approval. Check separately licensed dependencies. Commercial permission is not scientific accuracy or trademark/other-rights clearance.
Source order: use the user's Polyfork-first sweep for narrative kits/props, then the relevant original-author/model-library sources in this guide; if Polyfork misses, continue to appropriate alternatives rather than declare that the internet has none. Educational subjects use their bounded exact-subject search and extra accuracy/structure gate. Reuse a compatible kit for coherence. Do not crawl every provider indiscriminately or repeatedly search the same noun. Actual search/download/import evidence stays on disk; never fabricate searches, licenses or successful loads.
Hand-model only the justified gap: necessary missing/custom geometry, unsuitable candidates after source/fit checks, or interfaces/animation adaptations not supplied by an imported model. Selection or movement alone is NOT a reason to reject an asset: use real part/pivot wrappers where feasible. Retain an all-authored approach when the user explicitly asks for it. If browsing/downloads are unavailable, disclose the limitation and fallback; never say the search found nothing when it never ran. A quality mismatch, unclear license or lack of useful motion is a documented reason to reject, not a reason to force a bad download.
Proof before completion: for each major role record search/source, chosen asset or rejection/fallback reason, license evidence, actual downloaded file/path/hash and import/style/motion result. A compliant matching candidate found → acquired and used; no suitable candidate → honest specific fallback. Verify the chosen asset actually exists in the final scene, not just in assets/. Offline/standalone delivery packages every permitted dependency and is tested without network; a warm cache or CDN loader is not self-contained. Sourcing adds NO education panels, callouts or other UI to narrative scenes.
references/representation.md: Earth means a planet, not a globe on a stand. Ask real subject / physical teaching model / explanatory abstraction / you choose only if materially ambiguous; preserve explicit choices. Keep representation, render preset, purpose, scene/object context and Inside independent. Natural subjects do not acquire invented platforms, frames or machinery merely because this guide contains mechanical examples.references/external-models.md. This extends the older model-library section; do not fall back to primitive-only scenery without checking suitable assets.references/educational-models.md, not a narrative full-catalogue crawl. Add authored semantic IDs, interfaces, pivots and explanation where needed.templates/educational-asset-gate.mjs with reviewed evidence/credits and actual file hashes; CC0/CC-BY can pass, unknown/custom terms require review, NC/ND/editorial/incompatible terms do not pass. Verify dependencies and offline bundling; a remote CDN load is not an offline standalone artifact. This rights gate overrides older library summaries, including casually accepted restrictive licenses.templates/construction-kit.js and templates/interface-checks.js; reserve working pockets, derive contact stacks from shared datums, check actual geometry and repeats. Keep the original detailed construction/selection chapters. Material/selection/annotation checks apply only to implemented/requested features; no forced annotation system to satisfy QA. AABB overlap is a candidate, not certified penetration. Use scoped real mutations, not bespoke injected-object detectors. Available helpers are supplemental, not proof of a whole scene.A diorama is a tiny staged scene with a resettable three-quarter hero camera and free user orbit. The default pixel preset uses a white cut-out, palette-snapped pixel grid and ink contour; the other presets follow their own presentation contracts. Narrative scenes retain the slab and toy-scale animated cast; educational scenes use the exception below.
Classic Pixel Art is the recommended new-project look. Stroked toon / illustrated miniature
(stroked-toon) and the pixel + stroke hybrid (pixel-stroke) are optional
rendering presets for any subject, not a coffee-machine genre. Ask which of the
three to build in at the start of every project — see Render Preset Gate —
because the look changes presentation only, never the subject, story, research
requirements, choreography or construction standard, and nobody should have it
chosen silently on their behalf.
Profile precedence (read first): For an educational explanation, read
Educational Mechanism Profile before the narrative defaults. One mechanism and
one causal sequence replace ALL mandatory cast/ritual/multiple-system/story-prop
quotas throughout this guide. Clean off-white and the single V8 right card/mobile dock replace empty
paper or decorative figure UI (explicit placement requests remain supported). Construction and mechanical correctness are never
waived. For EVERY preset, free user orbit is mandatory; fixed/hero views below
refer to deterministic QA/reset poses, not a locked interaction camera.
This file restores the full guide. The supplemental references named in the 5.0 additions carry later approved sourcing/representation rules; copy-in modules and the detailed design sheet remain in templates/.
Execution index — do not read every genre recipe first. Resolve the preset
and profile, then use the fast-path table. Read Research Before You Model and
The Detail Bar (including whole-object completeness) for every build. Narrative
builds additionally use One Prompt, One Build, The Animation Bar and their
chosen rendering recipe; educational builds go directly to the canonical UI/
inspection and construction contracts. The Look Contract is pixel-only.
This table indexes existing acceptance rules; detailed tests live only in the sections named here. Read other subject recipes only when the build uses them.
Before the first mesh or presentation work, ask using the structured-choice tool when available. Keep labels and one-sentence consequences visible:
Which look should I build this in?
- Classic Pixel Art (Recommended) — The original finer palette-snapped miniature look with ink contours and ordered dither.
- Stroked Toon / Illustrated Miniature — Smooth bevelled parts, stepped shading and fine charcoal outlines.
- Pixel + Stroke — Toon shading and outlines on a low-resolution pixel grid.
Map answers respectively to pixel, stroked-toon, pixel-stroke. Generic “pixel art”, explicit classic and explicit delegation select pixel; silence waits. A reference image alone does not settle a materially ambiguous request. Do not repeat the question per material or repair. Record the answer verbatim in DESIGN, including the preset ID and renderer implementation. Every preset supports free orbit and deterministic hero reset; no second orbit question. After the look answer, ask the sourcing question next unless already answered. While either is pending, inspect local files and research the subject, but do not start detailed geometry, model downloads or a presentation implementation that commits the unanswered choice.
How should I create the models?
- Hybrid — source + custom-build (Recommended) — Search for commercially usable models, download and use the ones that fit, then model missing or scene-specific pieces myself.
- Internet models throughout — Search for and use commercially usable downloaded models for all major roles; focus my work on assembly, styling, rigging and animation.
- Fully agent-modeled — Build all scene geometry myself for a unified custom look, without downloading third-party models.
This is a separate question after style, not a hidden assumption or a confused “pixel hybrid” choice. Use stable question ID asset-strategy, single-select, and map answers to hybrid, internet-full, authored-only. Record exact user wording. Explicit delegation selects hybrid; silence waits. Explicit requests for original/procedural geometry answer authored-only; an offline deliverable alone does NOT mean authored-only (permitted assets can be packaged locally).
Pre-build decision receipt: after both answers, state one short line such as “Classic Pixel Art · hybrid sourcing · narrative · minimal controls”, then record the choices in DESIGN. Before delivery reconcile each major role against its chosen source mode and record native render dimensions, scaling and style crops. Missing answers, unsupported render-preset claims or unapproved sourcing switches cannot pass QA.
The narrative shape is place + repeated ritual + interruption + consequence. Educational scenes instead use mechanism + causal sequence + observable result; do not add a fictional interruption or cast. The fast path selects the relevant reference notes, not extra narrative requirements.
Don't use for photoreal scenes or full-resolution photographic product renders. Every scene MUST support free user orbit by default, including pixel, stroked-toon and pixel-stroke. No separate orbit consent exists. Keep a deterministic hero angle for QA/reset, never auto-spin.
Four lookups come before the first mesh: the subject by frames, the asset libraries, the motion itself, and the capture loop. Skipping them is how a build ends up with a plausible silhouette that matches nothing and animation that reads as generic. Budget for them, they are usually faster than the modelling they save.
Find the real thing moving, not stills. For games, anime, sport or machinery the footage is the specification: it settles what the shape is, where the motion starts, how long each stage lasts and what colour it is at each step.
yt-dlp --flat-playlist --print "%(id)s | %(title)s | %(duration)s" "ytsearch6:<subject> animation"
yt-dlp --extractor-args "youtube:player_client=ios,android" -f 18 -o "refs/clip.%(ext)s" <id>
ffmpeg -i refs/clip.mp4 -vf "fps=8,scale=300:-1,tile=6x4" refs/sheet-%02d.png
Read the contact sheets with vision, then write the grammar down in words before touching geometry: ball leaves the hand on an arc, opens with a white burst, the creature springs out at full size, the ball snaps shut and returns. A paragraph like that is the acceptance test for the effect you are about to build.
Rules that come out of doing this repeatedly:
refs/<subject>/ next to the build so the next person can
see what you were matching, and so QA has an image to compare against.Internet-first sourcing applies to ALL major scene roles, not only creatures. Acquire and use fitting commercially licensed models by default; hand-build only a documented gap or explicit original-geometry request. Hand-building a creature from primitives is the last option, not the first. A rigged download with real deformation and usable clips beats four hundred lines of spheres the moment the camera comes within a metre. Search first, and keep a record of what you searched.
The ladder. Every hero asset walks down it in order.
tools/, assets/ or
model/ directory with GLBs in it. List it before anything else.Creatures, characters and rigs
Animation clips (motion is usually harder to hand-key than shape is to model)
Props, environments, textures, light
Searching them without a browser. Three of the libraries have open APIs, so a build can check them in a single command and read the licence back:
# Sketchfab: downloadable + CC0 only, name and page printed for each hit
curl -s "https://api.sketchfab.com/v3/search?type=models&downloadable=true&license=cc0&q=dragon&count=24" \
| python3 -c "import json,sys;[print(r['name'],'|','https://sketchfab.com/models/'+r['uid']) for r in json.load(sys.stdin)['results']]"
# Poly Haven: models, HDRIs, textures (filter by category)
curl -s "https://api.polyhaven.com/assets?t=models"
curl -s "https://api.polyhaven.com/assets?t=hdris&c=studio"
# ambientCG: materials and HDRIs by keyword
curl -s "https://ambientcg.com/api/v2/full_json?type=Material&limit=20&q=concrete" \
| python3 -c "import json,sys;print([a['assetId'] for a in json.load(sys.stdin)['foundAssets']])"
Poly Pizza, Quaternius, KayKit and Kenney are browsed by search on their own
pages; query them with the noun plus the style (low poly dragon, kaykit skeleton), not with a sentence.
Reference only, never geometry: The Spriters Resource, The Models Resource, sakugabooru, game rip archives, Pinterest. Use them to learn the shape and the timing, then build or buy the actual asset.
Shape is half the job; the other half is the motion, and it is researched the same way. Search the verb, not the noun.
# the motion itself, canonical first
web_search: "<subject> <move> animation" # a game doing it
web_search: "<subject> <move> slow motion" # real footage, for weight
web_search: "<subject> sprite sheet" # frame-by-frame timing
yt-dlp "ytsearch6:<subject> <move> animation"
ffmpeg -i clip.mp4 -vf "fps=12,scale=320:-1,tile=6x4" refs/move-%02d.png
Read the sheet, then count frames and convert: seconds = frames / fps, and
scale to the loop length you are building. That is how a 0.42 s anticipation and a
0.18 s contact become the beat table instead of a guess.
Write four lines per action before animating it:
wind-up 0.00 -> 0.42 weight back, head down, tail still
contact 0.42 -> 0.55 fastest frames, one pose held for two frames
follow 0.55 -> 0.90 overshoot, then settle
recover 0.90 -> 1.30 back to idle
Every attack in the beat sheet needs all four. Missing anticipation is why an effect reads as "it just happens", and missing follow-through is why it reads as "it snaps back".
For rigs, cross-check the reference against a real clip: if the library has a punch, a swipe or a jump that is close, retarget it and offset the acting, rather than keying a pose from scratch.
Every build writes refs/SOURCES.md. It is the proof the searches happened and
the reason the next person does not repeat them.
| Question | Searched | Found | Decision |
| --- | --- | --- | --- |
| what does the send-out look like | yt: "sword shield send out slow motion" | RoUJ_TWvB3g, orb + white burst | matched, timings below |
| hero creature rig | poly.pizza "dragon", quaternius characters | nothing matching the silhouette | hand-built from refs/sendout |
| hit reaction weight | yt: "pokemon take damage animation" | 0.9 s flinch, 1.7 s stagger | HURTS table |
A build with no SOURCES.md has not finished its research step, even if the
scene looks right.
Every beat gets frozen, captured and compared against the reference sheet before the next beat is built. The contact sheet of those captures is the review artifact, not a paragraph describing them.
?t=<second> in the page,
freeze(t) through the debug hook, screenshot the frame element.When the user gives a subject in one line, treat it as a commission, not a questionnaire. Make the creative decisions, state them in one short assumption line, and build the whole diorama. Do not stop at a plan, a blockout or a design sheet and wait for approval.
The only reasons to ask are credentials, a destructive action, a path that
would overwrite the user's work, or the Render Preset Gate. That gate is a
deliberate exception to autonomous assumptions: one question, once per project,
before the first mesh. Everything else is a default.
Ask the Render Preset Gate question first, then run the three lookups in
Research Before You Model:
CREDITS.md line per import and the search in refs/SOURCES.md.qa/shoot.mjs, a frozen ?t= frame, a contact
sheet) so every beat can be reviewed as a picture.For an invented subject, spend the same time on reference density instead: find three images that agree on what the place looks like, list the props they share, and build those before any invented detail.
Use these unless the prompt explicitly says otherwise:
State the assumption in one line before coding:
Assumption: market archetype, 46 s loop, 4 service systems, 6 roles plus a late customer, 21 x 14 slab, 64 colours. Say if you want a different scale or genre.
That line is the contract. State it, then continue in the same turn; do not wait for approval. It gives the user a chance to redirect after seeing the assumption, without blocking the build.
A scene like this runs for hours of agent time and thousands of messages: render loops, one screenshot per beat, one probe per bug. The session will need to compress its context, more than once, and compaction is lossy. Build so that a compact does not cost you the work:
DESIGN.md, refs/SOURCES.md,
CREDITS.md, qa/report.json and the beat table in stage.js must carry every
decision. If a fact only exists in a message, it is already gone.qa/frames/<entity>/sheet.png and shots/t-12.40.png are
stable handles a post-compact agent can re-read without rerunning anything.frames.mjs and
shoot.mjs rather than trusting your summary of what the last frame looked
like: the numbers are cheap, and a confident memory of an old build is the
most expensive thing in the session.TODO.md or an issue) so the thread
that survives compaction is the plan, not the chat.A prompt that names only a place is still a commission. Decide what the place does, who arrives, and what goes wrong. State the assumption and build.
Pick the closest row. Do not invent a new genre from scratch unless none fit.
If none fit, use the universal shape: **place + repeated ritual + interruption
Do not freeze. Answer four questions about the noun:
Those four answers give you the system, cast, goal and residue. Then use the five beats: normal output → first interruption → escalation → goal contact → residue and seam. No combat required. A deadline, an inspection, a storm or a closing bell is a valid boss.
Worked one-prompt example:
"a tiny bakery at closing time"
DESIGN.md yourself. Do not ask the user to fill it.file://, README and DESIGN.md agreeing.If time is tight, cut the number of systems or actors, never the detail per hero or the animation layers. Two detailed towers with five layers beat six blockout towers with one fire animation.
Do not report "done" until all of these are true:
DESIGN.md exists and matches the build.file:// with zero console errors.When the subject is new, the first deliverable is a design sheet, not a scene.
With a one-line prompt, fill it from the defaults in One Prompt, One Build and
do not ask the user to complete it.
templates/DESIGN.md into the project as DESIGN.md.The rest of this file is the recipe for each pass.
UI and inspection authority: Canonical educational UI and inspection contract
below owns placement, controls, lessons, selection, focus and restoration. Follow
it rather than inferring defaults from older screenshots. The render preset gate
and free orbit apply unchanged.
Choose sceneProfile: educational for explicit explanations, guided technical cutaways and how-it-works teaching requests—not a machine subject, rotation or a cutaway view alone. This profile takes precedence over ALL narrative quotas below: no mandatory cast, disruption, ritual, landmark, three systems, ambient loops, five actor layers or decorative story props. One accurately constructed mechanism and one clear causal sequence is sufficient. Do not invent a crowd or combat to satisfy the router. Research and construction accuracy remain mandatory; simple UI never means missing mechanical parts.
This is the single authority for educational UI, selection and lesson behavior. EDUCATIONAL / EXPLICITLY REQUESTED FEATURES ONLY: ordinary narrative scenes skip this chapter and its UI tests. Requested narrative inspection may reuse only its selection behavior; do not add the card, lessons or teaching labels. The exact V8 tokens/hierarchy below remain the 3.16 visual contract.
Use code, not an interpretation of “shadcn-style”. For new educational scenes WITH the educational UI enabled (not an explicit UI-free brief), copy templates/education-v8.css and build the DOM hierarchy below. UI-free educational scenes skip this chapter's DOM and UI tests; narrative scenes do not inherit it.
This is the canonical visual contract extracted from the V8 explorer, independent
of the chosen 3D render preset. Default to its ONE right card / mobile bottom dock;
do not substitute the older bottom/center examples as new-build defaults.
An explicitly requested bottom/center dock may change placement only, retaining
these tokens, controls and hierarchy. Existing repairs preserve requested placement.
The older education-dock.css is a minimal helper, NOT the V8 visual reference;
do not use it as the visual starting point for new educational builds.
Evidence: the grandfather-clock drift used beige/brass UI, a separate top-left title, translucent blurred panel and fixed top-to-bottom height. None follows from a clock subject. Brass belongs on the clock, not on its application chrome.
#f7f7f5, opaque card #fff, ink #18181b, muted #71717a,
border #e4e4e7, secondary #f4f4f5, focus/accent #2563eb..viewer: grid minmax(0,1fr) 360px, right padding 24px,
height 100dvh, vertically centered card. Stage is the first grid cell, NOT
a fullscreen canvas underneath an overlay. Card is content-height, max
calc(100dvh - 48px), 22px padding, 18px gap, 14px radius, 1px border,
shadow 0 1px 3px #18181b08, 0 8px 32px #18181b03.minmax(0,1fr) auto; dock max-height
48dvh, full width, top corners 14px, padding 16px 18px plus safe-area bottom.
Measure the actual remaining stage for camera fit and renderer sizing.<main class="viewer">
<div class="stage-wrap">
<canvas id="stage" tabindex="0" aria-label="Interactive mechanism; drag to orbit"></canvas>
<p class="gesture">Drag to orbit · scroll to zoom · click a part</p>
</div>
<aside class="panel" aria-label="Mechanism controls and explanation">
<div class="panel-top">
<header class="panel-head">
<div class="title-row"><h1>Subject name</h1><span class="badge">Interactive</span></div>
<p class="lede">Short input → change → output summary.</p>
</header>
<div class="tabs" role="tablist" aria-label="Mode">
<button id="tab-explore" role="tab" aria-selected="true" aria-controls="explore-panel">Explore</button>
<button id="tab-learn" role="tab" aria-selected="false" aria-controls="learn-panel" tabindex="-1">How it works</button>
</div>
<div class="controls" role="group" aria-label="Playback">
<button class="btn primary" id="play">Pause</button>
<button class="btn icon" id="prev" aria-label="Previous step">‹</button>
<button class="btn icon" id="next" aria-label="Next step">›</button>
<button class="btn icon" id="home" aria-label="Reset view">↺</button>
<button class="btn toggle" id="xray" aria-pressed="false">Inside</button>
</div>
</div>
<section id="learn-panel" role="tabpanel" aria-labelledby="tab-learn" hidden>
<p class="section-note">One short instruction.</p>
<div class="lesson-steps" role="group" aria-label="Causal steps"></div>
</section>
<div class="readout">
<p class="phase-title" id="phaseTitle"></p>
<p class="phase-meta" id="phaseMeta"></p>
<p class="explain" id="explainText"></p>
</div>
<button class="link" id="clearPart" hidden>← Back to cycle</button>
<section id="explore-panel" role="tabpanel" aria-labelledby="tab-explore">
<label class="label" for="parts">Inspect a part</label>
<select id="parts"><option value="">Choose a part…</option></select>
</section>
<details class="disclosure help"><summary>About this model</summary>
<p class="section-note">Simplifications and keyboard help.</p>
</details>
<p class="sr-only" role="status" aria-live="polite" id="announcer"></p>
</aside>
</main>
Adapt subject names, number of lesson steps, part IDs, explanatory text and
physical units only. Omit Inside for a mechanism with no enclosing shell; never
add a fake x-ray toggle. Optional scrubber/Back lives in this same surface, not a
second toolbar. Use line SVG icons matching the supplied CSS in production.
Implement tab click plus ArrowLeft/Right/Home/End roving tabindex, hidden panel
state, and semantic buttons/select/range. Bind controls to the actual evaluator:
play/pause, freeze(step.phase), orbit.reset, reversible inside,
selectPart(id) and clearSelection. A lesson change freezes synchronously and
updates explanation from that state; it must not trigger automatic camera motion.
The skeleton/CSS is not a functioning controller; do not ship inert controls.
#f7f7f5 consistently in CSS,
renderer clear/scene and ground composition; user-requested white overrides all
those together. A screenshot is not mechanical clearance proof.qa/report.json;
missing browser/computed-style/visual checks remain UNVERIFIED.Raycast actual visible geometry: nearest eligible hit wins, respecting nearer opaque occluders. Map the hit mesh to both its assembly ID and its actual piece ID; assembly selection and clicked-mesh selection are distinct scopes. The single labelled keyboard piece picker must expose the same pieces/actions, including hidden pieces; never silently broaden a click to an entire assembly. Show one short explanation in the card. An optional single label uses a live geometry-local anchor and hides behind camera, offscreen or when occluded.
A deliberate canvas/picker Inspect selection may make one short useful camera AND OrbitControls-target transition to live selected bounds. Avoid end-on shafts and blocking housings; use an authored reveal/cutaway for hidden pieces and report remaining occlusion honestly. Save the prior view for Back; Reset restores the hero. User orbit/pointer/keyboard navigation cancels the tween immediately. Reduced motion uses an immediate useful view. Never auto-spin, chase moving parts or restart focus per frame. Lesson step selection instead pauses and synchronously freezes the real evaluator, highlights its part and updates phase/text/readout without moving the camera; only an explicit Inspect action focuses. Scrubbing updates the lesson from evaluated state, not an independent clock. Announce intentional changes politely, not each frame.
Use semantic buttons/select/range, visible focus and non-colour part-name cues;
canvas arrows orbit and R resets. Tabs implement roving focus and keyboard
navigation; no focus trap. Drag/multitouch is orbit, not click (use the movement
threshold/cancel handling in templates/orbit.js); UI gestures never bubble into
the stage. Paused and reduced-motion modes retain inspection.
This is an inspection overlay, not a new render preset, bloom pass or a way to hide modelling errors. Use the same mechanism for a selected gear, valve, pump impeller, drawer slide or anatomical structure. The V8 selection implementation is the calibration evidence: restrained warm material lift, dimmed context, transparent outer castings and selective gold feature edges. Do not interpret “glow” as a white emissive blob.
1. Preserve and derive, never mutate the shared originals. Build a registry once from the actual selectable meshes, BEFORE adding overlays. Store each exact original material reference, including arrays of material slots; a mesh's slot array itself must also be restored by identity. Derive cached variants from each source UUID plus mode. Clone userData and outlineParameters before changing outline alpha, since nested objects may otherwise be shared. Keep toon ramps, texture maps, roughness and existing supported preset properties. Restore the originals before applying each new selection/X-ray state, not by attempting to reverse colour arithmetic.
Use templates/inspection.js rather than duplicating a second material controller.
Its API is createInspection(THREE, {parts, contextMeshes, resolveVisibility, onChange, style}), with select({partId, mesh}), clear(), refresh(),
dispose() and piecePickerEntries(partId, {visibleOnly:false}) (includes hidden
pieces for keyboard inspection). Validate actual mesh membership before selection.
The helper supports rigid meshes only; reject skinned/instanced/morph assumptions.
resolveVisibility returns named hiddenPartIds/hiddenMeshes plus description
for an authored cover removal. Hiding requires shell:true, or an explicit
inspectionOccluder:true part plus an active selection and nonempty cutaway
description; that latter exception may remove an upper gear/bridge to expose a
lower part, never hide construction failures. Optional ghostPartIds/ghostMeshes
are accepted only for shell:true. Selected assemblies/pieces remain visible;
context meshes (floor/stand/UI) cannot hide, ghost or dim.
Unknown parts, duplicate ownership, empty geometry and unsupported material or
deformation paths fail explicitly. Never request a whole-mechanism ghost. The host owns
camera focus, picking and V8 DOM; the helper owns emphasis/restoration, not UI or
mechanical certification. Cached variants derive per original material and mode; never
from the currently displayed variant. Lift colour gently; write emissive values
only where the original material supports them. Dim context as opaque solids.
Only the explicit housing reveal below may change transparency/depth-write.
2. Reveal only manifest-authorized occluders; ghosting is shell-only. Never defeat depth on the selected part. Declare internalPartIds and occludingShellIds per subject in the component manifest. For an internal selection, remove authored covers or optionally ghost only declared outer housings that obscure it; keep the selected part solid, retain non-selected internals as dim solids, and leave floor/stand/UI alone. A global Inside toggle applies that same named reveal plan without dimming all internals. A selected housing stays highlighted rather than ghosting itself. Unlisted opaque solids must still occlude correctly: renderOrder does not override the depth buffer. For an internal blocker, author an explained selection-only inspectionOccluder:true removal plan; the independent Inside toggle still affects shells only. Hidden siblings need a piece-level plan and cannot remove the selected scope. Do not set depthTest=false, use additive whole-body overlays, or fade all solids to pretend a mechanism is correctly constructed. Picker rays ignore generated edges and ghost-shell hits, but respect remaining opaque foreground objects; click and picker share the same selection action.
3. Make the hologram from feature edges, attached to the live part. Do not use wireframe:true: that exposes triangle diagonals. Use EdgesGeometry(source.geometry, 32) and a restrained LineBasicMaterial (color:0xffc35c, opacity:0.5, transparent:true, depthTest:true, depthWrite:false, toneMapped:false). Normal blending, no bloom. Exclude slivers, ring grooves, gaskets and tiny bolts when edges become noise; the V8 thresholds were minimum dimension 0.018 units and, for cast housings, volume 0.006 units³. Those are model-scale-dependent starting values, not universal dimensions. Use one physical edge overlay on the selected component only, not a second full-scene OutlineEffect/Sobel pipeline. Its surface outline may need suppression to avoid doubled contours. WebGL line width is generally one device pixel: do not promise a controllable CSS-pixel width through linewidth.
Attach each owned edge overlay as an identity-transform child of its live source mesh; mark it as an inspection overlay and exclude it from raycasting. On change, remove and dispose owned overlays, never source geometry or shared maps.
This child pattern follows moving rigid geometry without copying a stale pose. If an overlay must be a sibling/world-space object, synchronise its transform from the source every evaluation; copying position/quaternion once is insufficient when the source mesh moves. EdgesGeometry does not automatically follow vertex deformation or per-instance transforms: skinned/morphed/instanced subjects need a deformation-aware shader/overlay or a clearly declared unsupported path. Never claim those supported because a rigid V8 example works. Do not dispose the source geometry, shared source maps, shared toon ramps or original materials; dispose only owned variants/edge geometries and owned overlay materials. Keep overlay generation bounded to selection changes, never create/dispose hundreds of edge objects every frame.
State and restoration contract. One selection controller owns this effect. Resolve in order: restore exact originals → remove previous edges → compute selected/internal/Inside state → ghost selected occluding housings → highlight selected meshes → dim remaining mechanism meshes → attach selected edges. Re-apply from originals when Inside changes. Leaving How it works restores its earlier Inside state and removes its tutorial tint; clearing selection retains an independently enabled Inside toggle. Picker, canvas, keyboard and lesson adapters must not compete by writing materials from separate uncoordinated caches. Clear/reset/teardown restores material references, opacity/depth/blending/outline state, selection/readout and authored camera state; only teardown disposes long-lived caches. Respect reduced motion; avoid automatic pulsing, scanlines or flashing. Keep the part name and keyboard focus as non-colour cues.
Historical evidence (not project dependencies): quartz-watch/shots/highlights/dialPost1.png,
quartz-watch/shots/highlights/dialPost2.png, quartz-watch/shots/highlights/dialPost3.png,
quartz-watch/shots/highlights/dialPost4.png, quartz-watch/shots/highlights/individual-piece.png,
quartz-watch/shots/highlights/rotor.png, quartz-watch/shots/highlights/reduction.png,
quartz-watch/qa/highlights-report.json and quartz-watch/qa/construction-report.json.
These record this repair, not files future users must have. Twenty-six assembly
glow states had numerical tests/captures; only a subset received visual review.
Do not present that as universal contrast certification.
Evidence and test — selection contract (3.18). Quartz-watch selection was
almost invisible, posts were end-on/occluded, and adding emitter properties to
MeshBasicMaterial caused a shader.value error. Use templates/inspection.js,
with templates/qa/inspection.test.mjs and
templates/qa/inspection-browser.mjs; use the API above. Assert assembly versus actual clicked-piece identity,
keyboard equivalence, nearest opaque occlusion, and obvious visible glow with
retained shape/colour (never a white blob) in desktop/phone crops. Test shared
and array materials, Basic/toon, two frozen phases, moving/orbiting, rapid changes,
Inside/clear/Back/Reset/lesson exit, interrupted focus and reduced motion. Restore
exact original material AND slot-array identities, shadow flags and visible
state, plus original material properties; test source immutability and owned-only
disposal with stable overlay/material counts. Basic materials must never gain
emissive or emissiveIntensity, even temporarily; feature-test capability before
writing, and assert absent properties remain absent. Verify shader compilation
and no console errors in the fresh browser build. Scalar/material tests alone do
not establish visible contrast, depth correctness or useful focus.
Use this short checklist for existing educational scenes before re-reading narrative recipes. Evidence: the LEAP-1B repair was requested because its permanent section exposed the core, its fit cropped the model, its beige background and crowded panel did not match the requested V8 reference. These checks supplement mechanical QA; passing enclosure rays or a screenshot does not certify a complete mechanism.
distance - along, so each fit bound
contributes abs(transverse)/tanHalf + along (not minus along). Do not clamp
distance below the solved fit or distort portrait aspect. Re-measure on layout,
disclosure, resize/orientation and zoom changes without hijacking user orbit.
Test: project covered/exposed swept bounds at desktop, tablet, 390×844,
320×640 and 200% zoom, with lesson/disclosure open; front/back/high captures;
fail an injected protrusion and verify near-plane/focus fits separately.Canonical educational UI and inspection contract, including rendered
background, accessible lesson state and desktop/phone/200% zoom gates. Do not
copy the reference subject or introduce a second surface.These construction rules apply across subjects and all render presets; they supplement, not replace, the style gate and profile-aware verification above. They make known failures testable, not impossible.
Specify the mating interface before decorating the part. Extend the component manifest with units, parent-local frame, shaft/bore/slide axes, shared joint/port anchor IDs, mating surfaces, nominal dimensions and radial/axial tolerances. Derive both mating meshes and their motion from those anchors, not repeated guessed offsets. A bearing eye needs a real through-bore; its beam, cap, bolt and bevel must stop outside that bore. Budget bevel/fillet intrusion in the actual construction method (inward bevels reduce usable bore), axial lane widths, spacers, end float and end stops. Check coaxial alignment and anchor residual after parent transforms. Model the load path through real bearings, brackets, fasteners and a base; route each functional port through an actual connected opening to its destination, not a hose ending inside a solid. Document symbolic/omitted internals. Evidence: V8 running-gear repair found a centred rod beam cutting its crankpin despite an annular eye, bank stagger applied to only one mating member, and fillets facing the wrong local axis. Test: local-axis/anchor tests, measured bore plus bevel allowance and axial stack tests, section crops from two orbit directions, and traced port/support connections. Record geometry revision and proof frames in the manifest. Copy templates/mechanism-contract.mjs and fill the interface and connection sheets in templates/DESIGN.md; the helper validates scalar budgets, not arbitrary mesh bores or load strength.
Audit the complete swept assembly, with narrowly scoped intended contact. Derive every driven pose from one driver and test the actual transformed meshes or documented conservative collision proxies, including beams, caps, fasteners, webs, fillets and supports. Broad-phase boxes alone neither detect holes correctly nor prove clearance. Enumerate potentially interacting pairs and coverage; whitelist only a named pair of mating surfaces with phase window, normal-gap/penetration tolerance and rationale (bearing/journal, meshing teeth, valve/seat), never an entire assembly or all pairs of a part type. All other pairs need the declared positive clearance. Check full travel, extrema, cycle seam, contact transitions and close-approach intervals with refinement; include ports/FX containment. Report method, sample spacing, tolerance, worst phase/pair, exclusions and unresolved regions. Dense sampled vertex/triangle tests are bounded evidence, not continuous exact collision proof: use analytic bounds or conservative continuous checks where available, otherwise retain that limitation explicitly and block unsupported clearance claims. Evidence: the V8 12/12 invariant report omitted rod/crank interference; the later rod probe added bore triangle samples, axial lanes, journal vertices, anchor residual and fillet axes. Test: intentionally inject a beam-through-bore, wrong-axis fillet, too-wide lane, out-of-window contact and a non-whitelisted overlap; each must fail. Run full-cycle probes plus before/contact/after crops from two angles. tests budget/contact-policy failure detection only; per-scene geometry/sweep checks remain mandatory and UNVERIFIED until run.
Lesson/UI behavior and its tests are defined once in Canonical educational UI and inspection contract. templates/education-dock.mjs remains a dependency-free
state helper with templates/qa/education-dock.test.mjs; its older CSS is not the
V8 visual authority.
Copy templates/orbit.js for EVERY scene and preset. Create it after camera fit with the fitted target; keep animation evaluation independent of camera interaction. Render on control change even when paused. Expose orbit.reset() and have the QA freeze wrapper reset it before capture (freeze(t) evaluates time synchronously). User pause/freeze UI need not reset their chosen inspection angle. Fit zoom/polar limits to real subject bounds without preventing back/high inspection. No auto-rotation, no camera motion driven by the animation clock. Keep reset + a brief drag/keyboard hin
Full long-form guide for detailed rotatable Three.js dioramas. Narrative scenes are scene-first with no educational UI unless requested. Classic pixel, stroked-toon and pixel+stroke are rendering choi
---name: dioramadescription: Full long-form guide for detailed rotatable Three.js dioramas. Narrative scenes are scene-first with no…---# SKILL.mdÜbersicht
Full long-form guide for detailed rotatable Three.js dioramas. Narrative scenes are scene-first with no educational UI unless requested. Classic pixel, stroked-toon and pixel+stroke are rendering choices, not educational modes. Explanatory commissions use the separate educational contract. Includes composition, cast, animation, craft, sourcing and construction.
FAQ
Laden Sie SKILL.md vom Herausgeber herunter oder kopieren Sie den Pfad und öffnen Sie das Repository. PlugMCP listet den Skill und hostet die Datei nicht.
Der Herausgeber pflegt es unter https://github.com/sloemo01/diorama.
Claude, Cursor, Codex und Grok Build können eine SKILL.md lesen, die Sie aus dem Repository des Herausgebers hinzufügen. Grok Bot installiert sie, wenn Sie den Link zum GitHub-Ordner des Skills in einem Chat senden.
| user owns the output |
| anything the pack libraries do not have, generated from the reference |
export GLB, keep the prompt in CREDITS.md |
freeze(t)qa/report.jsonorbit.reset(), never during user inspection.templates/qa/mechanism-contract.test.mjsRepeated interfaces share anchors and axes (3.18 evidence + test).
Generate ALL repeated mating members from one anchor/axis table, not just the
first working example. Quartz-watch pads at radius 12.6 missed posts at 13;
rotating a native CylinderGeometry about Y did not redirect its native Y axis.
The seconds shaft opposed its hand and the model lacked a physical 60:1 stage.
Coplanar shaft-cap fans z-fought. Use transformed local axes (quaternion maps
native Y to the declared axis), common anchors, real through-bores and a single
end surface or measured axial separation; never hide coplanar caps with depth
overrides. Derive ratio/direction from the actual connected transmission, not
only a display hand formula. Test: with templates/mechanism-contract.mjs
shared anchors/checkRepeatedInterfaces/checkEndPlanes, enumerate every pad,
post, bore, cap and shaft; assert count, transformed axis/anchor residual,
radial/axial clearance and physical ratio/direction across the full cycle.
The repaired watch measured zero residual at all four pad anchors and 0.08
board-bore radial clearance; those are historical measurements, not defaults.
Inject one displaced repeat, wrong native axis, sealed bore, reversed shaft,
missing reduction and coplanar cap; each relevant check must fail. Review
section/end-on and oblique crops; scalars cannot prove real mesh openings.
Evidence: the historical construction report and highlight shots above.