erhe-creations

name

erhe-creations

description

Build an MCP-driven showcase scene ("creation") in the erhe editor. Read BEFORE starting, revising, or debugging any creation in scripts/creations/ - covers the workflow (self-launching scripts, screenshot iteration in either build, windowed showing), the mandatory scene-graph hierarchy rules, and the MCP editor gotchas (transforms, materials, lighting); domain recipes (vegetation, physics rigs, CSG/hulls, settling, sweep blades) live in references/*.md indexed inside. Revise this document (and the matching reference file) at the end of each creation session with new learnings.

Editor AI Creations

Showcase scenes built by driving the in-editor MCP server from Python scripts in scripts/creations/. Each script is self-contained and reproducible: it launches the editor, builds one scene, frames the camera, screenshots and saves the scene.

Maintenance contract: read this document before any creation work; at the end of a session, fold new facts in (and prune anything they made obsolete). This file is the workflow contract + gotcha index; stable domain recipes live in references/*.md (see "Domain recipes" below) - fold workflow/tooling facts HERE and domain facts into the matching reference file (new domain = new file + one index line here). This skill is the canonical home for creation knowledge - agent memory and prompt_queue.txt only point here.

Existing creations

creation_1_conway_cathedral … creation_20_frog (henge, reef, robots, ragdoll, glass audience, sandbox + L-system oak, forest glade, monster portal island, UAP hangar, windswept glade = glade + physics foliage + wind, spider sentinel = motor-held STANDING ragdoll, tree garden = 28 Finnish species via lsystem_trees.py, sail ships = CSG-carved convex-hull hulls + FFD-billowed sails, rockfall = physics-settled rock piles + staged cairn under the manual clock, fish = geometry-graph body box->lattice->subdivide + CSG-forked tail, dolphin = organic body as ONE editable geometry graph: per-part box->subdivide->lattice chains, Transform-posed (quaternion mode), Join + single Boolean union + final subdivide, see csg_hulls.md + geometry_graph_sculpt.md, frog = sitting frog on a lily pad, same one-graph recipe scaled to 25 parts: segment-aligned articulated legs + toes, probed surface accents (iris/nostril/tympanum), low-frequency mottle texture, CSG pad slits, and a LIVE POSE RIG - every part posed by a transform_from_node driven by a scene node under Frog > "Frog Rig" - see geometry_graph_sculpt.md + csg_hulls.md). Look at the two or three most recent scripts before writing a new one - they carry the current idioms.

Workflow

• Every script self-launches the WINDOWED Release editor with --commands config/editor/commands_empty.json (no default scene; the creation scene is the ONLY scene). Flags from common.standard_args: --reuse (attach to running editor), --editor-exe (pick a build), --pause N (recording pause after first visible mesh, default 10 s), --no-save (optional: skip save_scene; windowed saves work since the exporter's content-flag filter, 2026-08-08).
• Iterate with screenshots: capture_screenshot works in BOTH builds since 2026-08-08 (windowed captures the editor's own composited frame -- one frame of extra latency, handled inside the MCP server). Iterating against the WINDOWED build is now fine and needs no ini ritual; the headless build (--editor-exe build_vs2026_vulkan_headless/src/editor/Release/editor.exe) is still useful when the display is off or the user is using the machine. Judge the PNG in logs/creations/, fix, rerun. Expect 2-4 iterations; composition problems (occlusion, framing, washed lighting) are the usual finds.
• HEADLESS ONLY: big viewports need config/editor/desktop_window_imgui_host_imgui.ini seeded with [Window][Viewport_window N] Pos=8,28 Size=2288,1160 for N=2..12 BEFORE launch. Back up the user's ini first and restore it after the headless iterations (previous sessions keep a backup at %TEMP%\erhe_imgui_ini_backup.ini). Windowed runs use the user's real layout and skip all of this.
• Iteration modes (2026-08-08): --reuse attaches to the running editor AND closes the previous run's scenes first (--keep-scenes opts out) - iterate without relaunching or leaking scenes. --reframe <glb> skips the build: it load_scenes the saved .glb and runs only the script's camera/screenshot stage - composition iteration in seconds instead of a full rebuild. Generic since 2026-08-09: hoist the shot list to a module SHOTS constant and put if common.reframe(args, title, base_path, SHOTS): return at the top of main() (creation_16 is the pattern; creation_14 has the older hand-rolled version). EVERY new creation should wire this.
• --only <object> partial rebuild (2026-08-09; creation_16 is the pattern): attach to the running editor's scene (implies reuse + keep-scenes), c.delete_nodes(names=[obj]) the object's root group, rebuild only that object, close-up screenshot via . Structure main() so it supports this: objects in a name -> builder map, scene-level setup (ambience/lights/ground) gated on , materials through (returns the existing library material by name instead of stacking suffixed duplicates). Measured on creation 16: 182 vs 419 MCP calls for a one-ship change. EVERY new creation should wire this too.

Scene-graph hierarchy (MANDATORY for all creations)

Every logical object (a plant, a robot, a prop, a craft) is ONE subtree under its own group node, and nesting continues INSIDE the object following its construction logic:

• common.Creation.group(name, position, parent_node_id=None) makes the empty root node. Children pass parent_node_id= on create_shape / create_node with WORLD positions - create_shape sets world_from_node first, then parents world-preservingly, and create_node inserts synchronously, so a just-created group/shape id is immediately usable as a parent. No reparent pass, no settle needed.
• L-system structures mirror their bracket structure in the graph: the turtle's bracket stack doubles as the node parent stack - each segment's parent is the segment it grew from ([ pushes the current parent, ] pops it); leaves/blooms/pinnae hang off their carrying segment; canopy clusters attach to the branch that contributed most tips.
• Non-L-system props nest by construction: mushroom group > stem > cap > speckles; moss on its rock; a fallen log carries its stubs, moss and colonizing mushrooms on the log node; a lamp's shade/bulb/light are children of the swinging rod.
• Children under rotated parents keep working with world positions and global-space transform_selection - creation 8 (lamp) and 10 (deep glade) rely on this.
• Verify with get_scene_nodes (parent / parent_id fields): count root-level nodes (should be ~one per object + camera/floor/lights) and the depth histogram. Reference: forest glade = 742 nodes, 37 roots, depth up to 7.

Transform gotchas (cost real debugging time - trust these)

• Pose at creation: create_shape takes rotation_xyzw, scale (number = uniform brush bake, collision follows; [x,y,z] array = node TRS scale, visual only - pair with motion_mode "none") and mass (dynamic parts; inertia rescales). One call replaces the old create + select + rotate + deselect sequence, which was 69% of a big scene's MCP time.
• Geometry reuse (2026-08-09): common.shape() pools by shape type
  • geometry parameters - repeated calls place instances of ONE content-library brush (create_shape add_brush once, place_brush after), so N same-shaped parts cost one geometry + GPU allocation and save/load as one glTF mesh with N node references. Free win: keep geometry parameters identical across repeated parts (quantize instead of jittering slice counts / radii); vary look per instance with material, node scale ([x,y,z]) and pose, which stay per-instance. A NUMBER bake scale builds one primitive per distinct value (memoized) - fine for a few sizes, wasteful for per-part random scales. Pass reuse=False if a placed instance must not register a library brush at all; geometry ops are safe on shared instances - they REPLACE the mesh's primitives, so the edited instance silently goes private while the others keep sharing. Brushes appear in the scene's Content Library (Brushes folder) and persist in the saved .glb via ERHE_brushes.
• Unit-geometry parts: for procedurally SIZED visual parts (jittered lengths/radii would defeat the pool), use common.part() - a unit box/sphere/cone brush shared per proportion key, sized per instance with node TRS scale (cone taper quantizes to 0.1 steps; it is baked geometry). Node scale scales the whole subtree, so part() keeps the scaled mesh a LEAF: pass as_parent=True when the part will carry children and it inserts an unscaled pose node as the attach point. NOT for physics parts - collision shapes and body shape="auto" hulls ignore node scale, so sway spines and static colliders keep shape(). The pose node is RIGID (position + rotation, no scale; server-side via place_brush pose_node), so joint carriers on pose nodes keep the same rotated constraint frames a mesh carrier would have.
• Batch placements: batch = c.part_batch() collects parts and batch.flush() places them all with ONE place_brush_instances call (one round trip, one editor frame). batch.part() returns a handle usable as the parent_node_id of LATER parts in the same batch (server-side parent_index) - whole branch chains batch; handles resolve to real node ids at flush. Only spines/statics interleave: create them with shape() (real ids), flush part batches around them. Pilot numbers (windswept glade, 2026-08-09): baseline 37.6 s wall / 3060 MCP calls / 18.5 s MCP; unit-parts 33.0 s; + batching 25.8 s / 1099 calls / 5.8 s MCP (~2900 placements in 66 batch calls, 0.4 s); create_shape 2231 -> 170; viewport frame ~9.6 -> ~8.2 ms.

Materials & appearance

• common.make_material(name, **fields) CREATES a fresh material via the create_material MCP tool (2026-08-08) - no more 12-metal pool budget or copy_library_item fallback; make as many as the scene needs. Fresh materials are plain (no textures, isotropic BRDF, non-metal white), so clear_textures is a no-op kept for old call sites. Always set metallic and base_color explicitly - defaults are white non-metal, NOT the old stock-metal look.
• (Scene libraries still ship the 12 stock metals; they default to a circular-brushed anisotropic BRDF that draws an X/ring pattern per UV tile - avoid claiming them directly.)
• Translucency: raster transparency is selected by blending_mode="alpha_blend" + opacity (opacity alone renders OPAQUE; transmission only affects the ray tracer). Glass ~0.16 opacity, water ~0.55-0.7 over a bright seabed, UFO shells ~0.30.
• Emissive: emissive=[r,g,b] with values ~2-3.5 for visible glow.
• Procedural texture graphs (c.texture_graph + fbm/noise/colorize -> output, bind_material_texture) give sand/granite-style surfaces; box-face UV tiling repeats per face at box default steps.
• Texture slots default to clamp-to-edge (2026-08-10): a material slot without an explicit sampler renders clamped, so any UV that runs past [0, 1] smears the edge texel into stripe bands. Tiling textures need bind_material_texture(..., wrap="repeat"), which routes through the edit_material per-slot sampler args (wrap string or [u, v] pair: repeat / clamp_to_edge / mirrored_repeat, plus min_filter / mag_filter nearest|linear). The Properties window has matching Wrap/Filter rows per bound slot.

Lighting

• Sky: ambience(sky={"_version": 3, "enabled": True, "mode": 1}) for the physically-based blue atmosphere; enabled without mode: 1 keeps the gray checker (mode 0 = gradient/checker), and without _version: 3 the versionless JSON parses as v1 and drops fields. Indoor scenes: sky=False + dark clear_color.
• Point lights need intensity in the hundreds at room scale (150-400); they also wash large areas fast - accent glows want intensity < 100, range < 8 (a 320-intensity portal light turned a whole island pink).
• cast_shadow=False on fills avoids floor shadow blotches; keep ONE shadow-casting key light to ground objects.
• Directional sun: create, then rotate the node - light aims down -Z; pitch about X then yaw about Y (quat_mul(qy, qx)); pitch -134 deg ~ 45 deg elevation, -168 deg ~ dusk.
• Camera: place_camera(eye, target); exposure() if needed. Check every screenshot for objects occluding the camera ray and for the floor's horizon edge (floor boxes want ~60 m for eye-level cameras).
• Ground beyond the shadow fit renders as a hard dark band (creation 17): keep the WHOLE ground box - including its diagonal corners - inside shadow_range (500 m ground + 40 m range drew a giant dark trapezoid; a 160 m ground left a corner wedge past its 90 m range). Make the ground a THIN slab (0.08 m) so its unlit side face at the far edge reads as a hairline instead of a dark bar.
• Ground textures: a box face has ONE UV tile, so noise scales must be huge (fbm scale ~90 on a 110 m plane) or the pattern stretches to featureless flatness; and watch value-noise cell size - noise size 9 = 12 m cells that read as a regular checker from a raised camera (size 48 keeps grain ~2 m).
• Set up lights + shadow_range() FIRST (before any geometry) so a windowed viewing is lit and shadowed from the first shape onward. shadow_range(value) also sets the camera far clip to value - for big open scenes pass z_far explicitly (e.g. shadow_range(160, z_far=900)) or the ground/sea plane far-clips into a hard horizon band. Light nodes insert on the NEXT frame (unlike create_node's synchronous insert); rotate the sun with c.set_node_transform("<light name>", rotation_xyzw=q) - its not-found retry rides out the pending insert, no settle() needed.

Domain recipes (references/)

Stable domain knowledge lives in references/ next to this file - read the relevant file(s) BEFORE building in that domain, the same way this file is read before any creation work:

• references/vegetation.md - L-system plants and trees (lsystem_trees.py species system), the one-spine physics LOD, sway motor rigs, sibling-spine collision filters, scene wind + tuning tables. Creations 9-10, 13, 15.
• references/physics_rigs.md - joint plumbing (anchors, limits, drives), toggle/wake semantics, ragdolls, load-bearing motor rigs (the standing spider) and pose probes. Creations 7-8, 14.
• references/csg_hulls.md - CSG carving (batched tools), authored convex-hull silhouettes, lattice/FFD deformation, bent-strip trim, probed hull-hugging bands, ship-scale composition. Creation 16.
• references/settling_rock_piles.md - the manual simulation clock (advance_time), deterministic settles, SCOPED wakes, staged construction (the cairn), rock piles, chamfer batches, dunes and cacti. Creation 17.
• references/blades_sweep.md - the sweep shape for blades / leaves (agave rosettes). Creation 17.
• references/geometry_graph_sculpt.md - smooth organic bodies as live geometry graphs (box -> lattice FFD -> subdivide via MCP: offsets array layout, station-squeeze sculpting, cap rounding, cross-section shaping, probed attachments). Creation 18.

Conventions

• Commit message: scripts/creations: <scene> (<hook>) + a body that records WHY and any debugging lesson; end with the Claude co-author line. Only the script (and common.py changes) are committed; the user pushes.
• prompt_queue.txt ITEM -1 and the mcp-creation-scripts-* agent memory only POINT at git log and this skill - do not grow commit ledgers in them; git log is the history.
• MCP node/material ids are per-session - never hardcode them.
• Box "steps" means SUBDIVISIONS since 2026-08-10 (breaking change, user-approved): the create_shape/place pools still use the "steps" key, but the value is now interior subdivision planes per axis - s gives s + 1 cells, 0 = vertices only at that axis' min/max corners. The old semantics produced 2*s cells, so existing scripts get roughly half the resolution they used to; bump values where a lattice needs interior vertices. The geometry-graph Box node parameter/serialized key is renamed "subdivisions" outright.
• select_items requires scene_name. place_brush takes the full placement set since 2026-08-09 (rotation_xyzw, parent_node_id, name, scale number-or-array, mass, motion_mode incl. "none", brush_name) - identical to create_shape's instance parameters.

Open bugs (workarounds in place; fix only if asked)

• (The chamfer crash is FIXED 2026-08-08: it was a cross-thread Operation_stack::queue in seven async mesh-op lambdas, not a uv_sphere geometry problem - chamfer/truncate/gyro/kis/merge_faces all work now.)
• (Both former blockers are FIXED 2026-08-08: capture_screenshot works windowed -- swapchain readback + one-frame MCP deferral -- and the windowed save_scene crash is gone: the glTF exporter saves only Item_flags::content children, so the hotbar rendertarget quad no longer reaches export.)
• Graphics preset High once shipped shadow_light_count 32 (~2.1 GiB VRAM per view -> OOM with two scenes); trimmed to 8 locally in config/editor/graphics_presets.json - coordinate before reverting.
• (The graph-mesh material save/load loss is FIXED 2026-08-10 late: the exporter's lazy material pass dropped materials referenced only by graph output nodes because graph-controlled meshes are excluded from export; they now export via extra_materials, and graph-texture slot bindings carry sampler wrap/filter state. Files saved BEFORE the fix stay broken - the material is simply absent from them; re-save from a fresh build.)