summer-engine 1.5.0 → 2.2.0

package/skills/3d-assets/character-model/SKILL.md

@@ -0,0 +1,225 @@
+---
+name: character-model
+description: Use when generating a humanoid character ready for animation — player avatar, NPC, enemy, boss, companion. Generates a T-pose reference image, gates an un-rigged preview past the user, then runs the Meshy auto-rig pass and wires the result as a CharacterBody3D (movement) or Node3D (cinematic). Trigger on "make a character", "generate the player", "I need an enemy model", "create an NPC", "rigged humanoid", "character with a skeleton", "model for animation".
+license: MIT
+compatibility: [Cursor, Claude Code, Windsurf, Codex]
+category: 3d-assets
+user-invocable: true
+allowed-tools: Read Grep summer_search_assets summer_generate_image summer_generate_3d summer_import_from_url summer_add_node summer_set_prop summer_set_resource_property summer_inspect_node summer_inspect_resource summer_get_scene_tree summer_save_scene summer_check_job summer_generate_motion
+paths: ["assets/characters/**", "assets/models/**", "**/*.tscn", "**/*.gd"]
+---
+
+# Character Model — T-Pose to Rigged Humanoid, Gated
+
+This is the **canonical Meshy auto-rig pipeline**. It produces a humanoid `.glb` with a Meshy-compatible skeleton that `summer:animation/generate-motion` can drive directly. The work is split into two paid passes with a **mandatory user-review gate between them** — the rig pass is more expensive and locks the topology, so the user must see the un-rigged preview and approve before you spend on the rig.
+
+The whole flow:
+
+```
+1. T-pose reference image    →  summer_generate_image                          (~$0.05, ~10s)
+2. Un-rigged 3D mesh         →  summer_generate_3d(image-to-3d)                (~$0.50, ~60s)
+3. ── USER REVIEW GATE ──
+4. Rigged .glb               →  summer_generate_3d(image-to-3d, rig: true)     (~$1.00, ~90s)
+5. Import → editor RESTART → wire as CharacterBody3D / Node3D
+6. Hand off to summer:animation/generate-motion for clips
+```
+
+The animation skill (`summer:animation/generate-motion`) requires a rigged humanoid; a static `.glb` won't drive motion.
+
+## When to use
+
+- "Make a knight character for the player to control."
+- "I need a goblin enemy."
+- "Generate an old wizard NPC for the tavern."
+- "Create a boss — a four-armed demon."
+- The user is about to ask for animations and has nothing rigged yet.
+
+## When NOT to use
+
+- Static statue / mannequin display piece (no rig needed) → `summer:3d-assets/prop-model`.
+- Vehicle with a "driver" silhouette but no skeleton needed → `summer:3d-assets/vehicle-model`.
+- Quadruped (wolf, horse, dragon) → Meshy auto-rig is humanoid-only. Generate the mesh here for visuals, but skip the rig step — animation will need a hand-authored skeleton or a quadruped-specific provider (out of scope for this skill).
+- The user already has a rigged character and just wants a re-skin — that's a retexture pass, not this skill.
+- Facial blendshapes / lipsync rig → `summer:animation/facial-and-lipsync`.
+
+## Polycount targets
+
+| Role | Tris | Pass via |
+|---|---|---|
+| Hero character (player, close camera) | 8k–15k | `target_polycount: 12000` |
+| Grunt enemy (mid-range, multiple onscreen) | 3k–6k | `target_polycount: 5000` |
+| Crowd / background NPC (LOD-able) | 1k–2k | `target_polycount: 1500` |
+| Mobile-game character | 1k–3k | `target_polycount: 2000` |
+| Cinematic hero (no realtime constraint) | 20k–40k | `target_polycount: 30000` |
+
+Pass at the **mesh-generation step** (step 2). The rig pass preserves the topology; you can't reduce polycount after rigging without breaking weights.
+
+## Steps
+
+### 1. Generate the T-pose reference image
+
+The rig pass requires a **front-facing T-pose** with arms out and legs slightly apart. If the reference is in an action pose, the rig will bend wrong and locomotion clips will look broken (knees inverted, elbows snapped — common Meshy failure mode).
+
+```
+summer_generate_image(
+  prompt="A fantasy knight in full plate armor, red cape, T-pose, arms straight out horizontal, legs slightly apart, front-facing, neutral expression. Game character asset, stylized, clean white background, soft studio lighting, full body in frame, ready for 3D mesh generation.",
+  model="nano-banana-2"
+)
+```
+
+The phrase `T-pose, arms straight out horizontal, legs slightly apart, front-facing` is load-bearing — drop any of those and the model will drift toward A-pose or a hero stance.
+
+If the user already has a concept image in an action pose, re-pose it to T-pose via img2img without re-rolling the design:
+
+```
+summer_generate_image({
+  referenceImageUrl: "<existing concept image>",
+  prompt: "<character> in T-pose, arms extended horizontally, neutral facing camera, white background, clean lighting"
+})
+```
+
+Show the image to the user:
+
+> Generated the T-pose reference. [link]. Approve to proceed to mesh generation, or regenerate?
+
+### 2. Generate the un-rigged 3D mesh
+
+```
+summer_generate_3d(
+  kind="image-to-3d",
+  imageUrl="<image url from step 1>",
+  model="hunyuan",
+  options={ target_polycount: 12000 },
+  wait=true
+)
+```
+
+Returns `{ asset: { fileUrl } }` — an un-rigged static `.glb`. Import it for preview only:
+
+```
+summer_import_from_url(url="<fileUrl>", path="res://assets/characters/knight_unrigged.glb")
+```
+
+### 3. ⛔ USER REVIEW GATE — DO NOT SKIP
+
+Before paying for the rig pass, surface the un-rigged mesh:
+
+> Un-rigged knight mesh ready: `res://assets/characters/knight_unrigged.glb` (~12k tris, [preview link]).
+>
+> Next step is the **rig pass** (~$1.00, ~90s, Meshy auto-rig). It locks the topology and adds a skeleton compatible with `summer:animation/generate-motion`. Once you approve I'll run it.
+>
+> **Approve the mesh and proceed to rig?** Or regenerate the mesh first (different prompt, different polycount, different model)?
+
+If the user wants changes, loop back to step 1 or 2. Do NOT silently run the rig pass — it doubles the cost and locks the design.
+
+### 4. Run the rig pass
+
+```
+summer_generate_3d({
+  kind: "image-to-3d",
+  imageUrl: "<image url from step 1>",
+  options: { rig: true, polyTarget: 12000 }   // polyTarget is best-effort; backend may use options.target_polycount
+})
+```
+
+Returns a job whose result includes `{ asset: { fileUrl }, rigAssetId }`. If you ran with `wait: false`, poll via `summer_check_job(jobId)`. The `rigAssetId` is the handle `summer:animation/generate-motion` needs — store it.
+
+Import the rigged version, replacing the un-rigged file:
+
+```
+summer_import_from_url(url="<rigged fileUrl>", path="res://assets/characters/knight.glb")
+```
+
+### 5. ⚠️ Restart the editor
+
+**Known Godot 4.5 gotcha:** after importing a rigged `.glb`, the `Skeleton3D` node appears stale in the scene dock — bones are missing, `skeleton.get_bone_count()` returns 0, and `AnimationPlayer` libraries fail to bind. The fix:
+
+> The rigged mesh is imported. Please restart the Summer Engine editor (close and reopen) so the Skeleton3D rebuilds correctly. Without the restart, animations will fail to bind.
+
+There is no programmatic workaround as of Godot 4.5.x. Tell the user, wait, then continue.
+
+### 6. Wire as CharacterBody3D or Node3D — pick the right parent
+
+| Use case | Parent type | Why |
+|---|---|---|
+| Player or enemy that moves with code, collides with walls, jumps | `CharacterBody3D` | `move_and_slide()` API, kinematic physics, slope handling |
+| Cinematic NPC (talks, idles, never moves under physics) | `Node3D` | No physics overhead; cheaper for crowds |
+| Pure-visual character (background extra, dialogue head) | `Node3D` | Same as above |
+| Ragdoll-on-death enemy | `CharacterBody3D` while alive, swap to `RigidBody3D` skeleton on death | Two-mode rig; see `summer:animation/procedural-animation` |
+
+**CharacterBody3D wiring (player / enemy):**
+
+```
+summer_add_node(parent="./World", type="CharacterBody3D", name="Knight")
+summer_set_prop(path="./World/Knight", property="position", value="Vector3(0, 0, 0)")
+summer_add_node(parent="./World/Knight", type="Node3D", name="Mesh")
+# Instantiate the imported scene as a child of the Mesh node
+summer_set_prop(path="./World/Knight/Mesh", property="scene", value="res://assets/characters/knight.glb")
+summer_add_node(parent="./World/Knight", type="CollisionShape3D", name="Collider")
+# Add a CapsuleShape3D resource (height ~1.7m, radius ~0.4m) to the collider
+summer_save_scene
+```
+
+**Node3D wiring (cinematic NPC):**
+
+```
+summer_add_node(parent="./World/Tavern", type="Node3D", name="OldWizard")
+summer_set_prop(path="./World/Tavern/OldWizard", property="scene", value="res://assets/characters/wizard.glb")
+summer_save_scene
+```
+
+The imported `.glb` includes its own `Skeleton3D` and `AnimationPlayer` (empty library). The animation skill writes into that AnimationPlayer.
+
+### 7. Hand off to animation
+
+> Knight is wired at `./World/Knight` with a Meshy-rigged skeleton. `rigAssetId` saved.
+>
+> Next: `summer:animation/generate-motion` to add idle / walk / run / attack clips. Example call: `summer_generate_motion(rigAssetId: "<saved id>", backend: "meshy-library", motionName: "walk")`. The animation skill uses Meshy's curated mocap library (~70 standard motions). Custom prompt-driven motion is on the roadmap; for one-off signature moves not on the curated list, fall back to hand-authoring in the Godot editor or importing from Mixamo.
+
+## Anti-patterns
+
+- **Skipping the user-review gate.** Doubles cost, locks the design, and removes the user's chance to course-correct cheaply.
+- **Generating the mesh from a non-T-pose image.** Locomotion will look broken (inverted knees, snapped elbows). Always re-pose first.
+- **Forgetting the editor restart.** Animations will appear to bind successfully but play to a stale skeleton — the character T-poses motionless. The fix is always restart, never code.
+- **Wrapping a cinematic NPC in CharacterBody3D.** Wastes physics ticks; use Node3D.
+- **Wrapping the player in Node3D.** No `move_and_slide()`, no collision — the player walks through walls.
+- **Picking the rig pass before approving the silhouette.** The mesh defines what the character looks like; once the rig is on, you can't cheaply iterate the design.
+- **Using `meshy` model for the mesh step.** Legacy. `hunyuan` is the default and produces cleaner topology that Meshy's auto-rig handles better.
+
+## Edge cases
+
+- **Multiple characters share a silhouette.** Generate the rig once, then re-skin via texture swap (cheaper than re-rigging). See `summer:3d-assets/character-model` retexture flow (TBD) — for now, route to `summer:asset-pipeline/asset-strategy`.
+- **Character has wings, tail, extra limbs.** Meshy's humanoid rig only weights the standard skeleton — extras sag. Either prompt them as static (e.g. cape held by physics in-engine) or hand-rig in Blender post-export.
+- **Child / dwarf / giant.** Generate at correct proportions in the T-pose; the rig retargets cleanly. Locomotion clips from `summer:animation/generate-motion` will retarget but stride length needs `playback_speed` tuning on the AnimationPlayer.
+- **First-person hands-only character.** Generate just hands + forearms in T-pose; rig pass still works. See `summer:character-controllers/fps-controller` for first-person wiring.
+- **Stylized non-human (goblin, orc, halfling).** Works fine as long as the silhouette is bipedal with two arms, two legs, one head. Quadrupeds and centaurs do not.
+
+## Fallback (no MCP)
+
+1. Generate the T-pose reference at the Summer dashboard (or any image gen — Midjourney, nano-banana web, DALL-E).
+2. Upload to Meshy at meshy.ai → Image to 3D → enable rigging.
+3. Download the `.glb`.
+4. Drop into `res://assets/characters/` — Godot's import dock picks it up.
+5. Restart the editor.
+6. Wire as CharacterBody3D / Node3D in the Godot editor manually.
+
+The output is identical to the MCP path — same Meshy skeleton, same compatibility with `summer:animation/generate-motion` (which has its own dashboard fallback).
+
+## Handoff
+
+After the rigged character is wired:
+
+> `Knight` is at `./World/Knight` with a Meshy-rigged skeleton. Next:
+> - **Animations:** `summer:animation/generate-motion` for idle / walk / run / attack. Pass the `rigAssetId` returned in step 4.
+> - **State machine:** after a few clips exist, `summer:animation/animation-tree` for idle → walk → run blends.
+> - **Player input:** if this is the player, wire WASD + mouse via `summer:character-controllers/fps-controller` or a third-person controller skill.
+> - **NPC behavior:** if it's an NPC, `summer:ai-and-npcs/design-npc` for behavior trees and dialogue hooks.
+> - **Re-skin variants** (palette swap, armor swap): retexture pass — generate new albedo, assign via material override. Avoid re-rigging.
+
+## See also
+
+- `summer:animation/generate-motion` — the next-step animation skill that consumes the `rigAssetId` produced here.
+- `summer:asset-pipeline/asset-strategy` — meta-router; this skill is the canonical drill-down of its "Image-to-3D for characters" path.
+- `summer:3d-assets/prop-model` — for non-character props.
+- `summer:scene-composition` — for the CharacterBody3D + Mesh + Collider parent pattern.
+- `_shared/mcp-tools-reference.md` — full parameter schemas for `summer_generate_3d`, `summer_generate_image`, and `summer_generate_motion`.

