An AI agent skill that turns any subject into a 3D film or app
Add playable web game mode, frame-guard checks, longer self-review and look notes; release 0.4.3
Nguyen Xuan An480ad2e47bdd
diff --git a/plugins/visualize-in-3d/.claude-plugin/plugin.json b/plugins/visualize-in-3d/.claude-plugin/plugin.jsonindex cedbe0a..5380d88 100644--- a/plugins/visualize-in-3d/.claude-plugin/plugin.json+++ b/plugins/visualize-in-3d/.claude-plugin/plugin.json@@ -1,6 +1,6 @@{"name": "visualize-in-3d",- "version": "0.4.2",+ "version": "0.4.3","description": "Turn hard-to-picture places, systems, objects and events into a 3D world you can watch, learn from or click through: a live three.js app with a dashboard, a lesson app, a documentary film, or an illustrated cutaway book, built from real layouts and models made from real references.","author": {"name": "CodePawl",diff --git a/plugins/visualize-in-3d/skills/visualize-in-3d/SKILL.md b/plugins/visualize-in-3d/skills/visualize-in-3d/SKILL.mdindex 93447c5..3d6b0c3 100644--- a/plugins/visualize-in-3d/skills/visualize-in-3d/SKILL.md+++ b/plugins/visualize-in-3d/skills/visualize-in-3d/SKILL.md@@ -1,14 +1,16 @@---name: visualize-in-3d-description: Turn anything hard to picture into a 3D world people can watch or play with - an operation or system (airport, data center, port, factory, hospital), an event spreading over real land (wildfire, flood), a story in time (a historical event, a case), characters or machines in action (a fight, a chase, a launch), or how a thing works. Builds a live three.js app with a dashboard and a 30 s film, a lesson app, a quick no-Blender prototype, a live embed that runs on real data inside an existing dashboard, a documentary film, an action short, or an interactive cutaway plate or book. Looks include toy isometric, point cloud, photoreal terrain, dark documentary, pixel diorama and illustrated cutaway plate. Models come from ready sources or Blender builds made from real references, and the skill checks its own frames before showing anyone. Use for "visualize how X works", "show this event on a 3D map", "a live 3D dashboard of X", "a 3D lesson on how X works", "a documentary-style 3D explainer", "a quick 3D prototype", "two creatures fight in 3D".+description: Turn anything hard to picture into a 3D world people can watch or play with - an operation or system (airport, data center, port, factory, hospital), an event spreading over real land (wildfire, flood), a story in time (a historical event, a case), characters or machines in action (a fight, a chase, a launch), or how a thing works. Builds a live three.js app with a dashboard and a 30 s film, a lesson app, a quick no-Blender prototype, a live embed that runs on real data inside an existing dashboard, a documentary film, an action short, or an interactive cutaway plate or book. Looks include toy isometric, point cloud, photoreal terrain, dark documentary, pixel diorama and illustrated cutaway plate. Models come from ready sources or Blender builds made from real references, and the skill checks its own frames before showing anyone. Use for "visualize how X works", "show this event on a 3D map", "a live 3D dashboard of X", "a 3D lesson on how X works", "a documentary-style 3D explainer", "a quick 3D prototype", "two creatures fight in 3D", "app nhìn như game", "làm phim 3D về", "cho 2 con đánh nhau", "pixel battle", "theme point cloud", "kiểu wildfire tool".license: MIT----# Visualize in 3D+# Visualize in 3D (Dựng thế giới 3D để thấy mọi thứ vận hành)++If `references/local.md` exists, read it first: it sets the folders and house rules for this machine.Take any subject and make it visible in 3D: models from real references, a seeded simulation or a scripted timelinedriving them, a look chosen for the subject, and a film checked frame by frame. The user can also start it with-`/viz3d <mode> <subject>` (modes: app, lesson, prototype, embed, film, action, book).+`/viz3d <mode> <subject>` (modes: app, lesson, prototype, embed, film, action, book, game).Paths use `{{WORK_DIR}}` for the folder where projects live (the current directory unless the user names one) and`{{SKILL_DIR}}` for this skill's folder. Write paths with forward slashes on every platform.@@ -38,10 +40,11 @@ Read what the user wants people to see, then pick one shape (or combine two) and| Characters, creatures or machines doing something | Action short | `references/action.md` || One object cut open or exploded | Cutaway film, or an app with a section view | `references/film.md`, `references/looks.md` || One big object or building with many rooms, as a page or a book | Book: interactive illustrated cutaway plate, with quizzes | `references/book.md`, `references/looks.md` |+| A game people play in the browser (steer a creature, survive, grow) | Playable web game, bot-balanced | `references/game.md` || A demo for leaders in about an hour | Quick prototype from three.js primitives | `references/live-embed.md` || A live view inside an existing dashboard or product | Embed (web component or iframe) on real data | `references/live-embed.md`, `scripts/mock-feed.mjs` |-Pick the look in `references/looks.md` (Choosing): toy isometric, point cloud, photoreal terrain, dark documentary+Pick the look in `references/looks.md` (Choosing): clean ops world (default for a system that runs), toy isometric, point cloud, photoreal terrain, dark documentarypixel diorama or illustrated cutaway plate. Study a look the user shows from a reference video with timestamped frame sheets(`scripts/contact-sheet.sh <video> <folder> <fps>`), then write it up as a new section in `looks.md`.@@ -89,3 +92,5 @@ on the user's word.- Render and encode at low priority, one heavy job at a time, and stop every server you start.- Real people and real harm: facts from sources, victims named with respect, no gore (`references/documentary.md`).- Reference images and videos are for study only: never ship them in the app or the film.+- The public copy of this skill is mirrored from this folder. Edit only this folder; never put personal paths, names+ or tools outside `references/local.md`. A nightly sync script mirrors the rest.diff --git a/plugins/visualize-in-3d/skills/visualize-in-3d/agents/openai.yaml b/plugins/visualize-in-3d/skills/visualize-in-3d/agents/openai.yamlindex 78415f5..9bd6298 100644--- a/plugins/visualize-in-3d/skills/visualize-in-3d/agents/openai.yaml+++ b/plugins/visualize-in-3d/skills/visualize-in-3d/agents/openai.yaml@@ -1,4 +1,4 @@interface:- display_name: "Visualize in 3D"+ display_name: "Dựng thế giới 3D để thấy mọi thứ vận hành"short_description: "Turn a subject into a 3D world: live app, film, lesson or action short"default_prompt: "Use $visualize-in-3d to turn this into a 3D world: "diff --git a/plugins/visualize-in-3d/skills/visualize-in-3d/references/action.md b/plugins/visualize-in-3d/skills/visualize-in-3d/references/action.mdindex b265a80..ed6df3f 100644--- a/plugins/visualize-in-3d/skills/visualize-in-3d/references/action.md+++ b/plugins/visualize-in-3d/skills/visualize-in-3d/references/action.md@@ -67,6 +67,25 @@ Choreography:- Every special move gets its own cast. It has a wind-up pose and a charge that builds. Then the effect growsfrom its source to the target. An effect that pops into place at full size reads as cheap.+Creature motion has physics in every joint (from a user note on a cockroach idle: "a little rigid, make it more+insect movement, feel the physics in every joints"):++- Never drive joints straight from smooth noise or sine curves; that glides like a puppet. Behaviour picks targets+ and every joint is a damped spring chasing its target, stepped at a fixed rate from time 0 so frames stay+ deterministic.+- Insects and small animals dart and hold: targets jump on a seeded schedule (a few tenths of a second to a+ couple of seconds apart), with short flicks and taps between. Big animals use slower, softer targets.+- Chains (antennae, legs, tails, whiskers): each outer joint hangs off the one inside it and feels its parent's+ angular acceleration, so it lags and whips. Heavy inner joints are stiff and well damped, light outer ones+ springier. Keep damping near 0.5 and inherited inertia near 0.3 on long chains: nine light springs at 0.28+ damping and 0.6 inertia resonated into a 220 degree tip swing.+- Plot joint angles against targets before recording a clip: a move overshoots once and settles within about two+ cycles, and nothing grows.+- Before tuning a gait, wingbeat or strike, read the measured kinematics for that animal (or its nearest studied+ relative) and cite them in SOURCES.md: which joints carry the stroke, cycle rate, duty factor, body sway (An,+ 2026-10-29, "did you reference the cockroach walk + sprint?"). Insects push by extending the femur and tibia;+ the hip moves little, so a hip-only stroke looks like rowing. Mark slowed rates and judgement calls as such.+Effects must look heavy and dangerous:- Beams, jets, flames and exhaust have an opaque core with a white-hot centre and saturated outer layers. Firediff --git a/plugins/visualize-in-3d/skills/visualize-in-3d/references/game.md b/plugins/visualize-in-3d/skills/visualize-in-3d/references/game.mdnew file mode 100644index 0000000..7cf1fb3--- /dev/null+++ b/plugins/visualize-in-3d/skills/visualize-in-3d/references/game.md@@ -0,0 +1,116 @@+# A playable web game++A free browser game people play, not a film or a dashboard: one creature or unit the player steers, a world that+pushes back, and growth the player earns. Reading map: Core loop, Controls, Growth, Opponents and the director, Bot+playtests, Creature motion, Tutorial and first load, Performance, Film mode and the post, Deploy, Credits. Read the+whole file for a new game; read only the matching sections when fixing one part.++## Core loop++- Goal readable in 5 seconds with no text: move, eat, grow, survive. One screen shows the player's unit, its+ size count and the nearest threat.+- Third-person chase camera in an open world unless the user asks for a diorama. The player's unit must be the+ only strong colour in a quiet world, large enough to read at phone size.+- A run has a start (one small unit), a middle (growth, fights) and an end (death card with time and size, "play+ again" without a page reload).++## Controls++- Move: the unit follows the pointer (mouse, or drag on touch). Keep steering easy; hard controls were a complaint.+- Two abilities on separate buttons with cooldowns: an attack (lunge) and a defence (dodge that becomes a parry+ when started just before a hit, `PARRY_WINDOW` about 0.35 s). Each ability is a small object with active seconds,+ cooldown seconds, `ready(time)`, `trigger(time)` and `recharge(time)` (0 to 1 for the button fill), all on the+ simulation clock, never wall time.+- Every enemy attack has a telegraph (a shadow, wind-up, ground ring or line, a sound) that ends in the attack, so+ the player can react.++## Growth++- Growth is tied to food and never jumps. Food is handed in bites to the units whose heads are in reach; a unit has+ a belly 0 to 1 and a size that follows it; a full unit splits or grows after a short visible wind-up (a pinch).+- Cost per growth step rises with the count, so a chicken is a few steps for one unit and a fraction of one for a+ crowd. Check the food supply in the world is enough to reach the cap you set.+- Hunger drains the belly over minutes; a bite resets it. Show a hunger icon only when a fifth of the crowd starves.+- Eaten prey breaks into visible chunks (meat, bones) that the crowd then eats piece by piece. Cap the count+ (desktop and phone separately).++## Opponents and the director++- Opponents unlock over time (birds at about 1 minute, a farmer at 3, a mower at 6), each with a telegraph, an+ attack, a counter the player can learn, and meat when beaten. A pixel toast and an icon show a new kind the first+ time.+- A difficulty director owns spawning. A pressure budget fills at a rate that grows with minutes and with the+ log of the crowd size, and is spent on unlocked opponents (cost and cap per kind, cap in total). After a big fight+ there is a rest. An `adapt` factor (about 0.35 to 1.8) falls with recent losses (decay about 25 s) and rises when+ the crowd grew fast, so weak players are eased and strong players pushed.+- Cheap early opponents fade in weight later so they do not farm the player all game. After a late start time the+ pressure climbs every minute so every run ends.+- All numbers live in one tuning file that a URL flag can override (`?tune=name:value`) for playtests.++## Bot playtests (the balance gate)++- Balance by bots, not by feel. A headless script runs the real game on a manual clock with fixed 1/60 s steps and no+ drawing, with three bots: idle (never moves), simple (steers at the nearest food, no abilities) and good (hunts+ by value, lunges at fleeing prey, dodges at the end of a telegraph, avoids lanes and traps).+- Run several seeds per bot (8 is enough) with a time cap, at below-normal priority, against a served production+ build. Report survival median, min, max, peak crowd and when the cap is reached.+- Targets: idle dies in about a minute, simple in a few minutes, good in 10 to 16 minutes, with no seed where the+ good bot lives to the cap. A bimodal simple bot (some seeds die at the first enemy) means the first minute is+ too hard.+- Re-run after any change to tuning, the director or the opponents. Bots never start the tutorial.+- Seed everything (`?seed=N`) so a failure reproduces.++## Creature motion++- Legless bodies (worms, snakes) push side to side in proportion to speed: a serpenoid path where the head's heading+ swings as a sine of the distance travelled. No sideways slip, and the body is still at rest. Never a time-based+ wiggle on a follow-the-leader spine; it reads as flapping.+- Bodies follow the head's path (a trail of past head positions), slow and smooth-skinned.+- Creatures climb objects and each other with the body following the surface; stacking is capped to a few layers.+ They never pass through rocks, logs or crates, and a pile is overlapping S curves, never spiral coils.+- Seeded per-creature randomness: wavelength, amplitude, speed and hesitation drift slowly, read from noise along+ the distance travelled (shape) or time (pace), never white noise, so a crowd never moves in lockstep.+- Soft-chain physics rigs (dozens of tiny rigid links) are unstable in game physics engines. In Unreal Chaos, links+ of about 2 cm exploded on the first tick and force-driven chains flew apart. Drive the motion kinematically and+ use physics only for contact.++## Tutorial and first load++- In-world labels pinned to things, not a text wall: a pulsing ring ahead with "Move the mouse", an arrow and "Eat"+ on the first food, "Left click to lunge" on the first fleeing prey, and a short slow-down at the first telegraph+ with the spot outlined. Labels are DOM text projected from world points every frame and clamped to the screen.+- First run only (remember it in local storage), a "How to play" link replays it, a visible Skip, and a flag turns+ it off. The director holds real opponents back until the lunge step is done or a minute has passed.+- Pixel loader in the page itself (first paint before any script): the bar fills from the real loading manager and+ the last tenth is "building world". Favicon set (ico, 16, 32, apple-touch), a web manifest, an Open Graph image and+ title and description meta tags.++## Performance++- Draw calls are the usual cost. Merge every multi-box model into one mesh per moving part with vertex colours and+ one shared material; instance repeated things; do not draw or pose creatures outside the camera view (plus a+ margin for their shadows); update the shadow map every other frame.+- Write a perf script that holds the worst case (crowd at the cap, all opponents out) and logs draw calls and+ milliseconds per frame. Budget about 500 to 1000 draw calls and a frame that leaves headroom at 60 fps. The+ headless browser tops out near 57 to 59 fps, so judge by work per frame, not by that number.+- Lower caps on phones. After rendering is cheap, the simulation step is the next cost: profile it.++## Film mode and the post++- A film mode (`?film`, `?manual`) runs on a virtual clock (requestAnimationFrame and the time functions+ overridden) with scripted URL flags for seed, start size and camera pulls, so any frame renders the same and a+ film can be cut from real play. Play mode keeps the real rules.+- Record a real gameplay video of the live build before drafting any post about the game. A post shows play, not a+ render of something the game does not do.++## Deploy++- Static assets only: build to a folder, serve it from a static host (a Worker with an `assets` directory and a+ custom domain works). Cache headers: hashed build files `public, max-age=31536000, immutable`; models, sounds and+ fonts about a week.+- After deploy, open the live URL and check it plays, the loader shows, the OG image resolves and the manifest loads.++## Credits++- A credits page lists every asset with source and licence (CC0 model packs, an open-licence font, CC0 sounds);+ keep a machine-readable `credits.json`. Code under MIT. Do not ship an asset whose licence is unknown.diff --git a/plugins/visualize-in-3d/skills/visualize-in-3d/references/looks.md b/plugins/visualize-in-3d/skills/visualize-in-3d/references/looks.mdindex 3a2f957..f0e18ef 100644--- a/plugins/visualize-in-3d/skills/visualize-in-3d/references/looks.md+++ b/plugins/visualize-in-3d/skills/visualize-in-3d/references/looks.md@@ -2,13 +2,14 @@Each topic file names one look. The look sets the world's rendering, the UI skin and what the film shows; the datamodel, the dashboard parts and the film's click-driven shape stay the same. Reading map: Toy isometric (default),-Point-cloud survey, Photoreal terrain analysis, Dark documentary, Pixel diorama, Illustrated cutaway plate, Lived-in isometric, Dither + ASCII showcase, Choosing.+Point-cloud survey, Photoreal terrain analysis, Dark documentary, Pixel diorama, Illustrated cutaway plate,+Lived-in isometric, Dither + ASCII showcase, Gradient glow ASCII, Clean ops world, Choosing.Reference stills or clips for a look are optional. If you have some, save them under `{{WORK_DIR}}/references/<slug>/`and point the briefs at them; they are for study only and never ship in the app or the film. Without them, thedescription of each look below is enough.-## Toy isometric (default)+## Toy isometricBuilt for an AI data center, an agents office, an airport ramp, a chip fab, air traffic control, a metro and a tollplaza. Think of a clean isometric diorama inside a light operations dashboard.@@ -204,9 +205,74 @@ Required for every film that shows off assets, models, a tool or a product in 3Dproving the look held.- Type: one monospace face, white or ink on the dark ground. Credits for sourced assets sit on the end card.+## Gradient glow ASCII++For a creature or object that is itself the art (an insect, an animal, a machine in motion), where the ASCII body is+the point rather than a backdrop for a clean model. First used for a cockroach season.++- The real lit 3D scene and a view-normal pass render at 3x3 texels per character cell (about 7x12 px cells at+ 1080 wide). Each cell picks a glyph from a brightness ramp (`: - = + * # % @`); depth or normal edges pick a line+ glyph by direction. Every surface cell shows at least a colon so bodies read as filled shapes, not outlines.+- Brightness is light plus a rim term (surfaces turned from the camera glow), so the silhouette always lights up.+- Colour comes from a 5-stop gradient (deep violet, violet, magenta, orange, cream), positioned by light mixed with+ a diagonal screen sweep (about 0.8 sweep). Light alone goes cream and monochrome; the sweep is what makes it a+ gradient.+- Materials are made matte (roughness 0.7+, no metal): glossy highlights blow out to white and skip the gradient.+- Bloom only above about 0.55 luminance, so highlights and rims glow and the frame never fogs over.+- Ground is black with a faint radial haze drawn as 2 px 4x4 Bayer dots in the two darkest stops.+- Key light low and in front for faces (heads tucked under a shell go black otherwise), a strong rim from behind,+ and a soft fill from the camera.+- Creatures with antennae, whiskers or tails longer than the camera distance: never frame the close-up from in+ front of the head, where the lens sits inside their sweep and they whip across the frame. Use a low 3/4 profile+ behind the antenna's line. Antenna idle waves need a phase shift of about 1 radian per segment; an in-phase+ wave stacks over the chain and stands the antenna straight up.+- Blended-transparent materials (wings, fins, glass in many downloaded models) write no depth, so the glyph pass+ reads them as empty background and they vanish. Switch them to an alpha cutout (`transparent false`, `alphaTest`+ about 0.35, `depthWrite true`) and render the normal pass double-sided (roach wings, 2026-10-29).+- A floor under the glyphs needs its own sparse treatment (tag it in the normal pass, 1-4 small glyphs by light,+ wide grout) plus a light pool that travels with the subject, or a tracking shot reads as flat haze.++## Clean ops world (default for a system that runs)++A white-grey, evenly lit world with one teal accent, framed like a real operations product. Fits any place or system+that runs a process: a factory, port, airport, hospital, data center, warehouse. Values below come from a finished+reference app (a chip fab with a roof cut away, three.js with react-three-fiber).++- World: pale cool greys only (ground `#e6ebf2`, backdrop and fog `#d3dae5`, roads `#c3cad6`, pads `#dde3ec`, white+ markings, dark trim `#3a4250`). Machines are white and light-grey matte shells (roughness about 0.62, metalness+ about 0.02) with thin accent stripes in the brand colour (teal `#13a594`). Colour is kept for state: green running,+ amber waiting, red fault, and one warm orange for the thing being tracked (a lot, a parcel, a patient).+- Camera: high 3/4 view, field of view 30, started about 60 / 120 / 160 from the centre looking down at it. Polar+ angle limited to 0.25-1.25 rad so the user never goes flat or underground. Smoothed orbit (0.55 s), min distance+ about 7 m, a follow mode that tracks a clicked unit.+- Cutaway: roofs and near walls are removed or cut to stub height so the insides and the floor below show; keep the+ far wall as a thin backdrop with a teal top rail.+- Light: one warm sun (`#fff6ea`, intensity about 2.1) from the front-left and high, soft shadow (radius 4, 2048 map,+ shadow box fitted to the site and refreshed every other frame), a hemisphere fill (`#eef4ff` over `#aab6c8`, 0.6),+ a neutral room environment at 0.3, tone-mapping exposure about 0.74. Postprocessing: N8AO ambient occlusion+ (radius about 1.6, intensity about 2.4, tint `#33415c`), light bloom only above luminance 1.0 for lamps and screens+ (intensity 0.7), SMAA. Fog hides the edge of the world.+- Content: people, vehicles and goods run the real process on a seeded simulation (queue, move, process, move on,+ breakdowns with a ticket and a person who walks to fix it). Zone labels lie flat on the floor in teal pills.+- UI, framed as a real product with an invented name: top bar (logo, search with a `/` hint, site switcher, live clock+ with speed multiplier, alert bell, user); four KPI cards top left (icon in a soft teal square, label, big number+ with a delta, one line of context); a list panel bottom right with tabs per entity kind and rows with a status chip+ and progress bar; a progress or route timeline bar bottom left; zoom and home buttons on the left edge. Cards are+ white at 94 percent, 12-16 px radius, a soft blue-grey shadow, one system font, tabular numbers. Palette: ink+ `#18212f`, muted `#6a7588`, fills `#f2f5f9`, status chips tinted soft backgrounds with a matching mark.+- Interaction: click any unit to open its card (state, load, rate, what it is doing now) and a pin and tag over it; a+ list row flies the camera there and follows it; Esc or a click on empty floor closes the card.+- Data: every number on the dashboard is computed from the running model, never typed in; the delta and the lists+ change as the simulation runs.+- Film: a virtual clock and real clicks on units and list rows, ending on the world (see `film.md`).+- Traps: a second accent colour, a dark theme, camera too low (loses the cutaway), KPI numbers that do not move.+## Choosing-Toy isometric is the default for every topic. The point-cloud look can read as dull on a busy site, so use it when+Clean ops world is the default for a system that runs (an operation with units, tasks and flows). Toy isometric (a+more playful diorama on a slab, stronger colour) stays as an alternative when the user asks for it or the subject is+light-hearted. A showcase film always uses dither + ASCII with the model+rendered clean. The point-cloud look can read as dull on a busy site, so use it whenit is asked for. Otherwise pick the look the place itself suggests: built places full of moving vehicles go toyisometric; land and water seen from above go point-cloud; an event spreading across real land over time goesphotoreal terrain; a case or a piece of history told in order goes dark documentary; a small floating world withdiff --git a/plugins/visualize-in-3d/skills/visualize-in-3d/references/self-review.md b/plugins/visualize-in-3d/skills/visualize-in-3d/references/self-review.mdindex 34517a6..2d46bdc 100644--- a/plugins/visualize-in-3d/skills/visualize-in-3d/references/self-review.md+++ b/plugins/visualize-in-3d/skills/visualize-in-3d/references/self-review.md@@ -24,6 +24,12 @@ measurement or a look at the frames could have found.## Generic faults+Reading map: read "Every film" always, then only the groups that match what you built. Groups: Every film; Camera and framing; Apps and UI; Books and illustrated plates; Motion and physics; Vehicles, roads and terrain; Weather, light and water; Sound; Documentary screens and evidence; Game.++### Every film++Read always.+- The subject the viewer follows leaves the frame or shrinks under about 40 pixels tall.- An effect or a panel covers that subject for more than 0.3 s.- A colour, material or texture breaks for a few frames (a flat tint, a missing texture, z-fighting flicker).@@ -37,33 +43,31 @@ measurement or a look at the frames could have found.- A colour cast added by the encode grade: compare one raw render frame with the same frame of the encoded film. Run`eq` and `vignette` on YUV and the blend on gbrp. An `eq` on gbrp frames before a screen blend turned a whole filmpurple.-- A cut that leaves part of the scene standing: a custom ShaderMaterial ignores `clippingPlanes` unless its shaders- include the clipping_planes chunks. Shoot every cut view and look for water, sky domes or effects left in front of- the section.-- A surface that looks right headless and wrong in a real browser (a moat gone white from sky reflection). Check the- published page in Chrome at the default hour before reporting.-- Too many controls on an interactive page: panels in several corners, labels on every object at once, controls over- the subject. Use one dock at the bottom, one menu open at a time, and labels only for the current step. A phone card- must leave the subject in view.+- A result card or toasts over the last beat of a film that should end on the world itself. End on the simulation+ unless the plan asks for a card.++### Camera and framing++Any shot with a moving camera.+- A symbol in the frame centre: an emblem at the vanishing point, or wall parts that line up into a cross. A statue'sraised arm can also read as a salute. Check every documentary shot about a regime for these.- A close shot from inside the subject's own clutter: tall dark parts (pylons, racks, masts) fill the frame.Nothing reads as one object. Pull back until each part has space around it. In an app film, shrinkthe dashboard so the world fills most of the frame.-- A pop-up page that reads as a greeting card: one flat cut-out on one plane in front of a wall of text. A pop-up- needs depth layers at different distances, box folds with volume and a scenic backdrop. Its layers rise in a- staggered order and shadow each other.-- Stiff programmer drawing on painted textures: straight strokes, hard polygon edges, flat fills. Illustrated art- needs curved, tapered ink lines, soft washes and organic shapes.-- Close-ups that go soft or show only part of the detail. Paint each texture at 1.5 times the texels of the closest- shot, and draw text at that size. Use maximum anisotropy and frame the whole detail.-- Loud, hissy foley on a gentle action, such as leaf-rustle recordings used for page turns. Keep paper foley soft and- low-passed under the music, with few snaps, never louder than the beat it marks.-- Stacked sounds on one action, and "magic" stingers: a page turn with a creak, snaps, chimes and marimba at once.- Use one sound per action, and no wind chimes or sparkle on a reveal.-- Falling water drawn as opaque white sprites or a row of identical streaks. At phone size it reads as foam clumps or- a barcode. Draw clear falling water as a thin, mostly transparent sheet that catches light on its edges.- It turns white only where it breaks, and its width varies.++### Apps and UI++Interactive apps, dashboards and their films.++- Too many controls on an interactive page: panels in several corners, labels on every object at once, controls over+ the subject. Use one dock at the bottom, one menu open at a time, and labels only for the current step. A phone card+ must leave the subject in view.+- A cut that leaves part of the scene standing: a custom ShaderMaterial ignores `clippingPlanes` unless its shaders+ include the clipping_planes chunks. Shoot every cut view and look for water, sky domes or effects left in front of+ the section.+- A surface that looks right headless and wrong in a real browser (a moat gone white from sky reflection). Check the+ published page in Chrome at the default hour before reporting.- The main event is missing from the picture while the numbers say it happens: a flood stage that shows dry roomswith "46 cm" in the HUD. Shoot every stage and check that the event (water, fire, smoke) is drawn in everyview, the section view included.@@ -73,13 +77,74 @@ measurement or a look at the frames could have found.more than one line of text sits on an opaque surface.- A cut-away neighbour faded with a coarse dither reads as a ghost polka-dot block. Fade it to a clean low alpha orcut it to stub height like the main building.+- A map layer toggle that draws nothing readable: thin world-width lines vanish at overview zoom. Shoot each layer at+ overview and close, and draw network overlays with screen-space width lines and moving particles.+- A time scrubber that moves the numbers but not the world (An, 2026-10-29, Session Fab: "chỉnh mốc thời gian mà+ trên không gian k thay đổi j, hầu như đều tuyến tính"). Show the data's real rhythm in the scene: quiet days empty,+ peaks packed, areas rising and falling at different times. Shoot a quiet, a normal and a peak position side by side;+ they must differ at a glance.+- A real place that reads as sci-fi or cluttered (An, same day: the fab "k giống cái factory thật lắm, hơi scifi và+ khó nhìn"). Check against photos of the real place before shooting: real proportions, its own colour cues, fewer and+ larger elements, nothing decorative, readable at 1280x720.+- A film a stranger cannot read in two seconds (An, 2026-10-29, Claude Code Factory: "nhìn sơ qua video thì chưa thấy+ và hiểu được gì"). Small realistic people, identical stations repeated down the hall and a close camera hide the idea.+ Use big friendly units in the subject's own brand colours (a mascot-like bot for software), a different station+ design per role with a label sign, the links between stations drawn by their real volume, and open on the full+ overview.++### Books and illustrated plates++Pop-up books, cutaway plates, painted textures.++- A pop-up page that reads as a greeting card: one flat cut-out on one plane in front of a wall of text. A pop-up+ needs depth layers at different distances, box folds with volume and a scenic backdrop. Its layers rise in a+ staggered order and shadow each other.+- Stiff programmer drawing on painted textures: straight strokes, hard polygon edges, flat fills. Illustrated art+ needs curved, tapered ink lines, soft washes and organic shapes.+- Close-ups that go soft or show only part of the detail. Paint each texture at 1.5 times the texels of the closest+ shot, and draw text at that size. Use maximum anisotropy and frame the whole detail.++### Motion and physics++Anything that walks, crawls, drives or is simulated.++- A thin object resting on a surface that sinks into it or z-fights: a curled sheet of paper whose middle passes+ through the desk read as see-through (An, 2026-10-29). Run the contact check (`measureContacts` in+ `scripts/frame-guard.js`) on every frame for each object that rests on another; a vertex below the surface or+ within the z-fight gap is a fault.+- A character merged with what it lies on or under: a body sunk into a mattress and a sheet passing through it (An,+ 2026-10-29, "mền và model người nó bị dính vào nhau"). Lay the body on the surface with the contact check (sample the+ skinned vertices), and drape a blanket over it by shrink-wrapping a cloth grid onto the body and mattress with a+ small offset, never a fixed shape that intersects.+- A change the viewer cannot read: an empty corner meant to say "the machine vanished" looked like "the machine was+ smashed" (An, same day). Show the before and the after in the same framing, so the change itself is on screen.+- A light effect that reads as a prop: a visible red beam cone under a small EXIT sign looked odd. Small practical+ lights get a glow on the wall and floor, not a volumetric beam.++- A transition clip played on loop: a "sit" clip that is really the sit-down motion stands people up and sits them+ down every cycle. Check each clip's first and last root pose; a clip that ends in a different pose plays once and+ holds its last frame, or the model gets a separate held pose.+- A legless body that wiggles on a clock: a time-based wiggle on a follow-the-leader spine reads as flapping. Push side to side in proportion to speed (a serpenoid path driven by distance travelled), with no sideways slip and no motion at rest.+- A creature that goes through objects or moves in lockstep with its neighbours: bodies must follow the head's path, climb objects and each other with capped layering, and carry seeded per-creature randomness (wavelength, amplitude, speed, hesitation).+- A propeller or wheel that looks still in the film (An, 2026-10-29, Factory Clawds: "chong chóng tre nó k xoay").+ A two-blade rotor that steps near 90 degrees per frame aliases to frozen. Spin it at 25-35 degrees per frame, add a+ faint blur disc, and make the blades thick and light enough to read at phone size.+- Flying units that pass low over signs and stations and cover them (same day). Rise vertically, cruise above the+ tallest object, and descend vertically into an open spot. Paint station names on the floor like the belt labels+ instead of on floating sign cards, and keep landing spots off that text.+- Units that stand still while idle or working (An, 2026-10-29, Factory: "lúc nó idle hay làm việc thì nó k có tương+ tác gì, nhìn nó bị nhạt"). Give each role its own readable work loop with the station's prop (typing, page turns,+ scanning with a magnifier), idle fidgets out of sync (bounce, look around, turn to a neighbour), and a small payoff+ when a task ends. Moving units also leave a path trail, flights included.+- A soft chain built from dozens of tiny rigid physics links: it is unstable (in Unreal Chaos, links of about 2 cm exploded on the first tick and force-driven chains flew apart). Drive the motion kinematically and use physics only for contact.++### Vehicles, roads and terrain++Built places, traffic, ground.+- A town or site with no streets: houses and cars standing on grass because the layout had lots but no road graph.Every built place gets its circulation first (roads with curbs, sidewalks and lane paint, driveways, yard paths),and every vehicle drives on it.-- A map layer toggle that draws nothing readable: thin world-width lines vanish at overview zoom. Shoot each layer at- overview and close, and draw network overlays with screen-space width lines and moving particles.-- Dark puddle ellipses scattered on grass read as holes, and street-lamp light pools drawn as huge orange discs.- Puddles only on paving, few and sky-reflective; a lamp pool about the lamp's height in radius.- Vehicles that ignore the ground and the road: a car keeps its flat height and yaw on a hill, so it sinks into theslope going up and floats going down, or points off the lane. Sample the ground under the front and rear axles everyframe, set height and pitch from them (and roll from both sides), yaw from the lane tangent, wheels spinning with@@ -88,25 +153,72 @@ measurement or a look at the frames could have found.- Bare ground in the frame: neighbours cut low so the subject stays visible leave a flat empty field behind them.Put a next row of full-height buildings behind the subject (behind it as seen from the camera, so it hidesnothing) with facades turned toward the camera, never plain rear walls, then low plots out to the distance fade.-- A transition clip played on loop: a "sit" clip that is really the sit-down motion stands people up and sits them- down every cycle. Check each clip's first and last root pose; a clip that ends in a different pose plays once and- holds its last frame, or the model gets a separate held pose.-- A result card or toasts over the last beat of a film that should end on the world itself. End on the simulation- unless the plan asks for a card.-- A silent input: a click, wheel step, key press or drag in an app film with no sound on its frame. Check the- recorder's input log against the cue list.+- Dark puddle ellipses scattered on grass read as holes, and street-lamp light pools drawn as huge orange discs.+ Puddles only on paving, few and sky-reflective; a lamp pool about the lamp's height in radius.++### Weather, light and water++Rain, water, beams.++- Falling water drawn as opaque white sprites or a row of identical streaks. At phone size it reads as foam clumps or+ a barcode. Draw clear falling water as a thin, mostly transparent sheet that catches light on its edges.+ It turns white only where it breaks, and its width varies.- A flashlight beam drawn as a straight translucent cone: hard edges, even brightness, frozen in the hand. Draw itfrom the lens, fade it along its length and toward its edge, add faint haze noise and motes, and let the hand drifta little. Guard the shader against NaN (pow of a negative, normalize of zero): one NaN pixel through bloom turns thewhole frame black.- Rain that falls as one uniform slant: every streak tilted by the same wind vector, same length and brightness. Keeprain near vertical, give each drop its own lean, speed, length and brightness, and let gusts move across the scene.++### Sound++Any film or app with audio.++- Loud, hissy foley on a gentle action, such as leaf-rustle recordings used for page turns. Keep paper foley soft and+ low-passed under the music, with few snaps, never louder than the beat it marks.+- Stacked sounds on one action, and "magic" stingers: a page turn with a creak, snaps, chimes and marimba at once.+ Use one sound per action, and no wind chimes or sparkle on a reveal.- A rain bed that hisses, sounds dull or rings. A distant rain wash is a band of hiss, low-passing it sounds cheap,and offset copies of a mono bed comb-filter into a ringing room. Pick a close recording whose energy sits mostlyat 250 Hz to 4 kHz at a steady level, measure its band shares before mixing, and keep it quiet under the cues.- Sound tails that read as reverb in fast stretches (a howling wind bed, a clank left ringing, a thunder with a longfade) and a low tone under the whole film (a bed whose loudest band sits at 80-250 Hz). Keep wind thin, cut one-shotsto their dry attack, drop ambience with no picture event, high-pass rain near 500 Hz and water near 150 Hz.+- A silent input: a click, wheel step, key press or drag in an app film with no sound on its frame. Check the+ recorder's input log against the cue list.+- An empty opening: a cold open with only a faint hum or room tone before the music starts. Viewers leave in the+ first seconds. Music plays from the first second; keep true silence for one punch line later in the film.+- A long gap between two music pieces: 7 s of room tone under a documentary punch line read as "empty, boring" (An,+ 2026-10-29). Bridge with a drone or a pulse; true silence stays at 1 to 2 s.++### Documentary screens and evidence++Screen recordings, archive pages, documents, titles.++- A screen shown flat and still, filling the frame. Film it as an object: the plane at an angle, shallow depth of+ field on the action, a camera that pans with the cursor or typing and makes eased push-ins to close-ups (An,+ 2026-10-29, on a cold open with no zoom and no close-up). Typing, windows and cursor moves each get a sound.+- Evidence as flat frames on black: empty boxes with labels and a red strike read as slop (An, same day). Put the+ papers, photos and objects on a lit desk in 3D, with close-ups and a moving camera.+- A close-up everywhere, or a push-in before the viewer has seen the whole (An, 2026-10-29: "zoom quá nhanh, chưa kịp+ nhìn ở tổng thể"). Show a plain screen straight on; when a close-up earns its place, hold the full view 1.5 to 2 s,+ then push in slowly with eased, continuous camera curves (no speed jumps between segments).+- The narration names a state the picture does not show: "headaches, nausea" over a child standing still. Act it out+ (posture, sway, hands to head, a slow double-vision blur) without gore.+- A title cut away before it is read (An: "chuyển cảnh quá nhanh chưa kịp nhìn"). Let it land, hold still about 2 s,+ then move on with a camera move (a tilt down into the next scene) rather than a hard break.+- A paper or white flash frame between dark shots: one bright frame in a dark film reads as a glitch. Keep exits dark.+- A body that acts a symptom in silence: a headache, nausea or a nightmare acted with no breath, groan or cough+ under it. Give the figure its own voice sounds (no words).+- A title that only fades. Give it a short motion: assembling from slices, a light sweep, slow tracking, a break-up+ on exit.++### Game++A playable web game (`game.md`).++- A game balanced by feel: no bot playtest (idle, simple and good players, several seeds) with survival times against targets.+- A post about a game made from a render or a mock-up instead of a recording of the real build being played.## Growing the listsdiff --git a/plugins/visualize-in-3d/skills/visualize-in-3d/scripts/frame-guard.js b/plugins/visualize-in-3d/skills/visualize-in-3d/scripts/frame-guard.jsindex a935c9a..9cb3f68 100644--- a/plugins/visualize-in-3d/skills/visualize-in-3d/scripts/frame-guard.js+++ b/plugins/visualize-in-3d/skills/visualize-in-3d/scripts/frame-guard.js@@ -1,3 +1,16 @@+// Contact guard (measureContacts): for objects that rest on a surface (papers, a mug, a folder on a desk), checks every+// frame that nothing sinks into the surface or sits so close that it z-fights. Usage inside renderAt(time):+// const contacts = measureContacts([{ name: 'invoice', object: invoiceGroup, surface: deskMesh }], { minimumGap: 0.0003 });+// if (contacts.some((entry) => !entry.ok)) { /* log it with the time and fail the render */ }+// `surface` is a horizontal mesh (its top is found by a ray from above), a world height (number) or a function+// (worldX, worldZ) => worldY. Every vertex of every visible mesh under `object` is taken to world space and compared with+// the surface below it. A vertex lower than the surface is a 'penetration'; one above it by less than `minimumGap` is a+// 'z-fight'. Meshes with userData.contactIgnore = true are skipped. Each result is+// { name, ok, lowestGap, vertexCount, faults: [{ kind, gap, worldPosition }] }, faults capped by maxFaultsPerObject.+// Skinned meshes (a rigged character lying on a bed) are sampled with skinning applied (SkinnedMesh.getVertexPosition),+// measureContacts refreshes their world matrices itself; pose the bones before calling it.+// A pair may also set side: 'below' (the object must stay under the surface, e.g. a body under a blanket; the gap is+// surface minus vertex) and vertexFilter(mesh, vertexIndex) => boolean to measure only some vertices (e.g. not the hands).// Dependencies: none beyond "three" (tested with 0.186). Copy this file into the app next to your render code.// Frame guard: measures where the film's subjects land on screen, every frame, so a render// fails on the faults a viewer sees first (a creature cut by the frame edge, shrunk to a few@@ -128,3 +141,65 @@ export function findFaults(frameLog, { minHeightPixels = 24, minVisibleShare = 0}return faults;}++const contactRay = new THREE.Raycaster();+const contactOrigin = new THREE.Vector3();+const contactDown = new THREE.Vector3(0, -1, 0);++function surfaceHeightBelow(surface, worldX, worldY, worldZ) {+ if (typeof surface === 'number') {+ return surface;+ }+ if (typeof surface === 'function') {+ return surface(worldX, worldZ);+ }+ contactRay.set(contactOrigin.set(worldX, worldY + 1000, worldZ), contactDown);+ contactRay.far = 3000;+ const hits = contactRay.intersectObject(surface, true);+ return hits.length ? hits[0].point.y : null;+}++// pairs: [{ name, object, surface, side = 'above', vertexFilter }]. options: { minimumGap = 0.0002, penetrationTolerance = 0, maxFaultsPerObject = 3 }.+export function measureContacts(pairs, { minimumGap = 0.0002, penetrationTolerance = 0, maxFaultsPerObject = 3 } = {}) {+ const probe = new THREE.Vector3();+ return pairs.map(({ name, object, surface, side = 'above', vertexFilter }) => {+ // updateMatrixWorld (not only updateWorldMatrix) also refreshes a skinned mesh's bind matrix inverse.+ object.updateWorldMatrix(true, false);+ object.updateMatrixWorld(true);+ if (surface && surface.updateWorldMatrix) {+ surface.updateWorldMatrix(true, true);+ }+ const faults = [];+ let lowestGap = Infinity;+ let vertexCount = 0;+ object.traverse((child) => {+ if (!child.isMesh || child.userData.contactIgnore || !child.visible) {+ return;+ }+ const positions = child.geometry.attributes.position;+ for (let index = 0; index < positions.count; index += 1) {+ if (vertexFilter && !vertexFilter(child, index)) {+ continue;+ }+ if (child.isSkinnedMesh) {+ child.getVertexPosition(index, probe);+ } else {+ probe.fromBufferAttribute(positions, index);+ }+ probe.applyMatrix4(child.matrixWorld);+ const surfaceY = surfaceHeightBelow(surface, probe.x, probe.y, probe.z);+ if (surfaceY === null) {+ continue;+ }+ vertexCount += 1;+ const gap = side === 'below' ? surfaceY - probe.y : probe.y - surfaceY;+ lowestGap = Math.min(lowestGap, gap);+ const kind = gap < -penetrationTolerance ? 'penetration' : gap < minimumGap ? 'z-fight' : null;+ if (kind && faults.length < maxFaultsPerObject) {+ faults.push({ kind, gap, worldPosition: probe.toArray() });+ }+ }+ });+ return { name, ok: faults.length === 0, lowestGap, vertexCount, faults };+ });+}