From 61ed9a652267e0c638441e41b4b48988f1897394 Mon Sep 17 00:00:00 2001 From: sunzhenqiang Date: Wed, 28 Oct 2026 03:26:51 +0800 Subject: [PATCH 1/8] feat(tripo-3d): P2 game routing, tripo-cli 0.8 gate and source attribution (0.1.5) - Game/realtime recipes prefer P2; P1 stays optional for lower cost and speed, v3.1 for film/render/print. Rig defaults to v3.0, retopology smart_uv and tripo_smart_uv are separate billed workflows, fast textures require v3.5 and chat_image_1 is retired. - The CLI path requires tripo-cli >= 0.8.0 (npx tripo-cli@0.8) and runs only when the user explicitly chooses it; no automatic fallback from MCP. - MCP sends X-Tripo-Distribution: zcode_plugin; the SessionStart hook adds source/version and explicit model/billing rules. - Keep the upstream 0.1.4 marketplace descriptions and mirror them into .claude-plugin/plugin.json so both manifests stay identical. Co-authored-by: Cursor --- marketplace.json | 2 +- plugins/tripo-3d/.claude-plugin/plugin.json | 8 +- plugins/tripo-3d/.mcp.json | 5 +- plugins/tripo-3d/.zcode-plugin/plugin.json | 2 +- plugins/tripo-3d/README.md | 30 +++- plugins/tripo-3d/README_CN.md | 20 ++- plugins/tripo-3d/hooks/session-start.mjs | 5 +- plugins/tripo-3d/skills/tripo-3d/SKILL.md | 75 ++++++---- .../skills/tripo-3d/references/capability.md | 140 +++++++++++++----- .../tripo-3d/skills/tripo-game-asset/SKILL.md | 51 +++++-- 10 files changed, 245 insertions(+), 93 deletions(-) diff --git a/marketplace.json b/marketplace.json index c1a9a6ee..8b75927a 100644 --- a/marketplace.json +++ b/marketplace.json @@ -1102,7 +1102,7 @@ "en": "Generate textured 3D models from text or images, add rigging and animation, simplify meshes, and export assets for games or 3D printing. Requires a mainland China Tripo account.", "zh-CN": "用文字或图片生成带贴图的 3D 模型,添加骨骼与动画、精简模型面数,导出用于游戏或 3D 打印的素材。需使用 Tripo 国内站账号。" }, - "version": "0.1.4", + "version": "0.1.5", "author": { "name": "VAST", "url": "https://www.tripo3d.ai" diff --git a/plugins/tripo-3d/.claude-plugin/plugin.json b/plugins/tripo-3d/.claude-plugin/plugin.json index 16aab3c6..dd4f3542 100644 --- a/plugins/tripo-3d/.claude-plugin/plugin.json +++ b/plugins/tripo-3d/.claude-plugin/plugin.json @@ -1,10 +1,10 @@ { "name": "tripo-3d", - "version": "0.1.3", - "description": "Generate textured, rig-ready 3D models from a text prompt or a reference image with Tripo, and export GLB/FBX/OBJ/STL/USDZ/3MF straight into your project. Connect your China-mainland Tripo account once in the browser (OAuth), no API key pasting.", + "version": "0.1.5", + "description": "Generate textured 3D models from text or images, add rigging and animation, simplify meshes, and export assets for games or 3D printing. Requires a mainland China Tripo account.", "description_i18n": { - "en": "Generate textured, rig-ready 3D models from a text prompt or a reference image with Tripo, and export GLB/FBX/OBJ/STL/USDZ/3MF straight into your project. Connect your China-mainland Tripo account once in the browser (OAuth), no API key pasting.", - "zh-CN": "用 Tripo 从一句话或一张图生成带贴图、可绑骨的 3D 模型,支持动画、减面与 GLB/FBX/OBJ/STL/USDZ/3MF 导出,文件直接落到项目里。浏览器里授权一次国内站 Tripo 账号即可使用,无需粘贴 API Key。" + "en": "Generate textured 3D models from text or images, add rigging and animation, simplify meshes, and export assets for games or 3D printing. Requires a mainland China Tripo account.", + "zh-CN": "用文字或图片生成带贴图的 3D 模型,添加骨骼与动画、精简模型面数,导出用于游戏或 3D 打印的素材。需使用 Tripo 国内站账号。" }, "author": { "name": "VAST", diff --git a/plugins/tripo-3d/.mcp.json b/plugins/tripo-3d/.mcp.json index edf7df96..edca3688 100644 --- a/plugins/tripo-3d/.mcp.json +++ b/plugins/tripo-3d/.mcp.json @@ -4,7 +4,10 @@ "type": "http", "url": "https://developers.tripo3d.com/mcp", "enabled": true, - "timeoutMs": 90000 + "timeoutMs": 90000, + "headers": { + "X-Tripo-Distribution": "zcode_plugin" + } } } } diff --git a/plugins/tripo-3d/.zcode-plugin/plugin.json b/plugins/tripo-3d/.zcode-plugin/plugin.json index 55f169ee..dd4f3542 100644 --- a/plugins/tripo-3d/.zcode-plugin/plugin.json +++ b/plugins/tripo-3d/.zcode-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "tripo-3d", - "version": "0.1.4", + "version": "0.1.5", "description": "Generate textured 3D models from text or images, add rigging and animation, simplify meshes, and export assets for games or 3D printing. Requires a mainland China Tripo account.", "description_i18n": { "en": "Generate textured 3D models from text or images, add rigging and animation, simplify meshes, and export assets for games or 3D printing. Requires a mainland China Tripo account.", diff --git a/plugins/tripo-3d/README.md b/plugins/tripo-3d/README.md index 6f49a8b4..e5048f96 100644 --- a/plugins/tripo-3d/README.md +++ b/plugins/tripo-3d/README.md @@ -2,6 +2,21 @@ [中文](./README_CN.md) +## 0.1.5 + +Game/realtime recipes explicitly prefer **P2** (more credits than H/P1); **P1** +remains optional for lower cost and speed, and v3.1 for film/render/print. Rig defaults to v3.0, with +animation presets selected from the upstream rig model. Retopology v3.0's +`smart_uv` and standalone `tripo_smart_uv` are distinct billed workflows. +Fast textures require v3.5; `chat_image_1` is retired. + +The CLI path requires **0.8.0 or later**, run as `npx tripo-cli@0.8`; do not use +npm `latest`. Verify the version before executing; if unavailable, +stop rather than downgrade. A plan is not a price quote: cost is not estimated +here, and uncertainty needs explicit consent. Never switch accounts silently. +MCP remains the default; missing authorization is not permission to use CLI. +The hook also enforces source attribution and explicit model/billing decisions. + The official Tripo plugin for ZCode. Generate textured 3D models from a text prompt or a reference image, with rigging, animation, retopology and format conversion (GLB/FBX/OBJ/STL/USDZ/3MF), and land the files directly in your @@ -16,10 +31,10 @@ the CLI with `--region ov`. | Component | What it does | | --- | --- | -| Skill `tripo-3d` | Main workflow: execution-path selection, authorization guidance, MCP workflow, scenario → tool-chain mapping, input handling, credit rules; plus the fallback `tripo-cli` path | +| Skill `tripo-3d` | Main workflow: execution-path selection, authorization guidance, MCP workflow, scenario → tool-chain mapping, input handling, credit rules; plus an explicitly selected `tripo-cli` path | | Skill `tripo-game-asset` | Game-asset recipes: budgeted low-poly props, LOD chains, rigged characters with locomotion clips, wiring into Unity/Unreal/Godot/Three.js | -| MCP server `tripo` | Remote Streamable HTTP server `https://developers.tripo3d.com/mcp` (OAuth 2.1) exposing 26 tools such as `tripo_plan`, `tripo_text_to_3d`, `tripo_image_to_3d`, `tripo_task_wait`, `tripo_mesh_edit`, `tripo_rig`, `tripo_animate`, `tripo_convert` | -| Hook `SessionStart` | Injects five hard rules (async waiting, link expiry, credit confirmation / `tripo_plan`, browser authorization, honest failure reporting) so they hold even when no skill was triggered | +| MCP server `tripo` | Remote Streamable HTTP server `https://developers.tripo3d.com/mcp` (OAuth 2.1), including `tripo_plan`, generation, rigging, conversion and `tripo_smart_uv`; available tool schemas are authoritative | +| Hook `SessionStart` | Injects seven rules: async waiting, link expiry, credit confirmation, browser authorization, honest failures, source/version gates and explicit model/billing decisions | ## Usage @@ -66,10 +81,11 @@ The Tripo MCP server needs a one-time authorization: write nothing. - **Command execution**: on the MCP path, shell commands run only to upload a local image/model (the `curl` returned by `tripo_upload_ticket`) or to - download a result. The fallback CLI path downloads and runs - [tripo-cli](https://www.npmjs.com/package/tripo-cli) (MIT, via - `npx tripo-cli@latest`), only for jobs that need it (e.g. bulk generation), - and says so first. + download a result. The optional [tripo-cli](https://www.npmjs.com/package/tripo-cli) + path (MIT) runs as `npx tripo-cli@0.8`, minimum 0.8.0. It runs only after the user explicitly chooses CLI + and confirms the account, region and billing plan; check the actual version first. + If it is unavailable, stop. There is no automatic fallback from MCP + failure, missing authorization, batch work or a request to save files locally. - **Hook**: `hooks/session-start.mjs` needs `node` on PATH. It reads the event from stdin and prints a fixed text to stdout; no network, no file access. diff --git a/plugins/tripo-3d/README_CN.md b/plugins/tripo-3d/README_CN.md index 8fedd44c..09645e44 100644 --- a/plugins/tripo-3d/README_CN.md +++ b/plugins/tripo-3d/README_CN.md @@ -2,6 +2,18 @@ [English](./README.md) +## 0.1.5 + +游戏/实时资产显式优先选择 **P2**(积分高于 H/P1);看重积分更低、速度更快时仍可选 **P1**, +影视/渲染/打印用 v3.1。绑骨默认 v3.0,动画预设须跟随上游 rig 模型。 +重拓扑 v3.0 的 `smart_uv` 与独立 `tripo_smart_uv` 是不同计费流程。 +fast 贴图需 v3.5;`chat_image_1` 已退役。 + +CLI 最低 **0.8.0**,通过 `npx tripo-cli@0.8` 运行,不使用 npm `latest`;执行前 +检查实际版本,不满足则停止,不静默降级。计划不是报价,本文**费用未估算**, +计费前须说明不确定性并获得确认。禁止自动切换账号。MCP 是默认路径,未授权 +不构成使用 CLI 的许可。Hook 同步执行来源标记、版本门槛与选模/计费约束。 + Tripo 官方 ZCode 插件。用一句话或一张图生成带贴图的 3D 模型,支持骨骼绑定、动画、 减面和格式转换(GLB/FBX/OBJ/STL/USDZ/3MF),文件直接落到你的项目里。覆盖游戏、 影视、AR 和 3D 打印场景。 @@ -14,10 +26,10 @@ API Key。本构建的 MCP 只对接国内站;海外站账号请安装海外 | 组件 | 内容 | | --- | --- | -| Skill `tripo-3d` | 主流程:执行路径选择、授权引导、MCP 工作流、场景 → 工具链映射、输入处理、积分规则;以及备用的 `tripo-cli` 路径 | +| Skill `tripo-3d` | 主流程:执行路径选择、授权引导、MCP 工作流、场景 → 工具链映射、输入处理、积分规则;以及需明确选择的 `tripo-cli` 路径 | | Skill `tripo-game-asset` | 游戏资产配方:面数预算道具、LOD 链、绑骨角色与动画、接入 Unity/Unreal/Godot/Three.js | -| MCP 服务器 `tripo` | 远程 Streamable HTTP server `https://developers.tripo3d.com/mcp`(OAuth 2.1),提供 `tripo_plan`、`tripo_text_to_3d`、`tripo_image_to_3d`、`tripo_task_wait`、`tripo_mesh_edit`、`tripo_rig`、`tripo_animate`、`tripo_convert` 等 26 个工具 | -| Hook `SessionStart` | 会话开始时注入 5 条硬规则(异步等待、链接过期、积分确认 / `tripo_plan`、浏览器授权、如实报错),保证即使 skill 未被触发也遵守 | +| MCP 服务器 `tripo` | 远程 Streamable HTTP server `https://developers.tripo3d.com/mcp`(OAuth 2.1),含计划、生成、绑骨、转换与独立 UV;以实际可见工具 schema 为准 | +| Hook `SessionStart` | 注入 7 条规则:异步等待、链接过期、计费确认、浏览器授权、如实报错、来源/版本门槛、显式选模与计费决策 | ## 怎么用 @@ -45,7 +57,7 @@ API Key。本构建的 MCP 只对接国内站;海外站账号请安装海外 - **网络**:MCP 工具调用走 `https://developers.tripo3d.com/mcp`;授权页跳转到国内站 Tripo 控制台(developers.tripo3d.com)。生成结果通过 Tripo 的 CDN 短期链接(约 5 分钟过期)下载。 - **账号与计费**:所有生成任务消耗你自己 Tripo 账号的积分,每次工具返回 `credits_consumed`;失败任务自动退款。批量生成前 skill 会先用 `tripo_plan` 草稿、查余额并确认。 - **文件写入**:只在你要求把模型落到本地时,用 `curl` 把结果下载到项目目录;Hook 与 MCP 服务器本身不写任何文件。 -- **命令执行**:MCP 路径下仅在上传本地图片/模型(`tripo_upload_ticket` 返回的 curl)或下载结果时运行 shell 命令。备用 CLI 路径通过 `npx tripo-cli@latest` 从 npm 下载并运行 [tripo-cli](https://www.npmjs.com/package/tripo-cli)(MIT),只在批量生成等需要时使用,且会先说明。 +- **命令执行**:MCP 路径下仅在上传本地图片/模型(`tripo_upload_ticket` 返回的 curl)或下载结果时运行 shell 命令。可选 [tripo-cli](https://www.npmjs.com/package/tripo-cli) 路径(MIT)通过 `npx tripo-cli@0.8` 运行,最低 0.8.0。仅当用户明确选择 CLI 并确认账号、区域和计费计划后执行,先检查实际版本;不可用则停止。MCP 失败、未授权、批量或本地落盘需求均不自动切换 CLI。 - **Hook**:`hooks/session-start.mjs` 依赖 PATH 中的 `node`,只从 stdin 读取事件、向 stdout 输出一段固定文本,不访问网络、不读写文件。 - **不采集任何数据**:插件本体不含遥测;账号凭据由 ZCode 的凭据存储管理,不经过对话。 diff --git a/plugins/tripo-3d/hooks/session-start.mjs b/plugins/tripo-3d/hooks/session-start.mjs index e0d840db..691669e1 100644 --- a/plugins/tripo-3d/hooks/session-start.mjs +++ b/plugins/tripo-3d/hooks/session-start.mjs @@ -8,7 +8,10 @@ const RULES = `Tripo 3D — rules that apply whenever Tripo tools (tripo_*) are 2. Show the result, then the link. On success, embed preview_image_url as a markdown image and give model_url as the download link. Both URLs expire in about 5 minutes: never re-print an old one — call tripo_task_status for fresh links. If you saved the file locally, give its path as plain text in backticks, never as a clickable link (chat previews cannot render meshes). 3. Credits belong to the user. Call tripo_plan and get confirmation before any billed generation or chain. Every billed tool reports credits_consumed. Check tripo_balance and confirm before generating more than one asset in a batch; on insufficient balance give the returned plans_url instead of retrying. Never silently re-roll a disappointing result — show the preview and ask first. 4. Authorization is a browser flow, never a pasted key. This build's MCP is China-mainland only (developers.tripo3d.com/mcp); the auth page has no region picker. If Tripo tools are missing or a call reports an authorization error, tell the user to open ZCode 设置 → MCP, find the Tripo server under「Plugin MCP 服务器」and click「打开授权」, then sign in on the 国内站 console and Authorize. An overseas-site account needs the overseas plugin build or CLI login --region ov. Do not ask for an API key in the chat, and do not run tripo-cli instead just because a local login or TRIPO_API_KEY exists — offer the CLI only as an explicit alternative and use it only if the user picks it. -5. Failures are reported, not hidden. On failed/banned, relay failure_reason (and error_code) honestly; failed-task credits are refunded automatically. Never invent parameters — the tool schemas are authoritative. Stylize has been retired: there is no tripo_stylize and no CLI --then stylize. Use tripo_mesh_edit for P2 regional redo.`; +5. Failures are reported, not hidden. On failed/banned, relay failure_reason (and error_code) honestly; failed-task credits are refunded automatically. Never invent parameters — the tool schemas are authoritative. Stylize has been retired: there is no tripo_stylize and no CLI --then stylize. Use tripo_mesh_edit for P2 regional redo. +6. Keep source tags on every CLI invocation (CLI >= 0.8.0, run as npx tripo-cli@0.8), including each pipeline stage. Verify the installed version; ask before installing, and stop if unavailable. Never silently downgrade or change accounts. Set TRIPO_DISTRIBUTION_CHANNEL=zcode_plugin and TRIPO_CLIENT_APP=zcode in ZCode, or TRIPO_CLIENT_APP=claude in the Claude compatibility host; leave the client unset when the host is unknown. Prefix each POSIX command or set the variables in the same PowerShell call. Never save them to a profile. MCP sends the distribution header and uses client info for the actual host. +7. Choose models explicitly: P2 is preferred for game/realtime topology and costs more credits than H/P1; P1 remains optional for lower cost and speed, v3.1 for film/render/print. Do not infer the model from face_limit. Cost is not estimated by this text or guaranteed by tripo_plan: disclose uncertainty and obtain consent before billing. Rig defaults to v3.0; use preset:walk, reserving preset:biped:* for explicit v1.0 rigs. Retopology v3.0 with smart_uv and standalone tripo_smart_uv are separate workflows, not interchangeable free export switches. Load the capability reference before running either. chat_image_1 is retired; never fall back to it. fast textures require v3.5-20260815. +`; let raw = ""; process.stdin.setEncoding("utf8"); diff --git a/plugins/tripo-3d/skills/tripo-3d/SKILL.md b/plugins/tripo-3d/skills/tripo-3d/SKILL.md index 38758ebf..ca41acd1 100644 --- a/plugins/tripo-3d/skills/tripo-3d/SKILL.md +++ b/plugins/tripo-3d/skills/tripo-3d/SKILL.md @@ -5,6 +5,24 @@ description: Generate a 3D model from a text prompt, a reference image, or an ex # Tripo 3D +## Client attribution + +Use `tripo-cli` 0.8.0 or later, pinned as `npx tripo-cli@0.8`. Check the +version before using these contracts; if it is missing or older, ask before +installing it or offer the authorized MCP path, never +silently downgrade or switch accounts. The cost is not estimated by this document: +show a live estimate if available, otherwise disclose that uncertainty and obtain +explicit consent before any billed task. A plan is not a quote. +On every CLI command, including each command +in a pipeline and commands from references, set +`TRIPO_DISTRIBUTION_CHANNEL=zcode_plugin`. Set `TRIPO_CLIENT_APP=zcode` only +when running in ZCode; in the Claude compatibility host use `TRIPO_CLIENT_APP=claude`. +If the host is unknown, leave `TRIPO_CLIENT_APP` unset; never infer it from the +package name. Use a variable prefix in POSIX or set `$env:TRIPO_CLIENT_APP` and +`$env:TRIPO_DISTRIBUTION_CHANNEL` in the same PowerShell call. Never save these +values to an account profile. MCP sends only `X-Tripo-Distribution: zcode_plugin`; +its client info identifies the actual host. OAuth and region selection stay the same. + Generate engine-ready 3D assets with Tripo. Two execution paths exist; pick one before doing anything else, and never pretend to run what this environment cannot run. @@ -98,20 +116,22 @@ loses access too. credits, then add a skeleton with the `rig_type` the check returned. Prompt characters as **T-pose** at generation time; `spec: "mixamo"` for Unity Humanoid / Mixamo pipelines. Leave `model` unset: `tripo_rig` picks - the humanoid v1.0 rig for `biped` and the creature v2.5 rig for the other + v3.0 for `biped` and the creature v2.5 rig for the other body types, and its result says which preset family the rig takes. - `tripo_animate` — presets on a **successful rig task** (≤5 per call, billed per animation). Preset names follow the rig model reported by - `tripo_rig`: humanoid (v1.0) rigs take `preset:biped:walk`, - `preset:biped:idle`, …; creature (v2.5) rigs take `preset:walk`, - `preset:idle`, …; `animate_in_place: true` when game code drives movement. + `tripo_rig`: explicit legacy v1.0 rigs take `preset:biped:walk`, + `preset:biped:idle`, …; v3.0 and v2.5 rigs take `preset:walk`, + `preset:idle`, … on bipeds and only their body-type clip on creatures + (`preset:quadruped:walk`, …; avian has none); `animate_in_place: true` + when game code drives movement. - `tripo_convert` — export GLTF/USDZ/FBX/OBJ/STL/3MF, optional retopology via `face_limit`/`quad`. Quads cannot export GLTF. Any non-default option bills as "complex convert". - `tripo_decimate` — high-poly → low-poly (`face_limit` 500–20000, bakes the original textures); `tripo_segment` → `tripo_mesh_complete` — split into parts and close the cuts; `tripo_mesh_edit` — redo one region of an - existing mesh with P2 Preview (`bbox` required). Stylize (lego / voxel / + existing mesh with P2 (`bbox` required). Stylize (lego / voxel / voronoi / minecraft) has been retired — there is no `tripo_stylize` tool and no CLI `--then stylize` step. 6. **Deliver** — result URLs (`model_url`, `preview_image_url`) **expire in @@ -129,10 +149,10 @@ followed by `tripo_task_wait`. GLB is the native output — a `tripo_convert` step is only worth its credits when the target really needs another format. - **Game prop, mobile / WebGL / many instances** — generate with - `face_limit` ≤ 20000 (auto-selects the low-poly `P1` model) → + explicit `model: "P2"` and a confirmed `face_limit` → `tripo_convert` `format: "FBX"` (`texture_size: 2048`) for Unity/Unreal; Three.js/Godot take the GLB as is. -- **Game hero asset, PC / console** — default `v3.1`, `pbr: true`, +- **Game hero asset, PC / console** — explicit `model: "P2"`, `pbr: true`, `texture_quality: "detailed"` → FBX only if the engine needs it. - **Film / render / close-ups** — `v3.1` with `geometry_quality: "detailed"` and `texture_quality: "detailed"` (both cost extra credits). @@ -144,9 +164,10 @@ step is only worth its credits when the target really needs another format. with `template: "t_pose"` turns a character image into one) → `tripo_image_to_3d`/`tripo_text_to_3d` → `tripo_rig_check` → `tripo_rig` (`spec: "mixamo"` for Unity Humanoid) → `tripo_animate` with the preset - family named in the `tripo_rig` result: humanoids - `["preset:biped:walk", "preset:biped:idle"]`, creatures (quadruped and the - other body types) `["preset:walk", "preset:idle"]`. + family named in the `tripo_rig` result: v3.0 humanoids + `["preset:walk", "preset:idle"]`; creatures use their body-specific presets + (e.g. `preset:quadruped:walk`); explicit v1.0 humanoids alone use + `preset:biped:*`. - **LOD chain** — generate once → one `tripo_decimate` per level (`face_limit` is a target, not a hard ceiling — say so when the project has a strict budget). @@ -162,11 +183,10 @@ step is only worth its credits when the target really needs another format. ## Parameters that matter -- **Generation model version is chosen automatically**: `v3.1` high fidelity - by default, `P1` when the prompt smells low-poly or `face_limit ≤ 20000`. - Only pass `model` to the generation tools when the user explicitly asks - (`P2` / `P2-20260801` Preview for quads or a bigger low-poly budget). The - rig model is likewise chosen from `rig_type` by `tripo_rig` (see above). +- **Choose the generation model explicitly**: P2 for game/realtime topology + (costs more credits than H/P1); P1 remains optional for lower cost and speed. Use v3.1 + for film/render/print. This is plugin policy, not an API requirement. Confirm + the model, texture options and cost; re-confirm any paid model change. - 3D printing / untextured output: `texture: false, pbr: false` skips texture credits entirely; convert to `STL` (add `flatten_bottom: true` for stability). - `quad: true` (v3.1 or P2) needs a `tripo_convert` to FBX/OBJ/USDZ at the end; @@ -197,7 +217,7 @@ step is only worth its credits when the target really needs another format. per-stage breakdown when a chain misbehaves. - `tripo_task_list` — status of up to 100 task ids in one call (batches). - `tripo_usage` — recent per-task credit spend (includes per-task breakdown). -- `tripo_mesh_edit` — P2 Preview regional regenerate (`bbox` + optional +- `tripo_mesh_edit` — P2 regional regenerate (`bbox` + optional `ref_image`). ## Spending the user's credits @@ -218,7 +238,7 @@ record. ## Before the first generation ```bash -npx tripo-cli@latest doctor # verifies key, network, region, balance +npx tripo-cli@0.8 doctor # verifies key, network, region, balance ``` Auth resolves from `TRIPO_API_KEY` (a `tsk_...` key) or a previous `tripo login`. @@ -242,7 +262,7 @@ should pick `cn` (Alipay top-up), everyone else `ov` — signing up during the login flow is fine and new accounts get free credits. ```bash -npx tripo-cli@latest login --region cn --yes # or: --region ov +npx tripo-cli@0.8 login --region cn --yes # or: --region ov ``` `--yes` forces the non-interactive device flow. The command prints a @@ -269,12 +289,12 @@ assume they have never seen this page: When the command exits 0, re-run `doctor` and continue. Exit code 3 means the code expired or was denied — run the same login command again for a fresh code. If an older CLI rejects headless login with a usage error, fall back to -asking the user to run `npx tripo-cli@latest login` in their own terminal. +asking the user to run `npx tripo-cli@0.8 login` in their own terminal. -Installing globally (`npm install -g tripo-cli`) makes repeated calls faster and +Installing globally (`npm install -g tripo-cli@0.8`) makes repeated calls faster and is what makes the bare `tripo` command exist — ask before doing it. Without a global install, run every `tripo ...` command in this and related skills as -`npx tripo-cli@latest ...`; npx downloads the CLI on first use, so a fresh machine +`npx tripo-cli@0.8 ...`; npx downloads the CLI on first use, so a fresh machine needs no manual install. If `npx` itself is missing, Node.js is not installed — have the user install Node.js LTS first. On China-mainland networks, when the npx download stalls, switch to the npmmirror registry and retry: @@ -312,7 +332,7 @@ path instead. use a chain-free preset instead (`toy` for low-poly, with `-p face_limit=...`) or tell the user the extra format costs credits before running. - `--then ` overrides the chain. Steps: `texture` `convert` - `import` `rig-check` `rig` `retarget` `segment` `complete` `decimate` `smartsegment`. + `import` `rig-check` `rig` `retarget` `segment` `complete` `decimate` `smartsegment` `uv`. Arguments use `step:key=value`; a bare value maps to the step's primary argument (`convert:fbx`, `decimate:5000`). - `-o, --out ` sets the **parent** directory, not the artifact directory. `make` @@ -352,9 +372,9 @@ path instead. it does not, `tripo redo` re-rolls with a new seed. 5. **Never invent parameters.** Run `tripo docs --topic commands/make` for the full flag list, or `tripo docs --topic common-errors` for the error table. -6. **Let the CLI choose the model version.** It selects `tripo-v3.1` (high fidelity) - or `tripo-p1` (low-poly, face budget 50-20000) automatically. Only pass `--model` - when the user explicitly asks for one (`tripo-p2` Preview for quads). +6. **Pass `--model` explicitly.** Prefer `tripo-p2` for game/realtime + topology, retain `tripo-p1` for lower cost and speed, and `tripo-v3.1` for film/render/print. + Confirm cost before execution; presets are not a substitute for this choice. Download URLs returned by the API expire in about five minutes — never cache one. Re-run `tripo task get --download` instead. @@ -368,3 +388,8 @@ Model versions, generation/processing parameters, 2D steps, list prices, CLI result shape and other commands: read [`references/capability.md`](references/capability.md) (same parameter names on MCP and CLI). MCP also has `tripo_plan` (confirm before spend) and `tripo_mesh_edit` (P2 regional redo). + +Retopology: `tripo_decimate` with explicit `model: "v3.0", smart_uv: true` +combines retopology and UVs (35 tri / 40 quad credits). Standalone +`tripo_smart_uv` is a separate billed UV-layout task for inputs up to 80,000 +equivalent triangles; confirm the choice and cost. See the capability reference. diff --git a/plugins/tripo-3d/skills/tripo-3d/references/capability.md b/plugins/tripo-3d/skills/tripo-3d/references/capability.md index 39fbad1f..aad7e28b 100644 --- a/plugins/tripo-3d/skills/tripo-3d/references/capability.md +++ b/plugins/tripo-3d/skills/tripo-3d/references/capability.md @@ -10,16 +10,19 @@ strips, quad→FBX) and report what they changed (`notes` / warnings). | model | MCP `model` / CLI `--model` | use for | limits | | --- | --- | --- | --- | -| **v3.1** (default) | `v3.1` / `tripo-v3.1` | high fidelity: PC/console, film, print | full parameter set | -| **P1** | `P1` / `tripo-p1` | clean low-poly: mobile, UGC, ~2 s mesh | `face_limit` 50–20000; no `quad`, `smart_low_poly`, `generate_parts`, `geometry_quality`; adds `export_uv` | -| **P2** | `P2` / `tripo-p2` → wire `P2-20260801` | **Preview**: P1 upgrade, low-poly **with quads** or a bigger budget | `face_limit` 48–50000 tri / 48–25000 quad; supports `quad`, still no `smart_low_poly`, `generate_parts`, `geometry_quality`; ~5× the P1 price. Never auto-selected on the CLI — needs `--model tripo-p2` | +| **v3.1** (default) | `v3.1` / `tripo-v3.1` | high fidelity: film, render, print | full parameter set | +| **P1** | `P1` / `tripo-p1` | optional low-poly for lower cost and speed | `face_limit` 50–20000; no `quad`, `smart_low_poly`, `generate_parts`, `geometry_quality`; adds `export_uv` | +| **P2** | `P2` / `tripo-p2` → wire `P2-20260801` | preferred for game/realtime topology, with explicit user confirmation | `face_limit` 48–50000 tri / 48–25000 quad; supports `quad`, still no `smart_low_poly`, `generate_parts`, `geometry_quality`; costs more credits than H/P1, and price depends on input and texture options; confirm the estimate. Pass the generation model explicitly | | v3.0, v2.5 | `v3.0` / `tripo-v3.0`, `v2.5` / `tripo-v2.5` | legacy, only when the user asks | v2.5 has no `geometry_quality` | -Auto-selection: low-poly words in the prompt (low poly, voxel, 低模, 手游, -像素风) or **any `face_limit` ≤ 20000** pick P1; MCP picks P2 instead when -`quad: true` is also set (the CLI never auto-selects P2); everything else is -v3.1. CLI aliases (`tripo-p2`, `tripo-v3.1`…) are sent as dated wire values -(`P2-20260801`, `v3.1-20260211`); the API rejects the alias itself with 1004. +Website model names map to these rows: H3.1 → `v3.1`, P1.0 → `P1`, P2.0 → `P2`. + +Selection policy: explicitly choose P2 for game/realtime topology; +keep P1 available for lower cost and speed and v3.1 for film/render/print. +This is plugin guidance, not an API requirement. Do not rely on implicit routing +or infer a generation model from face_limit. Confirm the model, texture options +and estimated cost before a billed call; re-confirm any paid model change. +CLI generation aliases resolve to dated wire values (P2-20260801, v3.1-20260211). `tripo-turbo` and `tripo-v2.0` appear in older docs but the server rejects them. ## Generation parameters @@ -32,7 +35,7 @@ and to `tripo make` / `tripo generate *-to-model`. | `prompt`, `negative_prompt` | – | text input only; ≤1024 / ≤255 chars | | `face_limit` | adaptive | upper bound on triangles. v3.1 any; P1 50–20000; P2 48–50000 | | `texture`, `pbr` | `true`, `true` | `pbr=true` forces `texture=true`. `texture=false pbr=false` = bare geometry, no texture credits | -| `texture_quality` | `standard` | `standard` / `detailed` (HD, +10 credits) / `extreme` (8K, +20). API also has `fast` (v3.5 textures only; same price/size as `standard`); CLI local validation still rejects it with exit 2 — do not pass it until the CLI accepts it | +| `texture_quality` | `standard` | `standard` / `detailed` (HD, +10 credits) / `extreme` (8K, +20). API also has `fast` (v3.5 textures only; same price/size as `standard`); CLI 0.8.0 accepts it with `texture_version=v3.5-20260815`; other texture versions are incompatible | | `texture_version` | derived from `model` | pins the texture model independently of geometry: `v3.5-20260815` (newest), `v3.0-20250812` (default for v3.x and P-series), `v2.5-20250123` (default for v2.5). All generation models incl. P1/P2 | | `delight` | `true` | v3.5 textures only (`texture_version=v3.5-20260815`): remove baked-in lighting from the reference image; `false` keeps original shading. Older texture versions ignore it | | `geometry_quality` | `standard` | `detailed` = Ultra geometry, finer detail up to 2M faces (+20). v3.x only | @@ -54,6 +57,27 @@ Multiview (2–4 images): `front` is mandatory and at least two views are needed `tripo_edit_multiview` sheet); the CLI reads `front|back|left|right` from the filenames, otherwise positional order front, left, back, right. + +## Retopology and UV workflows + +CLI equivalents: `--then decimate:model=v3.0,face_limit=5000,smart_uv=true` +or `tripo mesh decimate --model v3.0 --face-limit 5000 --smart-uv`; +standalone `tripo mesh uv ` / `--then uv`. Run a dry-run and confirm cost first. + +`tripo_decimate` defaults to v2.0. Explicit `model: "v3.0"` supports +`smart_uv: true` in the same task: 35 credits triangle / 40 quad, versus +30 for v2.0; smart_uv adds no extra charge. Confirm this model/cost change +before submitting. v2.0/v3.0 targets: 500–20000 triangles or 500–10000 quads. +The face budget is a target, not a ceiling. The combined task has no UV preview. + +Standalone `tripo_smart_uv` is separately billed: re-unwrap UVs and remap existing +textures, rigging and animation. Input must be at most 80,000 equivalent triangles +(one quad counts as two); decimate larger meshes first. `bake` defaults true; +false keeps geometry + UVs only. Optional `export_orientation` and `compress` +follow the exposed schema. Its `output_urls.uv_render_url` is a UV-layout preview, +not the model download; show it when requested. Do not substitute this separate +paid task for integrated smart_uv without confirming the extra cost. + ## Processing steps Every step takes a model task_id, a `file_token` or a model URL as `input`, @@ -64,25 +88,24 @@ bare value to the primary argument (`convert:fbx`, `decimate:5000`). | MCP tool / CLI step | arguments and constraints | | --- | --- | -| `tripo_texture` / `texture` | `texture_quality` `standard`/`detailed`/`extreme`; `pbr` (true); `texture_seed`; `texture_alignment`; `model` `v3.0` / `v3.0-20250812` (default) / `v3.5-20260815` (newest; unlocks `delight` and `texture_quality=fast` on MCP) / `v2.5`; `bake`; `part_names` (segmented models); `compress`. MCP also takes guidance — exactly one of `prompt` (+ optional `style_image`), `image`, or `images` (4 views front/left/back/right). Re-textures any model, including imported files | -| `tripo_mesh_edit` | P2 Preview regional regenerate: `input` (task_id / file_token / URL) + axis-aligned `bbox` in model space; optional `ref_image`. Rest of mesh kept. Billed separately | +| `tripo_texture` / `texture` | `texture_quality` `standard`/`detailed`/`extreme`/`fast` (fast requires v3.5); `pbr` (true); `texture_seed`; `texture_alignment`; `model` `v3.0` / `v3.0-20250812` (default) / `v3.5-20260815` (newest; unlocks `delight` and `texture_quality=fast` on MCP and CLI 0.8.0) / `v2.5`; `bake`; `part_names` (segmented models); `compress`. MCP also takes guidance — exactly one of `prompt` (+ optional `style_image`), `image`, or `images` (4 views front/left/back/right). Re-textures any model, including imported files | +| `tripo_mesh_edit` | P2 regional regenerate: `input` (task_id / file_token / URL) + axis-aligned `bbox` in model space; optional `ref_image`. Rest of mesh kept. Billed separately | | `tripo_plan` | Free draft of the tool chain **before** any billed call; show the user and wait for confirmation. Skip only for pure reads (balance / usage / task status) | | `tripo_convert` / `convert` | `format` `GLTF` `USDZ` `FBX` `OBJ` `STL` `3MF` (3MF = single-colour print). Mesh: `quad`, `force_symmetry` (quad only), `face_limit` (default: keep), `flatten_bottom` + `flatten_bottom_threshold` (0.01). Texture: `texture_size` (4096), `texture_format` `JPEG`/`PNG`/`WEBP`/`BMP`/`TIFF`/`TARGA`/`HDR`/`DPX`/`OPEN_EXR`, `bake` (true), `pack_uv`, `export_vertex_colors` (OBJ/GLTF only). Export: `pivot_to_center_bottom`, `scale_factor`, `auto_size`, `with_animation` (true), `animate_in_place`, `part_names`, `export_orientation`, `fbx_preset` `blender`/`3dsmax`/`mixamo` (FBX only). `quad` with `GLTF` is rejected. Any non-default option bills the complex tier (10 credits instead of 5) | | `tripo_import_model` / `import` | GLB/GLTF/FBX/OBJ/STL ≤150 MB via `file_token` or URL (`.gltf` only as a URL — upload `.glb`). `tripo make ` runs it implicitly | | `tripo_rig_check` / `rig-check` | free. GLB input. Result: `riggable` and recommended `rig_type`: `biped` `quadruped` `hexapod` `octopod` `avian` `serpentine` `aquatic`. Gate step — not riggable → stop; riggable → rig the **original model task**, not the check task | -| `tripo_rig` / `rig` | `rig_type` one of the seven above (default `biped`; take it from rig-check); `spec` `tripo`/`mixamo` (Mixamo = Unity Humanoid-compatible skeleton); `out_format` `glb`/`fbx`; `model` — `v1.0` humanoid rig (biped only, 90+ `preset:biped:*` clips) / `v2.5` creature rig (the other six body types, 16 universal presets). MCP picks it from `rig_type` when unset (`biped` → v1.0, otherwise v2.5) and reports the choice plus the matching preset family in the result; CLI `rig:model=rig-v1.0` / `rig-v2.0` (CLI default is still v2.0 for every body type — pass `rig:model=rig-v1.0` for humanoids) | -| `tripo_animate` / `retarget` | needs a rig task. MCP `animations: [...]` (≤5, billed per clip); CLI one clip per `--then retarget:preset:walk`, several via `tripo anim retarget --animation preset:idle preset:walk`. `out_format` `glb`/`fbx`, `animate_in_place` (no root motion — game code drives movement), `bake_animation` (true, glb only), `export_with_geometry` (true) | +| `tripo_rig` / `rig` | `model`: `v3.0-20260909` (`v3.0`) for biped/default, `others` and `actorcore`/`unity`/`unreal`/`vrm` specs; `v2.5-20260210` (`v2.5`) for the six creature body types. Both take `preset:walk` / `preset:idle` on bipeds and body-type clips on creatures. Explicit `v1.0-20240301` (`v1.0`) is legacy biped-only for 90+ `preset:biped:*` clips. Read the returned model before animation. `rig_type` comes from rig-check; rig the original model, not the check task. `spec` is biped-only; `out_format` is `glb`/`fbx`. CLI default is v3.0; use `rig:model=rig-v3.0`, `rig-v2.5` for creatures or explicit `rig-v1.0` for legacy biped clips. | +| `tripo_animate` / `retarget` | needs a rig task. MCP `animations: [...]` (≤5, billed per clip); CLI one clip per `--then retarget:preset:walk`, several via `tripo anim retarget --animation preset:idle preset:walk`. `out_format` `glb`/`fbx`, `animate_in_place` (no root motion — game code drives movement), `export_with_geometry` (true); `bake_animation` is deprecated — do not pass it (it is ignored) | | `tripo_segment` / `segment` | `model` `v1.0-20250506` (geometry-based, default) or `v2.0-20260430` (semantic, beta) with `segmentation_granularity` `simple`/`balanced`/`detailed`, `split_by_connectivity` (true), `ref_image` (overrides the other two). MCP switches to v2.0 automatically when a v2-only argument is set | | `tripo_mesh_complete` / `complete` | needs a segment task. `completion_mode` `ai_completion` (default) / `quick_cap` (hole fill, cheaper); `part_names` (default all) | | `tripo_decimate` / `decimate` | `face_limit` target 500–20000 tri / 500–10000 with `quad=true` (docs quote 1000–20000); `bake` (true) bakes textures onto the low-poly; `part_names`. `model: "v1.0"` accepts up to 2 000 000 tri / 150 000 quad but requires `face_limit` and has no `bake`/`part_names`. The budget is a target, not a ceiling | | `tripo_smart_segment` / `smartsegment` | file_token/URL only. `seg_type` `model` (existing **GLB only**, 55 credits; default) or `image` (photo → auto-model → parts, 85); `granularity` `coarse`/`medium`/`fine`; `hint` describing the parts to find. Output: part labels, a PNG mask, the segmented GLB and the inner task ids. Unlike `segment`, it is an end-to-end pipeline | Animation presets depend on the rig model of the upstream rig task — on MCP -read it from the `tripo_rig` result (a `biped` rig is v1.0 unless `model` was -set). v2.5 rig (creature body types): `preset:idle` `preset:walk` `preset:run` `preset:dive` +read it from the `tripo_rig` result (biped defaults to v3.0). v3.0 and v2.5 biped rigs: `preset:idle` `preset:walk` `preset:run` `preset:dive` `preset:climb` `preset:jump` `preset:slash` `preset:shoot` `preset:hurt` -`preset:fall` `preset:turn`, plus `preset:quadruped:walk` `preset:hexapod:walk` -`preset:octopod:walk` `preset:serpentine:march` `preset:aquatic:march`. v1.0 rig +`preset:fall` `preset:turn`; creature rigs take only their body type's clip: `preset:quadruped:walk` `preset:hexapod:walk` +`preset:octopod:walk` `preset:serpentine:march` `preset:aquatic:march` (avian and others have none). v1.0 rig (biped only, 90+ clips as `preset:biped:`): `idle` `walk` `run` `jump` `sit` `swim`, `dance_01`…`dance_06`, `greet_01`…`greet_04`, `wave_goodbye_01`, `clap` `bow` `cry` `laugh_01`, `angry_01`…, `box_01`…`box_03`, `front_kick_01`, @@ -96,29 +119,65 @@ or `inputs`), `tripo_image_to_multiview`, `tripo_edit_multiview`, image-to-multiview|edit-multiview|image-to-splat`. An image task_id is a valid `input` for `tripo_image_to_3d` — no re-upload. -- **Templates** (`template`): `t_pose` (the pre-step for rigging), `3d_enhance` - (clean a photo before image-to-3D; image mode only), `character_completion`, - `asset_extraction` (text mode only), `variants`, `figure`. The CLI also - accepts `head_extraction`, `print_clay` and the shortcuts `t_pose=true`, - `sketch_to_render=true` via `-p`. Image editing needs `prompt` and/or - `template`; negative prompts go inside `prompt` after `--no`. +- **Templates** (`template`): choose from the documented endpoint whitelist: + - Text-to-image templates: `asset_extraction`, `character_completion`, `t_pose`, `variants`, `figure`. + - Image-to-image templates: `t_pose`, `character_completion`, `3d_enhance`, `variants`, `figure`. + - `head_extraction` and `print_clay` are not in the documented endpoint whitelists. + CLI 0.8.0's image validator currently passes these template strings through + without checking those whitelists; local acceptance is not server support. + Do not recommend them as supported templates or claim a local rejection. + - `-p t_pose=true` and `-p sketch_to_render=true` are raw parameters, not verified + template shortcuts. The CLI does not normalize these booleans into `template`. + Use `-p template=t_pose` for T-pose or a supported template/explicit prompt + for editing. `image-to-image` still requires `prompt` and/or `template`; + a boolean alone does not satisfy that command-level check. Text-to-image + requires a prompt. Negative prompts go inside `prompt` after `--no`. - **Image models** (`model`): `seedream_v4` (text-to-image default; **not accepted by image editing**), `seedream_v5` (editing default), Google Gemini as `banana` (= gemini-2.5-flash, fast), `banana_pro` (= gemini-3-pro, quality), `banana2` (= gemini-3.1-flash, latest fast) — MCP may take these `banana*` - names; the CLI takes either — and OpenAI `chat_image_2`, + names; the CLI accepts only `banana`, `banana_pro`, `banana2`, not Gemini display names — and OpenAI `chat_image_2`, `chat_image_2.5_flare` (faster), `chat_image_2.5_sunburst` (edits keep - untouched regions closer to the original). `chat_image_1` retires 2026-10-23 - and `chat_image_1.5` on 2026-12-01: pick `chat_image_2` or a 2.5 model. + untouched regions closer to the original). `chat_image_1` is retired (2026-10-23) + and `chat_image_1.5` retires on 2026-12-01: pick `chat_image_2` or a 2.5 model. GPT-image options: `quality` `low`/`medium`/`high` (`chat_image_2`; 2.5 also `xhigh`/`max`; omitted = `low`); `background` `auto`/`opaque`/`transparent` - (2.5 only; `transparent` needs `output_format=png`). The CLI still rejects - `texture_quality=fast` locally; MCP accepts `fast` only with texture model v3.5. + (2.5 only; `transparent` needs `output_format=png`). Both paths accept `fast` only with texture model v3.5. - **Several references** (`inputs`): seedream ≤4, gemini ≤10, chat_image ≤16; refer to them in the prompt as `[image 1]`, `[image 2]`. -- `size` `1K`/`2K`/`4K` or `WxH` (default 2048×2048; billed by tier); - `aspect_ratio` is honoured by the gemini (`banana*`) family only; `watermark` - by seedream only; `output_format` `png`/`jpeg`. +### Image size by model + +CLI 0.8.0 validates an explicitly supplied `size` per model: + +| model | accepted explicit size / CLI constraints | +| --- | --- | +| `banana` | Fixed pixel whitelist only: `1024x1024`, `832x1248`, `1248x832`, `864x1184`, `1184x864`, `896x1152`, `1152x896`, `768x1344`, `1344x768`, `1536x672` | +| `banana2` | Tiers only: `0.5K`, `1K`, `2K`, `4K`; no explicit pixels | +| `banana_pro` | `1K`, `2K`, `4K`, or positive-integer `WxH` | +| `seedream_v4` | `2K`, `4K`, or positive-integer `WxH` with width/height in [1/16, 16]; text-to-image only | +| `seedream_v5` | `2K`, `3K`, or positive-integer `WxH` with width/height in [1/16, 16] | +| `chat_image_1.5` | `1024x1024`, `1024x1536`, `1536x1024`, `auto`; observe the retirement date above | +| `chat_image_2` | `auto` or positive-integer `WxH`: each edge ≤3840 and divisible by 16; long edge ≤3 × short edge; total pixels 655360–8294400 inclusive | +| `chat_image_2.5_flare` | `auto` or positive-integer `WxH`: each edge ≤3840 and divisible by 16; long edge ≤3 × short edge; total pixels 655360–8294400 inclusive | +| `chat_image_2.5_sunburst` | `auto` or positive-integer `WxH`: each edge ≤3840 and divisible by 16; long edge ≤3 × short edge; total pixels 655360–8294400 inclusive | + +Do not apply one size/default to every model. Omitted `size` is not filled by +this CLI validator. Official model-specific docs list Seedream defaults as +2048x2048, banana_pro/banana2 as 2K, chat_image_1.5 as auto, and chat_image_2/2.5 +as 2048x2048. For banana, omission behavior is unverified: the docs also print +2048x2048 as a default despite the fixed-size whitelist. Prefer an explicit +whitelisted size; do not turn that inconsistent default into a CLI argument. +Seedream exact pixel-count limits unverified: official ranges are rounded +(v4 approximately 3.69–16.78 MP; v5 approximately 3.69–10.40 MP). Do not invent +exact server pixel thresholds from those figures. CLI acceptance is not proof +of server acceptance; server validation still applies, including banana_pro +custom pixel sizes. Chat example: 1536x864 is valid, 1080x1920 is not divisible +by 16; use 1088x1920 instead. No 1K/2K/4K tiers for chat_image models. + +`aspect_ratio` is honoured by the banana family only; Seedream/chat use size. +`watermark` control is Seedream-only; `output_format` is `png`/`jpeg`. + +### Other image steps - `image-to-multiview` → a 4-view sheet (front/left/back/right); `edit-multiview` takes that task plus 1–4 `{view, prompt}` edits; either task feeds `tripo_multiview_to_3d` (`multiview_task_id`). @@ -128,11 +187,18 @@ image-to-multiview|edit-multiview|image-to-splat`. An image task_id is a valid ## Prices -Approximate list prices, so the cost can be quoted before a run (the -authoritative number is `credits_consumed` on the result; `balance` and -`credits_consumed` are decimals, not integers): +Historical examples only, not a current regional estimate. The effective region +and date of the retained numbers below have not been verified. +Numeric prices and add-ons anywhere in this file (including processing tables) +are historical illustrations, not a price quote or dry-run estimate. A current +estimate must name its source, region and date and match the exact model/options. +If current regional pricing cannot estimate the request, report **not_estimated** +(unestimated), not zero; disclose that uncertainty and obtain consent before +billing. Never infer a fixed P2/P1 ratio or fill a plan with these static numbers. +Afterwards use the usage ledger and task `credits_consumed` for actual spending; +`balance` and `credits_consumed` are decimals, not integers: -| operation | credits | +| operation (historical example only) | historical credits, not an estimate | | --- | --- | | text-to-3D, v3.1 | 10 bare / 20 textured | | image- or multiview-to-3D, v3.1 | 20 bare / 30 textured | @@ -141,11 +207,11 @@ authoritative number is `credits_consumed` on the result; `balance` and | add-ons per generation | `texture_quality=detailed` +10, `extreme` +20, `geometry_quality=detailed` +20, `quad` +5, `smart_low_poly` +10, `generate_parts` +20 | | texture step | 10 standard / 20 detailed / 30 extreme | | convert | 5, or 10 with any non-default option | -| decimate | 30 (v2.0) / 10 (v1.0) | +| decimate | 35 tri / 40 quad (v3.0; smart_uv included), 30 (v2.0), 10 (v1.0) | | segment / complete | 40 / 50 (`quick_cap` 30) | | smartsegment | 85 image / 55 model | | rig-check / rig / animate | free / 25 / 10 per clip | -| text-to-image, image editing | 5 (seedream, banana 1K, chat_image_1) – 20 (banana_pro 4K) by model and size tier | +| text-to-image, image editing | 5 (seedream, banana 1K) – 20 (banana_pro 4K) by model and size tier | | image-to-multiview / edit-multiview / image-to-splat | 10 / 5 per edited view / 30 | Credits are frozen at submission and released on failure, ban or cancellation — diff --git a/plugins/tripo-3d/skills/tripo-game-asset/SKILL.md b/plugins/tripo-3d/skills/tripo-game-asset/SKILL.md index 4f070060..69f2f1d7 100644 --- a/plugins/tripo-3d/skills/tripo-game-asset/SKILL.md +++ b/plugins/tripo-3d/skills/tripo-game-asset/SKILL.md @@ -5,6 +5,20 @@ description: Recipes for producing game-ready 3D assets with Tripo and wiring th # Game asset pipeline +## Client attribution + +Use `tripo-cli` 0.8.0 or later (`npx tripo-cli@0.8`, not npm latest). +Follow the main skill's version gate and account confirmation. +On every CLI command, including each command +in a pipeline and commands from references, set +`TRIPO_DISTRIBUTION_CHANNEL=zcode_plugin`. Set `TRIPO_CLIENT_APP=zcode` only +when running in ZCode; in the Claude compatibility host use `TRIPO_CLIENT_APP=claude`. +If the host is unknown, leave `TRIPO_CLIENT_APP` unset; never infer it from the +package name. Use a variable prefix in POSIX or set `$env:TRIPO_CLIENT_APP` and +`$env:TRIPO_DISTRIBUTION_CHANNEL` in the same PowerShell call. Never save these +values to an account profile. MCP sends only `X-Tripo-Distribution: zcode_plugin`; +its client info identifies the actual host. OAuth and region selection stay the same. + Recipes on top of the `tripo-3d` skill. Read that skill first — it explains how to pick the execution path (MCP tools vs `tripo-cli`), authorization, blocking behaviour, exit codes, and credit rules. @@ -13,8 +27,9 @@ The recipes below are written as CLI commands because game work happens in a project tree where a shell exists and assets should land next to the code. The same pipelines map onto the MCP tools when the user prefers them: `tripo_text_to_3d`/`tripo_image_to_3d` with `face_limit` for budgeted props, -`tripo_rig` (`spec: "mixamo"`) + `tripo_animate` for characters (humanoid rigs -take `preset:biped:*` clips, creature rigs the plain `preset:walk` family — the +`tripo_rig` (`spec: "mixamo"`) + `tripo_animate` for characters (v3.0/v2.5 biped rigs +take `preset:walk`, creature rigs their body-type clip such as +`preset:quadruped:walk`; explicit legacy v1.0 takes `preset:biped:*` — the `tripo_rig` result says which), `tripo_convert` for FBX/texture-size export, `tripo_decimate` per LOD level, and `tripo_upload_ticket` → `tripo_import_model` for a mesh the project already has — @@ -28,26 +43,29 @@ to their final location afterwards if the user named a specific path. ## Pick a budget first +Explicitly choose P2 for game/realtime topology; retain P1 for +lower cost and speed and v3.1 for film/render/print. Confirm the selected +model, texture options and estimated cost; re-confirm any paid model change. + | target | preset | what it does | | ----------------------------- | ------------------- | ----------------------------------------------------- | -| mobile, WebGL, many instances | `--for game-mobile` | P1 low-poly model, face_limit 15000, 2K textures, FBX | -| PC / console hero asset | `--for game-pc` | v3.1, detailed PBR | +| mobile, WebGL, many instances | `--for game-mobile` | add `--model tripo-p2`, face_limit 15000, 2K textures, FBX | +| PC / console hero asset | `--for game-pc` | add `--model tripo-p2`, detailed PBR | | animated character | `--for anim` | rig-check, then rig, then retarget | Two budget-related choices the presets do not make for you: - **Quads at low poly** — P1 rejects `quad`; use `--model tripo-p2` (wire - `P2-20260801`, **Preview**; face_limit 48–25000 quads, ~5× the P1 price, + `P2-20260801`; face_limit 48–25000 quads, price depends on input and texture options; confirm the estimate, output is FBX) or v3.1 with `-p smart_low_poly=true -p quad=true` (face_limit 500–10000). On MCP pass `model: "P2"` / `quad: true`. -- **v3.1 quality under a face cap** — any `face_limit` ≤ 20000 auto-selects P1, - so add `--model tripo-v3.1` (MCP `model: "v3.1"`) when the user wants v3.1 +- **v3.1 quality under a face cap** — explicitly add `--model tripo-v3.1` (MCP `model: "v3.1"`) when the user wants v3.1 geometry with a budget. Override the face budget when the project has a stricter one: ```bash -tripo make "a health potion bottle" --for game-mobile \ +tripo make "a health potion bottle" --for game-mobile --model tripo-p2 \ -p face_limit=3000 --then convert:format=FBX,texture_size=1024 \ -o ./Assets/Art/Props --json --yes ``` @@ -55,7 +73,7 @@ tripo make "a health potion bottle" --for game-mobile \ ## Props ```bash -tripo make "an ornate treasure chest, fantasy style" --for game-pc \ +tripo make "an ornate treasure chest, fantasy style" --for game-pc --model tripo-p2 \ -o ./assets/models --json --yes ``` @@ -66,7 +84,7 @@ genuinely large sets use `tripo batch run manifest.yaml`, which is resumable. ## LOD chain from one source ```bash -tripo make "a stone golem" --for game-pc --then decimate:5000 --json --yes +tripo make "a stone golem" --for game-pc --model tripo-p2 --then decimate:5000 --json --yes tripo make @last --then decimate:1500,convert:fbx --json --yes ``` @@ -81,8 +99,12 @@ to `decimate`. ## Characters with animation +CLI default: v3.0 (`v3.0-20260909`) with universal `preset:walk` clips. +Use explicit `rig-v2.5` for creature rigs; use explicit `rig-v1.0` only for +legacy biped clips (`preset:biped:*`). Match the preset family to the rig result. + ```bash -tripo make "a knight in full armor, T-pose, standing straight" --for anim --json --yes +tripo make "a knight in full armor, T-pose, standing straight" --for anim --model tripo-p2 --json --yes ``` `--for anim` runs `rig-check` first, which gates the chain: if the mesh is not @@ -91,7 +113,7 @@ riggable it stops before spending rigging credits. Explicit control over the rig and clips: ```bash -tripo make "a robot soldier, T-pose" --json --yes \ +tripo make "a robot soldier, T-pose" --model tripo-p2 --json --yes \ | tripo anim check --json \ | tripo anim rig --spec mixamo --out-format fbx --json \ | tripo anim retarget --animation preset:idle preset:walk preset:run --json @@ -120,3 +142,8 @@ After a successful run, `model_file` in the result JSON is the path to import. D integration work the user actually asked for — add the loader call, register the prefab, update the asset manifest — rather than stopping at "the file is generated". Check `preview.png` first so a wrong asset does not get wired in. + +Retopology: `tripo_decimate` with explicit `model: "v3.0", smart_uv: true` +combines retopology and UVs (35 tri / 40 quad credits). Standalone +`tripo_smart_uv` is a separate billed UV-layout task for inputs up to 80,000 +equivalent triangles; confirm the choice and cost. See the capability reference. From 797ae099544bb72d68467d5d7dbfc3200ed528f3 Mon Sep 17 00:00:00 2001 From: sunzhenqiang Date: Fri, 30 Oct 2026 17:02:20 +0800 Subject: [PATCH 2/8] refactor(tripo-3d): update documentation and clarify execution paths - Revised README and skill documentation to emphasize that the plugin operates solely through the Tripo MCP tools, eliminating any CLI path references. - Clarified the model selection process, establishing P2 as the default for game/realtime topology, with P1 only used when explicitly chosen by the user. - Updated hook rules to ensure PBR is off by default unless explicitly requested. - Enhanced capability reference and game asset recipes to align with the new execution path guidelines. --- plugins/tripo-3d/README.md | 34 +-- plugins/tripo-3d/README_CN.md | 22 +- plugins/tripo-3d/hooks/session-start.mjs | 8 +- plugins/tripo-3d/skills/tripo-3d/SKILL.md | 284 ++++-------------- .../skills/tripo-3d/references/capability.md | 227 +++++--------- .../tripo-3d/skills/tripo-game-asset/SKILL.md | 202 ++++++------- 6 files changed, 266 insertions(+), 511 deletions(-) diff --git a/plugins/tripo-3d/README.md b/plugins/tripo-3d/README.md index e5048f96..2441053f 100644 --- a/plugins/tripo-3d/README.md +++ b/plugins/tripo-3d/README.md @@ -4,18 +4,18 @@ ## 0.1.5 -Game/realtime recipes explicitly prefer **P2** (more credits than H/P1); **P1** -remains optional for lower cost and speed, and v3.1 for film/render/print. Rig defaults to v3.0, with +Game/realtime recipes explicitly prefer **P2** (more credits than H/P1), the +P-series default; **P1** is used only when the user names it or picks it for lower +cost and speed, and v3.1 for film/render/print. Rig defaults to v3.0, with animation presets selected from the upstream rig model. Retopology v3.0's `smart_uv` and standalone `tripo_smart_uv` are distinct billed workflows. Fast textures require v3.5; `chat_image_1` is retired. -The CLI path requires **0.8.0 or later**, run as `npx tripo-cli@0.8`; do not use -npm `latest`. Verify the version before executing; if unavailable, -stop rather than downgrade. A plan is not a price quote: cost is not estimated +The plugin runs through the Tripo MCP tools only — there is no CLI path, and +missing authorization is never a reason to switch to one. PBR stays off unless +you explicitly ask for it. A plan is not a price quote: cost is not estimated here, and uncertainty needs explicit consent. Never switch accounts silently. -MCP remains the default; missing authorization is not permission to use CLI. -The hook also enforces source attribution and explicit model/billing decisions. +The hook also enforces the PBR default and explicit model/billing decisions. The official Tripo plugin for ZCode. Generate textured 3D models from a text prompt or a reference image, with rigging, animation, retopology and format @@ -24,17 +24,16 @@ project. Built for games, film, AR and 3D printing. Connect your **China-mainland** Tripo account once in the browser (developers.tripo3d.com) — no API key pasting. This build's MCP endpoint is -China-only; overseas-site accounts need the overseas Tripo 3D plugin build, or -the CLI with `--region ov`. +China-only; overseas-site accounts need the overseas Tripo 3D plugin build. ## Components | Component | What it does | | --- | --- | -| Skill `tripo-3d` | Main workflow: execution-path selection, authorization guidance, MCP workflow, scenario → tool-chain mapping, input handling, credit rules; plus an explicitly selected `tripo-cli` path | +| Skill `tripo-3d` | Main workflow: tool check, authorization guidance, MCP workflow, scenario → tool-chain mapping, input handling, credit rules | | Skill `tripo-game-asset` | Game-asset recipes: budgeted low-poly props, LOD chains, rigged characters with locomotion clips, wiring into Unity/Unreal/Godot/Three.js | | MCP server `tripo` | Remote Streamable HTTP server `https://developers.tripo3d.com/mcp` (OAuth 2.1), including `tripo_plan`, generation, rigging, conversion and `tripo_smart_uv`; available tool schemas are authoritative | -| Hook `SessionStart` | Injects seven rules: async waiting, link expiry, credit confirmation, browser authorization, honest failures, source/version gates and explicit model/billing decisions | +| Hook `SessionStart` | Injects seven rules: async waiting, link expiry, credit confirmation, browser authorization, honest failures, PBR off by default and explicit model/billing decisions | ## Usage @@ -59,7 +58,7 @@ The Tripo MCP server needs a one-time authorization: (developers.tripo3d.com — +86 SMS sign-in, Alipay top-up). There is no region picker on this page. You can sign up on the spot; new accounts get free credits. An international-site account will not authorize against this - build — use the overseas plugin or `tripo-cli` with `--region ov`. + build — use the overseas plugin. 3. The page shows a one-time verification code and opens the Tripo console: sign in, type the code into **Verification code**, click **Authorize**. 4. ZCode reconnects and loads the tools automatically. To revoke access, @@ -79,12 +78,9 @@ The Tripo MCP server needs a one-time authorization: - **File writes**: only when you ask for the model on disk, the agent downloads it into your project with `curl`. The hook and the MCP server write nothing. -- **Command execution**: on the MCP path, shell commands run only to upload a - local image/model (the `curl` returned by `tripo_upload_ticket`) or to - download a result. The optional [tripo-cli](https://www.npmjs.com/package/tripo-cli) - path (MIT) runs as `npx tripo-cli@0.8`, minimum 0.8.0. It runs only after the user explicitly chooses CLI - and confirms the account, region and billing plan; check the actual version first. - If it is unavailable, stop. There is no automatic fallback from MCP +- **Command execution**: shell commands run only to upload a local image/model + (the `curl` returned by `tripo_upload_ticket`) or to download a result. The + plugin never installs or runs a command-line client, including after an MCP failure, missing authorization, batch work or a request to save files locally. - **Hook**: `hooks/session-start.mjs` needs `node` on PATH. It reads the event from stdin and prints a fixed text to stdout; no network, no file @@ -98,6 +94,6 @@ The Tripo MCP server needs a one-time authorization: - Plugin: MIT, by [VAST](https://www.tripo3d.ai). - Both skills are ported from Tripo's official Kimi / Codex plugins (also maintained by VAST, MIT). -- The MCP server and `tripo-cli` are official Tripo implementations; +- The MCP server is an official Tripo implementation; generated content is subject to the [Tripo API content policy](https://platform.tripo3d.ai/docs). diff --git a/plugins/tripo-3d/README_CN.md b/plugins/tripo-3d/README_CN.md index 09645e44..d87e1fdb 100644 --- a/plugins/tripo-3d/README_CN.md +++ b/plugins/tripo-3d/README_CN.md @@ -4,32 +4,30 @@ ## 0.1.5 -游戏/实时资产显式优先选择 **P2**(积分高于 H/P1);看重积分更低、速度更快时仍可选 **P1**, +游戏/实时资产显式优先选择 **P2**(积分高于 H/P1),使用 P 系列时默认 **P2**;**P1**(积分更低、速度更快)仅在用户明确指定或选择时使用, 影视/渲染/打印用 v3.1。绑骨默认 v3.0,动画预设须跟随上游 rig 模型。 重拓扑 v3.0 的 `smart_uv` 与独立 `tripo_smart_uv` 是不同计费流程。 fast 贴图需 v3.5;`chat_image_1` 已退役。 -CLI 最低 **0.8.0**,通过 `npx tripo-cli@0.8` 运行,不使用 npm `latest`;执行前 -检查实际版本,不满足则停止,不静默降级。计划不是报价,本文**费用未估算**, -计费前须说明不确定性并获得确认。禁止自动切换账号。MCP 是默认路径,未授权 -不构成使用 CLI 的许可。Hook 同步执行来源标记、版本门槛与选模/计费约束。 +插件只通过 Tripo MCP 工具执行,没有 CLI 路径;未授权也不会改走 CLI。PBR 默认关闭, +只有你明确要求时才开启。计划不是报价,本文**费用未估算**,计费前须说明不确定性并 +获得确认。禁止自动切换账号。Hook 同步执行 PBR 默认关闭与选模/计费约束。 Tripo 官方 ZCode 插件。用一句话或一张图生成带贴图的 3D 模型,支持骨骼绑定、动画、 减面和格式转换(GLB/FBX/OBJ/STL/USDZ/3MF),文件直接落到你的项目里。覆盖游戏、 影视、AR 和 3D 打印场景。 浏览器里授权一次**国内站** Tripo 账号即可使用(developers.tripo3d.com),无需复制 -API Key。本构建的 MCP 只对接国内站;海外站账号请安装海外版插件,或用 CLI -`--region ov`。 +API Key。本构建的 MCP 只对接国内站;海外站账号请安装海外版插件。 ## 包含的组件 | 组件 | 内容 | | --- | --- | -| Skill `tripo-3d` | 主流程:执行路径选择、授权引导、MCP 工作流、场景 → 工具链映射、输入处理、积分规则;以及需明确选择的 `tripo-cli` 路径 | +| Skill `tripo-3d` | 主流程:工具检查、授权引导、MCP 工作流、场景 → 工具链映射、输入处理、积分规则 | | Skill `tripo-game-asset` | 游戏资产配方:面数预算道具、LOD 链、绑骨角色与动画、接入 Unity/Unreal/Godot/Three.js | | MCP 服务器 `tripo` | 远程 Streamable HTTP server `https://developers.tripo3d.com/mcp`(OAuth 2.1),含计划、生成、绑骨、转换与独立 UV;以实际可见工具 schema 为准 | -| Hook `SessionStart` | 注入 7 条规则:异步等待、链接过期、计费确认、浏览器授权、如实报错、来源/版本门槛、显式选模与计费决策 | +| Hook `SessionStart` | 注入 7 条规则:异步等待、链接过期、计费确认、浏览器授权、如实报错、PBR 默认关闭、显式选模与计费决策 | ## 怎么用 @@ -48,7 +46,7 @@ API Key。本构建的 MCP 只对接国内站;海外站账号请安装海外 首次使用时 Tripo 的 MCP 服务器需要授权: 1. 打开 **设置 → MCP**,在「Plugin MCP 服务器」分组找到 Tripo 一行(显示「需要授权」),点 **打开授权**。 -2. 系统浏览器打开的授权页对接**国内站**控制台(developers.tripo3d.com,+86 短信登录、支付宝充值),**没有选区步骤**。没有账号可以顺手注册,新账号有免费额度。海外站账号无法在此构建上授权——请改用海外版插件,或 CLI `--region ov`。 +2. 系统浏览器打开的授权页对接**国内站**控制台(developers.tripo3d.com,+86 短信登录、支付宝充值),**没有选区步骤**。没有账号可以顺手注册,新账号有免费额度。海外站账号无法在此构建上授权——请改用海外版插件。 3. 页面显示一次性验证码并跳转 Tripo 控制台:登录后把验证码填入 **Verification code**,点 **Authorize**。 4. ZCode 自动重连并加载工具。撤销授权:在 Tripo 控制台的 API Keys 页删除授权时选定的 Key。 @@ -57,7 +55,7 @@ API Key。本构建的 MCP 只对接国内站;海外站账号请安装海外 - **网络**:MCP 工具调用走 `https://developers.tripo3d.com/mcp`;授权页跳转到国内站 Tripo 控制台(developers.tripo3d.com)。生成结果通过 Tripo 的 CDN 短期链接(约 5 分钟过期)下载。 - **账号与计费**:所有生成任务消耗你自己 Tripo 账号的积分,每次工具返回 `credits_consumed`;失败任务自动退款。批量生成前 skill 会先用 `tripo_plan` 草稿、查余额并确认。 - **文件写入**:只在你要求把模型落到本地时,用 `curl` 把结果下载到项目目录;Hook 与 MCP 服务器本身不写任何文件。 -- **命令执行**:MCP 路径下仅在上传本地图片/模型(`tripo_upload_ticket` 返回的 curl)或下载结果时运行 shell 命令。可选 [tripo-cli](https://www.npmjs.com/package/tripo-cli) 路径(MIT)通过 `npx tripo-cli@0.8` 运行,最低 0.8.0。仅当用户明确选择 CLI 并确认账号、区域和计费计划后执行,先检查实际版本;不可用则停止。MCP 失败、未授权、批量或本地落盘需求均不自动切换 CLI。 +- **命令执行**:仅在上传本地图片/模型(`tripo_upload_ticket` 返回的 curl)或下载结果时运行 shell 命令。插件不会安装或调用任何命令行客户端,MCP 失败、未授权、批量或本地落盘需求也不例外。 - **Hook**:`hooks/session-start.mjs` 依赖 PATH 中的 `node`,只从 stdin 读取事件、向 stdout 输出一段固定文本,不访问网络、不读写文件。 - **不采集任何数据**:插件本体不含遥测;账号凭据由 ZCode 的凭据存储管理,不经过对话。 @@ -65,4 +63,4 @@ API Key。本构建的 MCP 只对接国内站;海外站账号请安装海外 - 插件本体:MIT,作者 [VAST](https://www.tripo3d.ai)。 - 两个 skill 由 Tripo 官方的 Kimi / Codex 插件(同为 VAST 维护,MIT)移植而来。 -- MCP 服务器与 `tripo-cli` 均为 Tripo 官方实现;生成内容遵循 [Tripo API 内容策略](https://platform.tripo3d.ai/docs)。 +- MCP 服务器为 Tripo 官方实现;生成内容遵循 [Tripo API 内容策略](https://platform.tripo3d.ai/docs)。 diff --git a/plugins/tripo-3d/hooks/session-start.mjs b/plugins/tripo-3d/hooks/session-start.mjs index 691669e1..f0fd9602 100644 --- a/plugins/tripo-3d/hooks/session-start.mjs +++ b/plugins/tripo-3d/hooks/session-start.mjs @@ -7,10 +7,10 @@ const RULES = `Tripo 3D — rules that apply whenever Tripo tools (tripo_*) are 1. Generation is asynchronous. Every tripo_* generation or processing tool returns a task_id immediately. Call tripo_task_wait with it and keep calling while status is queued/running — each call returns within about 55 seconds, a generation usually takes 1–4 minutes. Never present a result before status is success, and never treat a task_id as a finished model. 2. Show the result, then the link. On success, embed preview_image_url as a markdown image and give model_url as the download link. Both URLs expire in about 5 minutes: never re-print an old one — call tripo_task_status for fresh links. If you saved the file locally, give its path as plain text in backticks, never as a clickable link (chat previews cannot render meshes). 3. Credits belong to the user. Call tripo_plan and get confirmation before any billed generation or chain. Every billed tool reports credits_consumed. Check tripo_balance and confirm before generating more than one asset in a batch; on insufficient balance give the returned plans_url instead of retrying. Never silently re-roll a disappointing result — show the preview and ask first. -4. Authorization is a browser flow, never a pasted key. This build's MCP is China-mainland only (developers.tripo3d.com/mcp); the auth page has no region picker. If Tripo tools are missing or a call reports an authorization error, tell the user to open ZCode 设置 → MCP, find the Tripo server under「Plugin MCP 服务器」and click「打开授权」, then sign in on the 国内站 console and Authorize. An overseas-site account needs the overseas plugin build or CLI login --region ov. Do not ask for an API key in the chat, and do not run tripo-cli instead just because a local login or TRIPO_API_KEY exists — offer the CLI only as an explicit alternative and use it only if the user picks it. -5. Failures are reported, not hidden. On failed/banned, relay failure_reason (and error_code) honestly; failed-task credits are refunded automatically. Never invent parameters — the tool schemas are authoritative. Stylize has been retired: there is no tripo_stylize and no CLI --then stylize. Use tripo_mesh_edit for P2 regional redo. -6. Keep source tags on every CLI invocation (CLI >= 0.8.0, run as npx tripo-cli@0.8), including each pipeline stage. Verify the installed version; ask before installing, and stop if unavailable. Never silently downgrade or change accounts. Set TRIPO_DISTRIBUTION_CHANNEL=zcode_plugin and TRIPO_CLIENT_APP=zcode in ZCode, or TRIPO_CLIENT_APP=claude in the Claude compatibility host; leave the client unset when the host is unknown. Prefix each POSIX command or set the variables in the same PowerShell call. Never save them to a profile. MCP sends the distribution header and uses client info for the actual host. -7. Choose models explicitly: P2 is preferred for game/realtime topology and costs more credits than H/P1; P1 remains optional for lower cost and speed, v3.1 for film/render/print. Do not infer the model from face_limit. Cost is not estimated by this text or guaranteed by tripo_plan: disclose uncertainty and obtain consent before billing. Rig defaults to v3.0; use preset:walk, reserving preset:biped:* for explicit v1.0 rigs. Retopology v3.0 with smart_uv and standalone tripo_smart_uv are separate workflows, not interchangeable free export switches. Load the capability reference before running either. chat_image_1 is retired; never fall back to it. fast textures require v3.5-20260815. +4. Authorization is a browser flow, never a pasted key. This build's MCP is China-mainland only (developers.tripo3d.com/mcp); the auth page has no region picker. If Tripo tools are missing or a call reports an authorization error, tell the user to open ZCode 设置 → MCP, find the Tripo server under「Plugin MCP 服务器」and click「打开授权」, then sign in on the 国内站 console and Authorize. An overseas-site account needs the overseas plugin build. Do not ask for an API key in the chat. MCP is the only execution path: never install or run a command-line client instead, even when a local login or API key exists. +5. Failures are reported, not hidden. On failed/banned, relay failure_reason (and error_code) honestly; failed-task credits are refunded automatically. Never invent parameters — the tool schemas are authoritative. Stylize has been retired: there is no tripo_stylize tool. Use tripo_mesh_edit for P2 regional redo. +6. PBR is opt-in. Send pbr: false on every generation and tripo_texture call unless the user explicitly asks for PBR (e.g. "with PBR", 「PBR 材质」); only then send pbr: true, which also forces texture: true. The API turns PBR on when pbr is omitted, so never leave it out. Detailed or high-quality textures do not mean PBR. +7. Choose models explicitly: P2 is preferred for game/realtime topology and costs more credits than H/P1; within the P series the default is P2, and P1 is used only when the user names it or picks it for lower cost and speed; v3.1 for film/render/print. Do not infer the model from face_limit. Cost is not estimated by this text or guaranteed by tripo_plan: disclose uncertainty and obtain consent before billing. Rig defaults to v3.0; use preset:walk, reserving preset:biped:* for explicit v1.0 rigs. Retopology v3.0 with smart_uv and standalone tripo_smart_uv are separate workflows, not interchangeable free export switches. Load the capability reference before running either. chat_image_1 is retired; never fall back to it. fast textures require v3.5-20260815. `; let raw = ""; diff --git a/plugins/tripo-3d/skills/tripo-3d/SKILL.md b/plugins/tripo-3d/skills/tripo-3d/SKILL.md index ca41acd1..af42f2a3 100644 --- a/plugins/tripo-3d/skills/tripo-3d/SKILL.md +++ b/plugins/tripo-3d/skills/tripo-3d/SKILL.md @@ -5,58 +5,30 @@ description: Generate a 3D model from a text prompt, a reference image, or an ex # Tripo 3D -## Client attribution - -Use `tripo-cli` 0.8.0 or later, pinned as `npx tripo-cli@0.8`. Check the -version before using these contracts; if it is missing or older, ask before -installing it or offer the authorized MCP path, never -silently downgrade or switch accounts. The cost is not estimated by this document: -show a live estimate if available, otherwise disclose that uncertainty and obtain -explicit consent before any billed task. A plan is not a quote. -On every CLI command, including each command -in a pipeline and commands from references, set -`TRIPO_DISTRIBUTION_CHANNEL=zcode_plugin`. Set `TRIPO_CLIENT_APP=zcode` only -when running in ZCode; in the Claude compatibility host use `TRIPO_CLIENT_APP=claude`. -If the host is unknown, leave `TRIPO_CLIENT_APP` unset; never infer it from the -package name. Use a variable prefix in POSIX or set `$env:TRIPO_CLIENT_APP` and -`$env:TRIPO_DISTRIBUTION_CHANNEL` in the same PowerShell call. Never save these -values to an account profile. MCP sends only `X-Tripo-Distribution: zcode_plugin`; -its client info identifies the actual host. OAuth and region selection stay the same. - -Generate engine-ready 3D assets with Tripo. Two execution paths exist; pick one -before doing anything else, and never pretend to run what this environment -cannot run. - -## Pick the execution path - -1. **MCP path** — the tool list contains Tripo tools (`tripo_text_to_3d`, - `tripo_task_wait`, ...; ZCode prefixes them with the MCP server id, e.g. - `mcp__…__tripo_text_to_3d` — the rest of this skill uses the bare names). - This is the default path. -2. **Tripo tools missing** — the plugin's MCP server is almost always waiting - for authorization or switched off, not absent. Stop and tell the user first: - open **设置 → MCP**, find the Tripo server under 「Plugin MCP 服务器」, - click **打开授权** if the row says 「需要授权」 (or enable it), then start a - new session. See Authorization below. **Do not switch to `tripo-cli` - instead** — not for a balance check, not because a local `tripo login` - or `TRIPO_API_KEY` happens to exist (that may be a different account, and - the user installed this plugin to use MCP). Offer the CLI only as an - explicit alternative in the same message, and take it only if the user - picks it. -3. **CLI path** — the user explicitly asked for the CLI, or the Tripo MCP - tools are present but the job needs what only a shell gives: bulk - generation (`tripo batch`) or artifacts written straight into the project - tree without a download step. Drive `tripo-cli` as described in the second - half of this skill. -4. **Neither** — stop here and say so; do not describe generations as if - they had run. - -Local *files* do not require the CLI — MCP's `tripo_upload_ticket` covers both -images and mesh files (see Inputs below). - ---- - -# MCP path +Generate engine-ready 3D assets with the Tripo MCP tools. +The cost is not estimated by this document: show a live estimate if available, +otherwise disclose that uncertainty and obtain explicit consent before any +billed task. A plan is not a quote. + +## Before you start + +The tool list must contain the Tripo tools (`tripo_text_to_3d`, +`tripo_task_wait`, ...; ZCode prefixes them with the MCP server id, e.g. +`mcp__…__tripo_text_to_3d` — the rest of this skill uses the bare names). + +If they are missing, the plugin's MCP server is almost always waiting for +authorization or switched off, not absent. Stop and tell the user: open +**设置 → MCP**, find the Tripo server under 「Plugin MCP 服务器」, click +**打开授权** if the row says 「需要授权」 (or enable it), then start a new +session. See Authorization below. Do not describe generations as if they had +run. + +MCP is the only execution path. Never install or run a command-line client +instead — not for a balance check, not because a local login or +`TRIPO_API_KEY` happens to exist (that may be a different account, and the +user installed this plugin to use MCP). Local files and bulk jobs stay on MCP +too: `tripo_upload_ticket` covers both images and mesh files (see Inputs +below), and results are downloaded with `curl` (see Deliver). ## Authorization @@ -70,8 +42,7 @@ for an API key in the chat. offer a region picker — it always opens the **国内站** console (developers.tripo3d.com, +86 SMS sign-in, Alipay top-up). An overseas-site account (developers.tripo3d.ai) will not work here: tell the user to install -the overseas Tripo 3D plugin build, or use the CLI path with -`login --region ov`. +the overseas Tripo 3D plugin build. 1. **设置 → MCP** → group 「Plugin MCP 服务器」 → the Tripo row shows 「需要授权」 → click **打开授权**. The system browser opens the Tripo @@ -87,8 +58,8 @@ Generations spend credits from the account the user connected. The connection is bound to the API key the user picked on the Tripo console during authorization (an account with no key gets `cli-default` created automatically; with exactly one key it is used as is). To revoke access, delete that key on -the console's API Keys page — any other client sharing it (e.g. `tripo-cli`) -loses access too. +the console's API Keys page — any other client sharing that key loses access +too. ## Workflow @@ -132,15 +103,19 @@ loses access too. original textures); `tripo_segment` → `tripo_mesh_complete` — split into parts and close the cuts; `tripo_mesh_edit` — redo one region of an existing mesh with P2 (`bbox` required). Stylize (lego / voxel / - voronoi / minecraft) has been retired — there is no `tripo_stylize` tool - and no CLI `--then stylize` step. + voronoi / minecraft) has been retired — there is no `tripo_stylize` tool. 6. **Deliver** — result URLs (`model_url`, `preview_image_url`) **expire in about 5 minutes**; never cache or re-print an old one — call `tripo_task_status` for fresh links. Download the file into the project (`curl -L -o ""`) and give the local path as plain text in backticks — never as a clickable link, the chat preview cannot render - meshes. Only when no shell is available give the fresh link and say it is - short-lived, offering to refresh it on request. + meshes; offer the next real action: reveal it in the file manager + (`open -R ` on macOS, `explorer /select,` on Windows) or wire it + into the project. Only when no shell is available give the fresh link and + say it is short-lived, offering to refresh it on request. After a + `tripo_convert`, the native GLB and its preview stay on the earlier task — + fetch them with `tripo_task_status` on that task instead of paying for + another conversion. ## Scenario → tool chain @@ -152,7 +127,7 @@ step is only worth its credits when the target really needs another format. explicit `model: "P2"` and a confirmed `face_limit` → `tripo_convert` `format: "FBX"` (`texture_size: 2048`) for Unity/Unreal; Three.js/Godot take the GLB as is. -- **Game hero asset, PC / console** — explicit `model: "P2"`, `pbr: true`, +- **Game hero asset, PC / console** — explicit `model: "P2"`, `texture_quality: "detailed"` → FBX only if the engine needs it. - **Film / render / close-ups** — `v3.1` with `geometry_quality: "detailed"` and `texture_quality: "detailed"` (both cost extra credits). @@ -184,9 +159,20 @@ step is only worth its credits when the target really needs another format. ## Parameters that matter - **Choose the generation model explicitly**: P2 for game/realtime topology - (costs more credits than H/P1); P1 remains optional for lower cost and speed. Use v3.1 + (costs more credits than H/P1); within the P series the default is P2, and P1 is + used only when the user names it or picks it for lower cost and speed. Use v3.1 for film/render/print. This is plugin policy, not an API requirement. Confirm the model, texture options and cost; re-confirm any paid model change. +- **PBR is opt-in.** Send `pbr: false` on every generation and `tripo_texture` + call unless the user explicitly asks for PBR materials (for example "with + PBR" or 「PBR 材质」); only then send `pbr: true`, which also forces + `texture: true`. The API turns PBR on when `pbr` is left out, so never omit + it. Detailed or high-quality textures do not mean PBR. PBR can still be added + later: when the user asks for it after a model is already generated, do not + regenerate. Call `tripo_texture` with that task as `input` and `pbr: true`: it + bills only the texture step, not the generation again, and keeps the geometry, + but the textures are regenerated, so pass the original reference image again if + there was one. Confirm that cost like any other paid step. - 3D printing / untextured output: `texture: false, pbr: false` skips texture credits entirely; convert to `STL` (add `flatten_bottom: true` for stability). - `quad: true` (v3.1 or P2) needs a `tripo_convert` to FBX/OBJ/USDZ at the end; @@ -203,12 +189,14 @@ step is only worth its credits when the target really needs another format. known — ask for the path if only the picture is visible) goes through `tripo_upload_ticket`: run the `how_to` curl it returns in the shell (`curl -sS -X POST --data-binary @ -H "Content-Type: application/octet-stream" ""`) - and read `file_token` from the JSON response — no CLI login involved. + and read `file_token` from the JSON response. - Model files (GLB/FBX/OBJ/STL, ≤150 MB) use the same ticket with `kind: "model"` and `format`; the `file_token` then feeds `tripo_import_model` or any processing tool directly. - Task ids chain: a successful generation task is a valid `input` for every - processing tool, so never re-upload what Tripo already has. + processing tool, so never re-upload what Tripo already has. A task id only + resolves under the API key that created it; when an older task is not found, + upload the local model file instead. ## Other tools @@ -222,172 +210,22 @@ step is only worth its credits when the target really needs another format. ## Spending the user's credits -- `tripo_balance` first when the user asks for several assets; confirm before - generating more than one in a batch, and report `credits_consumed` after. +- `tripo_balance` first when the user asks for several assets; confirm the + whole batch and its cost once before generating more than one, then call the + tools one asset at a time, and report `credits_consumed` after. +- When a create call reports a full concurrency pool or a rate limit, wait for + running tasks to finish and retry with backoff instead of resubmitting in a + loop. - Insufficient balance errors: give the `plans_url` from `tripo_balance` (informational pricing page for this deployment's region) instead of retrying. ---- - -# CLI path - -Everything below runs through the shell. One command turns a prompt or an -image into local files: a model, a `preview.png` render, and a `task.json` -record. - -## Before the first generation - -```bash -npx tripo-cli@0.8 doctor # verifies key, network, region, balance -``` - -Auth resolves from `TRIPO_API_KEY` (a `tsk_...` key) or a previous `tripo login`. -If `doctor` reports no key, start the device login yourself — do not ask for -permission first, and never ask the user to paste a key into the chat. - -Tripo has two regions with separate accounts and consoles: - -| region | console | sign-in / top-up | -| --------------------- | ------------------------------ | ------------------------------ | -| `cn` — China mainland | https://developers.tripo3d.com | +86 SMS sign-in, Alipay top-up | -| `ov` — International | https://developers.tripo3d.ai | email sign-in, Stripe top-up | - -Pick the region yourself only when the context already says which site the -user's account is on — they mentioned it, `tripo whoami` shows a profile, or -`TRIPO_REGION` is set. Otherwise ask one question before starting the login: -"你的 Tripo 账号在国内站还是海外站?" An account lives in exactly one region, -and starting the device flow on the wrong console sends the user to a site -where their account does not exist. No account yet? China-mainland users -should pick `cn` (Alipay top-up), everyone else `ov` — signing up during the -login flow is fine and new accounts get free credits. - -```bash -npx tripo-cli@0.8 login --region cn --yes # or: --region ov -``` - -`--yes` forces the non-interactive device flow. The command prints a -verification URL and a one-time code right away, then blocks until the user -approves in a browser — up to 15 minutes. Do not kill it early, and do not -wait for it to exit before talking to the user: read the URL and code from -its output while it is still running (run it in the background or stream its -stderr). **Show the user the full verification URL and the code verbatim**, -plus the matching console address (`cn`: https://developers.tripo3d.com, -`ov`: https://developers.tripo3d.ai), and walk them through every step — -assume they have never seen this page: - -1. Open the verification URL in a browser. -2. If the page asks to sign in, they are not logged in on the web either: - sign in — or sign up at the console address above; new accounts get - free credits — then return to the verification page. -3. Type the one-time code into the **"Verification code"** field. -4. An account that already has several API keys is asked to pick one — any - of them works, the CLI will use the chosen key. With no keys, one is - created automatically and there is nothing to choose. -5. Click the **Authorize** button. The key arrives in the CLI and is stored — - nothing to copy by hand. - -When the command exits 0, re-run `doctor` and continue. Exit code 3 means the -code expired or was denied — run the same login command again for a fresh -code. If an older CLI rejects headless login with a usage error, fall back to -asking the user to run `npx tripo-cli@0.8 login` in their own terminal. - -Installing globally (`npm install -g tripo-cli@0.8`) makes repeated calls faster and -is what makes the bare `tripo` command exist — ask before doing it. Without a -global install, run every `tripo ...` command in this and related skills as -`npx tripo-cli@0.8 ...`; npx downloads the CLI on first use, so a fresh machine -needs no manual install. If `npx` itself is missing, Node.js is not installed — -have the user install Node.js LTS first. On China-mainland networks, when the -npx download stalls, switch to the npmmirror registry and retry: -`npm config set registry https://registry.npmmirror.com`. - -Exit code 3 means auth failed; run `tripo doctor`, which diagnoses key-vs-region -mismatches (`ov` = international, `cn` = China mainland) and prints the exact fix. - -## The command - -```bash -tripo make "a stylized treasure chest" --for game-mobile --json --yes -tripo make concept.png --for game-pc --json --yes -tripo make front.png back.png --json --yes # 2-4 images -> multiview -tripo make hero.glb --then texture,rig --json --yes # import an existing mesh -tripo make @last --then convert:fbx --json --yes # continue from the last task -``` - -Input type is auto-detected: quoted text, an image path or URL, 2-4 images, a model -file, or a task reference (`@last`, `@name`, a task id). - -A local image file is uploaded by the CLI itself — always reliable. An image -URL is passed straight to the API and **fetched by Tripo's servers**, so when -the user gives a URL, tell them explicitly: it must be publicly reachable and -served through a CDN or globally accelerated host, or the server-side fetch -can fail or time out (auth-protected, region-locked and slow-origin links all -break). When in doubt, download the image locally first and pass the file -path instead. - -- `--for ` picks model, parameters, chain and export format: - `game-mobile` `game-pc` `film` `print` `ar-web` `anim` `toy`. - The base generation already outputs GLB; some preset chains append a **paid** - convert step (`game-mobile`/`game-pc` → FBX, `print` → STL, `ar-web` → USDZ). - When the user only wants GLB, that convert buys a format nobody asked for — - use a chain-free preset instead (`toy` for low-poly, with `-p face_limit=...`) - or tell the user the extra format costs credits before running. -- `--then ` overrides the chain. Steps: `texture` `convert` - `import` `rig-check` `rig` `retarget` `segment` `complete` `decimate` `smartsegment` `uv`. - Arguments use `step:key=value`; a bare value maps to the step's primary argument - (`convert:fbx`, `decimate:5000`). -- `-o, --out ` sets the **parent** directory, not the artifact directory. `make` - always creates `/tripo-out/-/` underneath it, so `-o ./assets` writes - `./assets/tripo-out/-/model.glb`. Pass `-o` to keep artifacts inside the - project instead of the shell's working directory, but when the user asked for a file - at a specific path, **move it there after the run and report the final path** — `-o` - alone cannot put it there. (`tripo task get --download -o ` is the - exception: its `-o` is the final directory.) -- `-p key=value` passes an API parameter, repeatable. Useful ones: `face_limit=15000`, - `texture=false pbr=false` (bare geometry, skips texture credits), `auto_size=true`, - `texture_quality=detailed`, `negative_prompt=...`. `--model` forces the generation - model (`tripo-v3.1` / `tripo-p1` / `tripo-p2` → wire `v3.1-20260211` / - `P1-20260311` / `P2-20260801`). `--dry-run` plans and validates with zero network - calls (no credits, no key) and prints the chosen wire-value `model`, - `steps[].payload`, `warnings` and `errors`; only run for real when `valid` is true. - After a chained run, report `credits_consumed` (total) and `credits_breakdown` - (per task); if the field is missing, `tripo task get --json` each chain entry. - -## Rules that matter - -1. **`tripo make` is blocking.** It submits, polls, downloads, then exits. Wait for - the process to finish. Do not re-implement polling, do not set a timeout shorter - than the CLI's own (default 1800s), and do not treat a `task_id` appearing in the - logs as completion. -2. **stdout is the contract.** With `--json`, stdout carries exactly one final JSON - line; progress goes to stderr. Parse the last stdout line, not the logs. -3. **Branch on exit codes**, don't parse error text: - `0` ok · `1` fatal, and what `doctor` returns when a critical check fails · - `2` bad parameters · `3` auth · `4` insufficient credits · `5` content - policy · `6` task failed (credits auto-refunded, `tripo redo` often succeeds) · - `7` network · `8` not found — a task id only resolves under the key that created - it, so when an older task 404s, fall back to passing the local model file · - `9` rate limit (retry with backoff). -4. **Judge the result before moving on.** The result JSON gives `model_file` and - `preview`. Read `preview.png` to check the asset actually matches the request; if - it does not, `tripo redo` re-rolls with a new seed. -5. **Never invent parameters.** Run `tripo docs --topic commands/make` for the full - flag list, or `tripo docs --topic common-errors` for the error table. -6. **Pass `--model` explicitly.** Prefer `tripo-p2` for game/realtime - topology, retain `tripo-p1` for lower cost and speed, and `tripo-v3.1` for film/render/print. - Confirm cost before execution; presets are not a substitute for this choice. - -Download URLs returned by the API expire in about five minutes — never cache one. -Re-run `tripo task get --download` instead. - - --- # Capability reference -Model versions, generation/processing parameters, 2D steps, list prices, CLI -result shape and other commands: read [`references/capability.md`](references/capability.md) -(same parameter names on MCP and CLI). MCP also has `tripo_plan` (confirm before -spend) and `tripo_mesh_edit` (P2 regional redo). +Model versions, generation/processing parameters, 2D steps and list prices: +read [`references/capability.md`](references/capability.md). `tripo_plan` +confirms before spend and `tripo_mesh_edit` redoes a P2 region. Retopology: `tripo_decimate` with explicit `model: "v3.0", smart_uv: true` combines retopology and UVs (35 tri / 40 quad credits). Standalone diff --git a/plugins/tripo-3d/skills/tripo-3d/references/capability.md b/plugins/tripo-3d/skills/tripo-3d/references/capability.md index aad7e28b..a09d4697 100644 --- a/plugins/tripo-3d/skills/tripo-3d/references/capability.md +++ b/plugins/tripo-3d/skills/tripo-3d/references/capability.md @@ -1,73 +1,68 @@ -# Capability reference (both paths) +# Capability reference Mirrors the official API docs so the agent never has to send the user there. -Parameter names are identical on both paths: pass them as MCP tool arguments, -or as `-p key=value` (generation) / `step:key=value` (`--then`) on the CLI. -Both paths auto-fix the linkage rules below (pbr→texture, model-specific -strips, quad→FBX) and report what they changed (`notes` / warnings). +Pass these parameters as MCP tool arguments. The tools auto-fix the linkage +rules below (pbr→texture, model-specific strips, quad→FBX) and report what they +changed in `notes`. ## Models -| model | MCP `model` / CLI `--model` | use for | limits | +| model | MCP `model` | use for | limits | | --- | --- | --- | --- | -| **v3.1** (default) | `v3.1` / `tripo-v3.1` | high fidelity: film, render, print | full parameter set | -| **P1** | `P1` / `tripo-p1` | optional low-poly for lower cost and speed | `face_limit` 50–20000; no `quad`, `smart_low_poly`, `generate_parts`, `geometry_quality`; adds `export_uv` | -| **P2** | `P2` / `tripo-p2` → wire `P2-20260801` | preferred for game/realtime topology, with explicit user confirmation | `face_limit` 48–50000 tri / 48–25000 quad; supports `quad`, still no `smart_low_poly`, `generate_parts`, `geometry_quality`; costs more credits than H/P1, and price depends on input and texture options; confirm the estimate. Pass the generation model explicitly | -| v3.0, v2.5 | `v3.0` / `tripo-v3.0`, `v2.5` / `tripo-v2.5` | legacy, only when the user asks | v2.5 has no `geometry_quality` | +| **v3.1** (default) | `v3.1` | high fidelity: film, render, print | full parameter set | +| **P1** | `P1` | P series alternative, only when the user names it or picks it for lower cost and speed | `face_limit` 50–20000; no `quad`, `smart_low_poly`, `generate_parts`, `geometry_quality`; adds `export_uv` | +| **P2** | `P2` → wire `P2-20260801` | default P-series model, preferred for game/realtime topology, with explicit user confirmation | `face_limit` 48–50000 tri / 48–25000 quad; supports `quad`, still no `smart_low_poly`, `generate_parts`, `geometry_quality`; costs more credits than H/P1, and price depends on input and texture options; confirm the estimate. Pass the generation model explicitly | +| v3.0, v2.5 | `v3.0`, `v2.5` | legacy, only when the user asks | v2.5 has no `geometry_quality` | Website model names map to these rows: H3.1 → `v3.1`, P1.0 → `P1`, P2.0 → `P2`. -Selection policy: explicitly choose P2 for game/realtime topology; -keep P1 available for lower cost and speed and v3.1 for film/render/print. +Selection policy: explicitly choose P2 for game/realtime topology; within the +P series the default is P2, and P1 is used only when the user names it or picks +it for lower cost and speed; v3.1 for film/render/print. This is plugin guidance, not an API requirement. Do not rely on implicit routing or infer a generation model from face_limit. Confirm the model, texture options and estimated cost before a billed call; re-confirm any paid model change. -CLI generation aliases resolve to dated wire values (P2-20260801, v3.1-20260211). +Short names resolve to dated wire values (P2-20260801, v3.1-20260211). `tripo-turbo` and `tripo-v2.0` appear in older docs but the server rejects them. ## Generation parameters -Apply to `tripo_text_to_3d` / `tripo_image_to_3d` / `tripo_multiview_to_3d` -and to `tripo make` / `tripo generate *-to-model`. +Apply to `tripo_text_to_3d` / `tripo_image_to_3d` / `tripo_multiview_to_3d`. | param | default | notes | | --- | --- | --- | | `prompt`, `negative_prompt` | – | text input only; ≤1024 / ≤255 chars | | `face_limit` | adaptive | upper bound on triangles. v3.1 any; P1 50–20000; P2 48–50000 | -| `texture`, `pbr` | `true`, `true` | `pbr=true` forces `texture=true`. `texture=false pbr=false` = bare geometry, no texture credits | -| `texture_quality` | `standard` | `standard` / `detailed` (HD, +10 credits) / `extreme` (8K, +20). API also has `fast` (v3.5 textures only; same price/size as `standard`); CLI 0.8.0 accepts it with `texture_version=v3.5-20260815`; other texture versions are incompatible | -| `texture_version` | derived from `model` | pins the texture model independently of geometry: `v3.5-20260815` (newest), `v3.0-20250812` (default for v3.x and P-series), `v2.5-20250123` (default for v2.5). All generation models incl. P1/P2 | -| `delight` | `true` | v3.5 textures only (`texture_version=v3.5-20260815`): remove baked-in lighting from the reference image; `false` keeps original shading. Older texture versions ignore it | +| `texture`, `pbr` | `true`, see notes | **send `pbr: false` unless the user explicitly asks for PBR** (the API itself defaults it to true); `pbr: true` forces `texture: true`. `texture: false, pbr: false` = bare geometry, no texture credits | +| `texture_quality` | `standard` | `standard` / `detailed` (HD, +10 credits) / `extreme` (8K, +20). API also has `fast` (v3.5 textures only; same price/size as `standard`): it needs `texture_version: "v3.5"` (`v3.5-20260815`), which the tool picks when `texture_version` is omitted; other texture versions are incompatible | +| `texture_version` | derived from `model` | pins the texture model independently of geometry: `v3.5` (`v3.5-20260815`, newest), `v3.0` (`v3.0-20250812`, default for v3.x and P-series), `v2.5` (`v2.5-20250123`, default for v2.5). Pass the short name. All generation models incl. P1/P2 | +| `delight` | `true` | v3.5 textures only (`texture_version: "v3.5"`): remove baked-in lighting from the reference image; `false` keeps original shading. Older texture versions ignore it | | `geometry_quality` | `standard` | `detailed` = Ultra geometry, finer detail up to 2M faces (+20). v3.x only | | `quad` | `false` | quad mesh (+5); **delivered as FBX** — quads cannot be stored in GLB. v3.x and P2 | | `smart_low_poly` | `false` | hand-modelled-style low-poly topology (+10); requires `face_limit` 500–20000 tri / 500–10000 quad. v3.x only | -| `generate_parts` | `false` | editable segmented parts (+20). Requires `texture=false pbr=false` (both paths flip them and warn — re-texture afterwards with `tripo_texture` / `--then texture`); `quad` is ignored; `smart_low_poly` wins and suppresses parts. v3.x only | +| `generate_parts` | `false` | editable segmented parts (+20). Requires `texture: false, pbr: false` (the tool flips them and notes it — re-texture afterwards with `tripo_texture`); `quad` is ignored; `smart_low_poly` wins and suppresses parts. v3.x only | | `auto_size` | `false` | scale the model to real-world metres (AR, engines) | | `compress` | – | `geometry` = meshopt-compressed output. v3.x only | -| `model_seed`, `texture_seed`, `image_seed` | random | reproducibility: same seed → same geometry / textures / text-to-image stage. Keep `model_seed`, vary `texture_seed` to re-texture the same shape. CLI `--seed` sets `model_seed` | +| `model_seed`, `texture_seed`, `image_seed` | random | reproducibility: same seed → same geometry / textures / text-to-image stage. Keep `model_seed`, vary `texture_seed` to re-texture the same shape | | `enable_image_autofix` | `false` | image input: repair a low-quality / blurry / cropped photo first (slower) | | `texture_alignment` | `original_image` | image/multiview: `original_image` matches the picture, `geometry` matches the mesh | | `orientation` | `default` | image/multiview: `align_image` faces the model like the input viewpoint | | `export_uv` | `true` | P series only: `false` skips UV unwrap (faster, smaller file; UVs are created when texturing) | -| `export_orientation` | `+x` | forward axis `+x` `-x` `+y` `-y`. **Generation only**: downstream steps (texture, rig, convert…) read the default orientation and return a wrongly oriented `success` with no error. When a chain follows, leave it unset and pass `export_orientation` to the final convert step instead | +| `export_orientation` | `+x` | forward axis `+x` `-x` `+y` `-y`. **Only for output that is not processed further**: downstream steps (texture, rig, convert…) read the default orientation and return a wrongly oriented `success` with no error. When a chain follows, leave it unset and pass `export_orientation` to the final `tripo_convert` instead | Multiview (2–4 images): `front` is mandatory and at least two views are needed; -`left`/`back`/`right` are optional. MCP takes them as named arguments (or +`left`/`back`/`right` are optional. Pass them as named arguments (or `multiview_task_id` for a finished `tripo_image_to_multiview` / -`tripo_edit_multiview` sheet); the CLI reads `front|back|left|right` from the -filenames, otherwise positional order front, left, back, right. +`tripo_edit_multiview` sheet). ## Retopology and UV workflows -CLI equivalents: `--then decimate:model=v3.0,face_limit=5000,smart_uv=true` -or `tripo mesh decimate --model v3.0 --face-limit 5000 --smart-uv`; -standalone `tripo mesh uv ` / `--then uv`. Run a dry-run and confirm cost first. - `tripo_decimate` defaults to v2.0. Explicit `model: "v3.0"` supports `smart_uv: true` in the same task: 35 credits triangle / 40 quad, versus 30 for v2.0; smart_uv adds no extra charge. Confirm this model/cost change -before submitting. v2.0/v3.0 targets: 500–20000 triangles or 500–10000 quads. +before submitting. With any other model, `smart_uv: true` is rejected and no +task is created. v2.0/v3.0 targets: 500–20000 triangles or 500–10000 quads. The face budget is a target, not a ceiling. The combined task has no UV preview. Standalone `tripo_smart_uv` is separately billed: re-unwrap UVs and remap existing @@ -80,29 +75,28 @@ paid task for integrated smart_uv without confirming the extra cost. ## Processing steps -Every step takes a model task_id, a `file_token` or a model URL as `input`, -except: `tripo_animate` / `retarget` (a successful rig task), `tripo_mesh_complete` -/ `complete` (a successful segment task) and `tripo_smart_segment` / -`smartsegment` (file_token or URL only, never a task_id). CLI `--then` maps a -bare value to the primary argument (`convert:fbx`, `decimate:5000`). +Every tool takes a model task_id, a `file_token` or a model URL as `input`, +except: `tripo_animate` (`task_id` of a successful rig task), +`tripo_mesh_complete` (`task_id` of a successful segment task) and +`tripo_smart_segment` (file_token or URL only, never a task_id). -| MCP tool / CLI step | arguments and constraints | +| MCP tool | arguments and constraints | | --- | --- | -| `tripo_texture` / `texture` | `texture_quality` `standard`/`detailed`/`extreme`/`fast` (fast requires v3.5); `pbr` (true); `texture_seed`; `texture_alignment`; `model` `v3.0` / `v3.0-20250812` (default) / `v3.5-20260815` (newest; unlocks `delight` and `texture_quality=fast` on MCP and CLI 0.8.0) / `v2.5`; `bake`; `part_names` (segmented models); `compress`. MCP also takes guidance — exactly one of `prompt` (+ optional `style_image`), `image`, or `images` (4 views front/left/back/right). Re-textures any model, including imported files | +| `tripo_texture` | `texture_quality` `standard`/`detailed`/`extreme`/`fast` (fast requires v3.5); `pbr` (send `false` unless the user explicitly asks for PBR); `texture_seed`; `texture_alignment`; `model` `v3.0` (`v3.0-20250812`, default) / `v3.5` (`v3.5-20260815`, newest; unlocks `delight` and `texture_quality: "fast"`) / `v2.5`; `bake`; `part_names` (segmented models); `compress`. Guidance — exactly one of `prompt` (+ optional `style_image`), `image`, or `images` (4 views front/left/back/right). Re-textures any model, including imported files | | `tripo_mesh_edit` | P2 regional regenerate: `input` (task_id / file_token / URL) + axis-aligned `bbox` in model space; optional `ref_image`. Rest of mesh kept. Billed separately | | `tripo_plan` | Free draft of the tool chain **before** any billed call; show the user and wait for confirmation. Skip only for pure reads (balance / usage / task status) | -| `tripo_convert` / `convert` | `format` `GLTF` `USDZ` `FBX` `OBJ` `STL` `3MF` (3MF = single-colour print). Mesh: `quad`, `force_symmetry` (quad only), `face_limit` (default: keep), `flatten_bottom` + `flatten_bottom_threshold` (0.01). Texture: `texture_size` (4096), `texture_format` `JPEG`/`PNG`/`WEBP`/`BMP`/`TIFF`/`TARGA`/`HDR`/`DPX`/`OPEN_EXR`, `bake` (true), `pack_uv`, `export_vertex_colors` (OBJ/GLTF only). Export: `pivot_to_center_bottom`, `scale_factor`, `auto_size`, `with_animation` (true), `animate_in_place`, `part_names`, `export_orientation`, `fbx_preset` `blender`/`3dsmax`/`mixamo` (FBX only). `quad` with `GLTF` is rejected. Any non-default option bills the complex tier (10 credits instead of 5) | -| `tripo_import_model` / `import` | GLB/GLTF/FBX/OBJ/STL ≤150 MB via `file_token` or URL (`.gltf` only as a URL — upload `.glb`). `tripo make ` runs it implicitly | -| `tripo_rig_check` / `rig-check` | free. GLB input. Result: `riggable` and recommended `rig_type`: `biped` `quadruped` `hexapod` `octopod` `avian` `serpentine` `aquatic`. Gate step — not riggable → stop; riggable → rig the **original model task**, not the check task | -| `tripo_rig` / `rig` | `model`: `v3.0-20260909` (`v3.0`) for biped/default, `others` and `actorcore`/`unity`/`unreal`/`vrm` specs; `v2.5-20260210` (`v2.5`) for the six creature body types. Both take `preset:walk` / `preset:idle` on bipeds and body-type clips on creatures. Explicit `v1.0-20240301` (`v1.0`) is legacy biped-only for 90+ `preset:biped:*` clips. Read the returned model before animation. `rig_type` comes from rig-check; rig the original model, not the check task. `spec` is biped-only; `out_format` is `glb`/`fbx`. CLI default is v3.0; use `rig:model=rig-v3.0`, `rig-v2.5` for creatures or explicit `rig-v1.0` for legacy biped clips. | -| `tripo_animate` / `retarget` | needs a rig task. MCP `animations: [...]` (≤5, billed per clip); CLI one clip per `--then retarget:preset:walk`, several via `tripo anim retarget --animation preset:idle preset:walk`. `out_format` `glb`/`fbx`, `animate_in_place` (no root motion — game code drives movement), `export_with_geometry` (true); `bake_animation` is deprecated — do not pass it (it is ignored) | -| `tripo_segment` / `segment` | `model` `v1.0-20250506` (geometry-based, default) or `v2.0-20260430` (semantic, beta) with `segmentation_granularity` `simple`/`balanced`/`detailed`, `split_by_connectivity` (true), `ref_image` (overrides the other two). MCP switches to v2.0 automatically when a v2-only argument is set | -| `tripo_mesh_complete` / `complete` | needs a segment task. `completion_mode` `ai_completion` (default) / `quick_cap` (hole fill, cheaper); `part_names` (default all) | -| `tripo_decimate` / `decimate` | `face_limit` target 500–20000 tri / 500–10000 with `quad=true` (docs quote 1000–20000); `bake` (true) bakes textures onto the low-poly; `part_names`. `model: "v1.0"` accepts up to 2 000 000 tri / 150 000 quad but requires `face_limit` and has no `bake`/`part_names`. The budget is a target, not a ceiling | -| `tripo_smart_segment` / `smartsegment` | file_token/URL only. `seg_type` `model` (existing **GLB only**, 55 credits; default) or `image` (photo → auto-model → parts, 85); `granularity` `coarse`/`medium`/`fine`; `hint` describing the parts to find. Output: part labels, a PNG mask, the segmented GLB and the inner task ids. Unlike `segment`, it is an end-to-end pipeline | - -Animation presets depend on the rig model of the upstream rig task — on MCP -read it from the `tripo_rig` result (biped defaults to v3.0). v3.0 and v2.5 biped rigs: `preset:idle` `preset:walk` `preset:run` `preset:dive` +| `tripo_convert` | `format` `GLTF` `USDZ` `FBX` `OBJ` `STL` `3MF` (3MF = single-colour print). Mesh: `quad`, `force_symmetry` (quad only), `face_limit` (default: keep), `flatten_bottom` + `flatten_bottom_threshold` (0.01). Texture: `texture_size` (4096), `texture_format` `JPEG`/`PNG`/`WEBP`/`BMP`/`TIFF`/`TARGA`/`HDR`/`DPX`/`OPEN_EXR`, `bake` (true), `pack_uv`, `export_vertex_colors` (OBJ/GLTF only). Export: `pivot_to_center_bottom`, `scale_factor`, `auto_size`, `with_animation` (true), `animate_in_place`, `part_names`, `export_orientation`, `fbx_preset` `blender`/`3dsmax`/`mixamo` (FBX only). `quad` with `GLTF` is rejected. Any non-default option bills the complex tier (10 credits instead of 5) | +| `tripo_import_model` | GLB/GLTF/FBX/OBJ/STL ≤150 MB via `file_token` or URL (`.gltf` only as a URL — upload `.glb`) | +| `tripo_rig_check` | free. GLB input. Result: `riggable` and recommended `rig_type`: `biped` `quadruped` `hexapod` `octopod` `avian` `serpentine` `aquatic`. Gate step — not riggable → stop; riggable → rig the **original model task**, not the check task | +| `tripo_rig` | `model`: `v3.0-20260909` (`v3.0`) for biped/default, `others` and `actorcore`/`unity`/`unreal`/`vrm` specs; `v2.5-20260210` (`v2.5`) for the six creature body types. Both take `preset:walk` / `preset:idle` on bipeds and body-type clips on creatures. Explicit `v1.0-20240301` (`v1.0`) is legacy biped-only for 90+ `preset:biped:*` clips. Read the returned model before animation. `rig_type` comes from rig-check; rig the original model, not the check task. `spec` is biped-only; `out_format` is `glb`/`fbx`. | +| `tripo_animate` | needs a rig task. `animations: [...]` (≤5, billed per clip). `out_format` `glb`/`fbx`, `animate_in_place` (no root motion — game code drives movement), `export_with_geometry` (true); `bake_animation` is deprecated — do not pass it (it is ignored) | +| `tripo_segment` | `model` `v1.0-20250506` (geometry-based, default) or `v2.0-20260430` (semantic, beta) with `segmentation_granularity` `simple`/`balanced`/`detailed`, `split_by_connectivity` (true), `ref_image` (overrides the other two). The tool switches to v2.0 automatically when a v2-only argument is set | +| `tripo_mesh_complete` | needs a segment task. `completion_mode` `ai_completion` (default) / `quick_cap` (hole fill, cheaper); `part_names` (default all) | +| `tripo_decimate` | `face_limit` target 500–20000 tri / 500–10000 with `quad: true` (docs quote 1000–20000); `bake` (true) bakes textures onto the low-poly; `part_names`. `model: "v1.0"` accepts up to 2 000 000 tri / 150 000 quad but requires `face_limit` and has no `bake`/`part_names`. The budget is a target, not a ceiling | +| `tripo_smart_segment` | file_token/URL only. `seg_type` `model` (existing **GLB only**, 55 credits; default) or `image` (photo → auto-model → parts, 85); `granularity` `coarse`/`medium`/`fine`; `hint` describing the parts to find. Output: part labels, a PNG mask, the segmented GLB and the inner task ids. Unlike `tripo_segment`, it is an end-to-end pipeline | + +Animation presets depend on the rig model of the upstream rig task — read it +from the `tripo_rig` result (biped defaults to v3.0). v3.0 and v2.5 biped rigs: `preset:idle` `preset:walk` `preset:run` `preset:dive` `preset:climb` `preset:jump` `preset:slash` `preset:shoot` `preset:hurt` `preset:fall` `preset:turn`; creature rigs take only their body type's clip: `preset:quadruped:walk` `preset:hexapod:walk` `preset:octopod:walk` `preset:serpentine:march` `preset:aquatic:march` (avian and others have none). v1.0 rig @@ -113,43 +107,37 @@ read it from the `tripo_rig` result (biped defaults to v3.0). v3.0 and v2.5 bipe ## 2D steps before 3D -MCP: `tripo_generate_image` (text→image when no `input`; edit/fusion with `input` +`tripo_generate_image` (text→image when no `input`; edit/fusion with `input` or `inputs`), `tripo_image_to_multiview`, `tripo_edit_multiview`, -`tripo_image_to_splat`. CLI: `tripo generate text-to-image|image-to-image| -image-to-multiview|edit-multiview|image-to-splat`. An image task_id is a valid -`input` for `tripo_image_to_3d` — no re-upload. +`tripo_image_to_splat`. An image task_id is a valid `input` for +`tripo_image_to_3d` — no re-upload. - **Templates** (`template`): choose from the documented endpoint whitelist: - Text-to-image templates: `asset_extraction`, `character_completion`, `t_pose`, `variants`, `figure`. - Image-to-image templates: `t_pose`, `character_completion`, `3d_enhance`, `variants`, `figure`. - - `head_extraction` and `print_clay` are not in the documented endpoint whitelists. - CLI 0.8.0's image validator currently passes these template strings through - without checking those whitelists; local acceptance is not server support. - Do not recommend them as supported templates or claim a local rejection. - - `-p t_pose=true` and `-p sketch_to_render=true` are raw parameters, not verified - template shortcuts. The CLI does not normalize these booleans into `template`. - Use `-p template=t_pose` for T-pose or a supported template/explicit prompt - for editing. `image-to-image` still requires `prompt` and/or `template`; - a boolean alone does not satisfy that command-level check. Text-to-image - requires a prompt. Negative prompts go inside `prompt` after `--no`. + - `head_extraction` and `print_clay` are not in the documented endpoint whitelists, + and the `template` argument does not accept them; do not recommend them as + supported templates. + - Image editing requires `prompt` and/or `template`; text-to-image requires a + prompt. Negative prompts go inside `prompt` after `--no`. - **Image models** (`model`): `seedream_v4` (text-to-image default; **not accepted by image editing**), `seedream_v5` (editing default), Google Gemini as `banana` (= gemini-2.5-flash, fast), `banana_pro` (= gemini-3-pro, quality), - `banana2` (= gemini-3.1-flash, latest fast) — MCP may take these `banana*` - names; the CLI accepts only `banana`, `banana_pro`, `banana2`, not Gemini display names — and OpenAI `chat_image_2`, + `banana2` (= gemini-3.1-flash, latest fast) — pass these `banana*` names — + and OpenAI `chat_image_2`, `chat_image_2.5_flare` (faster), `chat_image_2.5_sunburst` (edits keep untouched regions closer to the original). `chat_image_1` is retired (2026-10-23) and `chat_image_1.5` retires on 2026-12-01: pick `chat_image_2` or a 2.5 model. GPT-image options: `quality` `low`/`medium`/`high` (`chat_image_2`; 2.5 also `xhigh`/`max`; omitted = `low`); `background` `auto`/`opaque`/`transparent` - (2.5 only; `transparent` needs `output_format=png`). Both paths accept `fast` only with texture model v3.5. + (2.5 only; `transparent` needs `output_format: "png"`). - **Several references** (`inputs`): seedream ≤4, gemini ≤10, chat_image ≤16; - refer to them in the prompt as `[image 1]`, `[image 2]`. + refer to them in the prompt as `image[1]`, `image[2]`. ### Image size by model -CLI 0.8.0 validates an explicitly supplied `size` per model: +Each model accepts its own explicit `size` values: -| model | accepted explicit size / CLI constraints | +| model | accepted explicit size | | --- | --- | | `banana` | Fixed pixel whitelist only: `1024x1024`, `832x1248`, `1248x832`, `864x1184`, `1184x864`, `896x1152`, `1152x896`, `768x1344`, `1344x768`, `1536x672` | | `banana2` | Tiers only: `0.5K`, `1K`, `2K`, `4K`; no explicit pixels | @@ -161,15 +149,15 @@ CLI 0.8.0 validates an explicitly supplied `size` per model: | `chat_image_2.5_flare` | `auto` or positive-integer `WxH`: each edge ≤3840 and divisible by 16; long edge ≤3 × short edge; total pixels 655360–8294400 inclusive | | `chat_image_2.5_sunburst` | `auto` or positive-integer `WxH`: each edge ≤3840 and divisible by 16; long edge ≤3 × short edge; total pixels 655360–8294400 inclusive | -Do not apply one size/default to every model. Omitted `size` is not filled by -this CLI validator. Official model-specific docs list Seedream defaults as -2048x2048, banana_pro/banana2 as 2K, chat_image_1.5 as auto, and chat_image_2/2.5 -as 2048x2048. For banana, omission behavior is unverified: the docs also print -2048x2048 as a default despite the fixed-size whitelist. Prefer an explicit -whitelisted size; do not turn that inconsistent default into a CLI argument. +Do not apply one size/default to every model. Official model-specific docs list +Seedream defaults as 2048x2048, banana_pro/banana2 as 2K, chat_image_1.5 as auto, +and chat_image_2/2.5 as 2048x2048. For banana, omission behavior is unverified: +the docs also print 2048x2048 as a default despite the fixed-size whitelist. +Prefer an explicit whitelisted size; do not pass that inconsistent default as an +explicit `size`. Seedream exact pixel-count limits unverified: official ranges are rounded (v4 approximately 3.69–16.78 MP; v5 approximately 3.69–10.40 MP). Do not invent -exact server pixel thresholds from those figures. CLI acceptance is not proof +exact server pixel thresholds from those figures. Schema acceptance is not proof of server acceptance; server validation still applies, including banana_pro custom pixel sizes. Chat example: 1536x864 is valid, 1080x1920 is not divisible by 16; use 1088x1920 instead. No 1K/2K/4K tiers for chat_image models. @@ -178,12 +166,12 @@ by 16; use 1088x1920 instead. No 1K/2K/4K tiers for chat_image models. `watermark` control is Seedream-only; `output_format` is `png`/`jpeg`. ### Other image steps -- `image-to-multiview` → a 4-view sheet (front/left/back/right); `edit-multiview` - takes that task plus 1–4 `{view, prompt}` edits; either task feeds - `tripo_multiview_to_3d` (`multiview_task_id`). -- `image-to-splat` returns a Gaussian-splat file (30 credits, ~4 min): no - texture, rig or convert downstream — use image-to-3D when a mesh is needed. - Input PNG/JPEG/WebP ≤20 MB, ≥256×256 px, subject clear and centred. +- `tripo_image_to_multiview` → a 4-view sheet (front/left/back/right); + `tripo_edit_multiview` takes that task plus 1–4 `{view, prompt}` edits; either + task feeds `tripo_multiview_to_3d` (`multiview_task_id`). +- `tripo_image_to_splat` returns a Gaussian-splat file (30 credits, ~4 min): no + texture, rig or convert downstream — use `tripo_image_to_3d` when a mesh is + needed. Input PNG/JPEG/WebP ≤20 MB, ≥256×256 px, subject clear and centred. ## Prices @@ -204,15 +192,15 @@ Afterwards use the usage ledger and task `credits_consumed` for actual spending; | image- or multiview-to-3D, v3.1 | 20 bare / 30 textured | | text-to-3D, P1 | 30 bare / 40 textured (P2: 100 / 110) | | image- or multiview-to-3D, P1 | 40 bare / 50 textured (P2: 100 / 110) | -| add-ons per generation | `texture_quality=detailed` +10, `extreme` +20, `geometry_quality=detailed` +20, `quad` +5, `smart_low_poly` +10, `generate_parts` +20 | -| texture step | 10 standard / 20 detailed / 30 extreme | -| convert | 5, or 10 with any non-default option | -| decimate | 35 tri / 40 quad (v3.0; smart_uv included), 30 (v2.0), 10 (v1.0) | -| segment / complete | 40 / 50 (`quick_cap` 30) | -| smartsegment | 85 image / 55 model | -| rig-check / rig / animate | free / 25 / 10 per clip | -| text-to-image, image editing | 5 (seedream, banana 1K) – 20 (banana_pro 4K) by model and size tier | -| image-to-multiview / edit-multiview / image-to-splat | 10 / 5 per edited view / 30 | +| add-ons per generation | `texture_quality: "detailed"` +10, `"extreme"` +20, `geometry_quality: "detailed"` +20, `quad` +5, `smart_low_poly` +10, `generate_parts` +20 | +| `tripo_texture` | 10 standard / 20 detailed / 30 extreme | +| `tripo_convert` | 5, or 10 with any non-default option | +| `tripo_decimate` | 35 tri / 40 quad (v3.0; smart_uv included), 30 (v2.0), 10 (v1.0) | +| `tripo_segment` / `tripo_mesh_complete` | 40 / 50 (`quick_cap` 30) | +| `tripo_smart_segment` | 85 image / 55 model | +| `tripo_rig_check` / `tripo_rig` / `tripo_animate` | free / 25 / 10 per clip | +| `tripo_generate_image` | 5 (seedream, banana 1K) – 20 (banana_pro 4K) by model and size tier | +| `tripo_image_to_multiview` / `tripo_edit_multiview` / `tripo_image_to_splat` | 10 / 5 per edited view / 30 | Credits are frozen at submission and released on failure, ban or cancellation — failed tasks are never charged. Task states: `queued` → `running` (with @@ -226,59 +214,8 @@ Every generation costs credits from the user's account, and `credits_consumed` i reported on each result. - Confirm the request before generating more than one asset in a batch. -- Run `tripo balance` first when the user asks for several assets, and report the - cost back after finishing. -- For 3D printing and other untextured output, add `-p texture=false -p pbr=false` +- Call `tripo_balance` first when the user asks for several assets, and report + the cost back after finishing. +- For 3D printing and other untextured output, pass `texture: false, pbr: false` — it skips texture credits entirely. - Do not silently re-roll a disappointing result. Show the user the preview and ask. - -## Result shape - -```json -{ - "task_id": "...", - "type": "convert_model", - "status": "success", - "credits_consumed": 25, - "credits_breakdown": [ - { "task_id": "", "type": "text_to_model", "credits_consumed": 20 }, - { "task_id": "", "type": "convert_model", "credits_consumed": 5 } - ], - "output_dir": "tripo-out/knight-1a2b3c4d", - "files": ["model.fbx", "preview.png", "task.json"], - "model_file": ".../model.fbx", - "preview": ".../preview.png", - "chain": [{ "task_id": "...", "type": "texture_model" }] -} -``` - -`model_file` and `preview` describe the **final** chain step. After a convert -step the native GLB and `preview.png` live on the earlier generation task — -fetch them free with `tripo task get --download` instead of -paying for another conversion. - -## Presenting the finished asset - -Every file is already on the user's disk when `tripo make` exits — never offer -a "download". Do not render the model file as a clickable link either: the chat -UI opens local-file links in a preview pane that cannot display binary meshes, -so the link just looks broken when clicked. Instead: - -- show `preview.png` — images render fine; -- give the model's location as a plain path in backticks; -- offer the next real action: reveal it in the file manager (`open -R ` - on macOS, `explorer /select,` on Windows) or wire it into the project. - -## Other commands - -| command | purpose | -| -------------------------------- | ------------------------------------ | -| `tripo task get --download` | fetch or re-download an earlier task | -| `tripo balance` / `tripo usage` | credits remaining / recent spend | -| `tripo redo [@last]` | same request, new seed | -| `tripo files upload ` | get a `file_token` for an image | -| `tripo batch run manifest.yaml` | bulk jobs, resumable | -| `tripo docs --topic ` | full docs for any command or recipe | - -Download URLs returned by the API expire in about five minutes — never cache one. -Re-run `tripo task get --download` instead. diff --git a/plugins/tripo-3d/skills/tripo-game-asset/SKILL.md b/plugins/tripo-3d/skills/tripo-game-asset/SKILL.md index 69f2f1d7..a7ec7720 100644 --- a/plugins/tripo-3d/skills/tripo-game-asset/SKILL.md +++ b/plugins/tripo-3d/skills/tripo-game-asset/SKILL.md @@ -1,147 +1,133 @@ --- name: tripo-game-asset -description: Recipes for producing game-ready 3D assets with Tripo and wiring them into a game project - low-poly props on a face budget, PBR hero assets, LOD chains, and rigged characters with locomotion clips for Unity, Unreal, Godot or Three.js. Use when the user is building a game or real-time 3D scene and needs props, characters, placeholder art, LODs, or an animated rig, rather than a single one-off model. 中文触发词:游戏资产、游戏素材、游戏模型、低模道具、面数预算、LOD、角色绑骨、走跑跳动画、Unity/Unreal/Godot 模型导入。 +description: Recipes for producing game-ready 3D assets with Tripo and wiring them into a game project - low-poly props on a face budget, detailed hero assets, LOD chains, and rigged characters with locomotion clips for Unity, Unreal, Godot or Three.js. Use when the user is building a game or real-time 3D scene and needs props, characters, placeholder art, LODs, or an animated rig, rather than a single one-off model. 中文触发词:游戏资产、游戏素材、游戏模型、低模道具、面数预算、LOD、角色绑骨、走跑跳动画、Unity/Unreal/Godot 模型导入。 --- # Game asset pipeline -## Client attribution - -Use `tripo-cli` 0.8.0 or later (`npx tripo-cli@0.8`, not npm latest). -Follow the main skill's version gate and account confirmation. -On every CLI command, including each command -in a pipeline and commands from references, set -`TRIPO_DISTRIBUTION_CHANNEL=zcode_plugin`. Set `TRIPO_CLIENT_APP=zcode` only -when running in ZCode; in the Claude compatibility host use `TRIPO_CLIENT_APP=claude`. -If the host is unknown, leave `TRIPO_CLIENT_APP` unset; never infer it from the -package name. Use a variable prefix in POSIX or set `$env:TRIPO_CLIENT_APP` and -`$env:TRIPO_DISTRIBUTION_CHANNEL` in the same PowerShell call. Never save these -values to an account profile. MCP sends only `X-Tripo-Distribution: zcode_plugin`; -its client info identifies the actual host. OAuth and region selection stay the same. - -Recipes on top of the `tripo-3d` skill. Read that skill first — it explains how -to pick the execution path (MCP tools vs `tripo-cli`), authorization, blocking -behaviour, exit codes, and credit rules. - -The recipes below are written as CLI commands because game work happens in a -project tree where a shell exists and assets should land next to the code. -The same pipelines map onto the MCP tools when the user prefers them: -`tripo_text_to_3d`/`tripo_image_to_3d` with `face_limit` for budgeted props, -`tripo_rig` (`spec: "mixamo"`) + `tripo_animate` for characters (v3.0/v2.5 biped rigs -take `preset:walk`, creature rigs their body-type clip such as -`preset:quadruped:walk`; explicit legacy v1.0 takes `preset:biped:*` — the -`tripo_rig` result says which), `tripo_convert` -for FBX/texture-size export, `tripo_decimate` per LOD level, and -`tripo_upload_ticket` → `tripo_import_model` for a mesh the project already has — -then download the fresh result URL into the project. Only `tripo batch` (bulk, -resumable) genuinely requires the CLI; say so instead of improvising. +Recipes on top of the `tripo-3d` skill. Read that skill first — it covers +authorization, the `tripo_task_wait` loop (call again while +`queued`/`running`), credit rules and the full parameter reference. Every +recipe runs through the Tripo MCP tools only. Every arrow below is a billed +task followed by `tripo_task_wait`; the `input` of each step is the previous +step's `task_id`. Every generation and `tripo_texture` call sends `pbr: false` +unless the user explicitly asks for PBR. The point of these recipes is that assets land in the project's own directory -structure. Always pass `-o` pointing at wherever the project keeps its art — but note -`-o` is the parent: the files end up in `/tripo-out/-/`, so move them -to their final location afterwards if the user named a specific path. +structure: after each final step download the file with +`curl -L -o /. ""` (links expire in about +5 minutes — fetch fresh ones with `tripo_task_status` if needed) and report the +local path. ## Pick a budget first -Explicitly choose P2 for game/realtime topology; retain P1 for -lower cost and speed and v3.1 for film/render/print. Confirm the selected +Explicitly choose P2 for game/realtime topology; within the P series the default +is P2, and P1 is used only when the user names it or picks it for lower cost and +speed; v3.1 for film/render/print. Confirm the selected model, texture options and estimated cost; re-confirm any paid model change. -| target | preset | what it does | -| ----------------------------- | ------------------- | ----------------------------------------------------- | -| mobile, WebGL, many instances | `--for game-mobile` | add `--model tripo-p2`, face_limit 15000, 2K textures, FBX | -| PC / console hero asset | `--for game-pc` | add `--model tripo-p2`, detailed PBR | -| animated character | `--for anim` | rig-check, then rig, then retarget | +| target | generation call | export | +| ----------------------------- | ------------------------------------------------------------ | -------------------------------------------- | +| mobile, WebGL, many instances | explicit `model: "P2"`, `face_limit: 15000` | `tripo_convert` `format: "FBX"`, `texture_size: 2048` | +| PC / console hero asset | explicit `model: "P2"`, `texture_quality: "detailed"` | FBX only if the engine needs it; GLB is native | +| animated character | T-pose model → `tripo_rig_check` → `tripo_rig` → `tripo_animate` | `out_format: "fbx"` for Unity/Unreal | -Two budget-related choices the presets do not make for you: +Two budget-related choices the defaults do not make for you: -- **Quads at low poly** — P1 rejects `quad`; use `--model tripo-p2` (wire - `P2-20260801`; face_limit 48–25000 quads, price depends on input and texture options; confirm the estimate, - output is FBX) or v3.1 with `-p smart_low_poly=true -p quad=true` - (face_limit 500–10000). On MCP pass `model: "P2"` / `quad: true`. -- **v3.1 quality under a face cap** — explicitly add `--model tripo-v3.1` (MCP `model: "v3.1"`) when the user wants v3.1 - geometry with a budget. +- **Quads at low poly** — P1 rejects `quad`; use `model: "P2", quad: true` + (face_limit 48–25000 quads, price depends on input and texture options; + confirm the estimate, output is FBX) or v3.1 with + `smart_low_poly: true, quad: true` (face_limit 500–10000). +- **v3.1 quality under a face cap** — explicitly set `model: "v3.1"` when the + user wants v3.1 geometry with a budget. -Override the face budget when the project has a stricter one: - -```bash -tripo make "a health potion bottle" --for game-mobile --model tripo-p2 \ - -p face_limit=3000 --then convert:format=FBX,texture_size=1024 \ - -o ./Assets/Art/Props --json --yes -``` +Override the face budget when the project has a stricter one, e.g. +`tripo_text_to_3d` `{ model: "P2", prompt: "a health potion bottle", face_limit: 3000, pbr: false }` → +`tripo_convert` `{ format: "FBX", texture_size: 1024 }`. ## Props -```bash -tripo make "an ornate treasure chest, fantasy style" --for game-pc --model tripo-p2 \ - -o ./assets/models --json --yes -``` +`tripo_text_to_3d` `{ model: "P2", prompt: "an ornate treasure chest, fantasy style", texture_quality: "detailed", pbr: false }` +→ download the GLB (or → `tripo_convert` `{ format: "FBX" }` for Unity/Unreal). -For a set of props, generate them one at a time and check each `preview.png` before -continuing — a bad seed early is cheaper to catch than at the end of a batch. For -genuinely large sets use `tripo batch run manifest.yaml`, which is resumable. +For a set of props, generate them one at a time and check each +`preview_image_url` before continuing — a bad seed early is cheaper to catch +than at the end of a batch. Confirm the total cost of the whole set with the +user first (`tripo_plan`, `tripo_balance`), then call the tools one asset at a +time, and use `tripo_task_list` to check the status of many task ids in one +call. ## LOD chain from one source -```bash -tripo make "a stone golem" --for game-pc --model tripo-p2 --then decimate:5000 --json --yes -tripo make @last --then decimate:1500,convert:fbx --json --yes -``` - -`decimate` bakes normals by default, so the low LODs keep the silhouette detail of -the source. Each `@last` continues from the previous task rather than regenerating. - -**`decimate`'s face budget is a target, not a ceiling** — a 1500-face request can come -back at ~1900 triangles. Read the actual triangle count from the result before handing -an LOD to a project with a hard budget, and reduce it locally if it overshoots. -Generation's own `face_limit` does hold as an upper bound, so this caveat is specific -to `decimate`. +Generate once, then one `tripo_decimate` per level — each with the **original +generation task** as `input`, not the previous LOD: -## Characters with animation - -CLI default: v3.0 (`v3.0-20260909`) with universal `preset:walk` clips. -Use explicit `rig-v2.5` for creature rigs; use explicit `rig-v1.0` only for -legacy biped clips (`preset:biped:*`). Match the preset family to the rig result. +`tripo_text_to_3d` `{ model: "P2", prompt: "a stone golem", pbr: false }` (LOD0) +→ `tripo_decimate` `{ input: , face_limit: 5000 }` (LOD1) +→ `tripo_decimate` `{ input: , face_limit: 1500 }` (LOD2) +→ `tripo_convert` `{ input: , format: "FBX" }` if the engine needs FBX. -```bash -tripo make "a knight in full armor, T-pose, standing straight" --for anim --model tripo-p2 --json --yes -``` +`tripo_decimate` bakes textures by default (`bake: true`), so the low LODs keep +the silhouette detail of the source. -`--for anim` runs `rig-check` first, which gates the chain: if the mesh is not -riggable it stops before spending rigging credits. +**`tripo_decimate`'s face budget is a target, not a ceiling** — a 1500-face +request can come back at ~1900 triangles. Read the actual triangle count from +the result before handing an LOD to a project with a hard budget, and reduce it +locally if it overshoots. Generation's own `face_limit` does hold as an upper +bound, so this caveat is specific to decimation. -Explicit control over the rig and clips: +For a budget above 20000 faces use `tripo_decimate` `model: "v1.0"` with an +explicit `face_limit` (up to 2 000 000, no bake). `model: "v3.0"` is the newest +retopology and the only one that takes `smart_uv: true` (see the end of this +skill). -```bash -tripo make "a robot soldier, T-pose" --model tripo-p2 --json --yes \ - | tripo anim check --json \ - | tripo anim rig --spec mixamo --out-format fbx --json \ - | tripo anim retarget --animation preset:idle preset:walk preset:run --json -``` +## Characters with animation -- Prompt for a **T-pose** — rigging quality depends heavily on it. -- `--spec mixamo` produces a Unity Humanoid-compatible skeleton. -- `--animate-in-place` for locomotion clips driven by game code rather than root motion. -- Retarget is billed per animation and accepts at most five. -- To animate a mesh the project already has: - `tripo make hero.glb --then rig-check,rig,retarget:preset:walk --json --yes` +1. **T-pose source.** Prompt for it (`"a knight in full armor, T-pose, standing straight"`) + or turn a character image into one with `tripo_generate_image` + `{ input: , template: "t_pose" }` — rigging quality depends heavily on it. +2. `tripo_text_to_3d` / `tripo_image_to_3d` with explicit `model: "P2"` → the + character model task. +3. `tripo_rig_check` `{ input: }` — free. It gates the chain: not + riggable → stop before spending rigging credits. Read the recommended + `rig_type` (`biped` `quadruped` `hexapod` `octopod` `avian` `serpentine` `aquatic`). +4. `tripo_rig` `{ input: , rig_type: , spec: "mixamo", out_format: "fbx" }` + — rig the **original model task**, not the check task. `spec: "mixamo"` + produces a Unity Humanoid-compatible skeleton. Leave `model` unset: `biped` + gets v3.0, the six creature body types get v2.5, and the + result names the preset family to use next. +5. `tripo_animate` `{ task_id: , animations: [...], out_format: "fbx", animate_in_place: true }` + — at most five clips, billed per clip. Explicit legacy v1.0 rigs take + `preset:biped:idle` `preset:biped:walk` `preset:biped:run` `preset:biped:jump` + plus emotes, dances and sports clips (`preset:biped:dance_01`, + `preset:biped:wave_goodbye_01`, …); v3.0 and v2.5 biped rigs take `preset:idle` + `preset:walk` `preset:run` `preset:jump` `preset:fall` `preset:turn` + `preset:climb` `preset:dive` `preset:slash` `preset:shoot` `preset:hurt`; + creature rigs take only their body-type clip (`preset:quadruped:walk`, …; + avian has none). `animate_in_place: true` + for locomotion driven by game code rather than root motion. + +To animate a mesh the project already has: `tripo_upload_ticket` +`{ kind: "model", format: "glb" }` → run the returned curl to upload the file → +`tripo_import_model` `{ input: }` → continue from step 3. ## Format notes -- **Three.js / web**: GLB. `--for ar-web` adds the web-oriented defaults. -- **Unity / Unreal**: FBX via `--then convert:fbx`, or `--for game-mobile` which - already converts. -- Quads (`-p quad=true`) force FBX — glTF cannot store them, so `convert:glb` - combined with quads is rejected. +- **Three.js / web**: GLB as generated; `auto_size: true` for real-world scale. +- **Unity / Unreal**: FBX via `tripo_convert` `{ format: "FBX" }` + (`fbx_preset: "mixamo"` for a Unity-Humanoid-oriented export of rigged models). +- Quads (`quad: true`) force FBX — glTF cannot store them, so `tripo_convert` + `format: "GLTF"` combined with quads is rejected. - `texture_size` is set on the convert step, not at generation: - `--then convert:format=FBX,texture_size=2048`. + `tripo_convert` `{ format: "FBX", texture_size: 2048 }`. ## Wiring into the project -After a successful run, `model_file` in the result JSON is the path to import. Do the -integration work the user actually asked for — add the loader call, register the -prefab, update the asset manifest — rather than stopping at "the file is generated". -Check `preview.png` first so a wrong asset does not get wired in. +After a successful chain, download the final `model_url` into the project's +art directory and use that path for the import. Do the integration work the +user actually asked for — add the loader call, register the prefab, update the +asset manifest — rather than stopping at "the file is generated". Check the +preview first so a wrong asset does not get wired in. Retopology: `tripo_decimate` with explicit `model: "v3.0", smart_uv: true` combines retopology and UVs (35 tri / 40 quad credits). Standalone From da4132cd4d5f89aaeef683ebf92f9a99e8c93298 Mon Sep 17 00:00:00 2001 From: sunzhenqiang Date: Fri, 30 Oct 2026 20:34:08 +0800 Subject: [PATCH 3/8] fix(tripo-3d): align skills with the hosted MCP and the official API docs Rigging passes the model per body type: v3.0 for bipeds and others, v2.5 (the official animal rig) for animals. The API's own default is v1.0-20240301 (biped only). Same plugin content as the Tripo GLM plugin repository's 0.1.5 candidate; the version is unchanged. --- plugins/tripo-3d/README.md | 8 ++- plugins/tripo-3d/README_CN.md | 2 +- plugins/tripo-3d/hooks/session-start.mjs | 6 +- plugins/tripo-3d/skills/tripo-3d/SKILL.md | 62 +++++++++++-------- .../skills/tripo-3d/references/capability.md | 48 +++++++------- .../tripo-3d/skills/tripo-game-asset/SKILL.md | 22 ++++--- 6 files changed, 82 insertions(+), 66 deletions(-) diff --git a/plugins/tripo-3d/README.md b/plugins/tripo-3d/README.md index 2441053f..b2e91cb3 100644 --- a/plugins/tripo-3d/README.md +++ b/plugins/tripo-3d/README.md @@ -6,8 +6,10 @@ Game/realtime recipes explicitly prefer **P2** (more credits than H/P1), the P-series default; **P1** is used only when the user names it or picks it for lower -cost and speed, and v3.1 for film/render/print. Rig defaults to v3.0, with -animation presets selected from the upstream rig model. Retopology v3.0's +cost and speed, and v3.1 for film/render/print. Rigs pass the model +explicitly, v3.0 for bipeds and v2.5 for animals (the API's own default, v1.0, +rigs bipeds only), with animation presets selected +from the upstream rig model. Retopology v3.0's `smart_uv` and standalone `tripo_smart_uv` are distinct billed workflows. Fast textures require v3.5; `chat_image_1` is retired. @@ -70,7 +72,7 @@ The Tripo MCP server needs a one-time authorization: - **Network**: MCP tool calls go to `https://developers.tripo3d.com/mcp`; authorization redirects to the China Tripo console (developers.tripo3d.com). Results are downloaded from Tripo's CDN through - short-lived links (about 5 minutes). + short-lived links (about 2 hours). - **Account and billing**: every generation spends credits from your own Tripo account; each tool reports `credits_consumed`, failed tasks are refunded automatically. The skill drafts the chain with `tripo_plan`, diff --git a/plugins/tripo-3d/README_CN.md b/plugins/tripo-3d/README_CN.md index d87e1fdb..ada5f332 100644 --- a/plugins/tripo-3d/README_CN.md +++ b/plugins/tripo-3d/README_CN.md @@ -52,7 +52,7 @@ API Key。本构建的 MCP 只对接国内站;海外站账号请安装海外 ## 依赖、网络访问与副作用 -- **网络**:MCP 工具调用走 `https://developers.tripo3d.com/mcp`;授权页跳转到国内站 Tripo 控制台(developers.tripo3d.com)。生成结果通过 Tripo 的 CDN 短期链接(约 5 分钟过期)下载。 +- **网络**:MCP 工具调用走 `https://developers.tripo3d.com/mcp`;授权页跳转到国内站 Tripo 控制台(developers.tripo3d.com)。生成结果通过 Tripo 的 CDN 短期链接(约 2 小时过期)下载。 - **账号与计费**:所有生成任务消耗你自己 Tripo 账号的积分,每次工具返回 `credits_consumed`;失败任务自动退款。批量生成前 skill 会先用 `tripo_plan` 草稿、查余额并确认。 - **文件写入**:只在你要求把模型落到本地时,用 `curl` 把结果下载到项目目录;Hook 与 MCP 服务器本身不写任何文件。 - **命令执行**:仅在上传本地图片/模型(`tripo_upload_ticket` 返回的 curl)或下载结果时运行 shell 命令。插件不会安装或调用任何命令行客户端,MCP 失败、未授权、批量或本地落盘需求也不例外。 diff --git a/plugins/tripo-3d/hooks/session-start.mjs b/plugins/tripo-3d/hooks/session-start.mjs index f0fd9602..ea39592e 100644 --- a/plugins/tripo-3d/hooks/session-start.mjs +++ b/plugins/tripo-3d/hooks/session-start.mjs @@ -5,12 +5,12 @@ const RULES = `Tripo 3D — rules that apply whenever Tripo tools (tripo_*) are used. These hold even when the tripo-3d skill was not loaded; load it for the full workflow. 1. Generation is asynchronous. Every tripo_* generation or processing tool returns a task_id immediately. Call tripo_task_wait with it and keep calling while status is queued/running — each call returns within about 55 seconds, a generation usually takes 1–4 minutes. Never present a result before status is success, and never treat a task_id as a finished model. -2. Show the result, then the link. On success, embed preview_image_url as a markdown image and give model_url as the download link. Both URLs expire in about 5 minutes: never re-print an old one — call tripo_task_status for fresh links. If you saved the file locally, give its path as plain text in backticks, never as a clickable link (chat previews cannot render meshes). -3. Credits belong to the user. Call tripo_plan and get confirmation before any billed generation or chain. Every billed tool reports credits_consumed. Check tripo_balance and confirm before generating more than one asset in a batch; on insufficient balance give the returned plans_url instead of retrying. Never silently re-roll a disappointing result — show the preview and ask first. +2. Deliver the file, then one link. On success, download model_url to a local file when a shell is available and give its path as plain text in backticks, never as a clickable link (chat previews cannot render meshes); then also offer model_url as a single markdown download link. Do not paste URLs from output_urls into the reply. Result URLs expire after about 2 hours: never re-print an old one — call tripo_task_status for fresh links. +3. Credits belong to the user. Call tripo_plan and get confirmation before any billed generation or chain. Every billed tool reports credits_consumed. Check tripo_balance and confirm before generating more than one asset in a batch; on insufficient balance give the returned plans_url instead of retrying. Never silently re-roll a disappointing result — say what is off and ask first. 4. Authorization is a browser flow, never a pasted key. This build's MCP is China-mainland only (developers.tripo3d.com/mcp); the auth page has no region picker. If Tripo tools are missing or a call reports an authorization error, tell the user to open ZCode 设置 → MCP, find the Tripo server under「Plugin MCP 服务器」and click「打开授权」, then sign in on the 国内站 console and Authorize. An overseas-site account needs the overseas plugin build. Do not ask for an API key in the chat. MCP is the only execution path: never install or run a command-line client instead, even when a local login or API key exists. 5. Failures are reported, not hidden. On failed/banned, relay failure_reason (and error_code) honestly; failed-task credits are refunded automatically. Never invent parameters — the tool schemas are authoritative. Stylize has been retired: there is no tripo_stylize tool. Use tripo_mesh_edit for P2 regional redo. 6. PBR is opt-in. Send pbr: false on every generation and tripo_texture call unless the user explicitly asks for PBR (e.g. "with PBR", 「PBR 材质」); only then send pbr: true, which also forces texture: true. The API turns PBR on when pbr is omitted, so never leave it out. Detailed or high-quality textures do not mean PBR. -7. Choose models explicitly: P2 is preferred for game/realtime topology and costs more credits than H/P1; within the P series the default is P2, and P1 is used only when the user names it or picks it for lower cost and speed; v3.1 for film/render/print. Do not infer the model from face_limit. Cost is not estimated by this text or guaranteed by tripo_plan: disclose uncertainty and obtain consent before billing. Rig defaults to v3.0; use preset:walk, reserving preset:biped:* for explicit v1.0 rigs. Retopology v3.0 with smart_uv and standalone tripo_smart_uv are separate workflows, not interchangeable free export switches. Load the capability reference before running either. chat_image_1 is retired; never fall back to it. fast textures require v3.5-20260815. +7. Choose models explicitly: P2 is preferred for game/realtime topology and costs more credits than H/P1; within the P series the default is P2, and P1 is used only when the user names it or picks it for lower cost and speed; v3.1 for film/render/print. Do not infer the model from face_limit. Cost is not estimated by this text or guaranteed by tripo_plan: disclose uncertainty and obtain consent before billing. Pass the rig model explicitly: v3.0 for bipeds, v2.5 for animal body types (the API's own default is v1.0, which rigs bipeds only); use preset:walk, reserving preset:biped:* for explicit v1.0 rigs. Retopology v3.0 with smart_uv and standalone tripo_smart_uv are separate workflows, not interchangeable free export switches. Load the capability reference before running either. chat_image_1 is retired; never fall back to it. fast textures require texture model v3.5: pass the short name v3.5, or omit the version and the tool picks it. `; let raw = ""; diff --git a/plugins/tripo-3d/skills/tripo-3d/SKILL.md b/plugins/tripo-3d/skills/tripo-3d/SKILL.md index af42f2a3..6be3c2cc 100644 --- a/plugins/tripo-3d/skills/tripo-3d/SKILL.md +++ b/plugins/tripo-3d/skills/tripo-3d/SKILL.md @@ -74,10 +74,11 @@ too. within about 55 s, so call it again while status is still `queued`/`running` (a generation takes 1–4 minutes). Do not invent your own sleep loop and do not treat the `task_id` as completion. -4. **Judge** — on `success`, look at `preview_image_url` and show it to the - user before building on the result. On `failed`/`banned`, report +4. **Judge** — on `success`, check the result before building on it: you may + look at the rendered image listed in `output_urls`, but never paste + `output_urls` into the reply. On `failed`/`banned`, report `failure_reason` honestly; failed-task credits are refunded automatically. - Do not silently re-roll a disappointing result — show the preview and ask; + Do not silently re-roll a disappointing result — say what is off and ask; re-rolling means creating a new task with the same prompt. 5. **Post-process** (each step is a new billed task: create → `tripo_task_wait`; `input` takes a model task_id, a `file_token` or a public model URL unless @@ -85,10 +86,12 @@ too. - `tripo_texture` — texture or re-texture a model. - `tripo_rig_check` → `tripo_rig` — check riggability before spending rig credits, then add a skeleton with the `rig_type` the check returned. - Prompt characters as **T-pose** at generation time; `spec: "mixamo"` for - Unity Humanoid / Mixamo pipelines. Leave `model` unset: `tripo_rig` picks - v3.0 for `biped` and the creature v2.5 rig for the other - body types, and its result says which preset family the rig takes. + Prompt characters as **T-pose** at generation time; `spec: "unity"` for + Unity Humanoid, `"mixamo"` for Mixamo pipelines. Always pass `model` by + body type: `"v3.0"` for `biped`, `"v2.5"` for the animal types the check + reports (`quadruped` `hexapod` `octopod` `avian` `serpentine` `aquatic`). + The API's own default is still `v1.0-20240301`, which rigs bipeds only. + The `tripo_rig` result says which preset family the rig takes. - `tripo_animate` — presets on a **successful rig task** (≤5 per call, billed per animation). Preset names follow the rig model reported by `tripo_rig`: explicit legacy v1.0 rigs take `preset:biped:walk`, @@ -97,25 +100,27 @@ too. (`preset:quadruped:walk`, …; avian has none); `animate_in_place: true` when game code drives movement. - `tripo_convert` — export GLTF/USDZ/FBX/OBJ/STL/3MF, optional retopology - via `face_limit`/`quad`. Quads cannot export GLTF. Any non-default option - bills as "complex convert". + via `face_limit`/`quad`. Quads cannot export GLTF. Any `face_limit`, or a + non-default `quad`, `flatten_bottom`, `texture_size`, `texture_format`, + `pivot_to_center_bottom` or `scale_factor`, bills as "complex convert". - `tripo_decimate` — high-poly → low-poly (`face_limit` 500–20000, bakes the original textures); `tripo_segment` → `tripo_mesh_complete` — split into parts and close the cuts; `tripo_mesh_edit` — redo one region of an existing mesh with P2 (`bbox` required). Stylize (lego / voxel / voronoi / minecraft) has been retired — there is no `tripo_stylize` tool. -6. **Deliver** — result URLs (`model_url`, `preview_image_url`) **expire in - about 5 minutes**; never cache or re-print an old one — call +6. **Deliver** — result URLs (`model_url` and `output_urls`) **expire after + about 2 hours**; never cache or re-print an old one — call `tripo_task_status` for fresh links. Download the file into the project - (`curl -L -o ""`) and give the local path as plain text in + (`curl -L -o ""`) and give the local path as plain text in backticks — never as a clickable link, the chat preview cannot render - meshes; offer the next real action: reveal it in the file manager + meshes — then also offer `model_url` as a single markdown download link; + offer the next real action: reveal it in the file manager (`open -R ` on macOS, `explorer /select,` on Windows) or wire it - into the project. Only when no shell is available give the fresh link and - say it is short-lived, offering to refresh it on request. After a - `tripo_convert`, the native GLB and its preview stay on the earlier task — - fetch them with `tripo_task_status` on that task instead of paying for - another conversion. + into the project. Only when no shell is available give just the fresh + `model_url` link and say it is short-lived, offering to refresh it on + request. Do not paste other URLs from `output_urls`. After a + `tripo_convert`, the native GLB stays on the earlier task — fetch it with + `tripo_task_status` on that task instead of paying for another conversion. ## Scenario → tool chain @@ -138,7 +143,8 @@ step is only worth its credits when the target really needs another format. - **Animated character** — T-pose reference first (`tripo_generate_image` with `template: "t_pose"` turns a character image into one) → `tripo_image_to_3d`/`tripo_text_to_3d` → `tripo_rig_check` → `tripo_rig` - (`spec: "mixamo"` for Unity Humanoid) → `tripo_animate` with the preset + (`model: "v3.0"`, or `"v2.5"` for an animal; `spec: "unity"` for Unity Humanoid) → + `tripo_animate` with the preset family named in the `tripo_rig` result: v3.0 humanoids `["preset:walk", "preset:idle"]`; creatures use their body-specific presets (e.g. `preset:quadruped:walk`); explicit v1.0 humanoids alone use @@ -153,8 +159,10 @@ step is only worth its credits when the target really needs another format. tool's `input`; a local file goes through `tripo_upload_ticket` (`kind: "model"`, `format: "glb"`) → `tripo_import_model`, which yields a reusable task_id with a preview (`.gltf` is rejected — export `.glb`). -- **Not a mesh** — `tripo_image_to_splat` outputs a Gaussian-splat `.ply` - scene for viewers, not an editable model; say so before running it. +- **Not a mesh** — `tripo_image_to_splat` outputs a Gaussian-splat `.splat` + scene for viewers, not an editable model; say so before running it. If the + result has no `model_url`, the file is the `model_url` entry of `output_urls`; + deliver that one. ## Parameters that matter @@ -175,8 +183,9 @@ step is only worth its credits when the target really needs another format. there was one. Confirm that cost like any other paid step. - 3D printing / untextured output: `texture: false, pbr: false` skips texture credits entirely; convert to `STL` (add `flatten_bottom: true` for stability). -- `quad: true` (v3.1 or P2) needs a `tripo_convert` to FBX/OBJ/USDZ at the end; - P1 rejects `quad`. +- `quad: true` (v3.1 or P2) is delivered as FBX directly, so FBX needs no + `tripo_convert`; a convert with `quad: true` always outputs FBX (GLTF is + rejected). P1 does not support `quad` (the tool strips it and notes it). ## Inputs @@ -213,9 +222,10 @@ step is only worth its credits when the target really needs another format. - `tripo_balance` first when the user asks for several assets; confirm the whole batch and its cost once before generating more than one, then call the tools one asset at a time, and report `credits_consumed` after. -- When a create call reports a full concurrency pool or a rate limit, wait for - running tasks to finish and retry with backoff instead of resubmitting in a - loop. +- Error `2000` means that category's concurrency pool is full and no task was + created: retry after `Retry-After` or once a running task of the same + category finishes. Error `1007` is the request rate limit: wait a few + seconds and retry the same call. Never resubmit in a loop. - Insufficient balance errors: give the `plans_url` from `tripo_balance` (informational pricing page for this deployment's region) instead of retrying. diff --git a/plugins/tripo-3d/skills/tripo-3d/references/capability.md b/plugins/tripo-3d/skills/tripo-3d/references/capability.md index a09d4697..e4a25e30 100644 --- a/plugins/tripo-3d/skills/tripo-3d/references/capability.md +++ b/plugins/tripo-3d/skills/tripo-3d/references/capability.md @@ -10,9 +10,9 @@ changed in `notes`. | model | MCP `model` | use for | limits | | --- | --- | --- | --- | | **v3.1** (default) | `v3.1` | high fidelity: film, render, print | full parameter set | -| **P1** | `P1` | P series alternative, only when the user names it or picks it for lower cost and speed | `face_limit` 50–20000; no `quad`, `smart_low_poly`, `generate_parts`, `geometry_quality`; adds `export_uv` | -| **P2** | `P2` → wire `P2-20260801` | default P-series model, preferred for game/realtime topology, with explicit user confirmation | `face_limit` 48–50000 tri / 48–25000 quad; supports `quad`, still no `smart_low_poly`, `generate_parts`, `geometry_quality`; costs more credits than H/P1, and price depends on input and texture options; confirm the estimate. Pass the generation model explicitly | -| v3.0, v2.5 | `v3.0`, `v2.5` | legacy, only when the user asks | v2.5 has no `geometry_quality` | +| **P1** | `P1` | P series alternative, only when the user names it or picks it for lower cost and speed | `face_limit` 50–20000; no `quad`, `smart_low_poly`, `generate_parts`, `geometry_quality` | +| **P2** | `P2` → wire `P2-20260801` | default P-series model, preferred for game/realtime topology, with explicit user confirmation | `face_limit` 48–50000 tri / 48–25000 quad; supports `quad`, still no `smart_low_poly`, `generate_parts`, `geometry_quality`; costs more credits than H/P1, and price depends on texture options; confirm the estimate. Pass the generation model explicitly | +| v3.0, v2.5 | `v3.0`, `v2.5` | legacy, only when the user asks | v2.5 has no `geometry_quality`, `quad`, `smart_low_poly`, `generate_parts`, `auto_size`, `compress` (stripped with a note) | Website model names map to these rows: H3.1 → `v3.1`, P1.0 → `P1`, P2.0 → `P2`. @@ -32,22 +32,22 @@ Apply to `tripo_text_to_3d` / `tripo_image_to_3d` / `tripo_multiview_to_3d`. | param | default | notes | | --- | --- | --- | | `prompt`, `negative_prompt` | – | text input only; ≤1024 / ≤255 chars | -| `face_limit` | adaptive | upper bound on triangles. v3.1 any; P1 50–20000; P2 48–50000 | +| `face_limit` | adaptive | upper bound on triangles. v3.1 any; P1 50–20000; P2 48–50000 (48–25000 with `quad`) | | `texture`, `pbr` | `true`, see notes | **send `pbr: false` unless the user explicitly asks for PBR** (the API itself defaults it to true); `pbr: true` forces `texture: true`. `texture: false, pbr: false` = bare geometry, no texture credits | | `texture_quality` | `standard` | `standard` / `detailed` (HD, +10 credits) / `extreme` (8K, +20). API also has `fast` (v3.5 textures only; same price/size as `standard`): it needs `texture_version: "v3.5"` (`v3.5-20260815`), which the tool picks when `texture_version` is omitted; other texture versions are incompatible | | `texture_version` | derived from `model` | pins the texture model independently of geometry: `v3.5` (`v3.5-20260815`, newest), `v3.0` (`v3.0-20250812`, default for v3.x and P-series), `v2.5` (`v2.5-20250123`, default for v2.5). Pass the short name. All generation models incl. P1/P2 | | `delight` | `true` | v3.5 textures only (`texture_version: "v3.5"`): remove baked-in lighting from the reference image; `false` keeps original shading. Older texture versions ignore it | | `geometry_quality` | `standard` | `detailed` = Ultra geometry, finer detail up to 2M faces (+20). v3.x only | -| `quad` | `false` | quad mesh (+5); **delivered as FBX** — quads cannot be stored in GLB. v3.x and P2 | +| `quad` | `false` | quad mesh (+5 on v3.1, none on P2); **delivered as FBX** — quads cannot be stored in GLB. v3.x and P2 | | `smart_low_poly` | `false` | hand-modelled-style low-poly topology (+10); requires `face_limit` 500–20000 tri / 500–10000 quad. v3.x only | -| `generate_parts` | `false` | editable segmented parts (+20). Requires `texture: false, pbr: false` (the tool flips them and notes it — re-texture afterwards with `tripo_texture`); `quad` is ignored; `smart_low_poly` wins and suppresses parts. v3.x only | +| `generate_parts` | `false` | editable segmented parts (+20). Requires `texture: false, pbr: false` (the tool flips them and notes it — re-texture afterwards with `tripo_texture`); `quad` is ignored; `smart_low_poly: true` with it is rejected (upstream it would win and produce no parts) — choose one. v3.x only | | `auto_size` | `false` | scale the model to real-world metres (AR, engines) | | `compress` | – | `geometry` = meshopt-compressed output. v3.x only | | `model_seed`, `texture_seed`, `image_seed` | random | reproducibility: same seed → same geometry / textures / text-to-image stage. Keep `model_seed`, vary `texture_seed` to re-texture the same shape | | `enable_image_autofix` | `false` | image input: repair a low-quality / blurry / cropped photo first (slower) | | `texture_alignment` | `original_image` | image/multiview: `original_image` matches the picture, `geometry` matches the mesh | | `orientation` | `default` | image/multiview: `align_image` faces the model like the input viewpoint | -| `export_uv` | `true` | P series only: `false` skips UV unwrap (faster, smaller file; UVs are created when texturing) | +| `export_uv` | `true` | `false` skips UV unwrap (faster, smaller file; UVs are created when texturing) | | `export_orientation` | `+x` | forward axis `+x` `-x` `+y` `-y`. **Only for output that is not processed further**: downstream steps (texture, rig, convert…) read the default orientation and return a wrongly oriented `success` with no error. When a chain follows, leave it unset and pass `export_orientation` to the final `tripo_convert` instead | Multiview (2–4 images): `front` is mandatory and at least two views are needed; @@ -82,21 +82,21 @@ except: `tripo_animate` (`task_id` of a successful rig task), | MCP tool | arguments and constraints | | --- | --- | -| `tripo_texture` | `texture_quality` `standard`/`detailed`/`extreme`/`fast` (fast requires v3.5); `pbr` (send `false` unless the user explicitly asks for PBR); `texture_seed`; `texture_alignment`; `model` `v3.0` (`v3.0-20250812`, default) / `v3.5` (`v3.5-20260815`, newest; unlocks `delight` and `texture_quality: "fast"`) / `v2.5`; `bake`; `part_names` (segmented models); `compress`. Guidance — exactly one of `prompt` (+ optional `style_image`), `image`, or `images` (4 views front/left/back/right). Re-textures any model, including imported files | +| `tripo_texture` | `texture_quality` `standard`/`detailed`/`extreme`/`fast` (fast requires v3.5); `pbr` (send `false` unless the user explicitly asks for PBR); `texture_seed`; `texture_alignment`; `model` as the short name: `v3.0` (`v3.0-20250812`, default) / `v3.5` (`v3.5-20260815`, newest; unlocks `delight` and `texture_quality: "fast"`, picked automatically for them when `model` is omitted) / `v2.5`; `bake`; `part_names` (segmented models); `compress`. Guidance — exactly one of `prompt` (+ optional `style_image`), `image`, or `images` (4 views front/left/back/right). Re-textures any model, including imported files | | `tripo_mesh_edit` | P2 regional regenerate: `input` (task_id / file_token / URL) + axis-aligned `bbox` in model space; optional `ref_image`. Rest of mesh kept. Billed separately | | `tripo_plan` | Free draft of the tool chain **before** any billed call; show the user and wait for confirmation. Skip only for pure reads (balance / usage / task status) | -| `tripo_convert` | `format` `GLTF` `USDZ` `FBX` `OBJ` `STL` `3MF` (3MF = single-colour print). Mesh: `quad`, `force_symmetry` (quad only), `face_limit` (default: keep), `flatten_bottom` + `flatten_bottom_threshold` (0.01). Texture: `texture_size` (4096), `texture_format` `JPEG`/`PNG`/`WEBP`/`BMP`/`TIFF`/`TARGA`/`HDR`/`DPX`/`OPEN_EXR`, `bake` (true), `pack_uv`, `export_vertex_colors` (OBJ/GLTF only). Export: `pivot_to_center_bottom`, `scale_factor`, `auto_size`, `with_animation` (true), `animate_in_place`, `part_names`, `export_orientation`, `fbx_preset` `blender`/`3dsmax`/`mixamo` (FBX only). `quad` with `GLTF` is rejected. Any non-default option bills the complex tier (10 credits instead of 5) | +| `tripo_convert` | `format` `GLTF` `USDZ` `FBX` `OBJ` `STL` `3MF` (3MF = single-colour print). Mesh: `quad`, `force_symmetry` (quad only), `face_limit` (default: keep), `flatten_bottom` + `flatten_bottom_threshold` (0.01). Texture: `texture_size` (4096), `texture_format` `JPEG`/`PNG`/`WEBP`/`BMP`/`TIFF`/`TARGA`/`HDR`/`DPX`/`OPEN_EXR`, `bake` (true), `pack_uv`, `export_vertex_colors` (OBJ/GLTF only). Export: `pivot_to_center_bottom`, `scale_factor`, `auto_size`, `with_animation` (true), `animate_in_place`, `part_names`, `export_orientation`, `fbx_preset` `blender`/`3dsmax`/`mixamo` (FBX only). `quad` with `GLTF` is rejected. A non-default `quad`, `flatten_bottom`/`flatten_bottom_threshold`, `texture_size`, `texture_format`, `pivot_to_center_bottom` or `scale_factor`, or any `face_limit`, bills the complex tier (10 credits instead of 5); the other options do not | | `tripo_import_model` | GLB/GLTF/FBX/OBJ/STL ≤150 MB via `file_token` or URL (`.gltf` only as a URL — upload `.glb`) | | `tripo_rig_check` | free. GLB input. Result: `riggable` and recommended `rig_type`: `biped` `quadruped` `hexapod` `octopod` `avian` `serpentine` `aquatic`. Gate step — not riggable → stop; riggable → rig the **original model task**, not the check task | -| `tripo_rig` | `model`: `v3.0-20260909` (`v3.0`) for biped/default, `others` and `actorcore`/`unity`/`unreal`/`vrm` specs; `v2.5-20260210` (`v2.5`) for the six creature body types. Both take `preset:walk` / `preset:idle` on bipeds and body-type clips on creatures. Explicit `v1.0-20240301` (`v1.0`) is legacy biped-only for 90+ `preset:biped:*` clips. Read the returned model before animation. `rig_type` comes from rig-check; rig the original model, not the check task. `spec` is biped-only; `out_format` is `glb`/`fbx`. | +| `tripo_rig` | `model`: always pass it by body type: `v3.0` (`v3.0-20260909`) for `biped` and `others`, `v2.5` (`v2.5-20260210`, the official animal rig) for `quadruped`/`hexapod`/`octopod`/`avian`/`serpentine`/`aquatic`. When it is omitted the MCP sends v3.0 for every body type, and the API's own default is `v1.0-20240301`, which rigs bipeds only. v3.0 is required for `others` and the `actorcore`/`unity`/`unreal`/`vrm` specs. Both take `preset:walk` / `preset:idle` on bipeds and body-type clips on creatures. Explicit `v1.0-20240301` (`v1.0`) is legacy biped-only for 90+ `preset:biped:*` clips. Read the returned model before animation. `rig_type` comes from rig-check; rig the original model, not the check task. `spec` is biped-only; `out_format` is `glb`/`fbx`. | | `tripo_animate` | needs a rig task. `animations: [...]` (≤5, billed per clip). `out_format` `glb`/`fbx`, `animate_in_place` (no root motion — game code drives movement), `export_with_geometry` (true); `bake_animation` is deprecated — do not pass it (it is ignored) | -| `tripo_segment` | `model` `v1.0-20250506` (geometry-based, default) or `v2.0-20260430` (semantic, beta) with `segmentation_granularity` `simple`/`balanced`/`detailed`, `split_by_connectivity` (true), `ref_image` (overrides the other two). The tool switches to v2.0 automatically when a v2-only argument is set | +| `tripo_segment` | `model` `v1.0-20250506` (geometry-based, default) or `v2.0-20260430` (semantic, beta) with `segmentation_granularity` `simple`/`balanced`/`detailed`, `split_by_connectivity` (true), `ref_image` (overrides the other two). The tool switches to v2.0 automatically when a v2-only argument is set without `model`; an explicit `v1.0-20250506` with any of them is rejected and no task is created | | `tripo_mesh_complete` | needs a segment task. `completion_mode` `ai_completion` (default) / `quick_cap` (hole fill, cheaper); `part_names` (default all) | | `tripo_decimate` | `face_limit` target 500–20000 tri / 500–10000 with `quad: true` (docs quote 1000–20000); `bake` (true) bakes textures onto the low-poly; `part_names`. `model: "v1.0"` accepts up to 2 000 000 tri / 150 000 quad but requires `face_limit` and has no `bake`/`part_names`. The budget is a target, not a ceiling | | `tripo_smart_segment` | file_token/URL only. `seg_type` `model` (existing **GLB only**, 55 credits; default) or `image` (photo → auto-model → parts, 85); `granularity` `coarse`/`medium`/`fine`; `hint` describing the parts to find. Output: part labels, a PNG mask, the segmented GLB and the inner task ids. Unlike `tripo_segment`, it is an end-to-end pipeline | Animation presets depend on the rig model of the upstream rig task — read it -from the `tripo_rig` result (biped defaults to v3.0). v3.0 and v2.5 biped rigs: `preset:idle` `preset:walk` `preset:run` `preset:dive` +from the `tripo_rig` result (this skill passes v3.0 for bipeds and v2.5 for animal body types). v3.0 and v2.5 biped rigs: `preset:idle` `preset:walk` `preset:run` `preset:dive` `preset:climb` `preset:jump` `preset:slash` `preset:shoot` `preset:hurt` `preset:fall` `preset:turn`; creature rigs take only their body type's clip: `preset:quadruped:walk` `preset:hexapod:walk` `preset:octopod:walk` `preset:serpentine:march` `preset:aquatic:march` (avian and others have none). v1.0 rig @@ -175,31 +175,31 @@ by 16; use 1088x1920 instead. No 1K/2K/4K tiers for chat_image models. ## Prices -Historical examples only, not a current regional estimate. The effective region -and date of the retained numbers below have not been verified. -Numeric prices and add-ons anywhere in this file (including processing tables) -are historical illustrations, not a price quote or dry-run estimate. A current -estimate must name its source, region and date and match the exact model/options. -If current regional pricing cannot estimate the request, report **not_estimated** -(unestimated), not zero; disclose that uncertainty and obtain consent before -billing. Never infer a fixed P2/P1 ratio or fill a plan with these static numbers. +Official list prices from the Tripo pricing pages (developers.tripo3d.com/zh/pricing +and developers.tripo3d.ai/pricing; the same numbers in both regions), checked on +2026-10-30. Numeric prices and add-ons anywhere in this file (including processing +tables) come from those pages. An estimate must name its source, region and date and +match the exact model/options. If this table cannot price the request (a legacy model +or anything not listed), report **not_estimated** (unestimated), not zero; disclose +that uncertainty and obtain consent before billing. Never infer a fixed P2/P1 ratio. Afterwards use the usage ledger and task `credits_consumed` for actual spending; `balance` and `credits_consumed` are decimals, not integers: -| operation (historical example only) | historical credits, not an estimate | +| operation | official list credits | | --- | --- | | text-to-3D, v3.1 | 10 bare / 20 textured | | image- or multiview-to-3D, v3.1 | 20 bare / 30 textured | | text-to-3D, P1 | 30 bare / 40 textured (P2: 100 / 110) | | image- or multiview-to-3D, P1 | 40 bare / 50 textured (P2: 100 / 110) | -| add-ons per generation | `texture_quality: "detailed"` +10, `"extreme"` +20, `geometry_quality: "detailed"` +20, `quad` +5, `smart_low_poly` +10, `generate_parts` +20 | +| add-ons per generation | `texture_quality: "detailed"` +10, `"extreme"` +20; v3.1 only: `geometry_quality: "detailed"` +20, `quad` +5, `smart_low_poly` +10, `generate_parts` +20 (P2 `quad` has no surcharge) | | `tripo_texture` | 10 standard / 20 detailed / 30 extreme | -| `tripo_convert` | 5, or 10 with any non-default option | +| `tripo_convert` | 5, or 10 with a complex-tier option (see the convert row) | | `tripo_decimate` | 35 tri / 40 quad (v3.0; smart_uv included), 30 (v2.0), 10 (v1.0) | +| `tripo_smart_uv` | 20 | | `tripo_segment` / `tripo_mesh_complete` | 40 / 50 (`quick_cap` 30) | | `tripo_smart_segment` | 85 image / 55 model | | `tripo_rig_check` / `tripo_rig` / `tripo_animate` | free / 25 / 10 per clip | -| `tripo_generate_image` | 5 (seedream, banana 1K) – 20 (banana_pro 4K) by model and size tier | +| `tripo_generate_image` | 5 (seedream, banana 1K) – 20 (banana_pro 4K) by model and size tier; GPT image `quality` `high` / `xhigh` / `max` 20–50 | | `tripo_image_to_multiview` / `tripo_edit_multiview` / `tripo_image_to_splat` | 10 / 5 per edited view / 30 | Credits are frozen at submission and released on failure, ban or cancellation — diff --git a/plugins/tripo-3d/skills/tripo-game-asset/SKILL.md b/plugins/tripo-3d/skills/tripo-game-asset/SKILL.md index a7ec7720..b983c960 100644 --- a/plugins/tripo-3d/skills/tripo-game-asset/SKILL.md +++ b/plugins/tripo-3d/skills/tripo-game-asset/SKILL.md @@ -15,8 +15,8 @@ unless the user explicitly asks for PBR. The point of these recipes is that assets land in the project's own directory structure: after each final step download the file with -`curl -L -o /. ""` (links expire in about -5 minutes — fetch fresh ones with `tripo_task_status` if needed) and report the +`curl -L -o /. ""` (links expire after about +2 hours — fetch fresh ones with `tripo_task_status` if needed) and report the local path. ## Pick a budget first @@ -34,8 +34,8 @@ model, texture options and estimated cost; re-confirm any paid model change. Two budget-related choices the defaults do not make for you: -- **Quads at low poly** — P1 rejects `quad`; use `model: "P2", quad: true` - (face_limit 48–25000 quads, price depends on input and texture options; +- **Quads at low poly** — P1 does not support `quad` (the tool strips it); use `model: "P2", quad: true` + (face_limit 48–25000 quads, price depends on texture options; confirm the estimate, output is FBX) or v3.1 with `smart_low_poly: true, quad: true` (face_limit 500–10000). - **v3.1 quality under a face cap** — explicitly set `model: "v3.1"` when the @@ -51,7 +51,7 @@ Override the face budget when the project has a stricter one, e.g. → download the GLB (or → `tripo_convert` `{ format: "FBX" }` for Unity/Unreal). For a set of props, generate them one at a time and check each -`preview_image_url` before continuing — a bad seed early is cheaper to catch +result before continuing — a bad seed early is cheaper to catch than at the end of a batch. Confirm the total cost of the whole set with the user first (`tripo_plan`, `tripo_balance`), then call the tools one asset at a time, and use `tripo_task_list` to check the status of many task ids in one @@ -91,11 +91,15 @@ skill). 3. `tripo_rig_check` `{ input: }` — free. It gates the chain: not riggable → stop before spending rigging credits. Read the recommended `rig_type` (`biped` `quadruped` `hexapod` `octopod` `avian` `serpentine` `aquatic`). -4. `tripo_rig` `{ input: , rig_type: , spec: "mixamo", out_format: "fbx" }` +4. `tripo_rig` `{ input: , model: "v3.0", rig_type: , spec: "mixamo", out_format: "fbx" }` — rig the **original model task**, not the check task. `spec: "mixamo"` - produces a Unity Humanoid-compatible skeleton. Leave `model` unset: `biped` - gets v3.0, the six creature body types get v2.5, and the - result names the preset family to use next. + gives Mixamo bone names (`"unity"` for Unity Humanoid, `"unreal"` for the UE + Mannequin); `spec` applies to `biped` + only, so drop it for the other body types (the tool rejects it). Pass + `model: "v3.0"` for `biped` and `model: "v2.5"` for the animal types + (`quadruped` `hexapod` `octopod` `avian` `serpentine` `aquatic`): the API's + own default, v1.0, rigs bipeds only. The result names the preset family to + use next. 5. `tripo_animate` `{ task_id: , animations: [...], out_format: "fbx", animate_in_place: true }` — at most five clips, billed per clip. Explicit legacy v1.0 rigs take `preset:biped:idle` `preset:biped:walk` `preset:biped:run` `preset:biped:jump` From d8483139c4b21f8f3a998e9ddb13f51cccebcad5 Mon Sep 17 00:00:00 2001 From: sunzhenqiang Date: Mon, 2 Nov 2026 18:48:20 +0800 Subject: [PATCH 4/8] refactor(tripo-3d): enhance documentation and clarify model selection process - Updated README and skill documentation to emphasize that a user's explicitly chosen compatible model takes precedence over usage-based defaults. - Clarified billing and cost estimation processes, ensuring users are informed about unestimated steps and required confirmations. - Revised hook rules to maintain PBR off by default unless explicitly requested, and detailed the implications of model selection on billing. - Enhanced capability reference to reflect the latest changes in model handling and processing workflows. --- plugins/tripo-3d/README.md | 10 +- plugins/tripo-3d/README_CN.md | 11 +- plugins/tripo-3d/hooks/session-start.mjs | 8 +- plugins/tripo-3d/skills/tripo-3d/SKILL.md | 102 +++++++++++------- .../skills/tripo-3d/references/capability.md | 39 ++++--- .../tripo-3d/skills/tripo-game-asset/SKILL.md | 25 +++-- 6 files changed, 118 insertions(+), 77 deletions(-) diff --git a/plugins/tripo-3d/README.md b/plugins/tripo-3d/README.md index b2e91cb3..3a29b17c 100644 --- a/plugins/tripo-3d/README.md +++ b/plugins/tripo-3d/README.md @@ -4,6 +4,7 @@ ## 0.1.5 +A user's explicitly chosen compatible model overrides usage-based defaults. Game/realtime recipes explicitly prefer **P2** (more credits than H/P1), the P-series default; **P1** is used only when the user names it or picks it for lower cost and speed, and v3.1 for film/render/print. Rigs pass the model @@ -15,8 +16,9 @@ Fast textures require v3.5; `chat_image_1` is retired. The plugin runs through the Tripo MCP tools only — there is no CLI path, and missing authorization is never a reason to switch to one. PBR stays off unless -you explicitly ask for it. A plan is not a price quote: cost is not estimated -here, and uncertainty needs explicit consent. Never switch accounts silently. +you explicitly ask for it. A plan is advisory, not a price quote or budget lock. +Show estimated or unestimated costs, cite the source, region and date of any +static list estimate, and obtain explicit consent. Never switch accounts silently. The hook also enforces the PBR default and explicit model/billing decisions. The official Tripo plugin for ZCode. Generate textured 3D models from a text @@ -74,8 +76,8 @@ The Tripo MCP server needs a one-time authorization: (developers.tripo3d.com). Results are downloaded from Tripo's CDN through short-lived links (about 2 hours). - **Account and billing**: every generation spends credits from your own - Tripo account; each tool reports `credits_consumed`, failed tasks are - refunded automatically. The skill drafts the chain with `tripo_plan`, + Tripo account; use task status and the usage ledger for actual charges. Failed + tasks are refunded automatically. The skill drafts the chain with `tripo_plan`, checks the balance and asks before generating a batch. - **File writes**: only when you ask for the model on disk, the agent downloads it into your project with `curl`. The hook and the MCP server diff --git a/plugins/tripo-3d/README_CN.md b/plugins/tripo-3d/README_CN.md index ada5f332..b9a2dc2d 100644 --- a/plugins/tripo-3d/README_CN.md +++ b/plugins/tripo-3d/README_CN.md @@ -4,14 +4,15 @@ ## 0.1.5 -游戏/实时资产显式优先选择 **P2**(积分高于 H/P1),使用 P 系列时默认 **P2**;**P1**(积分更低、速度更快)仅在用户明确指定或选择时使用, -影视/渲染/打印用 v3.1。绑骨默认 v3.0,动画预设须跟随上游 rig 模型。 +用户明确指定的兼容模型优先于按用途选择的默认值;游戏/实时资产显式优先选择 **P2**(积分高于 H/P1),使用 P 系列时默认 **P2**;**P1**(积分更低、速度更快)仅在用户明确指定或选择时使用, +影视/渲染/打印用 v3.1。绑骨按体型显式指定:双足 v3.0,动物 v2.5;动画预设须跟随上游 rig 模型。 重拓扑 v3.0 的 `smart_uv` 与独立 `tripo_smart_uv` 是不同计费流程。 fast 贴图需 v3.5;`chat_image_1` 已退役。 插件只通过 Tripo MCP 工具执行,没有 CLI 路径;未授权也不会改走 CLI。PBR 默认关闭, -只有你明确要求时才开启。计划不是报价,本文**费用未估算**,计费前须说明不确定性并 -获得确认。禁止自动切换账号。Hook 同步执行 PBR 默认关闭与选模/计费约束。 +只有你明确要求时才开启。计划仅供参考,不是实时报价或预算锁;静态价格估算须说明 +来源、区域和日期,未估算的步骤须明确标出,计费前取得确认。禁止自动切换账号。 +Hook 同步执行 PBR 默认关闭与选模/计费约束。 Tripo 官方 ZCode 插件。用一句话或一张图生成带贴图的 3D 模型,支持骨骼绑定、动画、 减面和格式转换(GLB/FBX/OBJ/STL/USDZ/3MF),文件直接落到你的项目里。覆盖游戏、 @@ -53,7 +54,7 @@ API Key。本构建的 MCP 只对接国内站;海外站账号请安装海外 ## 依赖、网络访问与副作用 - **网络**:MCP 工具调用走 `https://developers.tripo3d.com/mcp`;授权页跳转到国内站 Tripo 控制台(developers.tripo3d.com)。生成结果通过 Tripo 的 CDN 短期链接(约 2 小时过期)下载。 -- **账号与计费**:所有生成任务消耗你自己 Tripo 账号的积分,每次工具返回 `credits_consumed`;失败任务自动退款。批量生成前 skill 会先用 `tripo_plan` 草稿、查余额并确认。 +- **账号与计费**:所有生成任务消耗你自己 Tripo 账号的积分,通过任务状态与用量账单核对实际消耗;失败任务自动退款。批量生成前 skill 会先用 `tripo_plan` 草稿、查余额并确认。 - **文件写入**:只在你要求把模型落到本地时,用 `curl` 把结果下载到项目目录;Hook 与 MCP 服务器本身不写任何文件。 - **命令执行**:仅在上传本地图片/模型(`tripo_upload_ticket` 返回的 curl)或下载结果时运行 shell 命令。插件不会安装或调用任何命令行客户端,MCP 失败、未授权、批量或本地落盘需求也不例外。 - **Hook**:`hooks/session-start.mjs` 依赖 PATH 中的 `node`,只从 stdin 读取事件、向 stdout 输出一段固定文本,不访问网络、不读写文件。 diff --git a/plugins/tripo-3d/hooks/session-start.mjs b/plugins/tripo-3d/hooks/session-start.mjs index ea39592e..af7e310d 100644 --- a/plugins/tripo-3d/hooks/session-start.mjs +++ b/plugins/tripo-3d/hooks/session-start.mjs @@ -6,11 +6,11 @@ const RULES = `Tripo 3D — rules that apply whenever Tripo tools (tripo_*) are used. These hold even when the tripo-3d skill was not loaded; load it for the full workflow. 1. Generation is asynchronous. Every tripo_* generation or processing tool returns a task_id immediately. Call tripo_task_wait with it and keep calling while status is queued/running — each call returns within about 55 seconds, a generation usually takes 1–4 minutes. Never present a result before status is success, and never treat a task_id as a finished model. 2. Deliver the file, then one link. On success, download model_url to a local file when a shell is available and give its path as plain text in backticks, never as a clickable link (chat previews cannot render meshes); then also offer model_url as a single markdown download link. Do not paste URLs from output_urls into the reply. Result URLs expire after about 2 hours: never re-print an old one — call tripo_task_status for fresh links. -3. Credits belong to the user. Call tripo_plan and get confirmation before any billed generation or chain. Every billed tool reports credits_consumed. Check tripo_balance and confirm before generating more than one asset in a batch; on insufficient balance give the returned plans_url instead of retrying. Never silently re-roll a disappointing result — say what is off and ask first. +3. Credits belong to the user. Call tripo_plan and get confirmation before any billed generation or chain; supply structured generation only for tripo_text_to_3d, tripo_image_to_3d and tripo_multiview_to_3d, including the exact text prompt for text-to-3D; never add generation to other steps such as tripo_image_to_splat. For those three use dry_run only when the connected schema exposes it; validate other steps against their schemas and current pricing. Resolve user-requested parameter conflicts before billing. Plan estimates are advisory, not a budget lock; label unknown costs not_estimated, and cite source, region and date for any static list estimate. Use tripo_usage for all task_ids to report actual total and per-task charges; if unavailable say the amount is pending. Check tripo_balance and confirm before generating more than one asset in a batch; on insufficient balance give the returned plans_url instead of retrying. Never silently re-roll a disappointing result — say what is off and ask first. 4. Authorization is a browser flow, never a pasted key. This build's MCP is China-mainland only (developers.tripo3d.com/mcp); the auth page has no region picker. If Tripo tools are missing or a call reports an authorization error, tell the user to open ZCode 设置 → MCP, find the Tripo server under「Plugin MCP 服务器」and click「打开授权」, then sign in on the 国内站 console and Authorize. An overseas-site account needs the overseas plugin build. Do not ask for an API key in the chat. MCP is the only execution path: never install or run a command-line client instead, even when a local login or API key exists. -5. Failures are reported, not hidden. On failed/banned, relay failure_reason (and error_code) honestly; failed-task credits are refunded automatically. Never invent parameters — the tool schemas are authoritative. Stylize has been retired: there is no tripo_stylize tool. Use tripo_mesh_edit for P2 regional redo. -6. PBR is opt-in. Send pbr: false on every generation and tripo_texture call unless the user explicitly asks for PBR (e.g. "with PBR", 「PBR 材质」); only then send pbr: true, which also forces texture: true. The API turns PBR on when pbr is omitted, so never leave it out. Detailed or high-quality textures do not mean PBR. -7. Choose models explicitly: P2 is preferred for game/realtime topology and costs more credits than H/P1; within the P series the default is P2, and P1 is used only when the user names it or picks it for lower cost and speed; v3.1 for film/render/print. Do not infer the model from face_limit. Cost is not estimated by this text or guaranteed by tripo_plan: disclose uncertainty and obtain consent before billing. Pass the rig model explicitly: v3.0 for bipeds, v2.5 for animal body types (the API's own default is v1.0, which rigs bipeds only); use preset:walk, reserving preset:biped:* for explicit v1.0 rigs. Retopology v3.0 with smart_uv and standalone tripo_smart_uv are separate workflows, not interchangeable free export switches. Load the capability reference before running either. chat_image_1 is retired; never fall back to it. fast textures require texture model v3.5: pass the short name v3.5, or omit the version and the tool picks it. +5. Failures are reported, not hidden. On failed/banned, relay failure_reason (and error_code) honestly; failed-task credits are refunded automatically. Never invent parameters — the tool schemas are authoritative. If a creation call times out without a task_id, do not automatically retry: check the original account's balance and task history when available and ask before another submission. Stylize has been retired: there is no tripo_stylize tool. tripo_mesh_edit is experimental; use it only if the connected server lists it. +6. PBR is opt-in. Send pbr: false on every tripo_text_to_3d, tripo_image_to_3d, tripo_multiview_to_3d and tripo_texture call unless the user explicitly asks for PBR (e.g. "with PBR", 「PBR 材质」); only then send pbr: true, which also forces texture: true. The API turns PBR on when pbr is omitted, so never leave it out. Detailed or high-quality textures do not mean PBR. +7. Choose models explicitly: the user's explicit compatible model wins over usage-based defaults; if requirements conflict, explain and ask before changing model or dropping a requirement. P2 is preferred for game/realtime topology and costs more credits than H/P1; within the P series the default is P2, and P1 is used only when the user names it or picks it for lower cost and speed; v3.1 for film/render/print. Do not infer the model from face_limit. Cost is not estimated by this text or guaranteed by tripo_plan: disclose uncertainty and obtain consent before billing. Pass the rig model explicitly: v3.0 for bipeds, v2.5 for animal body types (the API's own default is v1.0, which rigs bipeds only); use preset:walk, reserving preset:biped:* for explicit v1.0 rigs. Retopology v3.0 with smart_uv and standalone tripo_smart_uv are separate workflows, not interchangeable free export switches. Load the capability reference before running either. chat_image_1 is retired; never fall back to it. chat_image_1.5 remains usable where supported before 2026-12-01; never silently replace a user-selected paid image model. fast textures require texture model v3.5: pass the short name v3.5, or omit the version and the tool picks it. `; let raw = ""; diff --git a/plugins/tripo-3d/skills/tripo-3d/SKILL.md b/plugins/tripo-3d/skills/tripo-3d/SKILL.md index 6be3c2cc..d1f76f77 100644 --- a/plugins/tripo-3d/skills/tripo-3d/SKILL.md +++ b/plugins/tripo-3d/skills/tripo-3d/SKILL.md @@ -6,9 +6,10 @@ description: Generate a 3D model from a text prompt, a reference image, or an ex # Tripo 3D Generate engine-ready 3D assets with the Tripo MCP tools. -The cost is not estimated by this document: show a live estimate if available, -otherwise disclose that uncertainty and obtain explicit consent before any -billed task. A plan is not a quote. +Use a live estimate if available. A dated list-price estimate may be shown with +its source, region and date, but is not a live quote; disclose any unestimated +steps and obtain explicit consent before any billed task. A plan is advisory, +not a budget limit or an authorization ticket. ## Before you start @@ -63,13 +64,25 @@ too. ## Workflow -1. **Plan** — for any billed generation or chain, call `tripo_plan` first, - show the draft to the user, and wait for explicit confirmation. Skip only - for pure reads (`tripo_balance`, `tripo_usage`, `tripo_task_status` / - `tripo_task_list`). +1. **Plan** — for any billed generation or chain, call `tripo_plan` first. + For `tripo_text_to_3d`, `tripo_image_to_3d` and `tripo_multiview_to_3d` + steps only, supply a structured `generation` object; include the exact + `prompt` for text-to-3D. Never attach `generation` to other tools, including + `tripo_image_to_splat`. Free-text `params` alone leave the model unresolved. + For these three generation tools, review the exact payload with `dry_run` only + when the connected tool schema exposes it. For other steps review their actual + schemas and current pricing without inventing a `dry_run` argument. Resolve + conflicts with explicit requirements before billing; do not accept silently + stripped requirements. + Show each billed step, selected model, options and estimate or + `not_estimated` to the user, and wait for explicit confirmation. Skip the + plan only for pure reads (`tripo_balance`, `tripo_usage`, `tripo_task_status` + / `tripo_task_list`). Re-plan and reconfirm changed paid steps. 2. **Create** — `tripo_text_to_3d` for prompts (Chinese or English, concrete nouns + style + materials), `tripo_image_to_3d` for images. Both return a - `task_id` immediately. + `task_id` immediately. If creation times out without a `task_id`, do not + automatically retry: check the original account's balance and task history + when available, then ask the user before considering another submission. 3. **Wait** — call `tripo_task_wait` with the `task_id`; each call returns within about 55 s, so call it again while status is still `queued`/`running` (a generation takes 1–4 minutes). Do not invent your own sleep loop and do @@ -80,10 +93,12 @@ too. `failure_reason` honestly; failed-task credits are refunded automatically. Do not silently re-roll a disappointing result — say what is off and ask; re-rolling means creating a new task with the same prompt. -5. **Post-process** (each step is a new billed task: create → `tripo_task_wait`; - `input` takes a model task_id, a `file_token` or a public model URL unless - noted): - - `tripo_texture` — texture or re-texture a model. +5. **Post-process** (each asynchronous task requires `tripo_task_wait`; check + billing for each step — `tripo_rig_check` is free. `input` takes a model + task_id, a `file_token` or a public model URL unless noted): + - `tripo_texture` — texture or re-texture a model. Provide guidance for an + imported mesh; it may be omitted for a Tripo-generated model. Re-supply + the original reference image when re-texturing a model made from one. - `tripo_rig_check` → `tripo_rig` — check riggability before spending rig credits, then add a skeleton with the `rig_type` the check returned. Prompt characters as **T-pose** at generation time; `spec: "unity"` for @@ -105,9 +120,10 @@ too. `pivot_to_center_bottom` or `scale_factor`, bills as "complex convert". - `tripo_decimate` — high-poly → low-poly (`face_limit` 500–20000, bakes the original textures); `tripo_segment` → `tripo_mesh_complete` — split into - parts and close the cuts; `tripo_mesh_edit` — redo one region of an - existing mesh with P2 (`bbox` required). Stylize (lego / voxel / - voronoi / minecraft) has been retired — there is no `tripo_stylize` tool. + parts and close the cuts. `tripo_mesh_edit` can redo one region of an + existing mesh with P2 (`bbox` required). It is experimental; use it only + when the connected server's actual tool list exposes it. Stylize (lego / + voxel / voronoi / minecraft) has been retired — there is no `tripo_stylize` tool. 6. **Deliver** — result URLs (`model_url` and `output_urls`) **expire after about 2 hours**; never cache or re-print an old one — call `tripo_task_status` for fresh links. Download the file into the project @@ -121,12 +137,17 @@ too. request. Do not paste other URLs from `output_urls`. After a `tripo_convert`, the native GLB stays on the earlier task — fetch it with `tripo_task_status` on that task instead of paying for another conversion. + Call `tripo_usage` with all workflow task IDs and report actual total and + per-task charges; if the ledger is unavailable, say the amount is pending. ## Scenario → tool chain -Pick the chain from what the user is building; every arrow is a billed task -followed by `tripo_task_wait`. GLB is the native output — a `tripo_convert` -step is only worth its credits when the target really needs another format. +Pick the chain from what the user is building; each asynchronous task must +finish before a dependent step runs. Check each tool's billing and input rules: +`tripo_rig_check` is free and rig uses the original model, not the check task. +The examples below are suggestions only; an explicitly requested compatible +model overrides the usage-based default. GLB is the native output — a +`tripo_convert` step is only worth its credits when the target needs another format. - **Game prop, mobile / WebGL / many instances** — generate with explicit `model: "P2"` and a confirmed `face_limit` → @@ -149,9 +170,9 @@ step is only worth its credits when the target really needs another format. `["preset:walk", "preset:idle"]`; creatures use their body-specific presets (e.g. `preset:quadruped:walk`); explicit v1.0 humanoids alone use `preset:biped:*`. -- **LOD chain** — generate once → one `tripo_decimate` per level - (`face_limit` is a target, not a hard ceiling — say so when the project has - a strict budget). +- **LOD chain** — generate once → one `tripo_decimate` per level, each using + the original generation task as input, not the previous LOD (`face_limit` is + a target, not a hard ceiling — say so when the project has a strict budget). - **Better views of one image** — `tripo_image_to_multiview` → `tripo_multiview_to_3d` with `multiview_task_id`; when the user already has 2–4 orthographic views, `tripo_multiview_to_3d` takes them directly. @@ -166,13 +187,17 @@ step is only worth its credits when the target really needs another format. ## Parameters that matter -- **Choose the generation model explicitly**: P2 for game/realtime topology - (costs more credits than H/P1); within the P series the default is P2, and P1 is - used only when the user names it or picks it for lower cost and speed. Use v3.1 - for film/render/print. This is plugin policy, not an API requirement. Confirm - the model, texture options and cost; re-confirm any paid model change. -- **PBR is opt-in.** Send `pbr: false` on every generation and `tripo_texture` - call unless the user explicitly asks for PBR materials (for example "with +- **Choose the generation model explicitly**: the user's explicitly chosen model + wins over usage-based defaults. If it conflicts with required features, explain + the conflict and ask before changing model or dropping a requirement. Otherwise, + P2 is preferred for game/realtime topology (costs more credits than H/P1); + within the P series the default is P2, and P1 is used only when the user names it + or picks it for lower cost and speed. Use v3.1 for film/render/print. This is + plugin policy, not an API requirement. Confirm the model, texture options and + cost; re-confirm any paid model change. +- **PBR is opt-in.** Send `pbr: false` on every `tripo_text_to_3d`, + `tripo_image_to_3d`, `tripo_multiview_to_3d` and `tripo_texture` call unless + the user explicitly asks for PBR materials (for example "with PBR" or 「PBR 材质」); only then send `pbr: true`, which also forces `texture: true`. The API turns PBR on when `pbr` is left out, so never omit it. Detailed or high-quality textures do not mean PBR. PBR can still be added @@ -185,7 +210,8 @@ step is only worth its credits when the target really needs another format. credits entirely; convert to `STL` (add `flatten_bottom: true` for stability). - `quad: true` (v3.1 or P2) is delivered as FBX directly, so FBX needs no `tripo_convert`; a convert with `quad: true` always outputs FBX (GLTF is - rejected). P1 does not support `quad` (the tool strips it and notes it). + rejected). P1 does not support `quad`; if the user requests both, stop and + ask which requirement to change before creating a paid task. ## Inputs @@ -202,10 +228,11 @@ step is only worth its credits when the target really needs another format. - Model files (GLB/FBX/OBJ/STL, ≤150 MB) use the same ticket with `kind: "model"` and `format`; the `file_token` then feeds `tripo_import_model` or any processing tool directly. -- Task ids chain: a successful generation task is a valid `input` for every - processing tool, so never re-upload what Tripo already has. A task id only - resolves under the API key that created it; when an older task is not found, - upload the local model file instead. +- Task ids chain: use a successful model task where the processing tool accepts + it. Animation requires a successful rig task, mesh completion a segment task, + and smart segmentation a file token or URL. Rig uses the original model task, + not a rig-check task. A task id only resolves under the API key that created + it; when an older task is not found, upload the local model file instead. ## Other tools @@ -214,8 +241,8 @@ step is only worth its credits when the target really needs another format. per-stage breakdown when a chain misbehaves. - `tripo_task_list` — status of up to 100 task ids in one call (batches). - `tripo_usage` — recent per-task credit spend (includes per-task breakdown). -- `tripo_mesh_edit` — P2 regional regenerate (`bbox` + optional - `ref_image`). +- `tripo_mesh_edit` — experimental P2 regional regenerate (`bbox` + optional + `ref_image`); use only if the connected server lists it. ## Spending the user's credits @@ -235,9 +262,10 @@ step is only worth its credits when the target really needs another format. Model versions, generation/processing parameters, 2D steps and list prices: read [`references/capability.md`](references/capability.md). `tripo_plan` -confirms before spend and `tripo_mesh_edit` redoes a P2 region. +is advisory and requires confirmation before spend; `tripo_mesh_edit` redoes a +P2 region only when the connected server lists the experimental tool. Retopology: `tripo_decimate` with explicit `model: "v3.0", smart_uv: true` -combines retopology and UVs (35 tri / 40 quad credits). Standalone +combines retopology and UVs; check current pricing. Standalone `tripo_smart_uv` is a separate billed UV-layout task for inputs up to 80,000 equivalent triangles; confirm the choice and cost. See the capability reference. diff --git a/plugins/tripo-3d/skills/tripo-3d/references/capability.md b/plugins/tripo-3d/skills/tripo-3d/references/capability.md index e4a25e30..fda1b169 100644 --- a/plugins/tripo-3d/skills/tripo-3d/references/capability.md +++ b/plugins/tripo-3d/skills/tripo-3d/references/capability.md @@ -1,9 +1,10 @@ # Capability reference Mirrors the official API docs so the agent never has to send the user there. -Pass these parameters as MCP tool arguments. The tools auto-fix the linkage -rules below (pbr→texture, model-specific strips, quad→FBX) and report what they -changed in `notes`. +Pass these parameters as MCP tool arguments. Tools may adjust linkage rules +(pbr→texture, model-specific strips, quad→FBX) and report changes in `notes`. +Preflight explicit user requirements first: if an adjustment would remove or +change one, resolve the conflict with the user before creating a paid task. ## Models @@ -16,9 +17,11 @@ changed in `notes`. Website model names map to these rows: H3.1 → `v3.1`, P1.0 → `P1`, P2.0 → `P2`. -Selection policy: explicitly choose P2 for game/realtime topology; within the -P series the default is P2, and P1 is used only when the user names it or picks -it for lower cost and speed; v3.1 for film/render/print. +Selection policy: the explicitly requested model wins over use-based defaults; +resolve incompatible requirements with the user before any paid call. Otherwise, +explicitly choose P2 for game/realtime topology; within the P series the default +is P2, and P1 is used only when the user names it or picks it for lower cost and +speed; v3.1 for film/render/print. This is plugin guidance, not an API requirement. Do not rely on implicit routing or infer a generation model from face_limit. Confirm the model, texture options and estimated cost before a billed call; re-confirm any paid model change. @@ -59,9 +62,8 @@ Multiview (2–4 images): `front` is mandatory and at least two views are needed ## Retopology and UV workflows `tripo_decimate` defaults to v2.0. Explicit `model: "v3.0"` supports -`smart_uv: true` in the same task: 35 credits triangle / 40 quad, versus -30 for v2.0; smart_uv adds no extra charge. Confirm this model/cost change -before submitting. With any other model, `smart_uv: true` is rejected and no +`smart_uv: true` in the same task. Check current pricing and confirm any +model/cost change before submitting. With any other model, `smart_uv: true` is rejected and no task is created. v2.0/v3.0 targets: 500–20000 triangles or 500–10000 quads. The face budget is a target, not a ceiling. The combined task has no UV preview. @@ -75,19 +77,19 @@ paid task for integrated smart_uv without confirming the extra cost. ## Processing steps -Every tool takes a model task_id, a `file_token` or a model URL as `input`, -except: `tripo_animate` (`task_id` of a successful rig task), +Most mesh processing tools accept a model task_id, a `file_token` or a model URL +as `input`. Check each tool's schema; for example: `tripo_animate` (`task_id` of a successful rig task), `tripo_mesh_complete` (`task_id` of a successful segment task) and `tripo_smart_segment` (file_token or URL only, never a task_id). | MCP tool | arguments and constraints | | --- | --- | -| `tripo_texture` | `texture_quality` `standard`/`detailed`/`extreme`/`fast` (fast requires v3.5); `pbr` (send `false` unless the user explicitly asks for PBR); `texture_seed`; `texture_alignment`; `model` as the short name: `v3.0` (`v3.0-20250812`, default) / `v3.5` (`v3.5-20260815`, newest; unlocks `delight` and `texture_quality: "fast"`, picked automatically for them when `model` is omitted) / `v2.5`; `bake`; `part_names` (segmented models); `compress`. Guidance — exactly one of `prompt` (+ optional `style_image`), `image`, or `images` (4 views front/left/back/right). Re-textures any model, including imported files | -| `tripo_mesh_edit` | P2 regional regenerate: `input` (task_id / file_token / URL) + axis-aligned `bbox` in model space; optional `ref_image`. Rest of mesh kept. Billed separately | -| `tripo_plan` | Free draft of the tool chain **before** any billed call; show the user and wait for confirmation. Skip only for pure reads (balance / usage / task status) | +| `tripo_texture` | `texture_quality` `standard`/`detailed`/`extreme`/`fast` (fast requires v3.5); `pbr` (send `false` unless the user explicitly asks for PBR); `texture_seed`; `texture_alignment`; `model` as the short name: `v3.0` (`v3.0-20250812`, default) / `v3.5` (`v3.5-20260815`, newest; unlocks `delight` and `texture_quality: "fast"`, picked automatically for them when `model` is omitted) / `v2.5`; `bake`; `part_names` (segmented models); `compress`. Guidance — select one of `prompt` (+ optional `style_image`), `image`, `images` (4 views front/left/back/right), or native `texture_prompt`; native `texture_prompt` cannot be combined with the shortcut fields. Provide guidance for imported meshes; it may be omitted for Tripo-generated models. Re-supply the original reference image when re-texturing a model made from one. Re-textures any model, including imported files | +| `tripo_mesh_edit` | Experimental P2 regional regenerate: use only when listed by the connected server. `input` (task_id / file_token / URL) + axis-aligned `bbox` in model space; optional `ref_image`. Rest of mesh kept. Billed separately | +| `tripo_plan` | Free advisory draft **before** any billed call. Pass structured `generation` only for `tripo_text_to_3d`, `tripo_image_to_3d` and `tripo_multiview_to_3d`; text-to-3D requires its exact prompt. Do not add `generation` to other steps such as `tripo_image_to_splat`. Review `dry_run` only for these three when their connected schemas expose it; validate other steps against their own schemas. Free-text `params` alone leave the model unresolved. Show billed steps and estimates or `not_estimated`, then wait for explicit confirmation; not a quote or budget lock. Skip only for pure reads | | `tripo_convert` | `format` `GLTF` `USDZ` `FBX` `OBJ` `STL` `3MF` (3MF = single-colour print). Mesh: `quad`, `force_symmetry` (quad only), `face_limit` (default: keep), `flatten_bottom` + `flatten_bottom_threshold` (0.01). Texture: `texture_size` (4096), `texture_format` `JPEG`/`PNG`/`WEBP`/`BMP`/`TIFF`/`TARGA`/`HDR`/`DPX`/`OPEN_EXR`, `bake` (true), `pack_uv`, `export_vertex_colors` (OBJ/GLTF only). Export: `pivot_to_center_bottom`, `scale_factor`, `auto_size`, `with_animation` (true), `animate_in_place`, `part_names`, `export_orientation`, `fbx_preset` `blender`/`3dsmax`/`mixamo` (FBX only). `quad` with `GLTF` is rejected. A non-default `quad`, `flatten_bottom`/`flatten_bottom_threshold`, `texture_size`, `texture_format`, `pivot_to_center_bottom` or `scale_factor`, or any `face_limit`, bills the complex tier (10 credits instead of 5); the other options do not | | `tripo_import_model` | GLB/GLTF/FBX/OBJ/STL ≤150 MB via `file_token` or URL (`.gltf` only as a URL — upload `.glb`) | -| `tripo_rig_check` | free. GLB input. Result: `riggable` and recommended `rig_type`: `biped` `quadruped` `hexapod` `octopod` `avian` `serpentine` `aquatic`. Gate step — not riggable → stop; riggable → rig the **original model task**, not the check task | +| `tripo_rig_check` | free. Input: successful model task ID, `file_token`, or public model URL; documented file formats are GLB, FBX, OBJ and STL (up to 150 MB). Result: `riggable` and recommended `rig_type`: `biped` `quadruped` `hexapod` `octopod` `avian` `serpentine` `aquatic`. Gate step — not riggable → stop; riggable → rig the **original model task**, not the check task | | `tripo_rig` | `model`: always pass it by body type: `v3.0` (`v3.0-20260909`) for `biped` and `others`, `v2.5` (`v2.5-20260210`, the official animal rig) for `quadruped`/`hexapod`/`octopod`/`avian`/`serpentine`/`aquatic`. When it is omitted the MCP sends v3.0 for every body type, and the API's own default is `v1.0-20240301`, which rigs bipeds only. v3.0 is required for `others` and the `actorcore`/`unity`/`unreal`/`vrm` specs. Both take `preset:walk` / `preset:idle` on bipeds and body-type clips on creatures. Explicit `v1.0-20240301` (`v1.0`) is legacy biped-only for 90+ `preset:biped:*` clips. Read the returned model before animation. `rig_type` comes from rig-check; rig the original model, not the check task. `spec` is biped-only; `out_format` is `glb`/`fbx`. | | `tripo_animate` | needs a rig task. `animations: [...]` (≤5, billed per clip). `out_format` `glb`/`fbx`, `animate_in_place` (no root motion — game code drives movement), `export_with_geometry` (true); `bake_animation` is deprecated — do not pass it (it is ignored) | | `tripo_segment` | `model` `v1.0-20250506` (geometry-based, default) or `v2.0-20260430` (semantic, beta) with `segmentation_granularity` `simple`/`balanced`/`detailed`, `split_by_connectivity` (true), `ref_image` (overrides the other two). The tool switches to v2.0 automatically when a v2-only argument is set without `model`; an explicit `v1.0-20250506` with any of them is rejected and no task is created | @@ -127,7 +129,10 @@ or `inputs`), `tripo_image_to_multiview`, `tripo_edit_multiview`, and OpenAI `chat_image_2`, `chat_image_2.5_flare` (faster), `chat_image_2.5_sunburst` (edits keep untouched regions closer to the original). `chat_image_1` is retired (2026-10-23) - and `chat_image_1.5` retires on 2026-12-01: pick `chat_image_2` or a 2.5 model. + and `chat_image_1.5` retires on 2026-12-01. Before retirement it remains + available where supported; respect a user's explicit selection. After retirement + explain alternatives such as `chat_image_2` or a 2.5 model and confirm any + replacement or changed cost; never silently substitute a paid model. GPT-image options: `quality` `low`/`medium`/`high` (`chat_image_2`; 2.5 also `xhigh`/`max`; omitted = `low`); `background` `auto`/`opaque`/`transparent` (2.5 only; `transparent` needs `output_format: "png"`). @@ -194,7 +199,7 @@ Afterwards use the usage ledger and task `credits_consumed` for actual spending; | add-ons per generation | `texture_quality: "detailed"` +10, `"extreme"` +20; v3.1 only: `geometry_quality: "detailed"` +20, `quad` +5, `smart_low_poly` +10, `generate_parts` +20 (P2 `quad` has no surcharge) | | `tripo_texture` | 10 standard / 20 detailed / 30 extreme | | `tripo_convert` | 5, or 10 with a complex-tier option (see the convert row) | -| `tripo_decimate` | 35 tri / 40 quad (v3.0; smart_uv included), 30 (v2.0), 10 (v1.0) | +| `tripo_decimate` | Check current pricing for the selected model and options; mark not_estimated if unavailable | | `tripo_smart_uv` | 20 | | `tripo_segment` / `tripo_mesh_complete` | 40 / 50 (`quick_cap` 30) | | `tripo_smart_segment` | 85 image / 55 model | diff --git a/plugins/tripo-3d/skills/tripo-game-asset/SKILL.md b/plugins/tripo-3d/skills/tripo-game-asset/SKILL.md index b983c960..b42f436c 100644 --- a/plugins/tripo-3d/skills/tripo-game-asset/SKILL.md +++ b/plugins/tripo-3d/skills/tripo-game-asset/SKILL.md @@ -8,10 +8,11 @@ description: Recipes for producing game-ready 3D assets with Tripo and wiring th Recipes on top of the `tripo-3d` skill. Read that skill first — it covers authorization, the `tripo_task_wait` loop (call again while `queued`/`running`), credit rules and the full parameter reference. Every -recipe runs through the Tripo MCP tools only. Every arrow below is a billed -task followed by `tripo_task_wait`; the `input` of each step is the previous -step's `task_id`. Every generation and `tripo_texture` call sends `pbr: false` -unless the user explicitly asks for PBR. +recipe runs through the Tripo MCP tools only. Wait for every asynchronous task +before its dependent step; billing and inputs vary: `tripo_rig_check` is free, +and rig uses the original model task rather than the check task. Each +`tripo_text_to_3d`, `tripo_image_to_3d`, `tripo_multiview_to_3d` and +`tripo_texture` call sends `pbr: false` unless the user explicitly asks for PBR. The point of these recipes is that assets land in the project's own directory structure: after each final step download the file with @@ -21,10 +22,13 @@ local path. ## Pick a budget first -Explicitly choose P2 for game/realtime topology; within the P series the default -is P2, and P1 is used only when the user names it or picks it for lower cost and -speed; v3.1 for film/render/print. Confirm the selected -model, texture options and estimated cost; re-confirm any paid model change. +An explicitly requested model takes priority over these recipes. If it cannot +support a requested feature, explain the conflict and ask before changing the +model or dropping the feature. Otherwise, explicitly choose P2 for game/realtime +topology; within the P series the default is P2, and P1 is used only when the +user names it or picks it for lower cost and speed; v3.1 for film/render/print. +Confirm the selected model, texture options and estimated or unestimated cost; +re-confirm any paid model change. The example calls below use defaults only. | target | generation call | export | | ----------------------------- | ------------------------------------------------------------ | -------------------------------------------- | @@ -34,7 +38,8 @@ model, texture options and estimated cost; re-confirm any paid model change. Two budget-related choices the defaults do not make for you: -- **Quads at low poly** — P1 does not support `quad` (the tool strips it); use `model: "P2", quad: true` +- **Quads at low poly** — P1 does not support `quad`. If the user requested both, + ask which to change before submitting; otherwise use `model: "P2", quad: true` (face_limit 48–25000 quads, price depends on texture options; confirm the estimate, output is FBX) or v3.1 with `smart_low_poly: true, quad: true` (face_limit 500–10000). @@ -134,6 +139,6 @@ asset manifest — rather than stopping at "the file is generated". Check the preview first so a wrong asset does not get wired in. Retopology: `tripo_decimate` with explicit `model: "v3.0", smart_uv: true` -combines retopology and UVs (35 tri / 40 quad credits). Standalone +combines retopology and UVs; check current pricing. Standalone `tripo_smart_uv` is a separate billed UV-layout task for inputs up to 80,000 equivalent triangles; confirm the choice and cost. See the capability reference. From 700df4e8fd648acaf34d77963e1ebc8f9ba2c038 Mon Sep 17 00:00:00 2001 From: sunzhenqiang Date: Tue, 3 Nov 2026 18:10:43 +0800 Subject: [PATCH 5/8] docs(tripo-3d): disclose server-side MCP analytics Replace the "no data collection" note in both READMEs with what the deployed Tripo MCP server records, the declared non-credential X-Tripo-Distribution: zcode_plugin header, and what analytics exclude. The plugin version stays 0.1.5: the marketplace still serves 0.1.4. --- plugins/tripo-3d/README.md | 12 +++++++++--- plugins/tripo-3d/README_CN.md | 2 +- 2 files changed, 10 insertions(+), 4 deletions(-) diff --git a/plugins/tripo-3d/README.md b/plugins/tripo-3d/README.md index 3a29b17c..4a097e0a 100644 --- a/plugins/tripo-3d/README.md +++ b/plugins/tripo-3d/README.md @@ -89,9 +89,15 @@ The Tripo MCP server needs a one-time authorization: - **Hook**: `hooks/session-start.mjs` needs `node` on PATH. It reads the event from stdin and prints a fixed text to stdout; no network, no file access. -- **No data collection**: the plugin contains no telemetry; account - credentials are managed by ZCode's credential store and never pass through - the chat. +- **Telemetry**: the plugin has no independent analytics SDK. When enabled on + the deployed Tripo MCP server, analytics can record tool results, task + metadata and the Tripo account ID when resolved. The plugin declares the + non-credential `X-Tripo-Distribution: zcode_plugin` header; if the host + forwards it, the server records the distribution channel separately from + the detected client (such as ZCode, Claude, or unknown). Analytics excludes + prompts, API keys, OAuth tokens, file paths and signed download links. + Account credentials are managed by ZCode's credential store and never pass + through the chat. ## Provenance and license diff --git a/plugins/tripo-3d/README_CN.md b/plugins/tripo-3d/README_CN.md index b9a2dc2d..08d71b16 100644 --- a/plugins/tripo-3d/README_CN.md +++ b/plugins/tripo-3d/README_CN.md @@ -58,7 +58,7 @@ API Key。本构建的 MCP 只对接国内站;海外站账号请安装海外 - **文件写入**:只在你要求把模型落到本地时,用 `curl` 把结果下载到项目目录;Hook 与 MCP 服务器本身不写任何文件。 - **命令执行**:仅在上传本地图片/模型(`tripo_upload_ticket` 返回的 curl)或下载结果时运行 shell 命令。插件不会安装或调用任何命令行客户端,MCP 失败、未授权、批量或本地落盘需求也不例外。 - **Hook**:`hooks/session-start.mjs` 依赖 PATH 中的 `node`,只从 stdin 读取事件、向 stdout 输出一段固定文本,不访问网络、不读写文件。 -- **不采集任何数据**:插件本体不含遥测;账号凭据由 ZCode 的凭据存储管理,不经过对话。 +- **遥测**:插件本体没有独立的分析 SDK。已部署的 Tripo MCP 服务启用分析时,可以记录工具调用结果、任务元数据及能够解析出的 Tripo 账号 ID。插件声明非凭据请求头 `X-Tripo-Distribution: zcode_plugin`;宿主透传时,服务端会分别记录分发渠道和识别出的客户端(如 ZCode、Claude 或 unknown)。埋点不包含提示词、API Key、OAuth token、文件路径或签名下载链接。账号凭据由 ZCode 的凭据存储管理,不经过对话。 ## 来源与许可 From 1e5da914cbb3f9e31ba3939208547485dc70db20 Mon Sep 17 00:00:00 2001 From: sunzhenqiang Date: Tue, 3 Nov 2026 21:34:23 +0800 Subject: [PATCH 6/8] feat(tripo-3d): support China and international accounts in one English-only plugin Add a second MCP server, tripo-global (https://openapi-mcp.tripo3d.ai/mcp), next to tripo (https://developers.tripo3d.com/mcp); both declare X-Tripo-Distribution: zcode_plugin. The skill and the SessionStart hook ask which site the account is on, use the system time zone only to phrase that question, and keep each task chain on one server. Make the package English-only: drop README_CN.md and the zh-CN example prompts, quote ZCode's English UI labels, and fill the required zh-CN description with the English text. The category keeps validate.py's fixed 3D enum value. Update the README for both servers, including the telemetry note. The version stays 0.1.5: the marketplace still serves 0.1.4. --- marketplace.json | 15 ++--- plugins/tripo-3d/.claude-plugin/plugin.json | 6 +- plugins/tripo-3d/.mcp.json | 9 +++ plugins/tripo-3d/.zcode-plugin/plugin.json | 6 +- plugins/tripo-3d/README.md | 62 ++++++++++------- plugins/tripo-3d/README_CN.md | 67 ------------------- plugins/tripo-3d/hooks/session-start.mjs | 14 ++-- plugins/tripo-3d/skills/tripo-3d/SKILL.md | 53 ++++++++++----- .../tripo-3d/skills/tripo-game-asset/SKILL.md | 2 +- 9 files changed, 102 insertions(+), 132 deletions(-) delete mode 100644 plugins/tripo-3d/README_CN.md diff --git a/marketplace.json b/marketplace.json index 8b75927a..2832baa9 100644 --- a/marketplace.json +++ b/marketplace.json @@ -1097,10 +1097,10 @@ "en": "Tripo 3D", "zh-CN": "Tripo 3D" }, - "description": "Generate textured 3D models from text or images, add rigging and animation, simplify meshes, and export assets for games or 3D printing. Requires a mainland China Tripo account.", + "description": "Generate textured 3D models from text or images, add rigging and animation, simplify meshes, and export assets for games or 3D printing. Works with mainland China and international Tripo accounts.", "description_i18n": { - "en": "Generate textured 3D models from text or images, add rigging and animation, simplify meshes, and export assets for games or 3D printing. Requires a mainland China Tripo account.", - "zh-CN": "用文字或图片生成带贴图的 3D 模型,添加骨骼与动画、精简模型面数,导出用于游戏或 3D 打印的素材。需使用 Tripo 国内站账号。" + "en": "Generate textured 3D models from text or images, add rigging and animation, simplify meshes, and export assets for games or 3D printing. Works with mainland China and international Tripo accounts.", + "zh-CN": "Generate textured 3D models from text or images, add rigging and animation, simplify meshes, and export assets for games or 3D printing. Works with mainland China and international Tripo accounts." }, "version": "0.1.5", "author": { @@ -1125,14 +1125,7 @@ "Generate a low-poly treasure chest and export it as FBX for Unity", "Turn this concept image into a textured 3D model and export it as GLB", "Make a 3D-printable knight figurine and export STL" - ], - "examplePrompts_i18n": { - "zh-CN": [ - "生成一个低多边形的宝箱 3D 模型,导出 FBX 给 Unity 用", - "把这张概念图变成带贴图的 3D 模型,导出 GLB", - "生成一个可 3D 打印的骑士小雕像,导出 STL 文件" - ] - } + ] }, { "name": "kicad", diff --git a/plugins/tripo-3d/.claude-plugin/plugin.json b/plugins/tripo-3d/.claude-plugin/plugin.json index dd4f3542..94c37a16 100644 --- a/plugins/tripo-3d/.claude-plugin/plugin.json +++ b/plugins/tripo-3d/.claude-plugin/plugin.json @@ -1,10 +1,10 @@ { "name": "tripo-3d", "version": "0.1.5", - "description": "Generate textured 3D models from text or images, add rigging and animation, simplify meshes, and export assets for games or 3D printing. Requires a mainland China Tripo account.", + "description": "Generate textured 3D models from text or images, add rigging and animation, simplify meshes, and export assets for games or 3D printing. Works with mainland China and international Tripo accounts.", "description_i18n": { - "en": "Generate textured 3D models from text or images, add rigging and animation, simplify meshes, and export assets for games or 3D printing. Requires a mainland China Tripo account.", - "zh-CN": "用文字或图片生成带贴图的 3D 模型,添加骨骼与动画、精简模型面数,导出用于游戏或 3D 打印的素材。需使用 Tripo 国内站账号。" + "en": "Generate textured 3D models from text or images, add rigging and animation, simplify meshes, and export assets for games or 3D printing. Works with mainland China and international Tripo accounts.", + "zh-CN": "Generate textured 3D models from text or images, add rigging and animation, simplify meshes, and export assets for games or 3D printing. Works with mainland China and international Tripo accounts." }, "author": { "name": "VAST", diff --git a/plugins/tripo-3d/.mcp.json b/plugins/tripo-3d/.mcp.json index edca3688..58e1b3bc 100644 --- a/plugins/tripo-3d/.mcp.json +++ b/plugins/tripo-3d/.mcp.json @@ -8,6 +8,15 @@ "headers": { "X-Tripo-Distribution": "zcode_plugin" } + }, + "tripo-global": { + "type": "http", + "url": "https://openapi-mcp.tripo3d.ai/mcp", + "enabled": true, + "timeoutMs": 90000, + "headers": { + "X-Tripo-Distribution": "zcode_plugin" + } } } } diff --git a/plugins/tripo-3d/.zcode-plugin/plugin.json b/plugins/tripo-3d/.zcode-plugin/plugin.json index dd4f3542..94c37a16 100644 --- a/plugins/tripo-3d/.zcode-plugin/plugin.json +++ b/plugins/tripo-3d/.zcode-plugin/plugin.json @@ -1,10 +1,10 @@ { "name": "tripo-3d", "version": "0.1.5", - "description": "Generate textured 3D models from text or images, add rigging and animation, simplify meshes, and export assets for games or 3D printing. Requires a mainland China Tripo account.", + "description": "Generate textured 3D models from text or images, add rigging and animation, simplify meshes, and export assets for games or 3D printing. Works with mainland China and international Tripo accounts.", "description_i18n": { - "en": "Generate textured 3D models from text or images, add rigging and animation, simplify meshes, and export assets for games or 3D printing. Requires a mainland China Tripo account.", - "zh-CN": "用文字或图片生成带贴图的 3D 模型,添加骨骼与动画、精简模型面数,导出用于游戏或 3D 打印的素材。需使用 Tripo 国内站账号。" + "en": "Generate textured 3D models from text or images, add rigging and animation, simplify meshes, and export assets for games or 3D printing. Works with mainland China and international Tripo accounts.", + "zh-CN": "Generate textured 3D models from text or images, add rigging and animation, simplify meshes, and export assets for games or 3D printing. Works with mainland China and international Tripo accounts." }, "author": { "name": "VAST", diff --git a/plugins/tripo-3d/README.md b/plugins/tripo-3d/README.md index 4a097e0a..78b51136 100644 --- a/plugins/tripo-3d/README.md +++ b/plugins/tripo-3d/README.md @@ -1,9 +1,11 @@ # Tripo 3D -[中文](./README_CN.md) - ## 0.1.5 +Works with both China-mainland and international Tripo accounts: the plugin +ships one MCP server per region, `tripo` for the China site and `tripo-global` +for the international site, and you authorize the one your account belongs to. + A user's explicitly chosen compatible model overrides usage-based defaults. Game/realtime recipes explicitly prefer **P2** (more credits than H/P1), the P-series default; **P1** is used only when the user names it or picks it for lower @@ -26,9 +28,10 @@ prompt or a reference image, with rigging, animation, retopology and format conversion (GLB/FBX/OBJ/STL/USDZ/3MF), and land the files directly in your project. Built for games, film, AR and 3D printing. -Connect your **China-mainland** Tripo account once in the browser -(developers.tripo3d.com) — no API key pasting. This build's MCP endpoint is -China-only; overseas-site accounts need the overseas Tripo 3D plugin build. +Connect your Tripo account once in the browser — no API key pasting. Both +**China-mainland** (developers.tripo3d.com) and **international** +(developers.tripo3d.ai) accounts work: the plugin ships one MCP server per +region and you authorize only the one your account belongs to. ## Components @@ -36,8 +39,9 @@ China-only; overseas-site accounts need the overseas Tripo 3D plugin build. | --- | --- | | Skill `tripo-3d` | Main workflow: tool check, authorization guidance, MCP workflow, scenario → tool-chain mapping, input handling, credit rules | | Skill `tripo-game-asset` | Game-asset recipes: budgeted low-poly props, LOD chains, rigged characters with locomotion clips, wiring into Unity/Unreal/Godot/Three.js | -| MCP server `tripo` | Remote Streamable HTTP server `https://developers.tripo3d.com/mcp` (OAuth 2.1), including `tripo_plan`, generation, rigging, conversion and `tripo_smart_uv`; available tool schemas are authoritative | -| Hook `SessionStart` | Injects seven rules: async waiting, link expiry, credit confirmation, browser authorization, honest failures, PBR off by default and explicit model/billing decisions | +| MCP server `tripo` | China site: remote Streamable HTTP server `https://developers.tripo3d.com/mcp` (OAuth 2.1), including `tripo_plan`, generation, rigging, conversion and `tripo_smart_uv`; available tool schemas are authoritative | +| MCP server `tripo-global` | International site: the same tools on `https://openapi-mcp.tripo3d.ai/mcp` (OAuth 2.1) | +| Hook `SessionStart` | Injects seven rules: async waiting, link expiry, credit confirmation, browser authorization, honest failures, PBR off by default and explicit model/billing decisions, plus a region hint from the system time zone | ## Usage @@ -54,15 +58,18 @@ from the Skills group. ### First-time authorization -The Tripo MCP server needs a one-time authorization: - -1. Open **Settings → MCP**, find the Tripo row under "Plugin MCP servers" - (it shows "Authorization required") and click **Open authorization**. -2. The system browser opens the Tripo authorization page for the **China site** - (developers.tripo3d.com — +86 SMS sign-in, Alipay top-up). There is no - region picker on this page. You can sign up on the spot; new accounts get - free credits. An international-site account will not authorize against this - build — use the overseas plugin. +Authorize the Tripo MCP server for your account's region once: + +1. Open **Settings → MCP Servers**. Under "Plugin MCP servers" there are two Tripo + rows, both showing "Authorization required": `tripo` for a China-mainland + account and `tripo-global` for an international account. Click + **Open authorization** on the row for your account; the other row can stay + as it is. +2. The system browser opens that site's authorization page: `tripo` uses the + **China site** (developers.tripo3d.com — +86 SMS sign-in, Alipay top-up), + `tripo-global` the **international site** (developers.tripo3d.ai — email + sign-in, Stripe top-up). The page has no region picker. You can sign up on + the spot; new accounts get free credits. 3. The page shows a one-time verification code and opens the Tripo console: sign in, type the code into **Verification code**, click **Authorize**. 4. ZCode reconnects and loads the tools automatically. To revoke access, @@ -71,27 +78,30 @@ The Tripo MCP server needs a one-time authorization: ## Dependencies, network access and side effects -- **Network**: MCP tool calls go to `https://developers.tripo3d.com/mcp`; - authorization redirects to the China Tripo console - (developers.tripo3d.com). Results are downloaded from Tripo's CDN through - short-lived links (about 2 hours). +- **Network**: ZCode connects to both MCP endpoints, + `https://developers.tripo3d.com/mcp` (China site) and + `https://openapi-mcp.tripo3d.ai/mcp` (international site); tool calls go + only to the one you authorized, and authorization redirects to that site's + Tripo console. Results are downloaded from Tripo's CDN through short-lived + links (about 2 hours). - **Account and billing**: every generation spends credits from your own Tripo account; use task status and the usage ledger for actual charges. Failed tasks are refunded automatically. The skill drafts the chain with `tripo_plan`, checks the balance and asks before generating a batch. - **File writes**: only when you ask for the model on disk, the agent - downloads it into your project with `curl`. The hook and the MCP server + downloads it into your project with `curl`. The hook and the MCP servers write nothing. - **Command execution**: shell commands run only to upload a local image/model (the `curl` returned by `tripo_upload_ticket`) or to download a result. The plugin never installs or runs a command-line client, including after an MCP failure, missing authorization, batch work or a request to save files locally. - **Hook**: `hooks/session-start.mjs` needs `node` on PATH. It reads the - event from stdin and prints a fixed text to stdout; no network, no file - access. + event from stdin and prints the rules plus a region hint derived from the + system time zone to stdout; no network, no file access. - **Telemetry**: the plugin has no independent analytics SDK. When enabled on - the deployed Tripo MCP server, analytics can record tool results, task - metadata and the Tripo account ID when resolved. The plugin declares the + the Tripo MCP server you authorized (China or international site; both + record the same fields), analytics can record tool results, task + metadata and the Tripo account ID when resolved. Both MCP servers declare the non-credential `X-Tripo-Distribution: zcode_plugin` header; if the host forwards it, the server records the distribution channel separately from the detected client (such as ZCode, Claude, or unknown). Analytics excludes @@ -104,6 +114,6 @@ The Tripo MCP server needs a one-time authorization: - Plugin: MIT, by [VAST](https://www.tripo3d.ai). - Both skills are ported from Tripo's official Kimi / Codex plugins (also maintained by VAST, MIT). -- The MCP server is an official Tripo implementation; +- Both MCP servers run the official Tripo implementation; generated content is subject to the [Tripo API content policy](https://platform.tripo3d.ai/docs). diff --git a/plugins/tripo-3d/README_CN.md b/plugins/tripo-3d/README_CN.md deleted file mode 100644 index 08d71b16..00000000 --- a/plugins/tripo-3d/README_CN.md +++ /dev/null @@ -1,67 +0,0 @@ -# Tripo 3D - -[English](./README.md) - -## 0.1.5 - -用户明确指定的兼容模型优先于按用途选择的默认值;游戏/实时资产显式优先选择 **P2**(积分高于 H/P1),使用 P 系列时默认 **P2**;**P1**(积分更低、速度更快)仅在用户明确指定或选择时使用, -影视/渲染/打印用 v3.1。绑骨按体型显式指定:双足 v3.0,动物 v2.5;动画预设须跟随上游 rig 模型。 -重拓扑 v3.0 的 `smart_uv` 与独立 `tripo_smart_uv` 是不同计费流程。 -fast 贴图需 v3.5;`chat_image_1` 已退役。 - -插件只通过 Tripo MCP 工具执行,没有 CLI 路径;未授权也不会改走 CLI。PBR 默认关闭, -只有你明确要求时才开启。计划仅供参考,不是实时报价或预算锁;静态价格估算须说明 -来源、区域和日期,未估算的步骤须明确标出,计费前取得确认。禁止自动切换账号。 -Hook 同步执行 PBR 默认关闭与选模/计费约束。 - -Tripo 官方 ZCode 插件。用一句话或一张图生成带贴图的 3D 模型,支持骨骼绑定、动画、 -减面和格式转换(GLB/FBX/OBJ/STL/USDZ/3MF),文件直接落到你的项目里。覆盖游戏、 -影视、AR 和 3D 打印场景。 - -浏览器里授权一次**国内站** Tripo 账号即可使用(developers.tripo3d.com),无需复制 -API Key。本构建的 MCP 只对接国内站;海外站账号请安装海外版插件。 - -## 包含的组件 - -| 组件 | 内容 | -| --- | --- | -| Skill `tripo-3d` | 主流程:工具检查、授权引导、MCP 工作流、场景 → 工具链映射、输入处理、积分规则 | -| Skill `tripo-game-asset` | 游戏资产配方:面数预算道具、LOD 链、绑骨角色与动画、接入 Unity/Unreal/Godot/Three.js | -| MCP 服务器 `tripo` | 远程 Streamable HTTP server `https://developers.tripo3d.com/mcp`(OAuth 2.1),含计划、生成、绑骨、转换与独立 UV;以实际可见工具 schema 为准 | -| Hook `SessionStart` | 注入 7 条规则:异步等待、链接过期、计费确认、浏览器授权、如实报错、PBR 默认关闭、显式选模与计费决策 | - -## 怎么用 - -安装并启用插件后,直接描述需求即可,例如: - -- 生成一个低多边形的宝箱 3D 模型,导出 FBX 给 Unity 用 -- Turn this concept image into a textured 3D model and export it as GLB -- 生成一个可 3D 打印的骑士小雕像,导出 STL 文件 -- 生成一个 T-pose 的机器人角色,绑好骨骼并加上走路动画 -- 查一下我的 Tripo 余额 - -也可以在输入框输入 `/` 从「技能」分组手动选用 `tripo-3d` 或 `tripo-game-asset`。 - -### 首次授权 - -首次使用时 Tripo 的 MCP 服务器需要授权: - -1. 打开 **设置 → MCP**,在「Plugin MCP 服务器」分组找到 Tripo 一行(显示「需要授权」),点 **打开授权**。 -2. 系统浏览器打开的授权页对接**国内站**控制台(developers.tripo3d.com,+86 短信登录、支付宝充值),**没有选区步骤**。没有账号可以顺手注册,新账号有免费额度。海外站账号无法在此构建上授权——请改用海外版插件。 -3. 页面显示一次性验证码并跳转 Tripo 控制台:登录后把验证码填入 **Verification code**,点 **Authorize**。 -4. ZCode 自动重连并加载工具。撤销授权:在 Tripo 控制台的 API Keys 页删除授权时选定的 Key。 - -## 依赖、网络访问与副作用 - -- **网络**:MCP 工具调用走 `https://developers.tripo3d.com/mcp`;授权页跳转到国内站 Tripo 控制台(developers.tripo3d.com)。生成结果通过 Tripo 的 CDN 短期链接(约 2 小时过期)下载。 -- **账号与计费**:所有生成任务消耗你自己 Tripo 账号的积分,通过任务状态与用量账单核对实际消耗;失败任务自动退款。批量生成前 skill 会先用 `tripo_plan` 草稿、查余额并确认。 -- **文件写入**:只在你要求把模型落到本地时,用 `curl` 把结果下载到项目目录;Hook 与 MCP 服务器本身不写任何文件。 -- **命令执行**:仅在上传本地图片/模型(`tripo_upload_ticket` 返回的 curl)或下载结果时运行 shell 命令。插件不会安装或调用任何命令行客户端,MCP 失败、未授权、批量或本地落盘需求也不例外。 -- **Hook**:`hooks/session-start.mjs` 依赖 PATH 中的 `node`,只从 stdin 读取事件、向 stdout 输出一段固定文本,不访问网络、不读写文件。 -- **遥测**:插件本体没有独立的分析 SDK。已部署的 Tripo MCP 服务启用分析时,可以记录工具调用结果、任务元数据及能够解析出的 Tripo 账号 ID。插件声明非凭据请求头 `X-Tripo-Distribution: zcode_plugin`;宿主透传时,服务端会分别记录分发渠道和识别出的客户端(如 ZCode、Claude 或 unknown)。埋点不包含提示词、API Key、OAuth token、文件路径或签名下载链接。账号凭据由 ZCode 的凭据存储管理,不经过对话。 - -## 来源与许可 - -- 插件本体:MIT,作者 [VAST](https://www.tripo3d.ai)。 -- 两个 skill 由 Tripo 官方的 Kimi / Codex 插件(同为 VAST 维护,MIT)移植而来。 -- MCP 服务器为 Tripo 官方实现;生成内容遵循 [Tripo API 内容策略](https://platform.tripo3d.ai/docs)。 diff --git a/plugins/tripo-3d/hooks/session-start.mjs b/plugins/tripo-3d/hooks/session-start.mjs index af7e310d..24101fdb 100644 --- a/plugins/tripo-3d/hooks/session-start.mjs +++ b/plugins/tripo-3d/hooks/session-start.mjs @@ -1,5 +1,5 @@ #!/usr/bin/env node -// SessionStart hook: inject the Tripo hard rules as additionalContext. +// SessionStart hook: inject the Tripo hard rules and a time-zone region hint as additionalContext. // Reads one JSON event from stdin, writes one JSON object to stdout. // Keep this text in sync with skills/tripo-3d/SKILL.md. @@ -7,12 +7,18 @@ const RULES = `Tripo 3D — rules that apply whenever Tripo tools (tripo_*) are 1. Generation is asynchronous. Every tripo_* generation or processing tool returns a task_id immediately. Call tripo_task_wait with it and keep calling while status is queued/running — each call returns within about 55 seconds, a generation usually takes 1–4 minutes. Never present a result before status is success, and never treat a task_id as a finished model. 2. Deliver the file, then one link. On success, download model_url to a local file when a shell is available and give its path as plain text in backticks, never as a clickable link (chat previews cannot render meshes); then also offer model_url as a single markdown download link. Do not paste URLs from output_urls into the reply. Result URLs expire after about 2 hours: never re-print an old one — call tripo_task_status for fresh links. 3. Credits belong to the user. Call tripo_plan and get confirmation before any billed generation or chain; supply structured generation only for tripo_text_to_3d, tripo_image_to_3d and tripo_multiview_to_3d, including the exact text prompt for text-to-3D; never add generation to other steps such as tripo_image_to_splat. For those three use dry_run only when the connected schema exposes it; validate other steps against their schemas and current pricing. Resolve user-requested parameter conflicts before billing. Plan estimates are advisory, not a budget lock; label unknown costs not_estimated, and cite source, region and date for any static list estimate. Use tripo_usage for all task_ids to report actual total and per-task charges; if unavailable say the amount is pending. Check tripo_balance and confirm before generating more than one asset in a batch; on insufficient balance give the returned plans_url instead of retrying. Never silently re-roll a disappointing result — say what is off and ask first. -4. Authorization is a browser flow, never a pasted key. This build's MCP is China-mainland only (developers.tripo3d.com/mcp); the auth page has no region picker. If Tripo tools are missing or a call reports an authorization error, tell the user to open ZCode 设置 → MCP, find the Tripo server under「Plugin MCP 服务器」and click「打开授权」, then sign in on the 国内站 console and Authorize. An overseas-site account needs the overseas plugin build. Do not ask for an API key in the chat. MCP is the only execution path: never install or run a command-line client instead, even when a local login or API key exists. +4. Authorization is a browser flow, never a pasted key. The plugin has one MCP server per Tripo region, and an account exists in only one region: tripo is the China site (developers.tripo3d.com, +86 SMS sign-in), tripo-global is the international site (developers.tripo3d.ai, email sign-in); neither auth page has a region picker. If Tripo tools are missing or a call reports an authorization error, ask which site the user's Tripo account is on unless they already said, then tell them to open ZCode Settings → MCP Servers, find that server under "Plugin MCP servers" and click "Open authorization" (ZCode shows these labels in its UI language), then sign in on that site's console and Authorize. The other server keeps showing "Authorization required", which is expected. If tools from both servers are available, ask which account to spend credits from and keep each task chain on that server: task IDs, file tokens and balances do not carry across regions. Never switch servers silently. Do not ask for an API key in the chat. MCP is the only execution path: never install or run a command-line client instead, even when a local login or API key exists. 5. Failures are reported, not hidden. On failed/banned, relay failure_reason (and error_code) honestly; failed-task credits are refunded automatically. Never invent parameters — the tool schemas are authoritative. If a creation call times out without a task_id, do not automatically retry: check the original account's balance and task history when available and ask before another submission. Stylize has been retired: there is no tripo_stylize tool. tripo_mesh_edit is experimental; use it only if the connected server lists it. -6. PBR is opt-in. Send pbr: false on every tripo_text_to_3d, tripo_image_to_3d, tripo_multiview_to_3d and tripo_texture call unless the user explicitly asks for PBR (e.g. "with PBR", 「PBR 材质」); only then send pbr: true, which also forces texture: true. The API turns PBR on when pbr is omitted, so never leave it out. Detailed or high-quality textures do not mean PBR. +6. PBR is opt-in. Send pbr: false on every tripo_text_to_3d, tripo_image_to_3d, tripo_multiview_to_3d and tripo_texture call unless the user explicitly asks for PBR (e.g. "with PBR" or "PBR materials", in any language); only then send pbr: true, which also forces texture: true. The API turns PBR on when pbr is omitted, so never leave it out. Detailed or high-quality textures do not mean PBR. 7. Choose models explicitly: the user's explicit compatible model wins over usage-based defaults; if requirements conflict, explain and ask before changing model or dropping a requirement. P2 is preferred for game/realtime topology and costs more credits than H/P1; within the P series the default is P2, and P1 is used only when the user names it or picks it for lower cost and speed; v3.1 for film/render/print. Do not infer the model from face_limit. Cost is not estimated by this text or guaranteed by tripo_plan: disclose uncertainty and obtain consent before billing. Pass the rig model explicitly: v3.0 for bipeds, v2.5 for animal body types (the API's own default is v1.0, which rigs bipeds only); use preset:walk, reserving preset:biped:* for explicit v1.0 rigs. Retopology v3.0 with smart_uv and standalone tripo_smart_uv are separate workflows, not interchangeable free export switches. Load the capability reference before running either. chat_image_1 is retired; never fall back to it. chat_image_1.5 remains usable where supported before 2026-12-01; never silently replace a user-selected paid image model. fast textures require texture model v3.5: pass the short name v3.5, or omit the version and the tool picks it. `; +const CHINA_TIME_ZONES = new Set(["Asia/Shanghai", "Asia/Urumqi", "Asia/Chongqing", "Asia/Chungking", "Asia/Harbin", "Asia/Kashgar", "PRC"]); +const timeZone = Intl.DateTimeFormat().resolvedOptions().timeZone; +const regionHint = timeZone + ? `Region hint: the system time zone is ${timeZone}, which suggests ${CHINA_TIME_ZONES.has(timeZone) ? "the China site (tripo)" : "the international site (tripo-global)"}. Use it only to phrase the question in rule 4; never choose a server for the user on this guess.\n` + : ""; + let raw = ""; process.stdin.setEncoding("utf8"); for await (const chunk of process.stdin) raw += chunk; @@ -28,6 +34,6 @@ try { process.stdout.write( JSON.stringify({ - hookSpecificOutput: { hookEventName: eventName, additionalContext: RULES }, + hookSpecificOutput: { hookEventName: eventName, additionalContext: RULES + regionHint }, }), ); diff --git a/plugins/tripo-3d/skills/tripo-3d/SKILL.md b/plugins/tripo-3d/skills/tripo-3d/SKILL.md index d1f76f77..7544fca0 100644 --- a/plugins/tripo-3d/skills/tripo-3d/SKILL.md +++ b/plugins/tripo-3d/skills/tripo-3d/SKILL.md @@ -1,6 +1,6 @@ --- name: tripo-3d -description: Generate a 3D model from a text prompt, a reference image, or an existing mesh, and deliver it as GLB, FBX, OBJ, STL, USDZ or 3MF. Use when the user asks for a 3D asset, model, mesh, prop, character or texture for a game, renderer, viewer, AR scene or 3D print — including requests like "make me a low-poly X", "turn this image into 3D", "rig this character", "convert this model to FBX", or "generate placeholder assets". 中文触发词:生成3D模型、建模、3D素材、把图片变成3D、图生3D、文生3D、骨骼绑定、绑骨、角色动画、贴图、纹理、低模、低多边形、减面、3D打印、手办、格式转换(FBX/GLB/OBJ/STL/USDZ/3MF)。Also use to re-run, convert or inspect a previous Tripo generation. +description: Generate a 3D model from a text prompt, a reference image, or an existing mesh, and deliver it as GLB, FBX, OBJ, STL, USDZ or 3MF. Use when the user asks for a 3D asset, model, mesh, prop, character or texture for a game, renderer, viewer, AR scene or 3D print — including requests like "make me a low-poly X", "turn this image into 3D", "rig this character", "convert this model to FBX", or "generate placeholder assets", and the same requests in any language (text-to-3D, image-to-3D, rigging, character animation, texturing, low-poly or face reduction, 3D-printed figurines, format conversion). Also use to re-run, convert or inspect a previous Tripo generation. --- # Tripo 3D @@ -15,14 +15,17 @@ not a budget limit or an authorization ticket. The tool list must contain the Tripo tools (`tripo_text_to_3d`, `tripo_task_wait`, ...; ZCode prefixes them with the MCP server id, e.g. -`mcp__…__tripo_text_to_3d` — the rest of this skill uses the bare names). +`mcp__…__tripo_text_to_3d` — the rest of this skill uses the bare names). The +server id in the prefix tells the region: `tripo` is the China site, +`tripo-global` is the international site. -If they are missing, the plugin's MCP server is almost always waiting for -authorization or switched off, not absent. Stop and tell the user: open -**设置 → MCP**, find the Tripo server under 「Plugin MCP 服务器」, click -**打开授权** if the row says 「需要授权」 (or enable it), then start a new -session. See Authorization below. Do not describe generations as if they had -run. +If they are missing, the plugin's MCP servers are almost always waiting for +authorization or switched off, not absent. Stop, ask which site the user's +Tripo account is on, and tell them: open **Settings → MCP Servers**, find that +region's server under "Plugin MCP servers", click **Open authorization** if the +row says "Authorization required" (if it says "Plugin disabled", enable the +Tripo 3D plugin first), then start a new session. See Authorization below. +Do not describe generations as if they had run. MCP is the only execution path. Never install or run a command-line client instead — not for a balance check, not because a local login or @@ -38,15 +41,26 @@ account. ZCode runs the OAuth flow but never opens a browser on its own — the user has to click once. Your job is to guide them through the pages; never ask for an API key in the chat. -**This plugin build talks to the China-mainland MCP** -(`https://developers.tripo3d.com/mcp`). The authorization page does **not** -offer a region picker — it always opens the **国内站** console -(developers.tripo3d.com, +86 SMS sign-in, Alipay top-up). An overseas-site -account (developers.tripo3d.ai) will not work here: tell the user to install -the overseas Tripo 3D plugin build. +**The plugin ships one MCP server per Tripo region.** An account lives in +exactly one region, and neither authorization page offers a region picker: -1. **设置 → MCP** → group 「Plugin MCP 服务器」 → the Tripo row shows - 「需要授权」 → click **打开授权**. The system browser opens the Tripo +| MCP server | Region | Console | +| --- | --- | --- | +| `tripo` (`https://developers.tripo3d.com/mcp`) | China site — mainland China | developers.tripo3d.com, +86 SMS sign-in, Alipay top-up | +| `tripo-global` (`https://openapi-mcp.tripo3d.ai/mcp`) | International site | developers.tripo3d.ai, email sign-in, Stripe top-up | + +Ask once whether the user's account is on the China site or the international +site, unless they already said. The session context may carry a time-zone region +hint; use it only to phrase the question, never to choose for the user. No +account yet? Users in mainland China pick the China site, everyone else the +international site; they can sign up during authorization and new accounts get +free credits. Only the chosen server needs authorizing; the other row keeps +showing "Authorization required", which is expected. ZCode shows these labels +in its UI language. + +1. **Settings → MCP Servers** → group "Plugin MCP servers" → the chosen + server's row (`tripo` or `tripo-global`) shows "Authorization required" → + click **Open authorization**. The system browser opens that region's authorization page. 2. The page shows a one-time verification code and opens the Tripo console: sign in (or sign up — new accounts get free credits), type the code into @@ -62,6 +76,11 @@ with exactly one key it is used as is). To revoke access, delete that key on the console's API Keys page — any other client sharing that key loses access too. +If tools from both servers are available, ask which account to spend credits +from before the first billed step, and keep the whole task chain on that +server: task IDs, file tokens and balances belong to one region and do not +carry over to the other server. Never switch servers silently. + ## Workflow 1. **Plan** — for any billed generation or chain, call `tripo_plan` first. @@ -198,7 +217,7 @@ model overrides the usage-based default. GLB is the native output — a - **PBR is opt-in.** Send `pbr: false` on every `tripo_text_to_3d`, `tripo_image_to_3d`, `tripo_multiview_to_3d` and `tripo_texture` call unless the user explicitly asks for PBR materials (for example "with - PBR" or 「PBR 材质」); only then send `pbr: true`, which also forces + PBR" or "PBR materials", in any language); only then send `pbr: true`, which also forces `texture: true`. The API turns PBR on when `pbr` is left out, so never omit it. Detailed or high-quality textures do not mean PBR. PBR can still be added later: when the user asks for it after a model is already generated, do not diff --git a/plugins/tripo-3d/skills/tripo-game-asset/SKILL.md b/plugins/tripo-3d/skills/tripo-game-asset/SKILL.md index b42f436c..803c728c 100644 --- a/plugins/tripo-3d/skills/tripo-game-asset/SKILL.md +++ b/plugins/tripo-3d/skills/tripo-game-asset/SKILL.md @@ -1,6 +1,6 @@ --- name: tripo-game-asset -description: Recipes for producing game-ready 3D assets with Tripo and wiring them into a game project - low-poly props on a face budget, detailed hero assets, LOD chains, and rigged characters with locomotion clips for Unity, Unreal, Godot or Three.js. Use when the user is building a game or real-time 3D scene and needs props, characters, placeholder art, LODs, or an animated rig, rather than a single one-off model. 中文触发词:游戏资产、游戏素材、游戏模型、低模道具、面数预算、LOD、角色绑骨、走跑跳动画、Unity/Unreal/Godot 模型导入。 +description: Recipes for producing game-ready 3D assets with Tripo and wiring them into a game project - low-poly props on a face budget, detailed hero assets, LOD chains, and rigged characters with locomotion clips for Unity, Unreal, Godot or Three.js. Use when the user is building a game or real-time 3D scene and needs props, characters, placeholder art, LODs, or an animated rig, rather than a single one-off model. Also covers walk/run/jump clips and importing models into Unity, Unreal or Godot, whatever language the request is in. --- # Game asset pipeline From 8049f9e4c4dd3aaed9269a22d75e459e6a0e70df Mon Sep 17 00:00:00 2001 From: sunzhenqiang Date: Thu, 19 Nov 2026 07:35:06 -0600 Subject: [PATCH 7/8] feat(tripo-3d): refine dual-region workflow and localization --- marketplace.json | 11 +- plugins/tripo-3d/.claude-plugin/plugin.json | 2 +- plugins/tripo-3d/.zcode-plugin/plugin.json | 2 +- plugins/tripo-3d/README.md | 35 +++-- plugins/tripo-3d/README_CN.md | 103 +++++++++++++ plugins/tripo-3d/hooks/session-start.mjs | 9 +- plugins/tripo-3d/skills/tripo-3d/SKILL.md | 140 +++++++++++------- .../skills/tripo-3d/references/capability.md | 30 +++- .../tripo-3d/skills/tripo-game-asset/SKILL.md | 104 ++++++++----- 9 files changed, 319 insertions(+), 117 deletions(-) create mode 100644 plugins/tripo-3d/README_CN.md diff --git a/marketplace.json b/marketplace.json index 2832baa9..98f3f23d 100644 --- a/marketplace.json +++ b/marketplace.json @@ -1100,7 +1100,7 @@ "description": "Generate textured 3D models from text or images, add rigging and animation, simplify meshes, and export assets for games or 3D printing. Works with mainland China and international Tripo accounts.", "description_i18n": { "en": "Generate textured 3D models from text or images, add rigging and animation, simplify meshes, and export assets for games or 3D printing. Works with mainland China and international Tripo accounts.", - "zh-CN": "Generate textured 3D models from text or images, add rigging and animation, simplify meshes, and export assets for games or 3D printing. Works with mainland China and international Tripo accounts." + "zh-CN": "用文字或图片生成带贴图的 3D 模型,添加骨骼与动画、精简模型面数,导出用于游戏或 3D 打印的素材。支持 Tripo 国内站和海外站账号。" }, "version": "0.1.5", "author": { @@ -1125,7 +1125,14 @@ "Generate a low-poly treasure chest and export it as FBX for Unity", "Turn this concept image into a textured 3D model and export it as GLB", "Make a 3D-printable knight figurine and export STL" - ] + ], + "examplePrompts_i18n": { + "zh-CN": [ + "生成一个低多边形的宝箱 3D 模型,导出 FBX 给 Unity 用", + "把这张概念图变成带贴图的 3D 模型,导出 GLB", + "生成一个可 3D 打印的骑士小雕像,导出 STL 文件" + ] + } }, { "name": "kicad", diff --git a/plugins/tripo-3d/.claude-plugin/plugin.json b/plugins/tripo-3d/.claude-plugin/plugin.json index 94c37a16..71e971e6 100644 --- a/plugins/tripo-3d/.claude-plugin/plugin.json +++ b/plugins/tripo-3d/.claude-plugin/plugin.json @@ -4,7 +4,7 @@ "description": "Generate textured 3D models from text or images, add rigging and animation, simplify meshes, and export assets for games or 3D printing. Works with mainland China and international Tripo accounts.", "description_i18n": { "en": "Generate textured 3D models from text or images, add rigging and animation, simplify meshes, and export assets for games or 3D printing. Works with mainland China and international Tripo accounts.", - "zh-CN": "Generate textured 3D models from text or images, add rigging and animation, simplify meshes, and export assets for games or 3D printing. Works with mainland China and international Tripo accounts." + "zh-CN": "用文字或图片生成带贴图的 3D 模型,添加骨骼与动画、精简模型面数,导出用于游戏或 3D 打印的素材。支持 Tripo 国内站和海外站账号。" }, "author": { "name": "VAST", diff --git a/plugins/tripo-3d/.zcode-plugin/plugin.json b/plugins/tripo-3d/.zcode-plugin/plugin.json index 94c37a16..71e971e6 100644 --- a/plugins/tripo-3d/.zcode-plugin/plugin.json +++ b/plugins/tripo-3d/.zcode-plugin/plugin.json @@ -4,7 +4,7 @@ "description": "Generate textured 3D models from text or images, add rigging and animation, simplify meshes, and export assets for games or 3D printing. Works with mainland China and international Tripo accounts.", "description_i18n": { "en": "Generate textured 3D models from text or images, add rigging and animation, simplify meshes, and export assets for games or 3D printing. Works with mainland China and international Tripo accounts.", - "zh-CN": "Generate textured 3D models from text or images, add rigging and animation, simplify meshes, and export assets for games or 3D printing. Works with mainland China and international Tripo accounts." + "zh-CN": "用文字或图片生成带贴图的 3D 模型,添加骨骼与动画、精简模型面数,导出用于游戏或 3D 打印的素材。支持 Tripo 国内站和海外站账号。" }, "author": { "name": "VAST", diff --git a/plugins/tripo-3d/README.md b/plugins/tripo-3d/README.md index 78b51136..eba93300 100644 --- a/plugins/tripo-3d/README.md +++ b/plugins/tripo-3d/README.md @@ -1,5 +1,7 @@ # Tripo 3D +[中文文档](./README_CN.md) + ## 0.1.5 Works with both China-mainland and international Tripo accounts: the plugin @@ -7,6 +9,9 @@ ships one MCP server per region, `tripo` for the China site and `tripo-global` for the international site, and you authorize the one your account belongs to. A user's explicitly chosen compatible model overrides usage-based defaults. +Choose from models that support the required features before applying the +scenario preference. If an explicitly chosen model conflicts with a required +feature, ask before changing the model or dropping the requirement. Game/realtime recipes explicitly prefer **P2** (more credits than H/P1), the P-series default; **P1** is used only when the user names it or picks it for lower cost and speed, and v3.1 for film/render/print. Rigs pass the model @@ -21,11 +26,11 @@ missing authorization is never a reason to switch to one. PBR stays off unless you explicitly ask for it. A plan is advisory, not a price quote or budget lock. Show estimated or unestimated costs, cite the source, region and date of any static list estimate, and obtain explicit consent. Never switch accounts silently. -The hook also enforces the PBR default and explicit model/billing decisions. +The hook also provides the PBR default and explicit model/billing guidance. The official Tripo plugin for ZCode. Generate textured 3D models from a text prompt or a reference image, with rigging, animation, retopology and format -conversion (GLB/FBX/OBJ/STL/USDZ/3MF), and land the files directly in your +conversion (GLB/FBX/OBJ/STL/USDZ/3MF). You can ask to save the files in your project. Built for games, film, AR and 3D printing. Connect your Tripo account once in the browser — no API key pasting. Both @@ -41,7 +46,7 @@ region and you authorize only the one your account belongs to. | Skill `tripo-game-asset` | Game-asset recipes: budgeted low-poly props, LOD chains, rigged characters with locomotion clips, wiring into Unity/Unreal/Godot/Three.js | | MCP server `tripo` | China site: remote Streamable HTTP server `https://developers.tripo3d.com/mcp` (OAuth 2.1), including `tripo_plan`, generation, rigging, conversion and `tripo_smart_uv`; available tool schemas are authoritative | | MCP server `tripo-global` | International site: the same tools on `https://openapi-mcp.tripo3d.ai/mcp` (OAuth 2.1) | -| Hook `SessionStart` | Injects seven rules: async waiting, link expiry, credit confirmation, browser authorization, honest failures, PBR off by default and explicit model/billing decisions, plus a region hint from the system time zone | +| Hook `SessionStart` | Injects eight rules covering async waiting, short-lived links, credit confirmation, browser authorization, honest failures, PBR, model selection and concept-image confirmation, plus a region hint from the system time zone | ## Usage @@ -56,6 +61,13 @@ Install and enable the plugin, then just describe what you need, for example: You can also type `/` in the composer and pick `tripo-3d` or `tripo-game-asset` from the Skills group. +For a text-only model request, the skill first plans and asks you to confirm +the concept-image cost. It generates and shows the image, then waits for your +acceptance before planning and asking for separate confirmation of the 3D step +and any requested post-processing. You can explicitly ask to skip the image and +generate directly from text. An image or multiview set you already supplied can +be used directly for 3D generation. + ### First-time authorization Authorize the Tripo MCP server for your account's region once: @@ -76,23 +88,28 @@ Authorize the Tripo MCP server for your account's region once: delete the API key you picked during authorization on the console's API Keys page. +If you connect accounts in both regions, choose the account for the task before +planning or uploading. Task IDs, file tokens and balances stay with that server. + ## Dependencies, network access and side effects - **Network**: ZCode connects to both MCP endpoints, `https://developers.tripo3d.com/mcp` (China site) and `https://openapi-mcp.tripo3d.ai/mcp` (international site); tool calls go only to the one you authorized, and authorization redirects to that site's - Tripo console. Results are downloaded from Tripo's CDN through short-lived - links (about 2 hours). + Tripo console. Results are available through short-lived Tripo CDN links. + `tripo_task_status` refreshes them when needed. - **Account and billing**: every generation spends credits from your own Tripo account; use task status and the usage ledger for actual charges. Failed - tasks are refunded automatically. The skill drafts the chain with `tripo_plan`, - checks the balance and asks before generating a batch. -- **File writes**: only when you ask for the model on disk, the agent + tasks are refunded automatically. The skill drafts billed steps with + `tripo_plan` and asks for explicit confirmation before they run. For a batch, + it checks the balance and confirms the cost of each phase before that phase runs. +- **File writes**: when you ask to save or integrate a model, the agent downloads it into your project with `curl`. The hook and the MCP servers write nothing. - **Command execution**: shell commands run only to upload a local image/model - (the `curl` returned by `tripo_upload_ticket`) or to download a result. The + (using the command returned by `tripo_upload_ticket` or, for larger files when + the connected server supports it, `tripo_upload_presign`) or to download a result. The plugin never installs or runs a command-line client, including after an MCP failure, missing authorization, batch work or a request to save files locally. - **Hook**: `hooks/session-start.mjs` needs `node` on PATH. It reads the diff --git a/plugins/tripo-3d/README_CN.md b/plugins/tripo-3d/README_CN.md new file mode 100644 index 00000000..beb45395 --- /dev/null +++ b/plugins/tripo-3d/README_CN.md @@ -0,0 +1,103 @@ +# Tripo 3D + +[English](./README.md) + +## 0.1.5 + +插件支持 Tripo 国内站和海外站账号,分别通过国内 MCP 服务器 `tripo` 和海外 MCP +服务器 `tripo-global` 连接。授权与自己账号所属站点对应的服务器即可。 + +用户明确指定的兼容模型优先于按用途选择的默认值。先按必需功能筛选兼容模型,再按 +场景选择。若用户指定的模型与必需功能冲突,变更模型或放弃要求前先询问。游戏和 +实时资产显式优先使用 **P2**(积分高于 H/P1),使用 P 系列时默认 **P2**,**P1** +(积分更低、速度更快)仅在用户明确指定或选择时使用,影视、渲染和打印场景使用 +v3.1。绑骨时显式指定模型,双足使用 v3.0,动物使用 v2.5。API 自身默认的 v1.0 只 +支持双足,动画预设须根据上游 rig 模型选择。重拓扑 v3.0 的 `smart_uv` 与独立 +`tripo_smart_uv` 是不同的计费流程。fast 贴图需要 v3.5,`chat_image_1` 已退役。 + +插件通过 Tripo MCP 工具执行,没有 CLI 路径,未授权也不会改走 CLI。PBR 默认关闭, +只有你明确要求时才开启。计划仅供参考,不是实时报价或预算锁。展示费用估算或明确 +标出无法估算的费用,使用静态价格时注明来源、区域和日期,计费前取得明确确认。 +禁止自动切换账号。Hook 同步提供 PBR 默认关闭与选模、计费指引。 + +这是 Tripo 官方 ZCode 插件。用文字或参考图生成带贴图的 3D 模型,支持骨骼绑定、 +动画、重拓扑和格式转换(GLB/FBX/OBJ/STL/USDZ/3MF)。你可以要求将文件保存到项目中, +用于游戏、影视、AR 和 3D 打印。 + +在浏览器中授权一次 Tripo 账号即可使用,无需粘贴 API Key。插件分别支持**国内站** +(developers.tripo3d.com)和**海外站**(developers.tripo3d.ai)账号,授权所属站点 +对应的 MCP 服务器即可。 + +## 包含的组件 + +| 组件 | 内容 | +| --- | --- | +| Skill `tripo-3d` | 主流程,包括工具检查、授权引导、MCP 工作流、场景到工具链的映射、输入处理和积分规则 | +| Skill `tripo-game-asset` | 游戏资产配方,包括面数预算道具、LOD 链、绑骨角色与动作,以及接入 Unity/Unreal/Godot/Three.js | +| MCP 服务器 `tripo` | 国内站远程 Streamable HTTP 服务器 `https://developers.tripo3d.com/mcp`(OAuth 2.1),提供 `tripo_plan`、生成、绑骨、转换和 `tripo_smart_uv` 等工具,以实际可见的工具 schema 为准 | +| MCP 服务器 `tripo-global` | 海外站远程服务器 `https://openapi-mcp.tripo3d.ai/mcp`(OAuth 2.1),提供相同工具 | +| Hook `SessionStart` | 注入 8 条规则,覆盖异步等待、短期链接、计费确认、浏览器授权、如实报错、PBR、模型选择和概念图确认,并根据系统时区提供区域提示 | + +## 使用方法 + +安装并启用插件后,直接描述需求即可,例如: + +- 生成一个低多边形的宝箱 3D 模型,导出 FBX 给 Unity 用 +- 把这张概念图变成带贴图的 3D 模型,导出 GLB +- 生成一个可 3D 打印的骑士小雕像,导出 STL 文件 +- 生成一个 T-pose 的机器人角色,绑好骨骼并加上走路动画 +- 查一下我的 Tripo 余额 + +也可以在输入框输入 `/`,从「技能」分组手动选用 `tripo-3d` 或 `tripo-game-asset`。 + +纯文字建模请求会先规划概念图并请你确认生图费用,生成并展示图片后等待你接受。 +接受图片后,Skill 再规划 3D 生成及你要求的后处理,并单独请你确认费用。你可以明确 +要求跳过概念图、直接文生 3D。你已提供的图片或多视图可直接用于 3D 生成。 + +### 首次授权 + +为账号所属站点的 Tripo MCP 服务器完成一次授权: + +1. 打开 **设置 → MCP 服务器**。在「Plugin MCP 服务器」分组中有两个 Tripo 条目, + 初次使用时会显示「需要授权」。`tripo` 对应国内站账号,`tripo-global` 对应海外 + 站账号。在账号所属站点的条目上点击 **打开授权**,另一个条目可以保持原样。 +2. 系统浏览器会打开对应站点的授权页。`tripo` 使用**国内站**(developers.tripo3d.com, + +86 短信登录、支付宝充值),`tripo-global` 使用**海外站**(developers.tripo3d.ai, + 邮箱登录、Stripe 充值)。授权页没有选区步骤。没有账号时可以注册,新账号有免费额度。 +3. 页面显示一次性验证码并打开 Tripo 控制台。登录后把验证码填入 **Verification code**, + 点击 **Authorize**。 +4. ZCode 自动重连并加载工具。需要撤销授权时,在 Tripo 控制台的 API Keys 页面删除 + 授权时选定的 Key。 + +如果已连接两个区域的账号,请在规划或上传前选择此次任务使用的账号。任务 ID、 +文件令牌和余额均归属所选服务器。 + +## 依赖、网络访问与副作用 + +- **网络**:ZCode 连接国内站 `https://developers.tripo3d.com/mcp` 和海外站 + `https://openapi-mcp.tripo3d.ai/mcp`,工具调用发往已授权的服务器,授权页跳转到 + 对应站点的 Tripo 控制台。生成结果通过 Tripo CDN 的短期链接获取,需要时用 + `tripo_task_status` 刷新。 +- **账号与计费**:生成任务消耗你自己 Tripo 账号的积分,通过任务状态与用量账单核对 + 实际消耗,失败任务自动退款。Skill 用 `tripo_plan` 规划计费步骤并在执行前取得明确 + 确认。批量生成时会查余额,并在各阶段执行前分别确认该阶段的费用。 +- **文件写入**:在你要求保存或集成模型时,Agent 用 `curl` 把结果下载到项目目录。 + Hook 与 MCP 服务器本身不写任何文件。 +- **命令执行**:仅在上传本地图片或模型,以及下载结果时运行 shell 命令。上传使用 + `tripo_upload_ticket` 返回的命令,较大文件可在连接的服务器支持时使用 + `tripo_upload_presign` 返回的命令。插件不会安装或调用命令行客户端,MCP 失败、 + 未授权、批量或本地落盘需求也不例外。 +- **Hook**:`hooks/session-start.mjs` 依赖 PATH 中的 `node`,从 stdin 读取事件,向 + stdout 输出规则和基于系统时区的区域提示,不访问网络、不读写文件。 +- **遥测**:插件本体没有独立的分析 SDK。已授权的 Tripo MCP 服务(国内或海外,记录 + 相同字段)启用分析时,可以记录工具调用结果、任务元数据及能够解析出的 Tripo 账号 + ID。两个 MCP 服务器均声明非凭据请求头 `X-Tripo-Distribution: zcode_plugin`。宿主 + 透传时,服务端会分别记录分发渠道和识别出的客户端(如 ZCode、Claude 或 unknown)。 + 埋点不包含提示词、API Key、OAuth token、文件路径或签名下载链接。账号凭据由 ZCode + 的凭据存储管理,不经过对话。 + +## 来源与许可 + +- 插件本体采用 MIT 许可,作者为 [VAST](https://www.tripo3d.ai)。 +- 两个 Skill 由 Tripo 官方的 Kimi / Codex 插件移植而来,同由 VAST 维护并采用 MIT 许可。 +- 两个 MCP 服务器均运行 Tripo 官方实现,生成内容遵循 [Tripo API 内容策略](https://platform.tripo3d.ai/docs)。 diff --git a/plugins/tripo-3d/hooks/session-start.mjs b/plugins/tripo-3d/hooks/session-start.mjs index 24101fdb..e3249dcd 100644 --- a/plugins/tripo-3d/hooks/session-start.mjs +++ b/plugins/tripo-3d/hooks/session-start.mjs @@ -5,12 +5,13 @@ const RULES = `Tripo 3D — rules that apply whenever Tripo tools (tripo_*) are used. These hold even when the tripo-3d skill was not loaded; load it for the full workflow. 1. Generation is asynchronous. Every tripo_* generation or processing tool returns a task_id immediately. Call tripo_task_wait with it and keep calling while status is queued/running — each call returns within about 55 seconds, a generation usually takes 1–4 minutes. Never present a result before status is success, and never treat a task_id as a finished model. -2. Deliver the file, then one link. On success, download model_url to a local file when a shell is available and give its path as plain text in backticks, never as a clickable link (chat previews cannot render meshes); then also offer model_url as a single markdown download link. Do not paste URLs from output_urls into the reply. Result URLs expire after about 2 hours: never re-print an old one — call tripo_task_status for fresh links. -3. Credits belong to the user. Call tripo_plan and get confirmation before any billed generation or chain; supply structured generation only for tripo_text_to_3d, tripo_image_to_3d and tripo_multiview_to_3d, including the exact text prompt for text-to-3D; never add generation to other steps such as tripo_image_to_splat. For those three use dry_run only when the connected schema exposes it; validate other steps against their schemas and current pricing. Resolve user-requested parameter conflicts before billing. Plan estimates are advisory, not a budget lock; label unknown costs not_estimated, and cite source, region and date for any static list estimate. Use tripo_usage for all task_ids to report actual total and per-task charges; if unavailable say the amount is pending. Check tripo_balance and confirm before generating more than one asset in a batch; on insufficient balance give the returned plans_url instead of retrying. Never silently re-roll a disappointing result — say what is off and ask first. -4. Authorization is a browser flow, never a pasted key. The plugin has one MCP server per Tripo region, and an account exists in only one region: tripo is the China site (developers.tripo3d.com, +86 SMS sign-in), tripo-global is the international site (developers.tripo3d.ai, email sign-in); neither auth page has a region picker. If Tripo tools are missing or a call reports an authorization error, ask which site the user's Tripo account is on unless they already said, then tell them to open ZCode Settings → MCP Servers, find that server under "Plugin MCP servers" and click "Open authorization" (ZCode shows these labels in its UI language), then sign in on that site's console and Authorize. The other server keeps showing "Authorization required", which is expected. If tools from both servers are available, ask which account to spend credits from and keep each task chain on that server: task IDs, file tokens and balances do not carry across regions. Never switch servers silently. Do not ask for an API key in the chat. MCP is the only execution path: never install or run a command-line client instead, even when a local login or API key exists. +2. Result links are short-lived. Refresh with tripo_task_status and offer one labeled download link. Save a local file only when the user requests a file on disk or project integration and a shell is available. Report the path in backticks. Do not paste raw URLs or the full output_urls list. For concept images, follow rule 8. +3. Credits belong to the user. Call tripo_plan and get confirmation before any billed generation or chain; supply structured generation only for tripo_text_to_3d, tripo_image_to_3d and tripo_multiview_to_3d, including the exact text prompt for text-to-3D; never add generation to other steps such as tripo_image_to_splat. For those three use dry_run only when the connected schema exposes it; validate other steps against their schemas and current pricing. Resolve user-requested parameter conflicts before billing. Plan estimates are advisory, not a budget lock; label unknown costs not_estimated, and cite source, region and date for any static list estimate. Use tripo_usage for all task_ids to report actual total and per-task charges; if unavailable say the amount is pending. Check tripo_balance and confirm the costs for each phase before generating a batch; on insufficient balance give the returned plans_url instead of retrying. Never silently re-roll a disappointing result — say what is off and ask first. +4. Authorization is a browser flow, never a pasted key. The plugin has one MCP server per Tripo region, and an account exists in only one region: tripo is the China site (developers.tripo3d.com, +86 SMS sign-in), tripo-global is the international site (developers.tripo3d.ai, email sign-in); neither auth page has a region picker. If Tripo tools are missing or a call reports an authorization error, ask which site the user's Tripo account is on unless they already said, then tell them to open ZCode Settings → MCP Servers, find that server under "Plugin MCP servers" and click "Open authorization" (ZCode shows these labels in its UI language), then sign in on that site's console and Authorize. The other server keeps showing "Authorization required", which is expected. If tools from both servers are available and the user has not chosen an account, ask before planning or uploading. Keep each task chain on the chosen server: task IDs, file tokens and balances do not carry across regions. Never switch servers silently. Do not ask for an API key in the chat. MCP is the only execution path: never install or run a command-line client instead, even when a local login or API key exists. 5. Failures are reported, not hidden. On failed/banned, relay failure_reason (and error_code) honestly; failed-task credits are refunded automatically. Never invent parameters — the tool schemas are authoritative. If a creation call times out without a task_id, do not automatically retry: check the original account's balance and task history when available and ask before another submission. Stylize has been retired: there is no tripo_stylize tool. tripo_mesh_edit is experimental; use it only if the connected server lists it. 6. PBR is opt-in. Send pbr: false on every tripo_text_to_3d, tripo_image_to_3d, tripo_multiview_to_3d and tripo_texture call unless the user explicitly asks for PBR (e.g. "with PBR" or "PBR materials", in any language); only then send pbr: true, which also forces texture: true. The API turns PBR on when pbr is omitted, so never leave it out. Detailed or high-quality textures do not mean PBR. -7. Choose models explicitly: the user's explicit compatible model wins over usage-based defaults; if requirements conflict, explain and ask before changing model or dropping a requirement. P2 is preferred for game/realtime topology and costs more credits than H/P1; within the P series the default is P2, and P1 is used only when the user names it or picks it for lower cost and speed; v3.1 for film/render/print. Do not infer the model from face_limit. Cost is not estimated by this text or guaranteed by tripo_plan: disclose uncertainty and obtain consent before billing. Pass the rig model explicitly: v3.0 for bipeds, v2.5 for animal body types (the API's own default is v1.0, which rigs bipeds only); use preset:walk, reserving preset:biped:* for explicit v1.0 rigs. Retopology v3.0 with smart_uv and standalone tripo_smart_uv are separate workflows, not interchangeable free export switches. Load the capability reference before running either. chat_image_1 is retired; never fall back to it. chat_image_1.5 remains usable where supported before 2026-12-01; never silently replace a user-selected paid image model. fast textures require texture model v3.5: pass the short name v3.5, or omit the version and the tool picks it. +7. Choose models explicitly: the user's explicit compatible model wins over usage-based defaults; if an explicit model conflicts with requirements, explain and ask before changing it or dropping a requirement. Without an explicit model, filter by required capabilities before applying scenario preferences (use v3.1 for generate_parts, smart_low_poly or detailed geometry). P2 is preferred for game/realtime topology and costs more credits than H/P1; within the P series the default is P2, and P1 is used only when the user names it or picks it for lower cost and speed; v3.1 for film/render/print. Do not infer the model from face_limit. Cost is not estimated by this text or guaranteed by tripo_plan: disclose uncertainty and obtain consent before billing. Pass the rig model explicitly: v3.0 for biped and others, v2.5 for animal body types, and use spec only for biped; use preset:walk, reserving preset:biped:* for explicit v1.0 rigs. Retopology v3.0 with smart_uv and standalone tripo_smart_uv are separate workflows, not interchangeable free export switches. Load the capability reference before running either. chat_image_1 is retired; never fall back to it. chat_image_1.5 remains usable where supported before 2026-12-01; never silently replace a user-selected paid image model. fast textures require texture model v3.5: pass the short name v3.5, or omit the version and the tool picks it. +8. Start a new 3D asset described only in words with a concept image unless the user explicitly asks to skip it. Plan and confirm only tripo_generate_image first. On success show the generated image from output_urls as a Markdown image, or provide one labeled link if inline display is unavailable. End the turn and wait for the user to accept that image. Only then plan tripo_image_to_3d using the accepted image task ID and ask separately for confirmation of the 3D costs. For a supplied image or multiview set, plan the corresponding 3D workflow directly. `; const CHINA_TIME_ZONES = new Set(["Asia/Shanghai", "Asia/Urumqi", "Asia/Chongqing", "Asia/Chungking", "Asia/Harbin", "Asia/Kashgar", "PRC"]); diff --git a/plugins/tripo-3d/skills/tripo-3d/SKILL.md b/plugins/tripo-3d/skills/tripo-3d/SKILL.md index 7544fca0..800cd50f 100644 --- a/plugins/tripo-3d/skills/tripo-3d/SKILL.md +++ b/plugins/tripo-3d/skills/tripo-3d/SKILL.md @@ -1,6 +1,6 @@ --- name: tripo-3d -description: Generate a 3D model from a text prompt, a reference image, or an existing mesh, and deliver it as GLB, FBX, OBJ, STL, USDZ or 3MF. Use when the user asks for a 3D asset, model, mesh, prop, character or texture for a game, renderer, viewer, AR scene or 3D print — including requests like "make me a low-poly X", "turn this image into 3D", "rig this character", "convert this model to FBX", or "generate placeholder assets", and the same requests in any language (text-to-3D, image-to-3D, rigging, character animation, texturing, low-poly or face reduction, 3D-printed figurines, format conversion). Also use to re-run, convert or inspect a previous Tripo generation. +description: Generate a 3D model from a text prompt, a reference image, or an existing mesh, and deliver it as GLB, FBX, OBJ, STL, USDZ or 3MF. Use when the user asks for a 3D asset, model, mesh, prop, character or texture for a game, renderer, viewer, AR scene or 3D print — including requests like "make me a low-poly X", "turn this image into 3D", "rig this character", "convert this model to FBX", or "generate placeholder assets", and the same requests in any language (text-to-3D, image-to-3D, rigging, character animation, texturing, low-poly or face reduction, 3D-printed figurines, format conversion). Also use to re-run, convert or inspect a previous Tripo generation, or to answer questions about Tripo model selection, supported parameters, and credits. --- # Tripo 3D @@ -32,7 +32,8 @@ instead — not for a balance check, not because a local login or `TRIPO_API_KEY` happens to exist (that may be a different account, and the user installed this plugin to use MCP). Local files and bulk jobs stay on MCP too: `tripo_upload_ticket` covers both images and mesh files (see Inputs -below), and results are downloaded with `curl` (see Deliver). +below). Use `curl` to save results into the project when the user requests a +local file or project integration (see Deliver). ## Authorization @@ -76,14 +77,44 @@ with exactly one key it is used as is). To revoke access, delete that key on the console's API Keys page — any other client sharing that key loses access too. -If tools from both servers are available, ask which account to spend credits -from before the first billed step, and keep the whole task chain on that -server: task IDs, file tokens and balances belong to one region and do not -carry over to the other server. Never switch servers silently. +If tools from both servers are available and the user has not chosen an +account, ask before planning or uploading. Keep the whole task chain on the +chosen server. Task IDs, file tokens and balances belong to that region. +Never switch servers silently. + +## Text prompts for new 3D assets + +When the user describes a new asset in words and has not supplied reference +images, start with a concept image: + +1. Plan and confirm only `tripo_generate_image`. Use the text prompt without + `input` or `inputs`. State the image model, options and cost or + `not_estimated`. For a humanoid to be rigged, describe the T-pose in this + prompt. The 3D model and its costs stay out of this first plan. +2. After the user confirms the image cost, generate the image and wait for + success. Get the generated image from the image task's `output_urls` + and show it as a Markdown image (`![Concept image]()`). If + inline display is unavailable, offer one labeled link to the image and + ask the user to open it before deciding. Use `tripo_task_status` on the same + task to refresh an expired link. End the turn and wait for explicit + acceptance of the image or a request to revise it. If the user cannot see + the image, help them open it and keep the 3D step pending. +3. After the user accepts the image, plan `tripo_image_to_3d` with its successful + image task ID as `input`, plus any requested post-processing. Show that + plan's model, options and costs and wait for separate spending confirmation + before starting it. A replacement concept needs a new image plan and + confirmation. + +Use `tripo_text_to_3d` for a new asset only if the user explicitly asks to +skip the concept image. If the image tool is unavailable, explain and ask +whether the user wants to supply an image or skip the concept step. If the user +supplied an image or a multiview set, plan `tripo_image_to_3d` or +`tripo_multiview_to_3d` directly using their input. ## Workflow -1. **Plan** — for any billed generation or chain, call `tripo_plan` first. +1. **Plan** — call `tripo_plan` for the billed steps being confirmed now. + For the first phase of Text prompts, this is only `tripo_generate_image`. For `tripo_text_to_3d`, `tripo_image_to_3d` and `tripo_multiview_to_3d` steps only, supply a structured `generation` object; include the exact `prompt` for text-to-3D. Never attach `generation` to other tools, including @@ -97,19 +128,19 @@ carry over to the other server. Never switch servers silently. `not_estimated` to the user, and wait for explicit confirmation. Skip the plan only for pure reads (`tripo_balance`, `tripo_usage`, `tripo_task_status` / `tripo_task_list`). Re-plan and reconfirm changed paid steps. -2. **Create** — `tripo_text_to_3d` for prompts (Chinese or English, concrete - nouns + style + materials), `tripo_image_to_3d` for images. Both return a - `task_id` immediately. If creation times out without a `task_id`, do not - automatically retry: check the original account's balance and task history - when available, then ask the user before considering another submission. +2. **Create** — use the tool in the confirmed plan. New 3D assets from words + follow Text prompts above, including its separate image and 3D confirmations. + Creation tools return a `task_id` immediately. If creation times out without + a `task_id`, do not automatically retry. Check the original account's + balance and task history when available, then ask before another submission. 3. **Wait** — call `tripo_task_wait` with the `task_id`; each call returns within about 55 s, so call it again while status is still `queued`/`running` (a generation takes 1–4 minutes). Do not invent your own sleep loop and do not treat the `task_id` as completion. -4. **Judge** — on `success`, check the result before building on it: you may - look at the rendered image listed in `output_urls`, but never paste - `output_urls` into the reply. On `failed`/`banned`, report - `failure_reason` honestly; failed-task credits are refunded automatically. +4. **Judge** — on `success`, check the result before building on it. Inspect + the rendered preview if available. For a concept image, show the single + generated image by following Text prompts above. On `failed`/`banned`, + report `failure_reason` honestly. Failed-task credits are refunded automatically. Do not silently re-roll a disappointing result — say what is off and ask; re-rolling means creating a new task with the same prompt. 5. **Post-process** (each asynchronous task requires `tripo_task_wait`; check @@ -120,10 +151,11 @@ carry over to the other server. Never switch servers silently. the original reference image when re-texturing a model made from one. - `tripo_rig_check` → `tripo_rig` — check riggability before spending rig credits, then add a skeleton with the `rig_type` the check returned. - Prompt characters as **T-pose** at generation time; `spec: "unity"` for - Unity Humanoid, `"mixamo"` for Mixamo pipelines. Always pass `model` by - body type: `"v3.0"` for `biped`, `"v2.5"` for the animal types the check - reports (`quadruped` `hexapod` `octopod` `avian` `serpentine` `aquatic`). + Prompt humanoids in a **T-pose** and use `spec` only for `biped` + (e.g. `"unity"` for Unity Humanoid or `"mixamo"` for Mixamo pipelines). + Pass `model` explicitly by body type: `"v3.0"` for `biped` and `others`, + `"v2.5"` for `quadruped`, `hexapod`, `octopod`, `avian`, `serpentine` + and `aquatic`. The API's own default is still `v1.0-20240301`, which rigs bipeds only. The `tripo_rig` result says which preset family the rig takes. - `tripo_animate` — presets on a **successful rig task** (≤5 per call, @@ -143,19 +175,16 @@ carry over to the other server. Never switch servers silently. existing mesh with P2 (`bbox` required). It is experimental; use it only when the connected server's actual tool list exposes it. Stylize (lego / voxel / voronoi / minecraft) has been retired — there is no `tripo_stylize` tool. -6. **Deliver** — result URLs (`model_url` and `output_urls`) **expire after - about 2 hours**; never cache or re-print an old one — call - `tripo_task_status` for fresh links. Download the file into the project - (`curl -L -o ""`) and give the local path as plain text in - backticks — never as a clickable link, the chat preview cannot render - meshes — then also offer `model_url` as a single markdown download link; - offer the next real action: reveal it in the file manager - (`open -R ` on macOS, `explorer /select,` on Windows) or wire it - into the project. Only when no shell is available give just the fresh - `model_url` link and say it is short-lived, offering to refresh it on - request. Do not paste other URLs from `output_urls`. After a - `tripo_convert`, the native GLB stays on the earlier task — fetch it with - `tripo_task_status` on that task instead of paying for another conversion. +6. **Deliver** — result links are short-lived. If a link is stale or missing, + refresh it with `tripo_task_status`. Offer the model + as a single labeled download link. Only save a local file when the user + asks for a file on disk or for project integration. With a shell available, + download it to the requested or appropriate project path + (`curl -fL -o "" ""`) and report the path in backticks. If + saving was requested but the shell is unavailable or the download failed, + report that and provide the fresh link. Do not paste raw URLs or the full + `output_urls` list. After `tripo_convert`, fetch the native GLB through + `tripo_task_status` on the original task whenever it is needed. Call `tripo_usage` with all workflow task IDs and report actual total and per-task charges; if the ledger is unavailable, say the amount is pending. @@ -164,9 +193,10 @@ carry over to the other server. Never switch servers silently. Pick the chain from what the user is building; each asynchronous task must finish before a dependent step runs. Check each tool's billing and input rules: `tripo_rig_check` is free and rig uses the original model, not the check task. -The examples below are suggestions only; an explicitly requested compatible -model overrides the usage-based default. GLB is the native output — a -`tripo_convert` step is only worth its credits when the target needs another format. +The examples pick 3D options after any required concept-image approval. Use +the model compatible with the user's requirements before applying these +suggestions. GLB is the native output — a `tripo_convert` step is only worth +its credits when the target needs another format. - **Game prop, mobile / WebGL / many instances** — generate with explicit `model: "P2"` and a confirmed `face_limit` → @@ -180,12 +210,10 @@ model overrides the usage-based default. GLB is the native output — a `format: "STL"` (`flatten_bottom: true` for a stable base); `3MF` also works. - **AR / iOS Quick Look** — `auto_size: true` (real-world meters) → `tripo_convert` `format: "USDZ"`; WebXR uses the GLB directly. -- **Animated character** — T-pose reference first (`tripo_generate_image` - with `template: "t_pose"` turns a character image into one) → - `tripo_image_to_3d`/`tripo_text_to_3d` → `tripo_rig_check` → `tripo_rig` - (`model: "v3.0"`, or `"v2.5"` for an animal; `spec: "unity"` for Unity Humanoid) → - `tripo_animate` with the preset - family named in the `tripo_rig` result: v3.0 humanoids +- **Animated character** — use the accepted T-pose concept or supplied image + for `tripo_image_to_3d`, then `tripo_rig_check` → `tripo_rig` (explicit model + by body type; `spec: "unity"` only for a Unity Humanoid biped) → + `tripo_animate` with the preset family named in the `tripo_rig` result: v3.0 humanoids `["preset:walk", "preset:idle"]`; creatures use their body-specific presets (e.g. `preset:quadruped:walk`); explicit v1.0 humanoids alone use `preset:biped:*`. @@ -201,17 +229,19 @@ model overrides the usage-based default. GLB is the native output — a reusable task_id with a preview (`.gltf` is rejected — export `.glb`). - **Not a mesh** — `tripo_image_to_splat` outputs a Gaussian-splat `.splat` scene for viewers, not an editable model; say so before running it. If the - result has no `model_url`, the file is the `model_url` entry of `output_urls`; - deliver that one. + result has no `model_url`, deliver the `.splat` result from `output_urls`. ## Parameters that matter - **Choose the generation model explicitly**: the user's explicitly chosen model wins over usage-based defaults. If it conflicts with required features, explain - the conflict and ask before changing model or dropping a requirement. Otherwise, - P2 is preferred for game/realtime topology (costs more credits than H/P1); - within the P series the default is P2, and P1 is used only when the user names it - or picks it for lower cost and speed. Use v3.1 for film/render/print. This is + the conflict and ask before changing model or dropping a requirement. If the + user did not specify a model, first filter by required capabilities and then + apply the scenario preference. For example, use `v3.1` for `generate_parts`, + `smart_low_poly` or `geometry_quality: "detailed"` even for a game asset. + Among compatible models, P2 is preferred for game/realtime topology (costs + more credits than H/P1). For choices within the P series the default is P2, + and P1 is used only when the user names it or picks it for lower cost and speed. Use v3.1 for film/render/print. This is plugin policy, not an API requirement. Confirm the model, texture options and cost; re-confirm any paid model change. - **PBR is opt-in.** Send `pbr: false` on every `tripo_text_to_3d`, @@ -246,7 +276,11 @@ model overrides the usage-based default. GLB is the native output — a and read `file_token` from the JSON response. - Model files (GLB/FBX/OBJ/STL, ≤150 MB) use the same ticket with `kind: "model"` and `format`; the `file_token` then feeds - `tripo_import_model` or any processing tool directly. + `tripo_import_model` or any processing tool directly. Tell the user if the + import reports a `normalize_scale` other than 1, since it changed the model size. +- For larger local inputs, use `tripo_upload_presign` when the connected server + exposes it and supports the file format. Follow its returned upload command + and use the file token after the upload succeeds. - Task ids chain: use a successful model task where the processing tool accepts it. Animation requires a successful rig task, mesh completion a segment task, and smart segmentation a file token or URL. Rig uses the original model task, @@ -265,9 +299,11 @@ model overrides the usage-based default. GLB is the native output — a ## Spending the user's credits -- `tripo_balance` first when the user asks for several assets; confirm the - whole batch and its cost once before generating more than one, then call the - tools one asset at a time, and report `credits_consumed` after. +- Use `tripo_balance` before spending on several assets. Confirm the steps and + cost for each phase of the batch, and call the tools one asset at a time. + For concept-first batches, present each image for acceptance before planning + its 3D generation, then confirm the 3D costs before generating any models. + Report the actual charges from `tripo_usage` after the work. - Error `2000` means that category's concurrency pool is full and no task was created: retry after `Retry-After` or once a running task of the same category finishes. Error `1007` is the request rate limit: wait a few diff --git a/plugins/tripo-3d/skills/tripo-3d/references/capability.md b/plugins/tripo-3d/skills/tripo-3d/references/capability.md index fda1b169..6f66cb07 100644 --- a/plugins/tripo-3d/skills/tripo-3d/references/capability.md +++ b/plugins/tripo-3d/skills/tripo-3d/references/capability.md @@ -10,16 +10,20 @@ change one, resolve the conflict with the user before creating a paid task. | model | MCP `model` | use for | limits | | --- | --- | --- | --- | -| **v3.1** (default) | `v3.1` | high fidelity: film, render, print | full parameter set | +| **v3.1** | `v3.1` | high fidelity: film, render, print | full parameter set | | **P1** | `P1` | P series alternative, only when the user names it or picks it for lower cost and speed | `face_limit` 50–20000; no `quad`, `smart_low_poly`, `generate_parts`, `geometry_quality` | | **P2** | `P2` → wire `P2-20260801` | default P-series model, preferred for game/realtime topology, with explicit user confirmation | `face_limit` 48–50000 tri / 48–25000 quad; supports `quad`, still no `smart_low_poly`, `generate_parts`, `geometry_quality`; costs more credits than H/P1, and price depends on texture options; confirm the estimate. Pass the generation model explicitly | | v3.0, v2.5 | `v3.0`, `v2.5` | legacy, only when the user asks | v2.5 has no `geometry_quality`, `quad`, `smart_low_poly`, `generate_parts`, `auto_size`, `compress` (stripped with a note) | Website model names map to these rows: H3.1 → `v3.1`, P1.0 → `P1`, P2.0 → `P2`. +The current MCP resolves an omitted generation `model` to P2. Pass the +confirmed model explicitly and follow the connected tool schema. Selection policy: the explicitly requested model wins over use-based defaults; -resolve incompatible requirements with the user before any paid call. Otherwise, -explicitly choose P2 for game/realtime topology; within the P series the default +resolve incompatible requirements with the user before any paid call. When the +user has not specified a model, choose one that supports the required features +first: use v3.1 for `generate_parts`, `smart_low_poly`, or detailed geometry. +Otherwise, explicitly choose P2 for game/realtime topology; within the P series the default is P2, and P1 is used only when the user names it or picks it for lower cost and speed; v3.1 for film/render/print. This is plugin guidance, not an API requirement. Do not rely on implicit routing @@ -77,6 +81,16 @@ paid task for integrated smart_uv without confirming the extra cost. ## Processing steps +For local image or model files, `tripo_upload_presign` provides a direct storage +URL when the connected server exposes it. Pass the file extension as `format`, +then PUT the raw bytes using the returned `how_to`. Use the returned `file_token` +only after the PUT succeeds; do not send a Tripo authorization header with it. +The tool supports PNG/JPEG/WebP images and GLB/FBX/OBJ/STL models. + +If a model task reports a `normalize_scale` other than 1, tell the user that +Tripo scaled the imported model. Final size is original size multiplied by +`normalize_scale`, and the original size is the final size divided by that value. + Most mesh processing tools accept a model task_id, a `file_token` or a model URL as `input`. Check each tool's schema; for example: `tripo_animate` (`task_id` of a successful rig task), `tripo_mesh_complete` (`task_id` of a successful segment task) and @@ -87,10 +101,10 @@ as `input`. Check each tool's schema; for example: `tripo_animate` (`task_id` of | `tripo_texture` | `texture_quality` `standard`/`detailed`/`extreme`/`fast` (fast requires v3.5); `pbr` (send `false` unless the user explicitly asks for PBR); `texture_seed`; `texture_alignment`; `model` as the short name: `v3.0` (`v3.0-20250812`, default) / `v3.5` (`v3.5-20260815`, newest; unlocks `delight` and `texture_quality: "fast"`, picked automatically for them when `model` is omitted) / `v2.5`; `bake`; `part_names` (segmented models); `compress`. Guidance — select one of `prompt` (+ optional `style_image`), `image`, `images` (4 views front/left/back/right), or native `texture_prompt`; native `texture_prompt` cannot be combined with the shortcut fields. Provide guidance for imported meshes; it may be omitted for Tripo-generated models. Re-supply the original reference image when re-texturing a model made from one. Re-textures any model, including imported files | | `tripo_mesh_edit` | Experimental P2 regional regenerate: use only when listed by the connected server. `input` (task_id / file_token / URL) + axis-aligned `bbox` in model space; optional `ref_image`. Rest of mesh kept. Billed separately | | `tripo_plan` | Free advisory draft **before** any billed call. Pass structured `generation` only for `tripo_text_to_3d`, `tripo_image_to_3d` and `tripo_multiview_to_3d`; text-to-3D requires its exact prompt. Do not add `generation` to other steps such as `tripo_image_to_splat`. Review `dry_run` only for these three when their connected schemas expose it; validate other steps against their own schemas. Free-text `params` alone leave the model unresolved. Show billed steps and estimates or `not_estimated`, then wait for explicit confirmation; not a quote or budget lock. Skip only for pure reads | -| `tripo_convert` | `format` `GLTF` `USDZ` `FBX` `OBJ` `STL` `3MF` (3MF = single-colour print). Mesh: `quad`, `force_symmetry` (quad only), `face_limit` (default: keep), `flatten_bottom` + `flatten_bottom_threshold` (0.01). Texture: `texture_size` (4096), `texture_format` `JPEG`/`PNG`/`WEBP`/`BMP`/`TIFF`/`TARGA`/`HDR`/`DPX`/`OPEN_EXR`, `bake` (true), `pack_uv`, `export_vertex_colors` (OBJ/GLTF only). Export: `pivot_to_center_bottom`, `scale_factor`, `auto_size`, `with_animation` (true), `animate_in_place`, `part_names`, `export_orientation`, `fbx_preset` `blender`/`3dsmax`/`mixamo` (FBX only). `quad` with `GLTF` is rejected. A non-default `quad`, `flatten_bottom`/`flatten_bottom_threshold`, `texture_size`, `texture_format`, `pivot_to_center_bottom` or `scale_factor`, or any `face_limit`, bills the complex tier (10 credits instead of 5); the other options do not | +| `tripo_convert` | `format` `GLTF` `USDZ` `FBX` `OBJ` `STL` `3MF` (3MF = single-colour print). Mesh: `quad`, `force_symmetry` (quad only), `face_limit` (default: keep), `flatten_bottom` + `flatten_bottom_threshold` (0.01). Texture: `texture_size` (4096), `texture_format` `JPEG`/`PNG`/`WEBP`/`BMP`/`TIFF`/`TARGA`/`HDR`/`DPX`/`OPEN_EXR`, `bake` (true), `pack_uv`, `export_vertex_colors` (OBJ/GLTF only). Export: `pivot_to_center_bottom`, `scale_factor`, `auto_size`, `with_animation` (true), `animate_in_place`, `part_names`, `export_orientation`, `fbx_preset` `blender`/`3dsmax`/`mixamo`/`bake_scale` (FBX only; `bake_scale` bakes the scale transform into the geometry). `quad` with `GLTF` is rejected. A non-default `quad`, `flatten_bottom`/`flatten_bottom_threshold`, `texture_size`, `texture_format`, `pivot_to_center_bottom` or `scale_factor`, or any `face_limit`, bills the complex tier (10 credits instead of 5); the other options do not | | `tripo_import_model` | GLB/GLTF/FBX/OBJ/STL ≤150 MB via `file_token` or URL (`.gltf` only as a URL — upload `.glb`) | | `tripo_rig_check` | free. Input: successful model task ID, `file_token`, or public model URL; documented file formats are GLB, FBX, OBJ and STL (up to 150 MB). Result: `riggable` and recommended `rig_type`: `biped` `quadruped` `hexapod` `octopod` `avian` `serpentine` `aquatic`. Gate step — not riggable → stop; riggable → rig the **original model task**, not the check task | -| `tripo_rig` | `model`: always pass it by body type: `v3.0` (`v3.0-20260909`) for `biped` and `others`, `v2.5` (`v2.5-20260210`, the official animal rig) for `quadruped`/`hexapod`/`octopod`/`avian`/`serpentine`/`aquatic`. When it is omitted the MCP sends v3.0 for every body type, and the API's own default is `v1.0-20240301`, which rigs bipeds only. v3.0 is required for `others` and the `actorcore`/`unity`/`unreal`/`vrm` specs. Both take `preset:walk` / `preset:idle` on bipeds and body-type clips on creatures. Explicit `v1.0-20240301` (`v1.0`) is legacy biped-only for 90+ `preset:biped:*` clips. Read the returned model before animation. `rig_type` comes from rig-check; rig the original model, not the check task. `spec` is biped-only; `out_format` is `glb`/`fbx`. | +| `tripo_rig` | `model`: always pass it by body type: `v3.0` (`v3.0-20260909`) for `biped` and `others`, `v2.5` (`v2.5-20260210`, the official animal rig) for `quadruped`/`hexapod`/`octopod`/`avian`/`serpentine`/`aquatic`. When it is omitted the MCP sends v2.5 for `quadruped` and v3.0 for other body types, and the API's own default is `v1.0-20240301`, which rigs bipeds only. v3.0 is required for `others` and the `actorcore`/`unity`/`unreal`/`vrm` specs. Both take `preset:walk` / `preset:idle` on bipeds and body-type clips on creatures. Explicit `v1.0-20240301` (`v1.0`) is legacy biped-only for 90+ `preset:biped:*` clips. Read the returned model before animation. `rig_type` comes from rig-check; rig the original model, not the check task. `spec` is biped-only; `out_format` is `glb`/`fbx`. | | `tripo_animate` | needs a rig task. `animations: [...]` (≤5, billed per clip). `out_format` `glb`/`fbx`, `animate_in_place` (no root motion — game code drives movement), `export_with_geometry` (true); `bake_animation` is deprecated — do not pass it (it is ignored) | | `tripo_segment` | `model` `v1.0-20250506` (geometry-based, default) or `v2.0-20260430` (semantic, beta) with `segmentation_granularity` `simple`/`balanced`/`detailed`, `split_by_connectivity` (true), `ref_image` (overrides the other two). The tool switches to v2.0 automatically when a v2-only argument is set without `model`; an explicit `v1.0-20250506` with any of them is rejected and no task is created | | `tripo_mesh_complete` | needs a segment task. `completion_mode` `ai_completion` (default) / `quick_cap` (hole fill, cheaper); `part_names` (default all) | @@ -112,7 +126,8 @@ from the `tripo_rig` result (this skill passes v3.0 for bipeds and v2.5 for anim `tripo_generate_image` (text→image when no `input`; edit/fusion with `input` or `inputs`), `tripo_image_to_multiview`, `tripo_edit_multiview`, `tripo_image_to_splat`. An image task_id is a valid `input` for -`tripo_image_to_3d` — no re-upload. +`tripo_image_to_3d` — no re-upload. Follow the [main workflow](../SKILL.md) +for displaying and confirming a concept image before model generation. - **Templates** (`template`): choose from the documented endpoint whitelist: - Text-to-image templates: `asset_extraction`, `character_completion`, `t_pose`, `variants`, `figure`. @@ -121,7 +136,8 @@ or `inputs`), `tripo_image_to_multiview`, `tripo_edit_multiview`, and the `template` argument does not accept them; do not recommend them as supported templates. - Image editing requires `prompt` and/or `template`; text-to-image requires a - prompt. Negative prompts go inside `prompt` after `--no`. + prompt. For `tripo_generate_image`, pass exclusions using the separate + `negative_prompt` argument when it is exposed by the connected schema. - **Image models** (`model`): `seedream_v4` (text-to-image default; **not accepted by image editing**), `seedream_v5` (editing default), Google Gemini as `banana` (= gemini-2.5-flash, fast), `banana_pro` (= gemini-3-pro, quality), diff --git a/plugins/tripo-3d/skills/tripo-game-asset/SKILL.md b/plugins/tripo-3d/skills/tripo-game-asset/SKILL.md index 803c728c..610c5d56 100644 --- a/plugins/tripo-3d/skills/tripo-game-asset/SKILL.md +++ b/plugins/tripo-3d/skills/tripo-game-asset/SKILL.md @@ -14,21 +14,30 @@ and rig uses the original model task rather than the check task. Each `tripo_text_to_3d`, `tripo_image_to_3d`, `tripo_multiview_to_3d` and `tripo_texture` call sends `pbr: false` unless the user explicitly asks for PBR. -The point of these recipes is that assets land in the project's own directory -structure: after each final step download the file with -`curl -L -o /. ""` (links expire after about -2 hours — fetch fresh ones with `tripo_task_status` if needed) and report the -local path. +For a subject described in words, follow the `tripo-3d` concept-image workflow: +plan and confirm the billed `tripo_generate_image` step, wait for it, show the +image, and stop for the user's acceptance. Only after acceptance, plan and +confirm `tripo_image_to_3d` and any requested post-processing, then use the +accepted image task ID as `input`. Call `tripo_text_to_3d` only when the user +explicitly asks to skip the image. A user-supplied image or multiview set goes +directly to `tripo_image_to_3d` or `tripo_multiview_to_3d` respectively. + +Download the final file into the project only when the user asks to save it or +integrate it there. Result links are short-lived; call `tripo_task_status` for +a fresh link before use. Report the saved path when a file is downloaded. ## Pick a budget first An explicitly requested model takes priority over these recipes. If it cannot support a requested feature, explain the conflict and ask before changing the -model or dropping the feature. Otherwise, explicitly choose P2 for game/realtime -topology; within the P series the default is P2, and P1 is used only when the -user names it or picks it for lower cost and speed; v3.1 for film/render/print. -Confirm the selected model, texture options and estimated or unestimated cost; -re-confirm any paid model change. The example calls below use defaults only. +model or dropping the feature. When no model was specified, select a model that +supports the required features first: v3.1 supports `generate_parts`, +`smart_low_poly` and `geometry_quality: "detailed"`. Otherwise, explicitly choose +P2 for game/realtime topology; within the P series the default is P2, and P1 is +used only when the user names it or picks it for lower cost and speed; v3.1 for +film/render/print. Confirm the selected model, texture options and estimated or +unestimated cost before the billed model step; re-confirm any paid model change. +The example calls below use defaults only and start after image acceptance. | target | generation call | export | | ----------------------------- | ------------------------------------------------------------ | -------------------------------------------- | @@ -46,28 +55,32 @@ Two budget-related choices the defaults do not make for you: - **v3.1 quality under a face cap** — explicitly set `model: "v3.1"` when the user wants v3.1 geometry with a budget. -Override the face budget when the project has a stricter one, e.g. -`tripo_text_to_3d` `{ model: "P2", prompt: "a health potion bottle", face_limit: 3000, pbr: false }` → +Override the face budget when the project has a stricter one. For example, after +accepting a concept image of a health potion bottle and confirming this 3D chain: +`tripo_image_to_3d` `{ input: , model: "P2", face_limit: 3000, pbr: false }` → `tripo_convert` `{ format: "FBX", texture_size: 1024 }`. ## Props -`tripo_text_to_3d` `{ model: "P2", prompt: "an ornate treasure chest, fantasy style", texture_quality: "detailed", pbr: false }` -→ download the GLB (or → `tripo_convert` `{ format: "FBX" }` for Unity/Unreal). +For an ornate fantasy treasure chest, first create and show a concept image as +above. After the user accepts it and confirms the 3D chain, use +`tripo_image_to_3d` `{ input: , model: "P2", texture_quality: "detailed", pbr: false }` +→ deliver the GLB (or → `tripo_convert` `{ format: "FBX" }` for Unity/Unreal). -For a set of props, generate them one at a time and check each -result before continuing — a bad seed early is cheaper to catch -than at the end of a batch. Confirm the total cost of the whole set with the -user first (`tripo_plan`, `tripo_balance`), then call the tools one asset at a -time, and use `tripo_task_list` to check the status of many task ids in one -call. +For a set of props, plan and confirm the estimated or unestimated cost of the +image batch first (`tripo_plan`, `tripo_balance`), then show the images and wait +for acceptance. After acceptance, plan and confirm the 3D and post-processing +steps before running them. Generate assets one at a time and check each result +before continuing. Use `tripo_task_list` to check many task IDs in one call. ## LOD chain from one source Generate once, then one `tripo_decimate` per level — each with the **original generation task** as `input`, not the previous LOD: -`tripo_text_to_3d` `{ model: "P2", prompt: "a stone golem", pbr: false }` (LOD0) +After the user accepts a stone golem concept image and confirms the 3D chain: + +`tripo_image_to_3d` `{ input: , model: "P2", pbr: false }` (LOD0) → `tripo_decimate` `{ input: , face_limit: 5000 }` (LOD1) → `tripo_decimate` `{ input: , face_limit: 1500 }` (LOD2) → `tripo_convert` `{ input: , format: "FBX" }` if the engine needs FBX. @@ -88,23 +101,32 @@ skill). ## Characters with animation -1. **T-pose source.** Prompt for it (`"a knight in full armor, T-pose, standing straight"`) - or turn a character image into one with `tripo_generate_image` - `{ input: , template: "t_pose" }` — rigging quality depends heavily on it. -2. `tripo_text_to_3d` / `tripo_image_to_3d` with explicit `model: "P2"` → the - character model task. +1. **Character source.** For a humanoid described in words, include a T-pose in + the concept-image request (for example, `"a knight in full armor, T-pose, standing + straight"`) and use `template: "t_pose"` when the connected image tool supports + it. Confirm the image cost, show the image, and wait for acceptance as above. + A supplied character image or multiview set can be used directly. If the user + asks to make a T-pose image first, confirm and run `tripo_generate_image` + `{ input: , template: "t_pose" }`, then show it and wait for acceptance. +2. After any required image acceptance, plan and confirm the model and + requested post-processing. Use `tripo_image_to_3d` + `{ input: , model: "P2", pbr: false }` + or `tripo_multiview_to_3d` for supplied multiviews. Use + `tripo_text_to_3d` only for an explicit request to skip the image. Pass + `pbr: false` unless the user requested PBR. The result is the character model task. 3. `tripo_rig_check` `{ input: }` — free. It gates the chain: not riggable → stop before spending rigging credits. Read the recommended - `rig_type` (`biped` `quadruped` `hexapod` `octopod` `avian` `serpentine` `aquatic`). -4. `tripo_rig` `{ input: , model: "v3.0", rig_type: , spec: "mixamo", out_format: "fbx" }` - — rig the **original model task**, not the check task. `spec: "mixamo"` - gives Mixamo bone names (`"unity"` for Unity Humanoid, `"unreal"` for the UE - Mannequin); `spec` applies to `biped` - only, so drop it for the other body types (the tool rejects it). Pass - `model: "v3.0"` for `biped` and `model: "v2.5"` for the animal types - (`quadruped` `hexapod` `octopod` `avian` `serpentine` `aquatic`): the API's - own default, v1.0, rigs bipeds only. The result names the preset family to - use next. + `rig_type` (`biped` `quadruped` `hexapod` `octopod` `avian` `serpentine` `aquatic` `others`). +4. `tripo_rig` on the **original model task** using the returned body type: + - Biped: `{ input: , model: "v3.0", rig_type: "biped", spec: "mixamo", out_format: "fbx" }`. + `spec: "mixamo"` gives Mixamo bone names; use `"unity"` for Unity Humanoid + or `"unreal"` for the UE Mannequin. + - Animal: `{ input: , model: "v2.5", rig_type: , out_format: "fbx" }` + for `quadruped`, `hexapod`, `octopod`, `avian`, `serpentine` or `aquatic`. + - Other: `{ input: , model: "v3.0", rig_type: "others", out_format: "fbx" }`. + + `spec` applies only to `biped`. The API's own default, v1.0, rigs bipeds + only. The result names the preset family to use next. 5. `tripo_animate` `{ task_id: , animations: [...], out_format: "fbx", animate_in_place: true }` — at most five clips, billed per clip. Explicit legacy v1.0 rigs take `preset:biped:idle` `preset:biped:walk` `preset:biped:run` `preset:biped:jump` @@ -132,11 +154,11 @@ To animate a mesh the project already has: `tripo_upload_ticket` ## Wiring into the project -After a successful chain, download the final `model_url` into the project's -art directory and use that path for the import. Do the integration work the -user actually asked for — add the loader call, register the prefab, update the -asset manifest — rather than stopping at "the file is generated". Check the -preview first so a wrong asset does not get wired in. +When the user asks to integrate the asset into the project, download the final +`model_url` into the project's art directory and use that path for the import. +Do the integration work the user asked for — add the loader call, register the +prefab, or update the asset manifest. Check the preview first so a wrong asset +does not get wired in. Retopology: `tripo_decimate` with explicit `model: "v3.0", smart_uv: true` combines retopology and UVs; check current pricing. Standalone From 23de1f5e1626d7cac6e2886c2425ff840c2c30d2 Mon Sep 17 00:00:00 2001 From: sunzhenqiang Date: Thu, 19 Nov 2026 07:45:34 -0600 Subject: [PATCH 8/8] fix(tripo-3d): limit marketplace release to China accounts --- marketplace.json | 6 +- plugins/tripo-3d/.claude-plugin/plugin.json | 6 +- plugins/tripo-3d/.mcp.json | 9 --- plugins/tripo-3d/.zcode-plugin/plugin.json | 6 +- plugins/tripo-3d/README.md | 60 ++++++---------- plugins/tripo-3d/README_CN.md | 43 +++++------- plugins/tripo-3d/hooks/session-start.mjs | 12 +--- plugins/tripo-3d/skills/tripo-3d/SKILL.md | 68 +++++++------------ .../skills/tripo-3d/references/capability.md | 8 +-- .../tripo-3d/skills/tripo-game-asset/SKILL.md | 2 +- 10 files changed, 80 insertions(+), 140 deletions(-) diff --git a/marketplace.json b/marketplace.json index 98f3f23d..8b75927a 100644 --- a/marketplace.json +++ b/marketplace.json @@ -1097,10 +1097,10 @@ "en": "Tripo 3D", "zh-CN": "Tripo 3D" }, - "description": "Generate textured 3D models from text or images, add rigging and animation, simplify meshes, and export assets for games or 3D printing. Works with mainland China and international Tripo accounts.", + "description": "Generate textured 3D models from text or images, add rigging and animation, simplify meshes, and export assets for games or 3D printing. Requires a mainland China Tripo account.", "description_i18n": { - "en": "Generate textured 3D models from text or images, add rigging and animation, simplify meshes, and export assets for games or 3D printing. Works with mainland China and international Tripo accounts.", - "zh-CN": "用文字或图片生成带贴图的 3D 模型,添加骨骼与动画、精简模型面数,导出用于游戏或 3D 打印的素材。支持 Tripo 国内站和海外站账号。" + "en": "Generate textured 3D models from text or images, add rigging and animation, simplify meshes, and export assets for games or 3D printing. Requires a mainland China Tripo account.", + "zh-CN": "用文字或图片生成带贴图的 3D 模型,添加骨骼与动画、精简模型面数,导出用于游戏或 3D 打印的素材。需使用 Tripo 国内站账号。" }, "version": "0.1.5", "author": { diff --git a/plugins/tripo-3d/.claude-plugin/plugin.json b/plugins/tripo-3d/.claude-plugin/plugin.json index 71e971e6..dd4f3542 100644 --- a/plugins/tripo-3d/.claude-plugin/plugin.json +++ b/plugins/tripo-3d/.claude-plugin/plugin.json @@ -1,10 +1,10 @@ { "name": "tripo-3d", "version": "0.1.5", - "description": "Generate textured 3D models from text or images, add rigging and animation, simplify meshes, and export assets for games or 3D printing. Works with mainland China and international Tripo accounts.", + "description": "Generate textured 3D models from text or images, add rigging and animation, simplify meshes, and export assets for games or 3D printing. Requires a mainland China Tripo account.", "description_i18n": { - "en": "Generate textured 3D models from text or images, add rigging and animation, simplify meshes, and export assets for games or 3D printing. Works with mainland China and international Tripo accounts.", - "zh-CN": "用文字或图片生成带贴图的 3D 模型,添加骨骼与动画、精简模型面数,导出用于游戏或 3D 打印的素材。支持 Tripo 国内站和海外站账号。" + "en": "Generate textured 3D models from text or images, add rigging and animation, simplify meshes, and export assets for games or 3D printing. Requires a mainland China Tripo account.", + "zh-CN": "用文字或图片生成带贴图的 3D 模型,添加骨骼与动画、精简模型面数,导出用于游戏或 3D 打印的素材。需使用 Tripo 国内站账号。" }, "author": { "name": "VAST", diff --git a/plugins/tripo-3d/.mcp.json b/plugins/tripo-3d/.mcp.json index 58e1b3bc..edca3688 100644 --- a/plugins/tripo-3d/.mcp.json +++ b/plugins/tripo-3d/.mcp.json @@ -8,15 +8,6 @@ "headers": { "X-Tripo-Distribution": "zcode_plugin" } - }, - "tripo-global": { - "type": "http", - "url": "https://openapi-mcp.tripo3d.ai/mcp", - "enabled": true, - "timeoutMs": 90000, - "headers": { - "X-Tripo-Distribution": "zcode_plugin" - } } } } diff --git a/plugins/tripo-3d/.zcode-plugin/plugin.json b/plugins/tripo-3d/.zcode-plugin/plugin.json index 71e971e6..dd4f3542 100644 --- a/plugins/tripo-3d/.zcode-plugin/plugin.json +++ b/plugins/tripo-3d/.zcode-plugin/plugin.json @@ -1,10 +1,10 @@ { "name": "tripo-3d", "version": "0.1.5", - "description": "Generate textured 3D models from text or images, add rigging and animation, simplify meshes, and export assets for games or 3D printing. Works with mainland China and international Tripo accounts.", + "description": "Generate textured 3D models from text or images, add rigging and animation, simplify meshes, and export assets for games or 3D printing. Requires a mainland China Tripo account.", "description_i18n": { - "en": "Generate textured 3D models from text or images, add rigging and animation, simplify meshes, and export assets for games or 3D printing. Works with mainland China and international Tripo accounts.", - "zh-CN": "用文字或图片生成带贴图的 3D 模型,添加骨骼与动画、精简模型面数,导出用于游戏或 3D 打印的素材。支持 Tripo 国内站和海外站账号。" + "en": "Generate textured 3D models from text or images, add rigging and animation, simplify meshes, and export assets for games or 3D printing. Requires a mainland China Tripo account.", + "zh-CN": "用文字或图片生成带贴图的 3D 模型,添加骨骼与动画、精简模型面数,导出用于游戏或 3D 打印的素材。需使用 Tripo 国内站账号。" }, "author": { "name": "VAST", diff --git a/plugins/tripo-3d/README.md b/plugins/tripo-3d/README.md index eba93300..aef17435 100644 --- a/plugins/tripo-3d/README.md +++ b/plugins/tripo-3d/README.md @@ -4,9 +4,8 @@ ## 0.1.5 -Works with both China-mainland and international Tripo accounts: the plugin -ships one MCP server per region, `tripo` for the China site and `tripo-global` -for the international site, and you authorize the one your account belongs to. +This plugin connects to the Tripo China site through its `tripo` MCP server. +It requires a Tripo mainland China account. A user's explicitly chosen compatible model overrides usage-based defaults. Choose from models that support the required features before applying the @@ -33,10 +32,8 @@ prompt or a reference image, with rigging, animation, retopology and format conversion (GLB/FBX/OBJ/STL/USDZ/3MF). You can ask to save the files in your project. Built for games, film, AR and 3D printing. -Connect your Tripo account once in the browser — no API key pasting. Both -**China-mainland** (developers.tripo3d.com) and **international** -(developers.tripo3d.ai) accounts work: the plugin ships one MCP server per -region and you authorize only the one your account belongs to. +Connect your Tripo mainland China account (developers.tripo3d.com) once in +the browser, without pasting an API key into the chat. ## Components @@ -45,8 +42,7 @@ region and you authorize only the one your account belongs to. | Skill `tripo-3d` | Main workflow: tool check, authorization guidance, MCP workflow, scenario → tool-chain mapping, input handling, credit rules | | Skill `tripo-game-asset` | Game-asset recipes: budgeted low-poly props, LOD chains, rigged characters with locomotion clips, wiring into Unity/Unreal/Godot/Three.js | | MCP server `tripo` | China site: remote Streamable HTTP server `https://developers.tripo3d.com/mcp` (OAuth 2.1), including `tripo_plan`, generation, rigging, conversion and `tripo_smart_uv`; available tool schemas are authoritative | -| MCP server `tripo-global` | International site: the same tools on `https://openapi-mcp.tripo3d.ai/mcp` (OAuth 2.1) | -| Hook `SessionStart` | Injects eight rules covering async waiting, short-lived links, credit confirmation, browser authorization, honest failures, PBR, model selection and concept-image confirmation, plus a region hint from the system time zone | +| Hook `SessionStart` | Injects eight rules covering async waiting, short-lived links, credit confirmation, browser authorization, honest failures, PBR, model selection and concept-image confirmation | ## Usage @@ -70,34 +66,24 @@ be used directly for 3D generation. ### First-time authorization -Authorize the Tripo MCP server for your account's region once: - -1. Open **Settings → MCP Servers**. Under "Plugin MCP servers" there are two Tripo - rows, both showing "Authorization required": `tripo` for a China-mainland - account and `tripo-global` for an international account. Click - **Open authorization** on the row for your account; the other row can stay - as it is. -2. The system browser opens that site's authorization page: `tripo` uses the - **China site** (developers.tripo3d.com — +86 SMS sign-in, Alipay top-up), - `tripo-global` the **international site** (developers.tripo3d.ai — email - sign-in, Stripe top-up). The page has no region picker. You can sign up on - the spot; new accounts get free credits. -3. The page shows a one-time verification code and opens the Tripo console: - sign in, type the code into **Verification code**, click **Authorize**. +Authorize the Tripo China MCP server once: + +1. Open **Settings → MCP Servers**. Under "Plugin MCP servers", find the + `tripo` row and click **Open authorization**. +2. The browser opens the **China site** authorization page + (developers.tripo3d.com, +86 SMS sign-in, Alipay top-up). The page has no + region picker. You can sign up on the spot. +3. The page shows a one-time verification code and opens the Tripo console. + Sign in, type the code into **Verification code**, and click **Authorize**. 4. ZCode reconnects and loads the tools automatically. To revoke access, delete the API key you picked during authorization on the console's API Keys page. -If you connect accounts in both regions, choose the account for the task before -planning or uploading. Task IDs, file tokens and balances stay with that server. - ## Dependencies, network access and side effects -- **Network**: ZCode connects to both MCP endpoints, - `https://developers.tripo3d.com/mcp` (China site) and - `https://openapi-mcp.tripo3d.ai/mcp` (international site); tool calls go - only to the one you authorized, and authorization redirects to that site's - Tripo console. Results are available through short-lived Tripo CDN links. +- **Network**: MCP tool calls go to `https://developers.tripo3d.com/mcp`; + authorization redirects to the Tripo China console (developers.tripo3d.com). + Results are available through short-lived Tripo CDN links. `tripo_task_status` refreshes them when needed. - **Account and billing**: every generation spends credits from your own Tripo account; use task status and the usage ledger for actual charges. Failed @@ -105,7 +91,7 @@ planning or uploading. Task IDs, file tokens and balances stay with that server. `tripo_plan` and asks for explicit confirmation before they run. For a batch, it checks the balance and confirms the cost of each phase before that phase runs. - **File writes**: when you ask to save or integrate a model, the agent - downloads it into your project with `curl`. The hook and the MCP servers + downloads it into your project with `curl`. The hook and the MCP server write nothing. - **Command execution**: shell commands run only to upload a local image/model (using the command returned by `tripo_upload_ticket` or, for larger files when @@ -113,12 +99,10 @@ planning or uploading. Task IDs, file tokens and balances stay with that server. plugin never installs or runs a command-line client, including after an MCP failure, missing authorization, batch work or a request to save files locally. - **Hook**: `hooks/session-start.mjs` needs `node` on PATH. It reads the - event from stdin and prints the rules plus a region hint derived from the - system time zone to stdout; no network, no file access. + event from stdin and prints the rules to stdout; no network, no file access. - **Telemetry**: the plugin has no independent analytics SDK. When enabled on - the Tripo MCP server you authorized (China or international site; both - record the same fields), analytics can record tool results, task - metadata and the Tripo account ID when resolved. Both MCP servers declare the + the deployed Tripo China MCP server, analytics can record tool results, task + metadata and the Tripo account ID when resolved. The plugin declares the non-credential `X-Tripo-Distribution: zcode_plugin` header; if the host forwards it, the server records the distribution channel separately from the detected client (such as ZCode, Claude, or unknown). Analytics excludes @@ -131,6 +115,6 @@ planning or uploading. Task IDs, file tokens and balances stay with that server. - Plugin: MIT, by [VAST](https://www.tripo3d.ai). - Both skills are ported from Tripo's official Kimi / Codex plugins (also maintained by VAST, MIT). -- Both MCP servers run the official Tripo implementation; +- The MCP server runs the official Tripo implementation; generated content is subject to the [Tripo API content policy](https://platform.tripo3d.ai/docs). diff --git a/plugins/tripo-3d/README_CN.md b/plugins/tripo-3d/README_CN.md index beb45395..cb233e99 100644 --- a/plugins/tripo-3d/README_CN.md +++ b/plugins/tripo-3d/README_CN.md @@ -4,8 +4,7 @@ ## 0.1.5 -插件支持 Tripo 国内站和海外站账号,分别通过国内 MCP 服务器 `tripo` 和海外 MCP -服务器 `tripo-global` 连接。授权与自己账号所属站点对应的服务器即可。 +插件通过 MCP 服务器 `tripo` 连接 Tripo 国内站,使用时需要 Tripo 国内站账号。 用户明确指定的兼容模型优先于按用途选择的默认值。先按必需功能筛选兼容模型,再按 场景选择。若用户指定的模型与必需功能冲突,变更模型或放弃要求前先询问。游戏和 @@ -24,9 +23,8 @@ v3.1。绑骨时显式指定模型,双足使用 v3.0,动物使用 v2.5。API 动画、重拓扑和格式转换(GLB/FBX/OBJ/STL/USDZ/3MF)。你可以要求将文件保存到项目中, 用于游戏、影视、AR 和 3D 打印。 -在浏览器中授权一次 Tripo 账号即可使用,无需粘贴 API Key。插件分别支持**国内站** -(developers.tripo3d.com)和**海外站**(developers.tripo3d.ai)账号,授权所属站点 -对应的 MCP 服务器即可。 +在浏览器中授权一次 Tripo 国内站账号(developers.tripo3d.com)即可使用,无需在 +对话中粘贴 API Key。 ## 包含的组件 @@ -35,8 +33,7 @@ v3.1。绑骨时显式指定模型,双足使用 v3.0,动物使用 v2.5。API | Skill `tripo-3d` | 主流程,包括工具检查、授权引导、MCP 工作流、场景到工具链的映射、输入处理和积分规则 | | Skill `tripo-game-asset` | 游戏资产配方,包括面数预算道具、LOD 链、绑骨角色与动作,以及接入 Unity/Unreal/Godot/Three.js | | MCP 服务器 `tripo` | 国内站远程 Streamable HTTP 服务器 `https://developers.tripo3d.com/mcp`(OAuth 2.1),提供 `tripo_plan`、生成、绑骨、转换和 `tripo_smart_uv` 等工具,以实际可见的工具 schema 为准 | -| MCP 服务器 `tripo-global` | 海外站远程服务器 `https://openapi-mcp.tripo3d.ai/mcp`(OAuth 2.1),提供相同工具 | -| Hook `SessionStart` | 注入 8 条规则,覆盖异步等待、短期链接、计费确认、浏览器授权、如实报错、PBR、模型选择和概念图确认,并根据系统时区提供区域提示 | +| Hook `SessionStart` | 注入 8 条规则,覆盖异步等待、短期链接、计费确认、浏览器授权、如实报错、PBR、模型选择和概念图确认 | ## 使用方法 @@ -56,28 +53,22 @@ v3.1。绑骨时显式指定模型,双足使用 v3.0,动物使用 v2.5。API ### 首次授权 -为账号所属站点的 Tripo MCP 服务器完成一次授权: +为 Tripo 国内站 MCP 服务器完成一次授权: -1. 打开 **设置 → MCP 服务器**。在「Plugin MCP 服务器」分组中有两个 Tripo 条目, - 初次使用时会显示「需要授权」。`tripo` 对应国内站账号,`tripo-global` 对应海外 - 站账号。在账号所属站点的条目上点击 **打开授权**,另一个条目可以保持原样。 -2. 系统浏览器会打开对应站点的授权页。`tripo` 使用**国内站**(developers.tripo3d.com, - +86 短信登录、支付宝充值),`tripo-global` 使用**海外站**(developers.tripo3d.ai, - 邮箱登录、Stripe 充值)。授权页没有选区步骤。没有账号时可以注册,新账号有免费额度。 +1. 打开 **设置 → MCP 服务器**。在「Plugin MCP 服务器」分组中找到 `tripo`, + 点击 **打开授权**。 +2. 系统浏览器打开**国内站**授权页(developers.tripo3d.com,+86 短信登录、支付宝 + 充值)。授权页没有选区步骤,没有账号时可以注册。 3. 页面显示一次性验证码并打开 Tripo 控制台。登录后把验证码填入 **Verification code**, 点击 **Authorize**。 4. ZCode 自动重连并加载工具。需要撤销授权时,在 Tripo 控制台的 API Keys 页面删除 授权时选定的 Key。 -如果已连接两个区域的账号,请在规划或上传前选择此次任务使用的账号。任务 ID、 -文件令牌和余额均归属所选服务器。 - ## 依赖、网络访问与副作用 -- **网络**:ZCode 连接国内站 `https://developers.tripo3d.com/mcp` 和海外站 - `https://openapi-mcp.tripo3d.ai/mcp`,工具调用发往已授权的服务器,授权页跳转到 - 对应站点的 Tripo 控制台。生成结果通过 Tripo CDN 的短期链接获取,需要时用 - `tripo_task_status` 刷新。 +- **网络**:MCP 工具调用走 `https://developers.tripo3d.com/mcp`,授权页跳转到 + Tripo 国内站控制台(developers.tripo3d.com)。生成结果通过 Tripo CDN 的短期链接 + 获取,需要时用 `tripo_task_status` 刷新。 - **账号与计费**:生成任务消耗你自己 Tripo 账号的积分,通过任务状态与用量账单核对 实际消耗,失败任务自动退款。Skill 用 `tripo_plan` 规划计费步骤并在执行前取得明确 确认。批量生成时会查余额,并在各阶段执行前分别确认该阶段的费用。 @@ -88,10 +79,10 @@ v3.1。绑骨时显式指定模型,双足使用 v3.0,动物使用 v2.5。API `tripo_upload_presign` 返回的命令。插件不会安装或调用命令行客户端,MCP 失败、 未授权、批量或本地落盘需求也不例外。 - **Hook**:`hooks/session-start.mjs` 依赖 PATH 中的 `node`,从 stdin 读取事件,向 - stdout 输出规则和基于系统时区的区域提示,不访问网络、不读写文件。 -- **遥测**:插件本体没有独立的分析 SDK。已授权的 Tripo MCP 服务(国内或海外,记录 - 相同字段)启用分析时,可以记录工具调用结果、任务元数据及能够解析出的 Tripo 账号 - ID。两个 MCP 服务器均声明非凭据请求头 `X-Tripo-Distribution: zcode_plugin`。宿主 + stdout 输出规则,不访问网络、不读写文件。 +- **遥测**:插件本体没有独立的分析 SDK。已部署的 Tripo 国内站 MCP 服务启用分析时, + 可以记录工具调用结果、任务元数据及能够解析出的 Tripo 账号 ID。插件声明非凭据请求头 + `X-Tripo-Distribution: zcode_plugin`。宿主 透传时,服务端会分别记录分发渠道和识别出的客户端(如 ZCode、Claude 或 unknown)。 埋点不包含提示词、API Key、OAuth token、文件路径或签名下载链接。账号凭据由 ZCode 的凭据存储管理,不经过对话。 @@ -100,4 +91,4 @@ v3.1。绑骨时显式指定模型,双足使用 v3.0,动物使用 v2.5。API - 插件本体采用 MIT 许可,作者为 [VAST](https://www.tripo3d.ai)。 - 两个 Skill 由 Tripo 官方的 Kimi / Codex 插件移植而来,同由 VAST 维护并采用 MIT 许可。 -- 两个 MCP 服务器均运行 Tripo 官方实现,生成内容遵循 [Tripo API 内容策略](https://platform.tripo3d.ai/docs)。 +- MCP 服务器运行 Tripo 官方实现,生成内容遵循 [Tripo API 内容策略](https://platform.tripo3d.ai/docs)。 diff --git a/plugins/tripo-3d/hooks/session-start.mjs b/plugins/tripo-3d/hooks/session-start.mjs index e3249dcd..bd73fecc 100644 --- a/plugins/tripo-3d/hooks/session-start.mjs +++ b/plugins/tripo-3d/hooks/session-start.mjs @@ -1,5 +1,5 @@ #!/usr/bin/env node -// SessionStart hook: inject the Tripo hard rules and a time-zone region hint as additionalContext. +// SessionStart hook: inject the Tripo hard rules as additionalContext. // Reads one JSON event from stdin, writes one JSON object to stdout. // Keep this text in sync with skills/tripo-3d/SKILL.md. @@ -7,19 +7,13 @@ const RULES = `Tripo 3D — rules that apply whenever Tripo tools (tripo_*) are 1. Generation is asynchronous. Every tripo_* generation or processing tool returns a task_id immediately. Call tripo_task_wait with it and keep calling while status is queued/running — each call returns within about 55 seconds, a generation usually takes 1–4 minutes. Never present a result before status is success, and never treat a task_id as a finished model. 2. Result links are short-lived. Refresh with tripo_task_status and offer one labeled download link. Save a local file only when the user requests a file on disk or project integration and a shell is available. Report the path in backticks. Do not paste raw URLs or the full output_urls list. For concept images, follow rule 8. 3. Credits belong to the user. Call tripo_plan and get confirmation before any billed generation or chain; supply structured generation only for tripo_text_to_3d, tripo_image_to_3d and tripo_multiview_to_3d, including the exact text prompt for text-to-3D; never add generation to other steps such as tripo_image_to_splat. For those three use dry_run only when the connected schema exposes it; validate other steps against their schemas and current pricing. Resolve user-requested parameter conflicts before billing. Plan estimates are advisory, not a budget lock; label unknown costs not_estimated, and cite source, region and date for any static list estimate. Use tripo_usage for all task_ids to report actual total and per-task charges; if unavailable say the amount is pending. Check tripo_balance and confirm the costs for each phase before generating a batch; on insufficient balance give the returned plans_url instead of retrying. Never silently re-roll a disappointing result — say what is off and ask first. -4. Authorization is a browser flow, never a pasted key. The plugin has one MCP server per Tripo region, and an account exists in only one region: tripo is the China site (developers.tripo3d.com, +86 SMS sign-in), tripo-global is the international site (developers.tripo3d.ai, email sign-in); neither auth page has a region picker. If Tripo tools are missing or a call reports an authorization error, ask which site the user's Tripo account is on unless they already said, then tell them to open ZCode Settings → MCP Servers, find that server under "Plugin MCP servers" and click "Open authorization" (ZCode shows these labels in its UI language), then sign in on that site's console and Authorize. The other server keeps showing "Authorization required", which is expected. If tools from both servers are available and the user has not chosen an account, ask before planning or uploading. Keep each task chain on the chosen server: task IDs, file tokens and balances do not carry across regions. Never switch servers silently. Do not ask for an API key in the chat. MCP is the only execution path: never install or run a command-line client instead, even when a local login or API key exists. +4. Authorization is a browser flow, never a pasted key. This plugin uses the China-mainland tripo MCP server at https://developers.tripo3d.com/mcp and requires a Tripo China-site account. If tools are missing or authorization fails, tell the user to open ZCode Settings → MCP Servers, find tripo under "Plugin MCP servers" and click "Open authorization", then sign in and authorize on developers.tripo3d.com. Keep each workflow on the authorized account; do not silently switch accounts or servers after authorization or balance errors. Do not ask for an API key or verification code in the chat. MCP is the only execution path: never install or run a command-line client instead, even when a local login or API key exists. 5. Failures are reported, not hidden. On failed/banned, relay failure_reason (and error_code) honestly; failed-task credits are refunded automatically. Never invent parameters — the tool schemas are authoritative. If a creation call times out without a task_id, do not automatically retry: check the original account's balance and task history when available and ask before another submission. Stylize has been retired: there is no tripo_stylize tool. tripo_mesh_edit is experimental; use it only if the connected server lists it. 6. PBR is opt-in. Send pbr: false on every tripo_text_to_3d, tripo_image_to_3d, tripo_multiview_to_3d and tripo_texture call unless the user explicitly asks for PBR (e.g. "with PBR" or "PBR materials", in any language); only then send pbr: true, which also forces texture: true. The API turns PBR on when pbr is omitted, so never leave it out. Detailed or high-quality textures do not mean PBR. 7. Choose models explicitly: the user's explicit compatible model wins over usage-based defaults; if an explicit model conflicts with requirements, explain and ask before changing it or dropping a requirement. Without an explicit model, filter by required capabilities before applying scenario preferences (use v3.1 for generate_parts, smart_low_poly or detailed geometry). P2 is preferred for game/realtime topology and costs more credits than H/P1; within the P series the default is P2, and P1 is used only when the user names it or picks it for lower cost and speed; v3.1 for film/render/print. Do not infer the model from face_limit. Cost is not estimated by this text or guaranteed by tripo_plan: disclose uncertainty and obtain consent before billing. Pass the rig model explicitly: v3.0 for biped and others, v2.5 for animal body types, and use spec only for biped; use preset:walk, reserving preset:biped:* for explicit v1.0 rigs. Retopology v3.0 with smart_uv and standalone tripo_smart_uv are separate workflows, not interchangeable free export switches. Load the capability reference before running either. chat_image_1 is retired; never fall back to it. chat_image_1.5 remains usable where supported before 2026-12-01; never silently replace a user-selected paid image model. fast textures require texture model v3.5: pass the short name v3.5, or omit the version and the tool picks it. 8. Start a new 3D asset described only in words with a concept image unless the user explicitly asks to skip it. Plan and confirm only tripo_generate_image first. On success show the generated image from output_urls as a Markdown image, or provide one labeled link if inline display is unavailable. End the turn and wait for the user to accept that image. Only then plan tripo_image_to_3d using the accepted image task ID and ask separately for confirmation of the 3D costs. For a supplied image or multiview set, plan the corresponding 3D workflow directly. `; -const CHINA_TIME_ZONES = new Set(["Asia/Shanghai", "Asia/Urumqi", "Asia/Chongqing", "Asia/Chungking", "Asia/Harbin", "Asia/Kashgar", "PRC"]); -const timeZone = Intl.DateTimeFormat().resolvedOptions().timeZone; -const regionHint = timeZone - ? `Region hint: the system time zone is ${timeZone}, which suggests ${CHINA_TIME_ZONES.has(timeZone) ? "the China site (tripo)" : "the international site (tripo-global)"}. Use it only to phrase the question in rule 4; never choose a server for the user on this guess.\n` - : ""; - let raw = ""; process.stdin.setEncoding("utf8"); for await (const chunk of process.stdin) raw += chunk; @@ -35,6 +29,6 @@ try { process.stdout.write( JSON.stringify({ - hookSpecificOutput: { hookEventName: eventName, additionalContext: RULES + regionHint }, + hookSpecificOutput: { hookEventName: eventName, additionalContext: RULES }, }), ); diff --git a/plugins/tripo-3d/skills/tripo-3d/SKILL.md b/plugins/tripo-3d/skills/tripo-3d/SKILL.md index 800cd50f..4e946b7a 100644 --- a/plugins/tripo-3d/skills/tripo-3d/SKILL.md +++ b/plugins/tripo-3d/skills/tripo-3d/SKILL.md @@ -1,6 +1,6 @@ --- name: tripo-3d -description: Generate a 3D model from a text prompt, a reference image, or an existing mesh, and deliver it as GLB, FBX, OBJ, STL, USDZ or 3MF. Use when the user asks for a 3D asset, model, mesh, prop, character or texture for a game, renderer, viewer, AR scene or 3D print — including requests like "make me a low-poly X", "turn this image into 3D", "rig this character", "convert this model to FBX", or "generate placeholder assets", and the same requests in any language (text-to-3D, image-to-3D, rigging, character animation, texturing, low-poly or face reduction, 3D-printed figurines, format conversion). Also use to re-run, convert or inspect a previous Tripo generation, or to answer questions about Tripo model selection, supported parameters, and credits. +description: Generate a 3D model from a text prompt, a reference image, or an existing mesh, and deliver it as GLB, FBX, OBJ, STL, USDZ or 3MF. Use when the user asks for a 3D asset, model, mesh, prop, character or texture for a game, renderer, viewer, AR scene or 3D print — including requests like "make me a low-poly X", "turn this image into 3D", "rig this character", "convert this model to FBX", or "generate placeholder assets", and the same requests in any language (text-to-3D, image-to-3D, rigging, character animation, texturing, low-poly or face reduction, 3D-printed figurines, format conversion). Also use to re-run, convert or inspect a previous Tripo generation, or to answer questions about Tripo model selection, supported parameters, and credits. 中文触发词:生成3D模型、建模、3D素材、把图片变成3D、图生3D、文生3D、骨骼绑定、绑骨、角色动画、贴图、纹理、低模、低多边形、减面、3D打印、手办、格式转换(FBX/GLB/OBJ/STL/USDZ/3MF)。 --- # Tripo 3D @@ -15,17 +15,15 @@ not a budget limit or an authorization ticket. The tool list must contain the Tripo tools (`tripo_text_to_3d`, `tripo_task_wait`, ...; ZCode prefixes them with the MCP server id, e.g. -`mcp__…__tripo_text_to_3d` — the rest of this skill uses the bare names). The -server id in the prefix tells the region: `tripo` is the China site, -`tripo-global` is the international site. - -If they are missing, the plugin's MCP servers are almost always waiting for -authorization or switched off, not absent. Stop, ask which site the user's -Tripo account is on, and tell them: open **Settings → MCP Servers**, find that -region's server under "Plugin MCP servers", click **Open authorization** if the -row says "Authorization required" (if it says "Plugin disabled", enable the -Tripo 3D plugin first), then start a new session. See Authorization below. -Do not describe generations as if they had run. +`mcp__…__tripo_text_to_3d` — the rest of this skill uses the bare names). +Use the plugin's `tripo` server for the China-mainland site. + +If those tools are missing, the plugin's MCP server may need authorization or +may be switched off. Tell the user to open **Settings → MCP Servers**, find +`tripo` under "Plugin MCP servers", and click **Open authorization** if the +row says "Authorization required". If it says "Plugin disabled", enable the +Tripo 3D plugin first. Start a new session if tools still do not appear. See +Authorization below. Do not describe generations as if they had run. MCP is the only execution path. Never install or run a command-line client instead — not for a balance check, not because a local login or @@ -42,33 +40,20 @@ account. ZCode runs the OAuth flow but never opens a browser on its own — the user has to click once. Your job is to guide them through the pages; never ask for an API key in the chat. -**The plugin ships one MCP server per Tripo region.** An account lives in -exactly one region, and neither authorization page offers a region picker: - -| MCP server | Region | Console | -| --- | --- | --- | -| `tripo` (`https://developers.tripo3d.com/mcp`) | China site — mainland China | developers.tripo3d.com, +86 SMS sign-in, Alipay top-up | -| `tripo-global` (`https://openapi-mcp.tripo3d.ai/mcp`) | International site | developers.tripo3d.ai, email sign-in, Stripe top-up | - -Ask once whether the user's account is on the China site or the international -site, unless they already said. The session context may carry a time-zone region -hint; use it only to phrase the question, never to choose for the user. No -account yet? Users in mainland China pick the China site, everyone else the -international site; they can sign up during authorization and new accounts get -free credits. Only the chosen server needs authorizing; the other row keeps -showing "Authorization required", which is expected. ZCode shows these labels -in its UI language. - -1. **Settings → MCP Servers** → group "Plugin MCP servers" → the chosen - server's row (`tripo` or `tripo-global`) shows "Authorization required" → - click **Open authorization**. The system browser opens that region's - authorization page. -2. The page shows a one-time verification code and opens the Tripo console: - sign in (or sign up — new accounts get free credits), type the code into - the **"Verification code"** field, click **Authorize**. Nothing is ever - copied or pasted into the chat. -3. ZCode reconnects and loads the tools automatically. If the tools still do - not show up, start a new session. +**This plugin uses the China-mainland MCP server** +`tripo` at `https://developers.tripo3d.com/mcp`. Authorize it with a Tripo +China-site account (`developers.tripo3d.com`). Keep uploads, tasks, balances, +and downloads associated with the authorized account. Do not silently switch +accounts when authorization or balance checks fail. + +1. Open **Settings → MCP Servers**, find `tripo` under "Plugin MCP servers", + and click **Open authorization** when its row says "Authorization required". + The system browser opens the China-site authorization page. +2. The page shows a one-time verification code and opens the Tripo console. + Sign in or sign up, enter the code in **Verification code**, and click + **Authorize**. Do not copy the code or credentials into the chat. +3. ZCode reconnects and loads the tools. If they still do not appear, start a + new session. Generations spend credits from the account the user connected. The connection is bound to the API key the user picked on the Tripo console during @@ -77,11 +62,6 @@ with exactly one key it is used as is). To revoke access, delete that key on the console's API Keys page — any other client sharing that key loses access too. -If tools from both servers are available and the user has not chosen an -account, ask before planning or uploading. Keep the whole task chain on the -chosen server. Task IDs, file tokens and balances belong to that region. -Never switch servers silently. - ## Text prompts for new 3D assets When the user describes a new asset in words and has not supplied reference diff --git a/plugins/tripo-3d/skills/tripo-3d/references/capability.md b/plugins/tripo-3d/skills/tripo-3d/references/capability.md index 6f66cb07..aa61fb34 100644 --- a/plugins/tripo-3d/skills/tripo-3d/references/capability.md +++ b/plugins/tripo-3d/skills/tripo-3d/references/capability.md @@ -196,10 +196,10 @@ by 16; use 1088x1920 instead. No 1K/2K/4K tiers for chat_image models. ## Prices -Official list prices from the Tripo pricing pages (developers.tripo3d.com/zh/pricing -and developers.tripo3d.ai/pricing; the same numbers in both regions), checked on -2026-10-30. Numeric prices and add-ons anywhere in this file (including processing -tables) come from those pages. An estimate must name its source, region and date and +Official list prices from the Tripo China-site pricing page +(developers.tripo3d.com/zh/pricing), checked on 2026-10-30. Numeric prices +and add-ons anywhere in this file (including processing tables) come from that +page. An estimate must name its source, region and date and match the exact model/options. If this table cannot price the request (a legacy model or anything not listed), report **not_estimated** (unestimated), not zero; disclose that uncertainty and obtain consent before billing. Never infer a fixed P2/P1 ratio. diff --git a/plugins/tripo-3d/skills/tripo-game-asset/SKILL.md b/plugins/tripo-3d/skills/tripo-game-asset/SKILL.md index 610c5d56..d0d960e2 100644 --- a/plugins/tripo-3d/skills/tripo-game-asset/SKILL.md +++ b/plugins/tripo-3d/skills/tripo-game-asset/SKILL.md @@ -1,6 +1,6 @@ --- name: tripo-game-asset -description: Recipes for producing game-ready 3D assets with Tripo and wiring them into a game project - low-poly props on a face budget, detailed hero assets, LOD chains, and rigged characters with locomotion clips for Unity, Unreal, Godot or Three.js. Use when the user is building a game or real-time 3D scene and needs props, characters, placeholder art, LODs, or an animated rig, rather than a single one-off model. Also covers walk/run/jump clips and importing models into Unity, Unreal or Godot, whatever language the request is in. +description: Recipes for producing game-ready 3D assets with Tripo and wiring them into a game project - low-poly props on a face budget, detailed hero assets, LOD chains, and rigged characters with locomotion clips for Unity, Unreal, Godot or Three.js. Use when the user is building a game or real-time 3D scene and needs props, characters, placeholder art, LODs, or an animated rig, rather than a single one-off model. Also covers walk/run/jump clips and importing models into Unity, Unreal or Godot, whatever language the request is in. 中文触发词:游戏资产、游戏素材、游戏模型、低模道具、面数预算、LOD、角色绑骨、走跑跳动画、Unity/Unreal/Godot 模型导入。 --- # Game asset pipeline