package/skills/3d-assets/environment-kit/SKILL.md

@@ -0,0 +1,164 @@
+---
+name: environment-kit
+description: Use when generating a modular environment kit — wall pieces, floor tiles, pillars, doors, arches, corner blocks that snap together to form a level. Multiple meshes that share a visual style. Trigger on "build a dungeon kit", "modular walls", "level kit", "tileset", "interior pieces", "snap-together pieces", "make a kit for the temple".
+license: MIT
+compatibility: [Cursor, Claude Code, Windsurf, Codex]
+category: 3d-assets
+user-invocable: true
+allowed-tools: Read Grep summer_search_assets summer_generate_3d summer_generate_image summer_import_from_url summer_add_node summer_set_prop summer_inspect_node summer_get_scene_tree summer_save_scene
+paths: ["assets/kits/**", "assets/models/**", "**/*.tscn", "**/*.gd"]
+---
+
+# Environment Kit — Style-Locked Modular Pieces
+
+A kit is a *family* of meshes — wall, floor, door, pillar, corner, arch — that the level designer snaps together to build interiors and exteriors. The skill exists to solve **one specific failure mode**: generating each piece with a fresh prompt produces six pieces that look like they came from six different games. The fix is the **style anchor pattern** — generate one piece first, lock its prompt suffix, and reuse that exact suffix for every subsequent piece.
+
+The backing tool is `summer_generate_3d`, called multiple times. Each call costs ~$0.50, so a 6-piece kit is ~$3 and ~5 minutes. Confirm scope before starting.
+
+## When to use
+
+- "Build me a dungeon kit — walls, floor, door, pillar."
+- "I need modular wall pieces for a sci-fi corridor."
+- "Make a tileset for a wooden tavern interior."
+- "Generate the pieces for a stone temple — I'll assemble the level."
+- The user wants to build a level out of repeating, snapping pieces.
+
+## When NOT to use
+
+- A single hero prop (single chest, single throne) → `summer:3d-assets/prop-model`.
+- Open-world terrain (rolling hills, forests) → use a heightmap + scattered organic models from `summer:3d-assets/organic-model`.
+- Repeating flat surfaces only (just walls and floors, no decorative pieces) → `summer:asset-pipeline/asset-strategy` Pipeline 2 (textures + CSG) is cheaper and snaps perfectly to grid.
+- Characters or vehicles in the scene — those are separate skills.
+
+## The style anchor pattern
+
+This is the whole skill. Get this right and the kit looks unified. Get this wrong and you waste $3.
+
+1. **Generate the anchor piece first.** Pick the most visually defining piece — usually the wall or the door. Iterate the prompt until the user approves it visually.
+2. **Extract the style suffix.** Everything after the object description. Example anchor prompt:
+   ```
+   A stone dungeon wall section, mossy granite blocks with iron reinforcements, 
+   torch-bracket sconce, weathered surface. Game asset, centered, stylized 
+   low-poly game art, warm torchlight palette, white background, isolated object.
+   ```
+   The suffix to lock is everything from `Game asset, ...` onward, plus `mossy granite blocks with iron reinforcements, weathered surface, warm torchlight palette` — the material + palette tokens.
+3. **Reuse the suffix verbatim** for every other piece. Only change the object description at the front.
+
+| Anchor: wall | `A stone dungeon wall section, ...` + LOCKED SUFFIX |
+| Floor tile | `A stone dungeon floor tile, square, ...` + SAME LOCKED SUFFIX |
+| Pillar | `A stone dungeon pillar, square base, fluted shaft, ...` + SAME LOCKED SUFFIX |
+| Door | `A stone dungeon doorway, arched, heavy wooden door with iron studs, ...` + SAME LOCKED SUFFIX |
+| Corner block | `A stone dungeon corner wall section, two walls joined at right angle, ...` + SAME LOCKED SUFFIX |
+| Arch | `A stone dungeon archway with keystone, ...` + SAME LOCKED SUFFIX |
+
+If the user says "the door doesn't match the rest", the answer is almost always: the suffix drifted. Check the exact strings.
+
+## Snap-grid alignment
+
+Kit pieces only feel modular if they snap to a fixed grid. Pick the grid before generating and tell the user.
+
+| Grid size | Use for | Notes |
+|---|---|---|
+| **1m** | Tight interiors (dungeons, ship corridors, cells) | Wall = 1×3×0.3m. Floor = 1×1m. Most common. |
+| **2m** | Standard interiors (homes, taverns, offices) | Wall = 2×3×0.3m. Floor = 2×2m. Halves piece count. |
+| **4m** | Exteriors and large halls (temples, warehouses, throne rooms) | Wall = 4×4×0.4m. Floor = 4×4m. Quarter the piece count for the same area. |
+
+**Critical:** include the dimensions in the prompt. `summer_generate_3d` doesn't enforce them, but Hunyuan respects scale cues — `2 meter tall wall section` produces a mesh that imports near 2m tall. Then verify with `summer_inspect_resource` and scale-correct in the editor if needed.
+
+## Steps
+
+### 1. Confirm scope and pick the grid
+
+> About to build a dungeon kit. Suggested pieces: wall, floor, pillar, door, corner, arch (6 pieces, ~$3, ~5 min). Snap grid: 2m (standard interior). OK?
+
+### 2. Generate the anchor (wall)
+
+Use the prop-style prompt with explicit dimensions:
+
+```
+summer_generate_3d(
+  prompt="A 2 meter wide by 3 meter tall stone dungeon wall section, mossy granite blocks with iron reinforcements, torch-bracket sconce, weathered surface. Game asset, centered, stylized low-poly game art, warm torchlight palette, white background, isolated object.",
+  model="hunyuan",
+  options={ target_polycount: 1500 },
+  wait=true
+)
+summer_import_from_url(url="<fileUrl>", path="res://assets/kits/dungeon/wall.glb")
+```
+
+Show the result to the user. **Iterate the anchor until approved** — every other piece copies its style.
+
+### 3. Lock the suffix and generate the remaining pieces
+
+Once the user says "yes, that's the look", store the locked suffix and crank through the rest. Same model, same polycount, same `options`. Only the object description changes.
+
+```
+# Floor
+summer_generate_3d(prompt="A 2 by 2 meter square stone dungeon floor tile, mossy granite blocks with iron reinforcements, weathered surface. Game asset, centered, stylized low-poly game art, warm torchlight palette, white background, isolated object.", model="hunyuan", options={ target_polycount: 800 })
+
+# Pillar
+summer_generate_3d(prompt="A 3 meter tall stone dungeon pillar, square base, fluted shaft, mossy granite blocks with iron reinforcements, weathered surface. Game asset, ...", model="hunyuan", options={ target_polycount: 1500 })
+
+# Door, Corner, Arch — same pattern.
+```
+
+Polycount targets per kit piece: walls/floors 800–1500 tris (placed dozens of times), decorative (pillar, arch) 1500–3000, doors 2000–3000.
+
+### 4. Import and stage in a kit scene
+
+Don't dump the kit into the level scene. Make a `kit_dungeon.tscn` that holds one of every piece, labelled, positioned next to each other on the snap grid. The level designer instantiates from there.
+
+```
+summer_add_node(parent="./KitRoot", type="Node3D", name="Wall")
+summer_set_prop(path="./KitRoot/Wall", property="scene", value="res://assets/kits/dungeon/wall.glb")
+summer_set_prop(path="./KitRoot/Wall", property="position", value="Vector3(0, 0, 0)")
+# ...repeat for floor, pillar, door, corner, arch with positions Vector3(2,0,0), Vector3(4,0,0), ...
+summer_save_scene
+```
+
+### 5. Verify scale and pivots
+
+```
+summer_inspect_resource(path="res://assets/kits/dungeon/wall.glb")
+```
+
+Check the AABB. If the wall is 1.85m tall when you asked for 3m, scale it in the editor (or re-import with `Scale` in the import dock). Pivots should sit at the *bottom-back* corner for walls and *bottom-center* for floors — that makes snapping to a 2m grid trivial. If pivots are wrong, use Godot's "Center to Origin" import option.
+
+## Anti-patterns
+
+- **Drifting style suffix.** Each piece gets a slightly different suffix → the kit looks mismatched. Copy-paste the exact string.
+- **Different polycount per piece.** A 5k-tri pillar next to a 500-tri wall reads as "the pillar is a hero piece" — wrong; they should feel like equal kit citizens. Match polycount within ~2× across the kit.
+- **Skipping the anchor approval.** If you generate all six pieces in a batch, you bake in whatever the first call's interpretation of the style was — and the user may hate it after $3 of generation.
+- **Generating walls / floors as individual meshes when you only need a tileable texture.** A flat wall section is cheaper as a textured `CSGBox3D`. Reserve the kit for pieces that need actual geometric detail (sconces, mouldings, doorways, arches).
+- **No scale cue in the prompt.** Wall comes back 0.4m tall. Always include `2 meter wide by 3 meter tall` (or your chosen grid).
+- **Forgetting the snap grid.** A 1.87m-tall wall with no scale fix → level looks crooked when tiled.
+
+## Edge cases
+
+- **Curved or organic kit (cave, alien hive).** Modular geometry resists snapping. Generate longer pieces (4m walls, transition tiles) and accept some overlap. Or switch to procedural — `summer:level-design` can scatter cave pieces with rotation jitter.
+- **Outdoor kit (cliffs, ruins, forest path).** Use the kit pattern but accept rotation/jitter at placement time. Mesh edges should fade naturally rather than snap cleanly. Pair with `summer:3d-assets/organic-model` for foliage scatter.
+- **Sci-fi kit (corridors, doors, terminals).** The style suffix becomes critical — `clean panels, soft cyan emissive trim, brushed metal, white background, isolated object`. Hard surfaces drift more than organic ones; review every piece.
+- **The user wants to add a piece later.** The locked suffix lives in the kit's notes (drop it in `assets/kits/dungeon/STYLE.md` if the user wants persistence). Reuse it verbatim for any addition — never re-derive.
+
+## Fallback (no MCP)
+
+1. Run each prompt at the Summer dashboard (or Hunyuan / Trellis web UIs), keeping the locked suffix.
+2. Download each `.glb`.
+3. Drop into `res://assets/kits/<kit-name>/`.
+4. Build the kit-display scene manually in Godot — one of each piece, snapped to grid.
+5. Hand to the level designer.
+
+## Handoff
+
+After the kit is staged:
+
+> Dungeon kit ready: `res://assets/kits/dungeon/` with wall, floor, pillar, door, corner, arch on a 2m snap grid. Display scene at `res://assets/kits/dungeon/kit_dungeon.tscn`.
+>
+> Next: hand off to the level-design step — instantiate kit pieces into `level_01.tscn`, snap to the 2m grid, dress with props (`summer:3d-assets/prop-model`) and foliage (`summer:3d-assets/organic-model`). For lighting, see `summer:3d-lighting`.
+
+## See also
+
+- `summer:3d-assets/prop-model` — for the chests, statues, and decorative props that dress the kit.
+- `summer:3d-assets/organic-model` — for foliage and rocks that break up modular repetition.
+- `summer:asset-pipeline/asset-strategy` — Pipeline 2 (textures + CSG) is the cheaper alternative when pieces are flat.
+- `summer:scene-composition` — how to organize the kit scene and the level scenes that consume it.
+- `summer:3d-lighting` — interior kit pieces typically need warm point lights at sconce positions.

