Skip to content

Agent skill for creative 3D visualization: turn an idea into a Three.js/Blender scene worth exploring. Claude Code + Codex plugin, 223 recipes, 440 knowledge records, 22 proved kits, 37 runnable studies.

17.4 KB
Raw Blame

Roadmap

The foundation begins with three pilot subjects: fantasy village, linear transformation, and cube face turns. They exercise artistic composition, factual geometry, and discrete state changes. Pilot records are not equivalent to evaluated scenes.

Milestone Completion evidence needed
Three-recipe foundation Canonical skill/data, clear contracts, useful local checks, English documentation
Pilot scene evaluation One retired pilot preserved with committed software-rendered captures and an observation report, plus a controlled before/after generation run over five artifacts — baseline, with-skill, with-skill after the scaffold fix, with-skill after the kit steps, and with-skill after the quality tiers (2026-09, one 30-item scale, n=1 per condition, self-graded, software-rendered)
Installation verification Actual discovery, invocation, update and removal on named host versions; so far one observed Claude Code 2.1.265 --plugin-dir load (2026-09-09), no marketplace or Codex app install
Full direction coverage Original 144-recipe milestone reached across 24 directions; current 223 recipes provide at least six per direction, with deeper topic coverage remaining
Broader catalog Authored budgets complete: 144 recipes, 96 conditional reasoning rules and 72 domain-validation records
Public release License selected, asset rights reviewed, reproducible packages, release rehearsal and verified install instructions

The milestone table distinguishes authored coverage from remaining targets. No completion date or compatibility promise is implied.

Creative workflow refinement

The current entrypoint puts object identity and representation before kit selection. Direct reuse, adapted kits, custom geometry and sourced assets are valid routes; T0–T4 remains a description of shipped kit pipelines rather than a universal art or factual-quality scale. Visual review is conditional on the subject. Existing evaluation scores describe the earlier rubric; evaluation of this revised guidance remains separate work.

Subject-clarity and meaningful-motion guidance now covers synchronized annotations, local deformation and clearance, readable control effects, and scientific model/unit/readout consistency. It consolidates author feedback into conditional workflow guidance; it does not increase dataset counts or establish new runtime proof.

Lighting guidance now covers visible key direction, uniform inverse-square scene rescaling, shadow fit at tiny world scales, practical emitter/receiver ownership and reversible day/night state. This is skill workflow guidance only; catalog counts and runtime-proof status are unchanged.

Foundation implementation status

Two hundred twenty-three recipes cover all 24 registered directions, with at least six per direction. The canonical catalog contains 440 reusable knowledge records across 18 populated families, including 18 theme profiles and 22 kit blueprints, plus 451 source records and 3,599 public evidence events. This includes 99 conditional reasoning rules, 75 domain-validation records, 12 geometry profiles, 22 lighting profiles, 28 tool adapters and 12 output profiles. The retained 144-recipe, 96-reasoning-rule and 72-domain-validation authoring budgets remain completed historical targets; source and editorial checks do not establish rendered or runtime validity.

The skill entrypoint, optional search/resolve/design-context helpers, evidence validation and local ZIP packaging are implemented. Shared-script governance and its current command inventory are documented in shared tooling; broader experiment/export inspection commands require demonstrated reuse before implementation. Generated indexes lead progressively to 24 direction pages and 17 knowledge-family pages. Search includes applicability conditions so conditional rules can be retrieved for their intended context.

The four original depth batches are promoted after source and editorial review. Further subject depth, broader paraphrase retrieval evaluation and runtime evaluation are separate follow-on work, not unfinished rows in the completed authoring budgets. Latent Village received a bounded catalog-guided refinement: supported locomotion, connected mill/door mechanics and an isolated cargo contact experiment. Its sequential checks and software-rendered browser observations remain in the historical demo validation report. The documented showcase captures landed on 2026-09-09. Existing desktop observations remain separately scoped to their artifact revisions; see coverage accounting.

The object/material/physical/tool expansion adds eight reviewed records per family (32 total). Three water revisions are also promoted with portable historical snapshots. Later reviewed batches add handbook inspection, object/science construction, mixed-domain recipes and bounded experience/math/physics records. The first two Blender/Three.js waves add 29 records: 17 evaluated-asset, rendering and physics handoffs, followed by 12 functional-object, decal/height, decoder/texture-transform and lighting contracts. A third wave adds 21 presentation/composition, motion, interaction and geometry profiles, and a fourth adds 14 inspection, validation, delivery and breakable-joint profiles, bringing the four-wave total to 64 records, 88 net-new sources and 605 events; see Blender and Three.js: design the handoff. No Blender export, decoder, solver, browser or renderer was run for these data batches. At that checkpoint all 229 authored lexical retrieval cases, all unit tests, schema/evidence, generated-index and package checks passed; 209 protected baseline files and the original 414-source prefix remained exact. This does not establish runtime or subject validity. The approved depth collection is complete. Broader model coverage can be proposed through the handbook coverage audit; concrete adapter and artifact validation remain separate work.

