evomeme 0.1.9 → 0.1.10-beta.13

package/dist/skills/en-US/game-asset-mesh-generator/references/generation-contracts.md

@@ -0,0 +1,131 @@
+# Text, image and multiview generation
+
+Use `evomeme_text_to_mesh` or `evomeme_image_to_mesh`. Common task options, output fields and recovery are defined once in [tool-reference.md](tool-reference.md). Examples are illustrative MCP arguments; replace their prompts and source URLs for the actual task.
+
+## Contents
+
+- [Versions](#versions)
+- [Common parameters](#common-parameters)
+- [Face limits](#face-limits)
+- [Source parameters](#source-parameters)
+- [Image inputs](#image-inputs)
+- [Examples](#examples)
+
+## Versions
+
+Choose `model_version` from the request: **high precision / 高精度模型 → `v3.1-20260211` (H)**; **smart mesh / 智能网格 → `P2-20260801` (P)**. An explicit user version wins. Omission defaults to H `v3.1-20260211`. Send the version, not a `family` field; H `smart_low_poly` does not select P.
+
+| Family | Versions | Unsupported fields to omit entirely |
+| --- | --- | --- |
+| H3 | `v3.1-20260211`, `v3.0-20250812` | None of the common fields below solely because of this family; combination rules still apply. |
+| H2.5 | `v2.5-20250123` | `texture_quality`, `geometry_quality`, `auto_size`, `quad`, `smart_low_poly`, `generate_parts`, `compress` |
+| P1 | `P1-20260311` | `quad`, `geometry_quality`, `smart_low_poly`, `generate_parts`, `compress` |
+| P2 | `P2-20260801` (preview) | `geometry_quality`, `smart_low_poly`, `generate_parts`, `compress` |
+
+Unsupported fields must be omitted even when their value is `false` or a usual default. Preserve explicit `false` and `0` for supported fields. Seeds must be JavaScript safe integers.
+
+## Common parameters
+
+Defaults below apply only to supported versions. Optional omission preserves provider behavior unless the plugin default is stated.
+
+| Parameter | Type | Default and constraints |
+| --- | --- | --- |
+| `model_version` | string | Plugin default `v3.1-20260211`; versions above. |
+| `mesh_format` | string | `auto` (default), `glb`, `fbx`. H3 `quad=true` produces FBX; other generation modes use GLB. An explicit format must match; use `evomeme_convert_mesh` for another format. |
+| `model_seed` | integer | Random when omitted; `0` is valid. |
+| `face_limit` | integer | Adaptive when omitted, except H3 quads default to 10000. Bounds below. |
+| `texture` | boolean | `true`. For bare geometry also set `pbr=false`. |
+| `pbr` | boolean | `true`; enabling PBR forces texture generation. |
+| `texture_seed` | integer | Random when omitted; `0` is valid. |
+| `texture_quality` | string | `standard`; also `fast`, `detailed`, `extreme` (8K). `fast` requires explicit `texture_version="v3.5-20260815"`. |
+| `texture_version` | string | `v3.5-20260815`, `v3.0-20250812`, `v2.5-20250123`. H3/P default to v3.0; H2.5 defaults to v2.5. |
+| `delight` | boolean | `true`; removes baked reference lighting, read only by texture v3.5. |
+| `auto_size` | boolean | `false`; scale to real dimensions in meters. |
+| `export_uv` | boolean | `true`; `false` defers UV unwrapping. |
+| `export_orientation` | string | `+x`; also `-x`, `+y`, `-y`. Omit before downstream processing and orient in final conversion. |
+| `quad` | boolean | `false`; supported by H3 and P2. H3 outputs FBX. |
+| `geometry_quality` | string | H3 only: `standard` (default) or `detailed` (Ultra). |
+| `smart_low_poly` | boolean | H3 only, `false`; low-poly mode with its own face limits. |
+| `generate_parts` | boolean | H3 only, `false`. Requires explicit `texture=false`, `pbr=false`; omit both `quad` and `smart_low_poly`, including `false`. |
+| `compress` | string | H3 only: `geometry` enables meshopt; omitted disables compression. |
+
+## Face limits
+
+| Mode | Allowed `face_limit` |
+| --- | --- |
+| H3.1 standard triangles | 1–1500000 |
+| H3.0 standard triangles | 1–1000000 |
+| H2.5 triangles | 1–500000 |
+| H3 Ultra triangles | 1–2000000 |
+| H3 quads | 1–150000; omission uses 10000 |
+| H3 `smart_low_poly` | Triangles 500–20000; quads 500–10000 |
+| P1 | 50–20000 |
+| P2 | Triangles 48–50000; quads 48–25000 |
+
+## Source parameters
+
+| Tool | Parameter | Type | Requirement/default |
+| --- | --- | --- | --- |
+| `evomeme_text_to_mesh` | `prompt` | string | Required, 1–1024 characters. Describe silhouette, style, materials and intended use. |
+| `evomeme_text_to_mesh` | `negative_prompt` | string | Optional, at most 255 characters. |
+| `evomeme_text_to_mesh` | `image_seed` | integer | Optional text-to-image seed; random when omitted. |
+| `evomeme_image_to_mesh` | `input` | string | One image URL, file token or successful upstream image task ID. |
+| `evomeme_image_to_mesh` | `inputs` | array | Multiview forms below. |
+| `evomeme_image_to_mesh` | `image_url` | string | Compatibility form: one URL or four comma-separated view slots. |
+| `evomeme_image_to_mesh` | `enable_image_autofix` | boolean | Single-image only, `false`. Omit entirely for multiview. |
+| `evomeme_image_to_mesh` | `texture_alignment` | string | `original_image` (color priority) or `geometry`; default `original_image`. |
+| `evomeme_image_to_mesh` | `orientation` | string | `default` or `align_image`; default `default`, effective only with texture enabled. |
+
+Choose exactly one of `input`, `inputs`, `image_url`. Image generation has no text-only `prompt`, `negative_prompt` or `image_seed` field.
+
+## Image inputs
+
+Use PNG/JPEG/WebP, preferably at least 256×256; single-image input is limited to 20 MB. Upload local files first. Views must depict the same object; use consistent lighting. Multiview creates one model jointly from the images, not one model per image.
+
+- **Single image:** `input` is a string URL, file token or successful upstream `text_to_image`/`image_to_image` task ID. It does not accept view objects or a local file path.
+- **Named multiview:** 2–4 objects, each containing exactly one unique `front`, `left`, `back` or `right` key. Require `front` and another view. Values accept strings, `{"url":"https://example.com/front.png"}`, `{"file_token":"file_front"}` or `{"object":{"bucket":"images","key":"front.png"}}`.
+- **Positional multiview:** exactly four strings in `[front,left,back,right]` order. Keep `""` for missing views; require front and at least one other view.
+- **Task multiview:** exactly `[{"task_id":"task_upstream_multiview_image"}]` from successful upstream `generate_multiview_image`/`edit_multiview_image`. Do not mix with other forms.
+- **Compatibility URL:** `image_url` takes one public URL or four comma-separated positional slots; two or three unlabelled URLs are rejected.
+
+Upstream image IDs are not gateway model IDs; see the shared identifier rules in the tool reference.
+
+## Examples
+
+### evomeme_text_to_mesh — H precision
+
+```json
+{"prompt":"Detailed carved stone guardian, full body in T-pose","model_version":"v3.1-20260211","geometry_quality":"detailed","texture_quality":"fast","texture_version":"v3.5-20260815"}
+```
+
+### evomeme_text_to_mesh — P smart mesh
+
+```json
+{"prompt":"Low-poly wooden chair","model_version":"P2-20260801","face_limit":3000,"model_seed":0}
+```
+
+### evomeme_image_to_mesh — single image
+
+```json
+{"input":"https://example.com/front.png","model_version":"v3.1-20260211","enable_image_autofix":false}
+```
+
+### evomeme_image_to_mesh — named multiview
+
+```json
+{"inputs":[{"front":"https://example.com/front.png"},{"back":"https://example.com/back.png"}],"model_version":"P2-20260801","quad":true}
+```
+
+### evomeme_image_to_mesh — positional multiview
+
+```json
+{"inputs":["https://example.com/front.png","","https://example.com/back.png",""],"model_version":"v3.1-20260211"}
+```
+
+### evomeme_text_to_mesh — separate parts
+
+```json
+{"prompt":"An oak tree with separable trunk and crown","model_version":"v3.1-20260211","texture":false,"pbr":false,"generate_parts":true}
+```
+
+For P1, omit `quad` and use P1 face limits. For H2.5, remove every unsupported field. Parts output follows the shared readiness rules; keep all returned part links and inspect the actual primary file.

package/dist/skills/en-US/game-asset-mesh-generator/references/image-generator-workflows.md

@@ -0,0 +1,65 @@
+# 2D To 3D Pairing (local image generator skill removed)
+
+Use a strong 2D input when it improves `game-asset-mesh-generator` output or when the final asset is 2D rather than 3D.
+
+**Sources for 2D references:**
+
+- User-supplied PNG/JPG/WebP uploaded via `evomeme_upload_game_asset` → public URL → MCP `evomeme_image_to_mesh`
+- Local MCP `evomeme_generate_game_image` for remote image generation (`model`: `asset-max`, `asset-pro`, `asset-lite`).
+- Procedural/CSS/canvas UI art exported to disk, then published via `evomeme_upload_game_asset`
+
+Do **not** load removed local `threejs-image-generator` or require `GEMINI_API_KEY`.
+
+## 2D To 3D Reference Images
+
+Generate or obtain clean reference images before image-to-3D for:
+
+- Characters: full-body T-pose or A-pose, neutral expression, visible hands/feet, no cropped limbs.
+- Creatures: side/front silhouettes, clear limb count, readable anatomy.
+- Vehicles: front/side/three-quarter concepts, clear wheels/thrusters/wings, material zones.
+- Buildings: front elevation, roof silhouette, doors/windows, scale cues.
+- Weapons/tools: side view, readable handle/blade/barrel proportions, material callouts.
+- Props/pickups: centered object, plain background, strong silhouette, no text baked in unless wanted.
+- Terrain/world modules: tileable rocks, cliffs, rails, gates, arena pieces, modular set dressing.
+
+For prompt wording (image-to-3D reference, riggable character/creature, texture/material, logo/icon/UI, sky/background), adapt the asset brief in the active card or AAA/UI skill references — there is no separate image-generator SKILL.md in this plugin.
+
+## Texture And Material References
+
+Obtain 2D references via procedural canvas textures, user art, or remote MCP when you need:
+
+- Terrain albedo references: rock, sand, mud, snow, moss, cracked asphalt.
+- Sci-fi trim sheets, panel lines, decals, hazard stripes, window bands.
+- Metal, leather, fabric, glass, ceramic, wood, painted plastic, worn armor.
+- Sky, clouds, nebula, city haze, horizon plates, menu backgrounds.
+- Faction marks, logos, numbers, signs, pickup icons, hazard labels.
+
+## UI And Logo Use Cases
+
+Handle as 2D assets directly (not 3D generation) when appropriate:
+
+- Logos and faction marks.
+- HUD icons, item icons, ability icons, pickup symbols.
+- Menu backgrounds and loading illustrations.
+- Button/icon textures, decals, title art, achievement badges.
+- 2D sky/backdrop cards when a 3D model is unnecessary.
+
+Prefer procedural/CSS/canvas UI from `game-ui` before external 2D sourcing.
+
+## 3D Generator Handoff
+
+After obtaining a 2D reference:
+
+1. Save the image in the working project, usually `assets/concepts/`.
+2. Publish it to a public https URL via `evomeme_upload_game_asset`, or use an already-public URL from remote image tools.
+3. Call evomemeMCP `evomeme_image_to_mesh` with that `image_url` (never a local path).
+4. For a rough single image, consider `enable_image_autofix=true`; omit this field for multiview.
+5. Prefer `texture_alignment=original_image` when visual match matters; use `geometry` when structural accuracy matters.
+6. Use the successful MCP result's `local_path` and final `asset_url`; follow [shared readiness and recovery rules](tool-reference.md). MCP handles polling and download.
+
+## Avoid
+
+- Crowded scene images for single-object 3D generation.
+- Cropped limbs, hidden backs, extreme perspective, motion blur, or heavy depth of field.
+- Tiny UI/logo text in 3D model textures unless text fidelity is noncritical.
+- Using 3D generation for pure 2D UI assets.

package/dist/skills/en-US/game-asset-mesh-generator/references/postprocess-contracts.md

@@ -0,0 +1,187 @@
+# Model processing and animation
+
+Read only the selected operation below. Common task options, results, ID meanings and recovery are in [tool-reference.md](tool-reference.md). Examples are MCP arguments with illustrative IDs; substitute a real completed source.
+
+## Contents
+
+- [Shared inputs](#shared-inputs)
+- [Texture](#texture)
+- [Stylize](#stylize)
+- [Segment](#segment)
+- [Complete](#complete)
+- [Decimate](#decimate)
+- [Convert](#convert)
+- [Rig](#rig)
+- [Retarget](#retarget)
+
+## Shared inputs
+
+| Parameter | Type | Use |
+| --- | --- | --- |
+| `task_id` | string | Successful gateway public source-task ID. |
+| `url` | string | Public HTTP(S) model URL. |
+| `input` | string | Public model URL, uploaded file token or gateway public source-task ID. |
+| `mesh_format` | string | Optional storage hint, default `glb`, for texture/stylize/segment/complete/decimate only. It does not convert the file. |
+
+Select exactly one of `task_id`, `url`, `input`. **Complete and retarget accept only `task_id` or `input` containing the specific successful segment/rig public ID**; they do not accept URLs or file tokens. Other operations accept GLB/GLTF/FBX/OBJ/STL source models up to 150 MB; upload local files first.
+
+Versions and defaults are operation-specific, independent of generation H/P versions. Omit unsupported fields entirely, including `false`. Preserve supported `false`/`0`. The parameter tables below exclude shared task/source options; use the actual returned format.
+
+<a id="texture"></a>
+
+## Texture — evomeme_texture_mesh
+
+| Parameter | Type | Default and constraints |
+| --- | --- | --- |
+| `model_version` | string | `v3.0-20250812`; also `v2.5-20250123`, `v3.5-20260815`. |
+| `texture_prompt` | object or string | Optional guidance; forms below. A string is shorthand for text. |
+| `pbr` | boolean | `true`; PBR materials. |
+| `texture_seed` | integer | Random when omitted; `0` valid. |
+| `texture_alignment` | string | `original_image` or `geometry`; default `original_image`. |
+| `texture_quality` | string | `standard`; also `fast`, `detailed`, `extreme` (8K). Omit for v2.5. `fast` requires this operation's `model_version="v3.5-20260815"`. |
+| `part_names` | string[] | Omit to texture all parts; use actual segment names. |
+| `compress` | string | `geometry` for meshopt, omitted disables it; omit for v2.5. |
+| `bake` | boolean | `true`; bake material effects. |
+| `delight` | boolean | `true`; remove baked reference lighting, only read by v3.5. |
+
+A `texture_prompt` object selects exactly one of `text`, `image`, `images`; `style_image` may accompany `text` only. Image values accept URL/file-token strings or one-key `url`/`file_token` objects. `images` has exactly four entries in front,left,back,right order; a style image should be at least 256×256. Guidance may reuse a generated model's references; provide guidance for imported models and re-supply image references when retexturing image-generated models. Do not pass generation-only geometry options.
+
+```json
+{"task_id":"task_public_model","texture_prompt":{"text":"Weathered oak bark and moss"},"model_version":"v3.5-20260815","texture_quality":"fast","texture_seed":0}
+```
+
+<a id="stylize"></a>
+
+## Stylize — evomeme_stylize_mesh
+
+| Parameter | Type | Default and constraints |
+| --- | --- | --- |
+| `style` | string | Required: `lego`, `voxel`, `voronoi`, `minecraft`. |
+| `block_size` | integer | Optional positive integer; omission retains the provider default. |
+
+```json
+{"task_id":"task_public_model","style":"voxel","block_size":80}
+```
+
+<a id="segment"></a>
+
+## Segment — evomeme_segment_mesh
+
+| Parameter | Type | Default and constraints |
+| --- | --- | --- |
+| `model_version` | string | `v1.0-20250506` for geometric segmentation; `v2.0-20260430` for semantic segmentation (Beta). |
+| `segmentation_granularity` | string | v2 only: `simple`, `balanced` (default), `detailed`. |
+| `split_by_connectivity` | boolean | v2 only, `true`. |
+| `ref_image` | string | v2 only, optional reference URL/file token. |
+
+Omit the last three fields for v1. When `ref_image` is supplied, the provider ignores `segmentation_granularity` and `split_by_connectivity`. Use part names from the actual result instead of guessing filenames or assuming a fixed nested part schema.
+
+```json
+{"task_id":"task_public_model","model_version":"v2.0-20260430","segmentation_granularity":"balanced","split_by_connectivity":false}
+```
+
+<a id="complete"></a>
+
+## Complete — evomeme_complete_mesh
+
+| Parameter | Type | Default and constraints |
+| --- | --- | --- |
+| `model_version` | string | `v1.0-20250506`. |
+| `part_names` | string[] | Omit to complete all parts; use actual segment names. |
+| `completion_mode` | string | `ai_completion` synthesizes missing geometry; `quick_cap` seals holes. Default `ai_completion`. |
+
+Source must be the successful `evomeme_segment_mesh` public task ID. A generation ID or ID from another kind of segmentation cannot substitute.
+
+```json
+{"task_id":"task_public_segment","completion_mode":"quick_cap"}
+```
+
+<a id="decimate"></a>
+
+## Decimate — evomeme_decimate_mesh
+
+| Parameter | Type | Default and constraints |
+| --- | --- | --- |
+| `model_version` | string | `v2.0`; also `v1.0`, `v3.0`. v1 decimates; v2/v3 use smart retopology. |
+| `face_limit` | integer | v1 required: triangles 1–2000000, quads 1–150000. v2/v3 adaptive when omitted: triangles 500–20000, quads 500–10000 when specified. |
+| `quad` | boolean | `false`; supported by all three versions. |
+| `smart_uv` | boolean | v3 only, `false`; UV unwrapping without an atlas preview. |
+| `bake` | boolean | v2/v3 only, `true`; bake textures. |
+| `part_names` | string[] | v2/v3 only; omit to process all parts. |
+
+Omit `bake`/`part_names` for v1, and omit `smart_uv` entirely for v1/v2, including `false`.
+
+```json
+{"task_id":"task_public_model","model_version":"v3.0","face_limit":5000,"smart_uv":true,"bake":false}
+```
+
+<a id="convert"></a>
+
+## Convert — evomeme_convert_mesh
+
+| Parameter | Type | Default and constraints |
+| --- | --- | --- |
+| `format` | string | `GLTF`; also `FBX`, `USDZ`, `OBJ`, `STL`, `3MF`. |
+| `quad` | boolean | `false`; `true` forces FBX. |
+| `face_limit` | integer or null | Omit/null preserves original faces, except quads default to 10000; explicit integer must be positive. |
+| `force_symmetry` | boolean | `false`; enabling requires `quad=true`. |
+| `flatten_bottom` | boolean | `false`; flatten the base. |
+| `flatten_bottom_threshold` | number | `0.01`; nonnegative flattening depth. |
+| `texture_size` | integer | `4096`; positive pixel size. |
+| `texture_format` | string | `JPEG`; also `PNG`, `WEBP`, `BMP`, `DPX`, `HDR`, `OPEN_EXR`, `TARGA`, `TIFF`. |
+| `bake` | boolean | `true`; bake material effects. |
+| `pack_uv` | boolean | `false`; unified UV layout. |
+| `export_vertex_colors` | boolean | `false`; enabling requires OBJ/GLTF and `quad=false`. |
+| `pivot_to_center_bottom` | boolean | `false`; move the pivot to bottom center. |
+| `scale_factor` | number | `1`; must be positive. |
+| `with_animation` | boolean or null | Default `true`; preserve skeleton/animation. Null leaves it unspecified. |
+| `animate_in_place` | boolean | `false`; remove root displacement. |
+| `part_names` | string[] | Omit to export all parts. |
+| `export_orientation` | string | `+x`; also `-x`, `+y`, `-y`. Apply final orientation here. |
+| `fbx_preset` | string | `blender`; also `3dsmax`, `mixamo`, `bake_scale`. `bake_scale` bakes scale into FBX geometry. |
+
+There is no `model_version` or `mesh_format` input for this tool. `format=GLTF` may return a package instead of a single GLB. Material and animation availability depends on the source and target format; OBJ does not carry animation and STL is for geometry printing. Follow the shared format/readiness rules.
+
+```json
+{"task_id":"task_public_model","format":"GLTF","pivot_to_center_bottom":true,"with_animation":true}
+```
+
+<a id="rig"></a>
+
+## Rig — evomeme_rig_mesh
+
+| Parameter | Type | Default and constraints |
+| --- | --- | --- |
+| `rig_type` | string | `biped`; also `quadruped`, `hexapod`, `octopod`, `avian`, `serpentine`, `aquatic`. |
+| `model_version` | string | Inferred: biped → `v1.0-20240301`; other body plans → `v2.5-20260210`. Explicit version wins; v1 supports bipeds only. |
+| `spec` | string | `tripo` or `mixamo`; default `tripo`. Selects bone naming; prefer `tripo` for Tripo presets. |
+| `out_format` | string | `glb` or `fbx`; default `glb`. Prefer GLB for animation. |
+
+Select the body plan from the actual model and inspect its rig. v2.5 also has a distinct biped preset catalog. Use the returned rig public `task_id` for retarget, not the original source ID.
+
+```json
+{"task_id":"task_public_model","rig_type":"quadruped","model_version":"v2.5-20260210","spec":"tripo","out_format":"glb"}
+```
+
+<a id="retarget"></a>
+
+## Retarget — evomeme_retarget_mesh
+
+| Parameter | Type | Default and constraints |
+| --- | --- | --- |
+| `animation` | string | One complete `preset:` identifier; mutually exclusive with `animations`. |
+| `animations` | string[] or string | Nonempty preset array; comma-separated string supported for compatibility. If both selection fields are omitted, the plugin selects walk using the rig hints below. |
+| `out_format` | string | `glb` or `fbx`; default `glb`. |
+| `bake_animation` | boolean | `true`; GLB only. |
+| `export_with_geometry` | boolean | `true`; `false` creates animation for an existing matching skeleton. |
+| `animate_in_place` | boolean | `false`; `true` removes root displacement. |
+| `rig_type` | string | Body-plan values from rig above; default `biped`. Compatibility hint for omitted/comma-separated presets. |
+| `model_version` | string | Inferred from `rig_type`, as above. Compatibility hint for preset mapping. |
+
+Source must be a successful rig public ID. Prefer explicit complete preset names matching the rig: v1 bipeds use `preset:biped:*`, while v2.5 bipeds use names such as `preset:walk`. Explicit `animation` and array `animations` are passed through. Read [animation-presets.md](animation-presets.md); no avian preset is catalogued, so do not invent one.
+
+Prefer `animate_in_place=false` and remove unwanted horizontal root motion in-engine when appropriate. An animation-only export needs the matching skeleton and is not a standalone visible character. Inspect returned clips before naming them; names and ordering are not guaranteed.
+
+```json
+{"task_id":"task_public_rig","animations":["preset:quadruped:walk"],"rig_type":"quadruped","model_version":"v2.5-20260210","out_format":"glb","animate_in_place":false}
+```

package/dist/skills/en-US/game-asset-mesh-generator/references/threejs-integration.md

@@ -0,0 +1,113 @@
+# Three.js Integration
+
+Use this after `game-asset-mesh-generator` generates or post-processes a model.
+
+## Preferred Outputs
+
+- Three.js runtime: prefer **GLB/PBR**. Generation defaults to `mesh_format=auto`; H quads produce FBX. Rig/retarget default to `out_format=glb`. Convert incompatible files before intake.
+- Successful MCP calls return a downloaded `local_path` and final `asset_url`. Use the shared [result and readiness rules](tool-reference.md); raw HTTP pending URLs are not ready assets.
+- Animation/game-engine interchange: use FBX only when explicitly required; otherwise keep GLB.
+- Static web asset exchange: GLTF/GLB.
+- 3D print only: STL or 3MF, not for textured game runtime.
+- Apple AR: USDZ.
+
+## Import Pattern
+
+Before runtime integration, use the downloaded GLB at `local_path` and follow [game-asset-align](../../game-asset-align/SKILL.md). Remote generation/postprocessing remains MCP; local intake and engine delivery use CLI. The [CLI contract](../../game-asset-align/references/tool-contract.md) defines launcher/version selection, relative paths, JSON results, and confirmation gates.
+
+```sh
+npx -y evomeme@latest asset import "<downloaded.glb>" --id character --workspace "<workspace>" --source tripo --type character --json
+npx -y evomeme@latest asset review character --workspace "<workspace>" --json
+npx -y evomeme@latest stage --asset character --workspace "<workspace>" --target three_js --json
+```
+
+Use the actual source/type for the asset; the example is a Tripo character. Keep Stage running in a persistent terminal/session and give the user `data.url`. After the user views and confirms the current version, run this in another terminal with the same CLI version:
+
+```sh
+npx -y evomeme@latest asset sync character --workspace "<workspace>" --target three_js --project "<project>" --json
+```
+
+Integrate through the synced canonical runtime described in [engine asset loading](../../threejs-3d-game/references/engine-asset-pipeline.md). Preserve the single alignment wrapper and reviewed appearance; a remote URL or a successful technical review alone does not authorize game import. Use the canonical loader's imported animation clips with the engine animation system.
+
+Animation intake notes (engine-side; remote MCP exposes `evomeme_rig_mesh` / `evomeme_retarget_mesh`):
+
+- Inspect the returned files and animation clips before assigning gameplay names. Generic `NlaTrack*` names may occur, but the API does not guarantee names, clip order, or one file per batch. Verify each motion before renaming it (`clip.name = 'walk'`); do not map presets by index without checking the actual clips.
+- Log `gltf.animations.map(c => `${c.name} ${c.tracks.length} tracks`)` after load. A healthy humanoid clip drives many bones; clips with only a handful of tracks mean the upstream auto-rig was degenerate — fix the rig, not the runtime.
+- Do NOT strip or neutralize twist-bone tracks (`UpperarmTwist`, `ForearmTwist`, …) on v1.0 rigs: Tripo skins most of the limb mesh to the twist bones, and their baked values differ greatly from the GLB rest pose — removing the tracks collapses the limbs into the torso. Tripo's slightly open, palm-forward hands are the preset house style, not corruption.
+- Prefer converting to in-place at import rather than trusting upstream `animate_in_place`. Use `animate_in_place=false` on `evomeme_retarget_mesh` (the default), then strip root motion precisely:
+  - Touch ONLY the top root bone's position track (`Root.position`). Tripo FBX clips bake position tracks on EVERY bone with values that differ from FBXLoader's rest transforms; filtering Hip/Pelvis or pattern-matching broadly collapses the skeleton into a hunch.
+  - Zero the HORIZONTAL components only — keep Y. Vertical root motion IS the animation for jumps (and the bob in gaits); deleting the whole track turns a jump into grounded hand-waving.
+
+```ts
+for (const clip of clips) {
+  for (const tr of clip.tracks) {
+    if (tr.name !== 'Root.position') continue;
+    const v = tr.values, x0 = v[0], z0 = v[2];
+    for (let i = 0; i < v.length; i += 3) { v[i] = x0; v[i + 2] = z0; }
+  }
+}
+```
+
+FBX intake specifics (only if the user explicitly required `out_format=fbx`; default path is GLB):
+
+- `FBXLoader` lives at `three/addons/loaders/FBXLoader.js` and imports `fflate`; bundler projects get it from npm automatically, but import-map/CDN pages must map it (e.g. `"fflate": "https://cdn.jsdelivr.net/npm/fflate@0.8.2/esm/browser.js"`).
+- Use ONE FBX per animation (the pipeline does this automatically) and play each file's `animations[0]` as exported. The variant order of duplicate takes differs per file — `animations[0]` is always the correct one.
+
+- `FBXLoader` emits each take twice under different node-path prefixes (`Armature.001|walk_…` and `Armature|Armature.001|walk_…`). Keep the variant with the SHALLOWER path (fewer `|` segments); the deep variant's tracks bind incorrectly.
+- Clips carry real names (`walk_normal_m_remap`, `idle_251105_remap`) — select by keyword (slash arrives as an attack/swing name), not by index.
+- Play the clips otherwise untouched. Every loader-side "fix" beyond the single root-position strip has been tested and makes things worse.
+- FBXLoader produces Phong materials (darker than GLB PBR). For final art parity, convert FBX→GLB offline (Blender import/export or FBX2glTF) — the corrected animation survives conversion.
+- Tripo preset retargeting only works on `spec=tripo` rigs. A `spec=mixamo` rig is for external animation pipelines (Mixamo clips, custom libraries) — retarget those in a DCC tool or at runtime with `SkeletonUtils.retargetClip`, and expect to supply bone-name mappings and check bind-pose orientation when skeleton conventions differ.
+
+## Asset Intake Checklist
+
+Inspect before shipping:
+
+- File size.
+- Triangle count.
+- Mesh count.
+- Material count.
+- Texture count and texture dimensions.
+- PBR material behavior under the game lighting rig.
+- Scale in meters and `auto_size` assumptions.
+- Pivot/origin and bounds.
+- Collision proxy separate from detailed mesh.
+- Animation clip names, durations, root motion, and in-place behavior.
+- Mobile memory/performance impact.
+
+## Game Asset Strategy
+
+- Use `game-asset-mesh-generator` for hero assets, characters, creatures, bosses, buildings, weapons, signature props, and complex pickups.
+- Use procedural Three.js kits for high-volume repeated detail such as bolts, windows, track plates, rails, debris, markers, and background silhouettes.
+- For concept art, texture references, decals, logos, UI icons, and backdrop images: prefer procedural/CSS/canvas; use user-supplied images or remote MCP `evomeme_generate_game_image` when needed.
+- Combine: 2D reference (user/remote/procedural) -> 3D-generator model -> canonical CLI intake, Stage confirmation and sync -> Three.js integration -> procedural set dressing -> visual scorecard.
+
+## Performance Discipline
+
+- Use `face_limit`, `smart_low_poly`, conversion, or low-poly postprocess for browser/mobile budgets.
+- Prefer one high-fidelity hero asset plus instanced/procedural supporting detail over many unique heavy models.
+- Keep textures compressed or reasonably sized.
+- Clone carefully. Share geometry/materials when possible.
+- Dispose loaded assets when leaving scenes.
+- Run renderer diagnostics after importing: calls, triangles, geometries, textures, materials, file sizes.
+
+## Common Fixes
+
+- Model too large/small: return to `game-asset-align` to measure the canonical scale recipe, review, and sync again.
+- Wrong orientation: update the canonical recipe through Stage or `asset align`, then review and sync again; do not add runtime compensation. Tripo image `orientation=align_image` can guide generation, but does not replace canonical review.
+- Animations move out of place: keep exported root motion intact (`animate_in_place=false` on MCP), then strip only horizontal root-position components in code as shown above. Do not rely on MCP `animate_in_place=true` for final quality.
+- Too expensive: lower `face_limit`, use `smart_low_poly` on H3 only, reduce texture quality/size, or convert with a face limit.
+- Materials too dark/bright: check color space, tone mapping, environment, and light exposure.
+- Collision too complex: build primitive proxies in Three.js and keep Tripo mesh visual-only.
+
+## Final Evidence
+
+Report:
+
+- MCP tool names used (`evomeme_text_to_mesh`, `evomeme_rig_mesh`, `evomeme_retarget_mesh`, …).
+- Gateway public `task_id` for each completed generation, rig and retarget stage, plus `job_id` and `local_task_id`.
+- Each stage's downloaded `local_path`, final `asset_url`, actual `mesh_format` and import verification.
+- Model version and generation/postprocess options (`rig_type`, `animations`, `out_format`, `animate_in_place`).
+- Local CLI commands, canonical asset ID, Stage confirmation status, synced loader/import files, and any clip rename or root-motion strip.
+- Renderer diagnostics before/after import.
+- Screenshot evidence in active gameplay.

package/dist/skills/en-US/game-asset-mesh-generator/references/tool-reference.md

@@ -0,0 +1,67 @@
+# Mesh MCP tool reference
+
+Shared calling contract for the ten local `evomemeMCP` Mesh tools. Read operation-specific parameters only when needed. Tool schemas and returned results are authoritative.
+
+## Tool selection
+
+| Tool | Use | Parameters |
+| --- | --- | --- |
+| `evomeme_text_to_mesh` | Text to model | [Generation](generation-contracts.md) |
+| `evomeme_image_to_mesh` | Single-image or multiview to one model | [Generation](generation-contracts.md) |
+| `evomeme_texture_mesh` | Apply or replace textures | [Texture](postprocess-contracts.md#texture) |
+| `evomeme_stylize_mesh` | Lego, voxel, voronoi or minecraft style | [Stylize](postprocess-contracts.md#stylize) |
+| `evomeme_segment_mesh` | Split into parts | [Segment](postprocess-contracts.md#segment) |
+| `evomeme_complete_mesh` | Complete segmented parts | [Complete](postprocess-contracts.md#complete) |
+| `evomeme_decimate_mesh` | Reduce faces or retopologize | [Decimate](postprocess-contracts.md#decimate) |
+| `evomeme_convert_mesh` | Convert format, scale, pivot or orientation | [Convert](postprocess-contracts.md#convert) |
+| `evomeme_rig_mesh` | Add a skeleton | [Rig](postprocess-contracts.md#rig) |
+| `evomeme_retarget_mesh` | Apply animation presets to a rig | [Retarget](postprocess-contracts.md#retarget) |
+
+Local tasks submit through the authenticated plugin API, wait for remote publication and download the resulting file. Upstream credentials stay on the server. Do not call Tripo directly or infer service availability from local provider credentials. Local processing and game integration use their respective tools.
+
+## Common task options
+
+| Parameter | Type | Behavior |
+| --- | --- | --- |
+| `workspace_dir` | string | Optional workspace path; defaults to the MCP working directory. Prefer an explicit absolute path when multiple workspaces are open. Files go to `assets/mesh/`. |
+| `client_operation_id` | string | Optional operation identity, 1–140 ASCII letters, digits, `_` or `-`. Omission creates a new identity. The same workspace, tool, identity and parameters reuse the task; changing parameters under that identity is a conflict. Use distinct identities for distinct operations/stages. |
+
+## Result and identifiers
+
+Success is MCP text with named fields followed by `result: <JSON>`. Parse that JSON to retain nested data; it is not an HTTP response envelope. Success means the remote job completed and the primary file was downloaded and registered locally.
+
+| Field | Meaning |
+| --- | --- |
+| `local_task_id` | Local root task identifier. Do not pass as a model source. |
+| `client_operation_id` | Identity used to resume or reuse this operation. |
+| `job_id` | Plugin-server job identifier. Do not pass as a model source. |
+| `task_id` | Gateway public task ID for this operation; use the appropriate completed stage as a downstream source. |
+| `role` | `model`, `rigged` or `animated`, according to the operation. |
+| `local_path` | Downloaded primary file. |
+| `asset_url` | Hosted primary file URL. |
+| `mesh_format` | Actual downloaded format; archives remain archives. |
+| `asset_id` | Registered workspace asset ID; also available as `result.id`. |
+| `result` | Full object, including `status`, `operation`, `operation_id`, `mime_type`, `bytes` and `generation`. |
+| `result.generation` | Remote receipt/result metadata: `output`, `metadata`, `generationParameters` and available progress/type/credit/timestamp fields. Preserve unknown nested output fields and URLs. |
+
+Upstream **image** task IDs accepted by generation `input`/`inputs` belong to a different namespace from gateway **model** task IDs. Prefixes such as `task_` do not establish ownership or task type. Do not invent IDs or substitute local IDs.
+
+## Readiness and chaining
+
+- Use a successful non-`isError` result, its downloaded file, final URL and actual format. A URL string or a raw HTTP `pending=true` receipt alone is not completion evidence.
+- The MCP task handles polling and downloading. Normal tool calls need no separate HTTP polling. Before engine use, verify the actual file imports successfully.
+- Each operation downloads its own primary result. Retain every stage's file and URL when chaining.
+- Retarget takes the successful **rig** `task_id`; complete takes the successful **segment** `task_id`. A generation ID or raw URL cannot replace these typed sources.
+- Preserve all `result.generation.output` links. Only the primary `asset_url` is guaranteed to be plugin-hosted; other links may expire. A parts-only primary file may be one part or an archive, not an assembled model. Inspect available parts and clips instead of assuming names or ordering.
+- Downloads preserve the actual bytes and format. Do not turn FBX/ZIP into GLB by renaming the file. Use conversion and appropriate import handling.
+
+## Failure and recovery
+
+1. Preserve MCP `isError` text and any `client_operation_id`, `local_task_id`, `job_id` and `stage` returned. A transport disconnect does not prove a remote task failed; the local worker may still be running.
+2. For an interrupted query or download, repeat the same tool with the original workspace, `client_operation_id` and identical parameters. It waits for the existing task, resumes eligible interrupted work or returns a cached result without intentionally creating another generation.
+3. An uncertain submission receipt (`NEEDS_ATTENTION`) requires inspection. Terminal generation failures are not automatically retried by reusing the identity. Do not issue a new identity merely to bypass either condition; a deliberate new generation is a new paid operation.
+4. Authentication renewal is handled by the client. If login cannot recover, resolve the reported authentication issue before resuming the original task. Preserve provider/moderation failures; do not replace them with a different paid operation.
+
+## Character composition
+
+The internal `character_pipeline` task composes optional generation → rig → optional retarget. It records and downloads stages separately. MCP exposes only the atomic tools above; neither the pipeline nor rig-check is a callable MCP tool. Body-plan and preset rules are in [postprocessing](postprocess-contracts.md#rig) and [animation presets](animation-presets.md).