package/skills/3d-assets/organic-model/SKILL.md

@@ -0,0 +1,192 @@
+---
+name: organic-model
+description: Use when generating organic shapes — trees, rocks, mushrooms, coral, bushes, alien plants, vines, crystals, fruit, bones. The "easy mode" of 3D generation; AI artifacts read as natural irregularity. Trigger on "make a tree", "generate rocks", "I need foliage", "mushroom prop", "alien plants", "fill the scene with shrubs", "scatter some boulders".
+license: MIT
+compatibility: [Cursor, Claude Code, Windsurf, Codex]
+category: 3d-assets
+user-invocable: true
+allowed-tools: Read Grep summer_search_assets summer_generate_3d summer_generate_image summer_import_from_url summer_add_node summer_set_prop summer_inspect_node summer_get_scene_tree summer_save_scene
+paths: ["assets/organic/**", "assets/models/**", "**/*.tscn", "**/*.gd"]
+---
+
+# Organic Model — Easy-Mode 3D Generation
+
+Organic shapes (trees, rocks, mushrooms, coral, alien flora, crystals, vines, bones) are **the most forgiving category for AI 3D generation**. Lumps look natural. Asymmetry looks natural. Smoothing-group artifacts read as bark texture. The "melted" look that ruins vehicles and characters is fine on a mossy boulder.
+
+This is the cheapest, fastest way to fill out a scene. Use it liberally — it's the recommended go-to when the user says "this scene feels empty". Each generation is ~$0.30–0.50, and the failure rate is the lowest of any 3D-asset family.
+
+Backing tool: `summer_generate_3d`. Default `hunyuan` is great here, but `trellis` is faster and quality difference is mostly invisible on organic shapes — `trellis` is the recommended pick when generating many at once.
+
+## When to use
+
+- "Make me a pine tree."
+- "Generate five different rocks I can scatter."
+- "I need glowing mushrooms for the cave."
+- "Fill this forest scene with foliage."
+- "Alien plants for the planet surface."
+- "Coral for the underwater level."
+- The user wants visual density without spending a lot of money or time.
+
+## When NOT to use
+
+- Character (humanoid, even if "tree-person") → `summer:3d-assets/character-model` (rigging matters).
+- Vehicle, weapon, hard-surface object → `summer:3d-assets/prop-model` or `summer:3d-assets/vehicle-model`.
+- Tileable ground (grass field, sand) → `summer:asset-pipeline/asset-strategy` Pipeline 2 (textures, not meshes).
+- Animated organic (Venus fly trap that opens, breathing pod) → generate static here, animate in-engine with bones or shape keys.
+- A single hero-tree centerpiece (Yggdrasil, the One Tree) — generate via `summer:3d-assets/prop-model` with higher polycount and detail attention.
+
+## Polycount targets
+
+Organic geometry tolerates aggressive polycount cuts because the silhouette is irregular — viewers can't spot poly-count drops the way they spot a low-poly cylinder.
+
+| Use case | Tris | Pass via |
+|---|---|---|
+| Hero tree (mid-distance, prominent) | 4k–8k | `target_polycount: 6000` |
+| Background tree (forest filler) | 1k–3k | `target_polycount: 2000` |
+| Distant tree (use billboard imposter) | 200–500 | `target_polycount: 400` |
+| Large rock / boulder | 800–2000 | `target_polycount: 1500` |
+| Small organic (mushroom, fruit, crystal) | 300–1000 | `target_polycount: 600` |
+| Vine / branch decoration | 200–500 | `target_polycount: 400` |
+
+Generating a forest? Make 3 hero trees + 5 background trees + 3 rocks at low polycount, then scatter via `MultiMeshInstance3D` for hundreds of copies at near-zero rendering cost.
+
+## Steps
+
+### 1. Search before generating
+
+```
+summer_search_assets(query="<organic type>", filter={ kind: "model" })
+```
+
+### 2. Build the prompt
+
+Pattern: `<species> + <state/condition> + <key features> + isolated suffix`. Organic prompts are shorter than prop prompts — the model already knows what a tree looks like.
+
+| Goal | Prompt that works |
+|---|---|
+| Pine tree | `A tall pine tree with dense green needles and a straight trunk, slight lean. Game asset, stylized low-poly game art, white background, isolated object.` |
+| Oak tree | `A wide oak tree with sprawling branches and seasonal autumn leaves in orange and red. Game asset, stylized, white background, isolated object.` |
+| Boulder | `A large mossy boulder, irregular weathered surface, patches of green moss on top. Game asset, stylized, white background, isolated object.` |
+| Glowing mushroom | `A cluster of three bioluminescent mushrooms on a small mossy base, pale cyan glow, translucent caps. Game asset, stylized, white background, isolated object.` |
+| Alien plant | `An alien spiral plant with tendril-like fronds, deep purple with glowing pink tips, growing from a bulbous base. Game asset, stylized, white background, isolated object.` |
+| Coral cluster | `A branching coral cluster, bright orange and pink, sea-fan shapes, multiple branches. Game asset, stylized, white background, isolated object.` |
+| Crystal | `A jagged amethyst crystal cluster growing from a stone base, deep purple with translucent facets. Game asset, stylized, white background, isolated object.` |
+| Vine | `A hanging jungle vine with broad green leaves and small white flowers, ~2 meter length. Game asset, stylized, white background, isolated object.` |
+
+Organic prompts that DON'T work:
+
+| Bad prompt | Failure mode |
+|---|---|
+| `a tree` | Returns a generic tree, but inconsistent species across regenerations — the scene looks chaotic. Always specify species. |
+| `a forest` | Returns one fused mesh of multiple trees → impossible to scatter. Generate one tree, scatter via MultiMeshInstance3D. |
+| `realistic tree with photoreal bark` | Realistic = expensive polycount, ugly when stylized assets surround it. Match scene style. |
+| `a tree on a hill` | The hill becomes geometry. Always say `isolated object`. |
+
+### 3. Confirm and call
+
+> About to generate `pine_tree_01` via `trellis`, target ~2k tris. ~$0.30, ~30s. OK?
+
+For batch generation, batch the confirmation:
+
+> About to generate 3 trees + 3 rocks + 5 mushrooms (11 generations, ~$3.50, ~5 min). All low-poly via `trellis`. OK?
+
+```
+summer_generate_3d(
+  prompt="A tall pine tree with dense green needles and a straight trunk, slight lean. Game asset, stylized low-poly game art, white background, isolated object.",
+  model="trellis",
+  options={ target_polycount: 2000 },
+  wait=true
+)
+summer_import_from_url(url="<fileUrl>", path="res://assets/organic/pine_tree_01.glb")
+```
+
+### 4. Generate variation, not duplication
+
+If the user wants "five rocks", don't generate one rock and copy it five times in the scene — generate five subtly different prompts:
+
+```
+"A medium boulder, mossy granite, rounded shape"
+"A medium boulder, weathered limestone, sharp jagged edges"
+"A medium boulder, dark basalt, flat-topped"
+"A medium boulder, sandstone, layered horizontal striations"
+"A medium boulder, mossy granite, tall narrow shape"
+```
+
+Then scatter all five with random rotation. Five unique meshes + rotation = looks like 50 unique rocks.
+
+### 5. Wire into the scene
+
+| Use case | Wiring | Notes |
+|---|---|---|
+| Single hero tree, mid-scene | `MeshInstance3D` under `Node3D` | One per scene; nothing fancy |
+| Forest scatter (50+ trees) | `MultiMeshInstance3D` with one mesh ref | Single draw call for all instances |
+| Foliage variety (3 species) | One `MultiMeshInstance3D` per species | Each species is one draw call |
+| Distant trees | Billboard imposter (Sprite3D with a tree image) | Switch from mesh to billboard at ~50m via LOD |
+| Rocks with collision | `StaticBody3D` parent + `CollisionShape3D` (ConcaveShape from mesh) | Only for rocks the player can walk into |
+| Rocks without collision (background) | Just `MeshInstance3D` | Most distant rocks don't need it |
+
+**Hero tree:**
+
+```
+summer_add_node(parent="./World/Forest", type="MeshInstance3D", name="HeroOak")
+summer_set_prop(path="./World/Forest/HeroOak", property="mesh", value="res://assets/organic/oak_tree.glb")
+summer_save_scene
+```
+
+**Forest scatter (MultiMesh):** create a `MultiMeshInstance3D`, assign a `MultiMesh` resource referencing the tree mesh, set `instance_count` to e.g. 100, and populate `set_instance_transform()` from a script with random positions + rotations. See `summer:scene-composition` for the scatter pattern.
+
+### 6. LOD and billboards
+
+For dense forests, the cheapest fix beyond MultiMesh is the billboard imposter:
+
+1. Generate the tree mesh once at high polycount.
+2. Render it from one angle to a transparent PNG (Godot's `EditorScript` can capture a viewport).
+3. Use that PNG as a `Sprite3D` with `billboard = enabled`.
+4. Swap from `MeshInstance3D` to `Sprite3D` at ~50m camera distance via Godot's `VisibleOnScreenNotifier3D` or a custom LOD script.
+
+For a 200-tree forest, ~10 close trees are real meshes, 190 are billboards. Frame budget saved: ~80%.
+
+## Anti-patterns
+
+- **Generating "a forest" as one prompt.** Returns a single fused mesh — useless for placement. Always one species per generation, then scatter.
+- **Regenerating the same species 5 times for variety.** Generate 5 *different* species/states/colors for true variety; identical regenerations don't differ enough.
+- **High polycount on background organics.** A 30k-tri rock used 50 times in the background tanks the frame rate. Cap distant organics at 2k.
+- **Ignoring MultiMeshInstance3D.** 100 individual MeshInstance3D nodes = 100 draw calls. 100 instances of one MultiMesh = 1 draw call. Same visual result.
+- **Adding collision to every leaf and pebble.** Player only needs collision on things the body can hit. Skip it for distant scenery and small ground litter.
+- **Using `meshy` (legacy).** No reason to — `trellis` is faster and `hunyuan` is higher quality.
+
+## Edge cases
+
+- **Animated foliage (wind sway).** Generate static here, then add wind sway via a vertex shader on the material — `summer:vfx/shaders` (when available). No animation rig needed.
+- **Underwater organics (kelp, anemones).** Same flow; expect Hunyuan to add a "ground attachment" base unless you say `floating, suspended in water`.
+- **Branching meshes (vines, roots) come back too thick.** Specify `thin tendril, fine branches`, or accept and scale Y down in the editor.
+- **Snow / ice / frozen variant.** Add `covered in snow, frosted, ice crystals` to the prompt — works well on trees and rocks. For temperature variants of the same scene, generate the variant rather than retexturing.
+- **Crystal/glass organic.** Mesh comes back opaque. Generate the geometry, then assign a `StandardMaterial3D` with `transparency = ALPHA` and emissive in the editor.
+- **Bones, skulls, dead trees.** All work great — organic forgives them more than props would. Add `weathered, sun-bleached` for desert / tundra feel.
+
+## Fallback (no MCP)
+
+1. Run prompts at the Summer dashboard or any 3D-gen web playground (Hunyuan, Trellis, Meshy).
+2. Download `.glb` files into `res://assets/organic/`.
+3. Build scatter scenes manually in Godot.
+
+For totally free / offline alternatives: **Quaternius** (free stylized organics), **AmbientCG** (rocks + textures), **Sketchfab** free filter, **Polyhaven** (HDRIs + scans).
+
+## Handoff
+
+After the organic models are scattered:
+
+> Forest scatter ready: 3 species at `res://assets/organic/`, 100 instances each via MultiMeshInstance3D in `./World/Forest`. Next:
+> - **Wind shader** (sway in breeze): `summer:vfx/shaders` when available, or hand-write a vertex displacement shader.
+> - **Ground texture** (grass beneath the trees): `summer:asset-pipeline/asset-strategy` Pipeline 2 for tileable ground.
+> - **Lighting / fog** (forest mood): `summer:3d-lighting` for ambient + directional sun + volumetric fog.
+> - **Ambient audio** (forest birds, leaves): `summer:audio/ambient-bed`.
+> - **Hero props** (a stump, a fallen log, a shrine): `summer:3d-assets/prop-model` for the hand-placed standouts.
+
+## See also
+
+- `summer:3d-assets/prop-model` — for hand-placed standout pieces.
+- `summer:3d-assets/environment-kit` — pair with this skill: kit pieces give the architecture, organic gives the natural softness.
+- `summer:asset-pipeline/asset-strategy` — meta-router; ground textures and skyboxes go to Pipeline 2 / panoramic gen.
+- `summer:scene-composition` — MultiMeshInstance3D scatter pattern.
+- `_shared/mcp-tools-reference.md` — `summer_generate_3d` schema.