Object Lab reached a bounded 37-body playground revision with pendulum impact, stacked blocks, dominoes, pointer grabbing and tunable contact/playback controls; its build and sequential Node tests passed at that revision. That scene was retired on 2026-09-08 together with the matrix and cube scenes, so the paragraph is historical and its artifacts no longer exist; the scoped upgrade report keeps the observations as history. These were local artifact observations, separate from catalog validation.

GitHub Actions files are authored and their local checks pass. Hosted workflow runs, app installation, marketplace discovery and the wider artifact evaluation remain unverified or incomplete.

Accuracy + creativity pass (2026-09)

An eight-phase pass closed the distance between what the catalog described and what an agent could actually execute. Status:

Phase Status and outcome
1 · Repository back to green Done — references left dangling by the retired scenes removed; validate.py, check-retrieval.py, check-docs.py and the unit suite pass again
2 · defaults contract Done — an authored / source-backed defaults block on recipe and knowledge records, plus scripts/evidence-log.py for revision evidence
3 · Look and mood numbers Done — numeric defaults on 33 style profiles, five named looks, eight mood lighting profiles, and the visual anti-slop checklist
4 · Execution layer Done — the 10-step entrypoint, templates/ scaffold, rigs, artifact document templates, inspection checklists and scripts/capture.py
5 · Subject accuracy Done — 21 recipes with worked numeric defaults, three state tables, a default tolerance rule and four factual tooling records
6 · Retrieval Done — both collections searched by default, validated alias expansion, 241 authored known-intent cases
7A · Example upgrade Done — historical pilot with sky, fog, environment, bloom, shared materials, instanced scatter, canvas picking and committed captures
7B · Before/after evaluation Done — before-after-2026-09: one prompt, same model and host, five artifacts published with capture sets and per-item scorecards, all scored on one 30-item scale. Baseline 21, round 1 19 (scene never animated), round 2 23 (after the scaffold fix that failure produced), round 3 23 (after the kit steps), round 4 25 (after the quality tiers; totals re-read on 2026-09-09 after item 9 gained a lightness floor, which every run now passes) — the only run to pass the surface item, with a Blender-baked T3 hero and the viewport fit recovered. It also costs 7,242 draw calls at 2.3 fps, the most of the five, and ships three of seven named views damaged by camera placement. n=1 per condition, self-graded, SwiftShader; item 17 and the T3 tier were authored in the same week by the same author
8A · Blueprint contract Done — the blueprint knowledge kind with asset, params, sockets, detail_ladder, footprint_m, poly_budget, fits_looks and proof; scripts/kit-proof.py and its offline harness; evidence-log.py check-run; one proved blueprint
8B · Village kit library Done — 22 proved blueprints (6 buildings, 8 props, 4 plants and rocks, 2 walkers, 2 Blender GLB heroes) with 95 captures, kit-core.js / kit-walk.js, nine primitives, layout/village-layout.js, and the scatterInstances colour-squaring fix
8C · Layout, retrieval and workflow Done — design-context.py --blueprints --look, SKILL.md steps 5 and 6, anti-slop item 16 (the detail ladder) and the per-frame close-up procedure, knowledge.hero-detail-ladder-defaults, 8 blueprint retrieval cases and the "Add a blueprint" contributor section
8D · Re-evaluation Done — the early-slice example rebuilt on the kit modules (152 example tests), and eval run 3 generated and scored with all four runs re-scored on the 16 + 13 scale

The pass produced authored guidance and one upgraded local artifact. It did not produce hardware-rendered frames, host certification or an independently graded quality result.

Quality tiers (phase 9, 2026-09-08 / 09)

A follow-on pass gave the kits a stated quality ceiling instead of an implied one. Status:

Phase Status and outcome
9A · Tier contract, textures and occlusion Done — a tiers block (T0 blockout, T1 flat, T2 procedural surface, T3 baked, T4 authored) on the blueprint contract, kit-surface.js canvas textures and vertex-baked occlusion through buildKit(create, { tier, surface }), knowledge.surface-tier-defaults, and kit-proof.py --tier writing per-tier captures and their own check id. Measured, not assumed: texture build 248 ms at 1024 px, vertex AO 107 ms at 13 samples, AO a fine 2.5–3.4 luma contact effect
9B · Host probe, quality brief and LOD Done — scripts/host-probe.py reports OS/CPU/GPU/Blender/runtime and computes a quality_ceiling; design-context.py --host --delivery --hero adds a per-blueprint quality_brief (role, tier, reason); lodFor() swaps tiers by distance; capture.py gained --gpu and --format/--quality and records webgl_renderer and capture_mode
9C · Blender T3 heroes Done — scripts/hero-tier.py bakes a T3 hero GLB from a kit module's own geometry through a located Blender (blender_locate.py), time-boxed and cached; a missing Blender is reported, never faked. Two heroes ship (timber-cottage-t3.glb, watermill-t3.glb), both under the 2 MB cap
9D · Tier proofs, mixed-tier example, eval run 4 In progress — all 22 records declare tiers; T2 proved on 18 with the four exceptions stating a measured reason; both T3 heroes proved after a 16 px bake-margin rebake; the example village runs heroes at T3, mid ground at T2 and instanced background at T1 (overview draw calls 2,902 → 2,330, first frame 0.45 s → 2.37 s of which 1.70 s is the AO bake). Anti-slop item 17 (surface on the hero) makes the checklists a 17 + 13 = 30 item scale and all four earlier runs were re-scored on it. Eval run 4 is generated, captured in SwiftShader (with a labelled, unscored GPU set beside it) and scored: 24 / 30, the only item-17 pass, and the most expensive scene of the five
9E · Showcase renders Done (2026-09-09) — 21 GPU-captured frames in docs/demos/showcase with a log naming host, capture mode, tiers and hashes; village at mixed tiers, harness frames at their proved tier, two breadth recipes. Limits stated in the gallery: four village looks via the example's look switch, harness frames are stills, T2 is stylized-game quality

The ceiling is stated, not implied. T2 is stylized-game quality drawn in the browser; T3 is what Blender can bake from the same geometry, and only two heroes have it; T4 — hand-built topology and edge flow for film or photoreal work — ships nowhere and is a schema slot every record declares missing. A tier a record does not prove is a tier it does not claim, and the AO bake cost, the draw-call floor and the single-bake limit are published rather than tuned away. Nothing in this pass was graded by an independent grader or rendered on certified hardware.

Follow-ups this pass deliberately left open:

  • Source hygiene: three duplicate URL pairs, and version strings that should become content hashes.
  • Knowledge gaps named while working: BatchedMesh, cascaded shadow maps and XR-controller records.
  • A uniform-grid broadphase for the example's creature sweeps.
  • A second independent grader for the before/after evaluation; the first run is self-graded with n=1.
  • A repeat of the before/after run against the scaffold fixed on 2026-09-08 (zero-dt render loop and the camera rig's missing invalidate, now covered by capture.py --motion-check and a liveness item in both checklists); the published run's numbers stand as recorded.

Design commitments

  • One standalone skill and one canonical dataset.
  • Creative freedom across styles, representations, and interactions.
  • Factual claims checked against sources and actual rendered output.
  • New knowledge added primarily as data, without topic-specific code branches.
  • Public evidence that distinguishes proposals, source verification, and observed behavior.
  • Small edits handled directly; substantial scenes get coherent design and validation artifacts.

Release blockers

The maintainer must choose a license and review third-party media rights before release. Plugin and host compatibility need actual tests. The existing historical village media must not be presented as an English runtime demo of the new skill; the documented showcase that need was waiting on landed on 2026-09-09 (gallery, twenty runtime captures with host and tier per frame), so what remains here is the license and media-rights review.

See the changelog for recorded changes and contributing for focused ways to help.

Character study follow-up

The rejected Yuna character experiment was removed from the local app at the user’s request on 2026-09-08. One interactive scene remains after the matrix, cube and Object Lab scenes were retired the same day. The skill showcase was produced on 2026-09-09; broader demo redesign remains deferred.

The fifth craft wave adds ten style/theme/reasoning profiles, bringing this depth program to 74 records, 89 net-new sources and 655 evidence events. Five overlapping reasoning candidates reuse existing contracts rather than duplicate them. The approved subject collection is now complete as authored and independently reviewed content.

The reviewed mathematics, logic and puzzle subject batch adds twelve recipes, fourteen sources and 92 events. Finite numerical/discrete models retain exact input/state boundaries and explicit Blender-to-Three.js construction; inverse history is distinct from imported-state solving. These are source-reviewed authoring contracts, not executed solvers. The subsequent scientific and applied collections are also complete, as recorded below.

Nineteen further scientific recipes cover supplied biomedical records, mechanical/XPBD/contact models, chemistry trajectories/orbitals and environmental/observer/scenario models. They add 23 net-new sources and 146 public evidence events. Each separates source facts, authored numerical assumptions, object construction and runtime ownership; no clinical, calibration, forecast or device validation is implied. Cities/operations, AI/quantum, art/story and concrete XR subjects are now promoted after independent review.

The completed Blender/Three.js depth program adds 74 knowledge records and 49 subject recipes (123 total), with 146 net-new sources and 1,016 public evidence events. The final applied collection contributes cities/operations 5, AI/quantum 5, art/story 5 and XR 3. Overlapping candidates reuse existing records; this is coverage of the approved collection, not exhaustive coverage of every 3D subject. A clinical intervention recipe still requires a named procedure/version, primary guidance and qualified review before collection. Actual artifact, specialist-data and device validation remain separate from documentary acceptance.