summer-engine 2.0.0 → 2.3.0

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.

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

@@ -0,0 +1,133 @@
+---
+name: prop-model
+description: Use when generating a single static 3D prop — sword, barrel, chest, lantern, throne, statue, crate, key, potion, banner. One isolated object, no rigging, wired into the scene as a MeshInstance3D. Trigger on "make a sword", "generate a chest", "I need a barrel", "add a lantern model", "give me a treasure prop", "create a statue".
+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/models/**", "**/*.tscn", "**/*.gd"]
+---
+
+# Prop Model — Generate One Static 3D Prop and Wire It
+
+One prop, one mesh, one MeshInstance3D. This is the bread-and-butter call of the 3D-asset family — most game-world objects are static props. The skill exists to keep two things tight: the **prompt shape** that produces a clean isolated mesh on the first try, and the **wire-in pattern** that gets the asset into the scene without leaving orphans in `res://assets/models/`.
+
+The backing tool is `summer_generate_3d`. Default model is `hunyuan` (Hunyuan 3D v3.1 Pro — best quality). Use `trellis` when speed matters (Trellis 2 is ~2× faster, slightly lower fidelity). `meshy` is the legacy fallback — only pick it if the user asks by name.
+
+## When to use
+
+- "Make me a treasure chest."
+- "Generate a viking axe."
+- "I need a wooden barrel for the cellar."
+- "Create a sci-fi crate."
+- Any single, static, non-character, non-modular object the player will see in 3D space.
+
+## When NOT to use
+
+- Character / humanoid → `summer:3d-assets/character-model` (needs T-pose + rig pass).
+- A set of matching pieces (walls, floors, doors, pillars) → `summer:3d-assets/environment-kit` (style-locked family).
+- Trees, rocks, foliage → `summer:3d-assets/organic-model` (organic forgives AI artifacts; cheaper recipe).
+- Cars, ships, mechs → `summer:3d-assets/vehicle-model` (hard-surface specifics).
+- Walls / floors / repeating geometry → `summer:asset-pipeline/asset-strategy` Pipeline 2 (textures + CSG).
+- "I just need a placeholder" → propose a primitive (`BoxMesh` / `CylinderMesh`) instead. Generation is metered.
+
+## Steps
+
+### 1. Search before generating
+
+```
+summer_search_assets(query="<prop name>", filter={ kind: "model" })
+```
+
+If a fitting model exists, propose reuse:
+
+> Found `assets/models/treasure_chest_01.glb`. Reuse this, or generate fresh?
+
+### 2. Pick a polycount target
+
+| Use case | Tris | Pass via |
+|---|---|---|
+| Hero prop (sword on hip, key item) | 3k–8k | `options: { target_polycount: 5000 }` |
+| Background prop (crate, barrel, sack) | 200–800 | `options: { target_polycount: 600 }` |
+| Mid-range interactive (chest, lantern) | 1k–3k | `options: { target_polycount: 2000 }` |
+| Cinematic showcase (throne, statue) | 10k–30k | `options: { target_polycount: 20000 }` |
+
+Default if you don't pass it: provider picks (~10k–30k). For most game-world props, that's overkill — pass a target.
+
+### 3. Build the prompt
+
+Pattern: `<object> + <material> + <silhouette/details> + isolated-object suffix`.
+
+| Goal | Prompt that works |
+|---|---|
+| Treasure chest | `A wooden treasure chest with iron bands and a heavy padlock, lid slightly ajar, gold coins spilling. Game asset, centered, stylized, white background, isolated object.` |
+| Viking axe | `A two-handed viking battle axe, weathered iron head with rune etchings, leather-wrapped wooden haft. Game asset, centered, stylized, white background, isolated object.` |
+| Lantern | `A medieval brass lantern with stained glass panels and a hooked handle, candle inside. Game asset, centered, stylized, white background, isolated object.` |
+| Throne | `An ornate stone throne carved with serpent motifs, red velvet cushion, tall pointed back. Game asset, centered, stylized, white background, isolated object.` |
+| Sci-fi crate | `A weathered sci-fi cargo crate, metal panels with yellow hazard stripes, recessed handles. Game asset, centered, stylized, white background, isolated object.` |
+| Potion bottle | `A glass potion bottle with a cork stopper, glowing purple liquid inside, leather strap around the neck. Game asset, centered, stylized, white background, isolated object.` |
+
+The `isolated object` and `white background` clauses are load-bearing — without them you get scene context (table, ground plane) baked into the mesh.
+
+### 4. Confirm and call
+
+> About to generate `viking_axe` via `hunyuan`, target ~5k tris. ~$0.50, ~60s. OK?
+
+```
+summer_generate_3d(
+  prompt="A two-handed viking battle axe, weathered iron head with rune etchings, leather-wrapped wooden haft. Game asset, centered, stylized, white background, isolated object.",
+  model="hunyuan",
+  options={ target_polycount: 5000 },
+  wait=true
+)
+```
+
+Returns `{ asset: { fileUrl }, ... }`.
+
+### 5. Import and wire
+
+```
+summer_import_from_url(url="<fileUrl>", path="res://assets/models/viking_axe.glb")
+summer_add_node(parent="./World/Props", type="MeshInstance3D", name="VikingAxe")
+summer_set_prop(path="./World/Props/VikingAxe", property="mesh", value="res://assets/models/viking_axe.glb")
+summer_save_scene
+```
+
+For interactive props (chest the player opens, lantern the player picks up), wrap the MeshInstance3D in a `StaticBody3D` (or `RigidBody3D` for physics props) with a `CollisionShape3D` sibling — see `summer:scene-composition` for the parent-shape pattern.
+
+## Anti-patterns
+
+- **Scene context in the prompt.** "A sword lying on a wooden table" → the table becomes geometry. Always say `isolated object`.
+- **Multi-object prompts.** "A sword and a shield" → fused single mesh. Generate separately.
+- **Skipping `target_polycount` for background props.** A 30k-tri barrel in the background tanks frame rate when the level has 50 of them.
+- **Forgetting to import.** `fileUrl` from `summer_generate_3d` is a remote URL — you MUST `summer_import_from_url` before referencing it as `res://...`.
+- **Generating before searching.** Reuse beats regenerate every time.
+- **Picking `meshy` by default.** It's legacy. `hunyuan` is better; `trellis` is faster.
+
+## Edge cases
+
+- **Transparent objects (glass, ice, gem).** AI 3D gen makes these opaque. Generate the mesh, then assign a `StandardMaterial3D` with `transparency = ALPHA` and a low `albedo_color.a` in the editor.
+- **Long thin props (spear, staff, banner pole).** Hunyuan sometimes thickens the shaft. Trellis handles thin geometry better — try it as the second attempt.
+- **Concave interior (open chest, hollow vase).** Specify "lid open" or "hollow inside" — Hunyuan defaults to closed solids.
+- **Symmetrical prop comes back asymmetric.** Add `symmetric, mirrored` to the prompt and regenerate.
+
+## Fallback (no MCP)
+
+The user can run the same prompt at the Summer dashboard (or directly via the Hunyuan / Trellis web UIs), download the `.glb`, drop it into `res://assets/models/`, and Godot's import dock will pick it up. Then add a MeshInstance3D manually in the Godot editor and assign the mesh.
+
+## Handoff
+
+After the prop is wired:
+
+> `viking_axe.glb` imported and placed at `./World/Props/VikingAxe`. Next:
+> - For physics (player can knock it over), wrap in `RigidBody3D` + `CollisionShape3D` — see `summer:scene-composition`.
+> - For pickup interaction, see `summer:design-mechanic` for the pickup pattern.
+> - For matching props in the same style (chest → barrel → crate as a treasure-room kit), use `summer:3d-assets/environment-kit` with this prop as the style anchor.
+
+## See also
+
+- `summer:asset-pipeline/asset-strategy` — the meta-router that decides between this skill and Pipeline 2 (textures).
+- `summer:3d-assets/character-model` — for humanoids.
+- `summer:3d-assets/environment-kit` — for style-locked sets.
+- `_shared/mcp-tools-reference.md` — `summer_generate_3d` parameter schema.

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

@@ -0,0 +1,202 @@
+---
+name: vehicle-model
+description: Use when generating a hard-surface vehicle — car, motorcycle, spaceship, hover bike, boat, mech, tank, helicopter. Static mesh, optional secondary detail-texture pass, wired as Vehicle3D (player-driven) or MeshInstance3D (background). Trigger on "make a car", "spaceship model", "generate a mech", "I need a vehicle", "hover bike", "tank model", "racing car".
+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_inspect_resource summer_get_scene_tree summer_save_scene
+paths: ["assets/vehicles/**", "assets/models/**", "**/*.tscn", "**/*.gd"]
+---
+
+# Vehicle Model — Hard-Surface 3D Generation
+
+Vehicles are the hardest 3D-gen category. Hard surfaces (flat panels, sharp edges, symmetrical bodies) expose every flaw the AI mesher has — smoothing-group artifacts on flat panels, asymmetric headlights, melted door seams. This skill exists to push the success rate up by giving the model **multi-angle reference**, picking the right backend, and using a **secondary detail-texture pass** to recover crispness on the body panels.
+
+Backing tool: `summer_generate_3d`. Default model is `hunyuan` (best general quality). For pure hard-surface (clean spaceship, F1 car), try `trellis` first — it tends to preserve panel edges better.
+
+## When to use
+
+- "Make me a player car for a racing game."
+- "Generate a sci-fi fighter spaceship."
+- "I need a hover bike for the desert level."
+- "Create a mech for the boss fight."
+- "Background traffic — generate three civilian sedans."
+
+## When NOT to use
+
+- Character driving the vehicle → that's `summer:3d-assets/character-model`. Generate them separately and parent the character to the vehicle's seat.
+- Vehicle interior (cockpit, dashboard) as a first-person view → generate as a separate "interior" prop via `summer:3d-assets/prop-model` with first-person framing.
+- A scenery vehicle that never moves and is far from camera (parked truck in the distance) → `summer:3d-assets/prop-model` is fine; vehicle-model's overhead isn't worth it.
+- Procedural / customizable vehicles (modular ship parts) → use `summer:3d-assets/environment-kit` to generate a vehicle-parts kit instead.
+
+## Polycount targets
+
+| Use case | Tris | Pass via |
+|---|---|---|
+| Player vehicle (close camera, lots of screen time) | 15k–30k | `target_polycount: 25000` |
+| Hero showpiece (cinematic, garage view) | 30k–60k | `target_polycount: 50000` |
+| Background traffic (mid-range, multiple onscreen) | 2k–5k | `target_polycount: 4000` |
+| Distant flyby / parked scenery | 1k–2k | `target_polycount: 1500` |
+
+Vehicles benefit more from polycount than props — flat panels need edge density to look right. Don't go below 2k for anything the camera will get close to.
+
+## Multi-angle reference — the single biggest quality lever
+
+Vehicles are highly view-dependent. A front-only reference produces a mesh with great front detail and a melted rear. The fix: generate a **front + 3/4 side composite reference** before the 3D pass.
+
+```
+summer_generate_image(
+  prompt="A sleek red sports car, front view AND 3/4 rear-side view side by side, two angles in one image, white background, studio lighting, clean references for 3D modeling, isolated, no scenery."
+)
+```
+
+Most image models will produce a two-view composite. Then feed it to image-to-3D:
+
+```
+summer_generate_3d(
+  kind="image-to-3d",
+  imageUrl="<composite reference url>",
+  model="hunyuan",
+  options={ target_polycount: 25000 }
+)
+```
+
+If the user has reference images already (concept art, photos), prefer those — composite them into a single image first if they aren't already.
+
+## Steps
+
+### 1. Search before generating
+
+```
+summer_search_assets(query="<vehicle type>", filter={ kind: "model" })
+```
+
+### 2. Pick model and polycount
+
+For hard-edged vehicles (spaceships, F1, mechs), try `trellis` first — sharper panel edges. For organic-curved vehicles (muscle cars, motorcycles, classic boats), `hunyuan` handles the curves better.
+
+### 3. Build the prompt
+
+Pattern: `<vehicle type> + <silhouette / era / style> + <materials> + <surface state> + isolated suffix`.
+
+| Goal | Prompt that works |
+|---|---|
+| Player race car | `A sleek modern Formula 1 race car, aerodynamic carbon-fiber bodywork, large rear wing, exposed wheels, racing livery in red and white. Front and 3/4 side views. Game asset, stylized, clean white background, isolated vehicle.` |
+| Sci-fi fighter | `A sleek single-seat sci-fi space fighter, swept-forward wings, twin engine nacelles, glass cockpit canopy, painted matte gray with cyan trim. Front and 3/4 side views. Game asset, stylized hard-surface, white background, isolated vehicle.` |
+| Hover bike | `A rusted desert hover bike, exposed engine block, single seat, handlebars, no wheels (hover thrusters underneath), weathered orange paint. Front and 3/4 side views. Game asset, stylized, white background, isolated vehicle.` |
+| Mech | `A 4 meter tall bipedal combat mech, blocky armored torso, articulated arms with rifle and missile pod, thick legs with hydraulic pistons, painted olive drab with hazard stripes. Front and 3/4 side views. Game asset, hard-surface stylized, white background, isolated vehicle.` |
+| Background sedan | `A generic 90s civilian sedan, four doors, beige paint, slightly worn. Front and 3/4 side views. Game asset, low-detail stylized, white background, isolated vehicle.` |
+
+The phrase `front and 3/4 side views` is what triggers the multi-angle composite reference internally.
+
+### 4. Confirm and call
+
+> About to generate `red_race_car` via `hunyuan`, target ~25k tris, multi-angle ref. ~$0.60, ~90s. OK?
+
+```
+summer_generate_3d(
+  prompt="A sleek modern Formula 1 race car, ...",
+  model="hunyuan",
+  options={ target_polycount: 25000 },
+  wait=true
+)
+summer_import_from_url(url="<fileUrl>", path="res://assets/vehicles/race_car.glb")
+```
+
+### 5. Inspect for hard-surface artifacts
+
+```
+summer_inspect_resource(path="res://assets/vehicles/race_car.glb")
+```
+
+Open the import preview. Look for:
+- **Smoothing-group artifacts on flat panels** (visible as banding under light) → fix in step 6 with a detail texture, or re-import with `Generate Tangents = on` and a custom shader.
+- **Asymmetric headlights / wheels** → regenerate with `symmetric, mirrored bilateral` added to the prompt.
+- **Melted door seams / panel gaps** → run the detail-texture pass (step 6).
+
+### 6. Optional: secondary detail-texture pass
+
+For hero vehicles, run a texture-only pass to recover panel-line crispness without re-meshing:
+
+```
+summer_generate_3d(
+  kind="texture",
+  imageUrl="<original front-view reference>",
+  model="hunyuan",
+  options={ target_polycount: 25000 }  // matched to existing mesh
+)
+```
+
+This re-textures the existing mesh with sharper detail — panel lines, decals, weathering. Cheaper than re-meshing. Apply via material override in the editor.
+
+### 7. Wire into the scene
+
+| Use case | Parent type | Notes |
+|---|---|---|
+| Player-driven (car, bike, hover) | `VehicleBody3D` (Godot 4.5 wheeled) or `RigidBody3D` (free physics) | Add `VehicleWheel3D` children for wheeled vehicles |
+| Player-driven (spaceship, mech) | `RigidBody3D` or `CharacterBody3D` | Custom thrust / walk code, see `summer:character-controllers` |
+| Background scenery (parked, flyby) | `MeshInstance3D` under a `Node3D` | No physics, no collision needed for distant traffic |
+| Background traffic (moving but not interactive) | `Node3D` + `AnimationPlayer` driving the position | Cheap, no physics overhead |
+
+**Player car wiring:**
+
+```
+summer_add_node(parent="./World", type="VehicleBody3D", name="RaceCar")
+summer_add_node(parent="./World/RaceCar", type="MeshInstance3D", name="Body")
+summer_set_prop(path="./World/RaceCar/Body", property="mesh", value="res://assets/vehicles/race_car.glb")
+summer_add_node(parent="./World/RaceCar", type="CollisionShape3D", name="Collider")
+# Add a BoxShape3D resource matched to the AABB
+# Add VehicleWheel3D children at each wheel position
+summer_save_scene
+```
+
+**Background scenery wiring:**
+
+```
+summer_add_node(parent="./World/Street", type="MeshInstance3D", name="ParkedSedan")
+summer_set_prop(path="./World/Street/ParkedSedan", property="mesh", value="res://assets/vehicles/sedan.glb")
+summer_save_scene
+```
+
+## Anti-patterns
+
+- **Single-angle reference for a hero vehicle.** Front-only → melted rear. Always go multi-angle for anything the player gets close to.
+- **Flat-shaded prompt for hard surfaces.** "Smooth shading", "rounded edges" → loses the panel-line crispness that defines vehicles. Prefer "hard-surface", "panel-lined", "crisp edges".
+- **Skipping symmetry callouts.** Vehicles are bilaterally symmetric — without `symmetric, mirrored` you get one headlight bigger than the other 30% of the time.
+- **Asking the mesh pass to invent decals / liveries.** It can't — the mesh has the silhouette but the decals get geometry-baked weirdly. Use the texture pass for liveries.
+- **Wrapping a background sedan in VehicleBody3D.** Wastes physics for a parked car. Use MeshInstance3D under Node3D.
+- **Picking `meshy` (legacy).** Worse hard-surface fidelity than hunyuan or trellis.
+
+## Edge cases
+
+- **Tracked vehicle (tank).** AI mesh-gen handles the hull but the tracks come back as a fused ring. Generate the hull only, then add tracks as a separate `summer:3d-assets/prop-model` (or use a tiled texture on a torus). For animation, scroll the track texture's UV.
+- **Articulated vehicle (mech with shoulders, hips, knees).** The mesh is one piece — joints aren't separated. For animated mechs, treat as a humanoid: generate as `summer:3d-assets/character-model` with the rig pass, then animate via `summer:animation/generate-motion` (custom backend, prompt as "mech walks heavily").
+- **Vehicle with rotor (helicopter, drone).** Generate without rotor, then add the rotor as a separate `summer:3d-assets/prop-model` and parent it. Spin via code in `_process`.
+- **Open-top vehicle (convertible, jeep).** Specify "open top, no roof" — defaults often add a roof.
+- **The user wants the cockpit interior visible.** Generate exterior here, then a separate `summer:3d-assets/prop-model` for the interior, and switch meshes when the camera enters first-person view.
+
+## Fallback (no MCP)
+
+1. Generate the multi-angle reference at the Summer dashboard (or Midjourney / nano-banana web).
+2. Upload to Hunyuan or Trellis web playground → image-to-3D → download `.glb`.
+3. Drop into `res://assets/vehicles/`.
+4. Wire as VehicleBody3D / MeshInstance3D in the Godot editor manually.
+
+## Handoff
+
+After the vehicle is wired:
+
+> `race_car.glb` placed at `./World/RaceCar` as a VehicleBody3D. Next:
+> - **Vehicle controls:** WASD steering / accel — see `summer:character-controllers` for the vehicle controller pattern (or write directly with `engine_force`, `steering`, and `brake` on VehicleBody3D).
+> - **Driver character:** generate via `summer:3d-assets/character-model` and parent to the seat position.
+> - **Engine sound + tire screech:** `summer:audio/sound-effect` for one-shots, `summer:audio/ambient-bed` for the engine loop.
+> - **Particles:** exhaust smoke, dust trail, sparks on collision — `summer:vfx/particles` (when available) or built-in GPUParticles3D.
+
+## See also
+
+- `summer:3d-assets/character-model` — for the driver/pilot.
+- `summer:3d-assets/prop-model` — for separable parts (rotors, decals as decals, modular kit pieces).
+- `summer:asset-pipeline/asset-strategy` — meta-router.
+- `summer:character-controllers` — for player-driven vehicle input wiring.
+- `_shared/mcp-tools-reference.md` — `summer_generate_3d` schema, including `kind: "texture"` for the secondary detail pass.

package/skills/ai-and-npcs/design-npc/SKILL.md

@@ -481,5 +481,7 @@ For a fully-rigged enemy with anim controller + loot drop:
 - `ai-and-npcs/navmesh-pathfinding/SKILL.md` — NavigationAgent3D for movement
 - `ai-and-npcs/llm-driven-dialogue/SKILL.md` — Summer's wedge for talking NPCs
 - `ai-and-npcs/boss-patterns/SKILL.md` — phase transitions, mechanics
-- `visual-effects/vfx/SKILL.md` — hit flash and death VFX recipes
+- `visual-effects/recipes/hit-spark/SKILL.md` — hit flash recipe
+- `visual-effects/recipes/dissolve/SKILL.md` — death dissolve recipe
+- `visual-effects/game-feel/SKILL.md` — screen-feel discipline (camera shake, hit-stop)
 - `scripting-patterns/state-machine-patterns/SKILL.md` — generic FSM patterns