@forgeax-extension/character-3d 0.1.2

package/schemas/refine-mesh.returns.json

@@ -0,0 +1,306 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "gen3d:refine-mesh returns",
+  "type": "object",
+  "properties": {
+    "ok": {
+      "const": true
+    },
+    "cacheKey": {
+      "type": "string"
+    },
+    "cacheHit": {
+      "type": "boolean"
+    },
+    "usedMock": {
+      "type": "boolean",
+      "description": "True when Meshy was not configured and a deterministic mock was used (quota-safe fallback)."
+    },
+    "manifest": {
+      "type": "object",
+      "properties": {
+        "manifestVersion": {
+          "const": 1
+        },
+        "assetId": {
+          "type": "string"
+        },
+        "kind": {
+          "enum": [
+            "mesh",
+            "animation"
+          ]
+        },
+        "provider": {
+          "enum": [
+            "meshy",
+            "hunyuan_workflow",
+            "hunyuan_rest",
+            "rodin",
+            "visvise"
+          ]
+        },
+        "providerMode": {
+          "enum": [
+            "mock",
+            "real"
+          ]
+        },
+        "mode": {
+          "enum": [
+            "text",
+            "image",
+            "views",
+            "refine"
+          ]
+        },
+        "sourceJobId": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "sourceInputAssetIds": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "prompt": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "files": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "fileId": {
+                "type": "string"
+              },
+              "role": {
+                "enum": [
+                  "source_mesh",
+                  "rigged_model",
+                  "preview_image",
+                  "texture",
+                  "animation_clip",
+                  "animated_model"
+                ]
+              },
+              "format": {
+                "enum": [
+                  "glb",
+                  "fbx",
+                  "obj",
+                  "mtl",
+                  "usdz",
+                  "stl",
+                  "png",
+                  "jpg",
+                  "mp4"
+                ]
+              },
+              "storageKey": {
+                "type": "string"
+              },
+              "bytes": {
+                "type": "integer",
+                "minimum": 0
+              },
+              "sha256": {
+                "type": "string"
+              },
+              "localUrl": {
+                "type": [
+                  "string",
+                  "null"
+                ]
+              },
+              "hasSkeleton": {
+                "type": "boolean"
+              },
+              "skeletonProfile": {
+                "enum": [
+                  "humanoid",
+                  "unknown"
+                ]
+              },
+              "animationInputReady": {
+                "type": "boolean"
+              },
+              "motionType": {
+                "type": "integer",
+                "minimum": 9,
+                "maximum": 16,
+                "description": "Present only on role=animated_model files: the motion_retarget v1 motion this clip is (9 跨步 / 10 摔倒 / 11 跳跃 / 12 踢腿 / 13 挥击 / 14 步行 / 15 跑步 / 16 跳舞). Structural so multiple motions coexist per asset. Absent for non-animated roles."
+              }
+            },
+            "required": [
+              "fileId",
+              "role",
+              "format",
+              "storageKey",
+              "bytes",
+              "sha256",
+              "localUrl",
+              "hasSkeleton",
+              "skeletonProfile",
+              "animationInputReady"
+            ],
+            "additionalProperties": false
+          }
+        },
+        "readiness": {
+          "type": "object",
+          "properties": {
+            "hasSourceMesh": {
+              "type": "boolean"
+            },
+            "rigged": {
+              "type": "boolean"
+            },
+            "animated": {
+              "type": "boolean"
+            }
+          },
+          "required": [
+            "hasSourceMesh",
+            "rigged",
+            "animated"
+          ],
+          "additionalProperties": false
+        },
+        "quality": {
+          "type": "object",
+          "properties": {
+            "geometry": {
+              "type": [
+                "number",
+                "null"
+              ]
+            },
+            "topology": {
+              "type": [
+                "number",
+                "null"
+              ]
+            },
+            "texture": {
+              "type": [
+                "number",
+                "null"
+              ]
+            },
+            "pbr": {
+              "type": [
+                "number",
+                "null"
+              ]
+            },
+            "prompt_fidelity": {
+              "type": [
+                "number",
+                "null"
+              ]
+            },
+            "total": {
+              "type": [
+                "number",
+                "null"
+              ]
+            }
+          },
+          "required": [
+            "geometry",
+            "topology",
+            "texture",
+            "pbr",
+            "prompt_fidelity",
+            "total"
+          ],
+          "additionalProperties": false
+        },
+        "createdAt": {
+          "type": "string"
+        },
+        "updatedAt": {
+          "type": "string"
+        },
+        "meshyTaskRefs": {
+          "type": "object",
+          "description": "Meshy preview vs result task ids. Manual refine uses previewTaskId; rig uses resultTaskId.",
+          "properties": {
+            "previewTaskId": {
+              "type": [
+                "string",
+                "null"
+              ]
+            },
+            "resultTaskId": {
+              "type": [
+                "string",
+                "null"
+              ]
+            }
+          },
+          "required": [
+            "previewTaskId",
+            "resultTaskId"
+          ],
+          "additionalProperties": false
+        },
+        "visviseRefs": {
+          "type": "object",
+          "description": "VISVISE COS URLs from generate/rig. Downstream rig/motion must reuse these; do not re-host on ForgeaX COS first.",
+          "properties": {
+            "meshUrl": {
+              "type": [
+                "string",
+                "null"
+              ]
+            },
+            "rigUrl": {
+              "type": [
+                "string",
+                "null"
+              ]
+            }
+          },
+          "required": [
+            "meshUrl",
+            "rigUrl"
+          ],
+          "additionalProperties": false
+        }
+      },
+      "required": [
+        "manifestVersion",
+        "assetId",
+        "kind",
+        "provider",
+        "providerMode",
+        "mode",
+        "sourceJobId",
+        "sourceInputAssetIds",
+        "prompt",
+        "files",
+        "readiness",
+        "quality",
+        "createdAt",
+        "updatedAt"
+      ],
+      "additionalProperties": false
+    }
+  },
+  "required": [
+    "ok",
+    "cacheKey",
+    "cacheHit",
+    "usedMock",
+    "manifest"
+  ],
+  "additionalProperties": false
+}

package/schemas/rename-asset.args.json

@@ -0,0 +1,22 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "gen3d:rename-asset args",
+  "type": "object",
+  "properties": {
+    "slug": {
+      "type": "string",
+      "description": "Active game slug. The workbench UI fills this automatically for manual use; an AI/agent caller MUST pass the active game's slug. Required for AI callers."
+    },
+    "assetPath": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Game-relative path of the asset (e.g. assets/3d/characters/hero.glb)."
+    },
+    "label": {
+      "type": ["string", "null"],
+      "description": "User-facing display name stored as sidecar custom.userLabel. Pass null or an empty string to clear and revert to the auto-name (prompt first line or filename stem). Does not rename the GLB file."
+    }
+  },
+  "required": ["assetPath", "label"],
+  "additionalProperties": false
+}

package/schemas/rename-asset.returns.json

@@ -0,0 +1,14 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "gen3d:rename-asset returns",
+  "type": "object",
+  "properties": {
+    "ok": { "const": true },
+    "manifest": {
+      "type": "object",
+      "description": "Updated Gen3DAssetManifest with userLabel applied."
+    }
+  },
+  "required": ["ok", "manifest"],
+  "additionalProperties": false
+}

package/schemas/retopo-lowpoly.args.json

@@ -0,0 +1,34 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "gen3d:retopo-lowpoly args",
+  "type": "object",
+  "properties": {
+    "slug": {
+      "type": "string",
+      "description": "Active game slug. Injected by the workbench host; required."
+    },
+    "assetPath": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Game-relative path of the high-poly source mesh asset (its main GLB) to retopologize. The source is RETAINED; a NEW derived low-poly GLB asset is produced. NOT a pre-rig step — textures are NOT preserved."
+    },
+    "assetName": {
+      "type": "string",
+      "description": "Optional base name for the new low-poly asset. Defaults to <source-name>-lowpoly."
+    },
+    "assetSlot": {
+      "enum": ["characters", "meshes"],
+      "description": "Slot for the new low-poly asset. Defaults to the source asset's slot."
+    },
+    "polygonType": {
+      "enum": ["triangle", "quadrilateral"],
+      "description": "Output topology. Defaults to quadrilateral."
+    },
+    "detailLevel": {
+      "enum": ["high", "medium", "low"],
+      "description": "Decimation target. Defaults to high."
+    }
+  },
+  "required": ["assetPath"],
+  "additionalProperties": false
+}

package/schemas/retopo-lowpoly.returns.json

@@ -0,0 +1,24 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "gen3d:retopo-lowpoly returns",
+  "type": "object",
+  "properties": {
+    "ok": { "const": true },
+    "cacheKey": { "type": "string" },
+    "cacheHit": {
+      "type": "boolean",
+      "description": "True when an identical low-poly result already existed (cache-first; the source's content hash + knobs key the cache)."
+    },
+    "usedMock": {
+      "type": "boolean",
+      "description": "True when no real Hunyuan provider was configured and a deterministic mock low-poly GLB was produced (quota-safe fallback)."
+    },
+    "manifest": {
+      "type": "object",
+      "description": "Manifest of the NEW derived low-poly asset. sourceInputAssetPaths references the high-poly source. Textures are NOT preserved.",
+      "additionalProperties": true
+    }
+  },
+  "required": ["ok", "cacheKey", "cacheHit", "usedMock", "manifest"],
+  "additionalProperties": false
+}

package/schemas/score-quality.args.json

@@ -0,0 +1,36 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "gen3d:score-quality args",
+  "type": "object",
+  "properties": {
+    "slug": { "type": "string", "description": "Active game slug. The workbench UI fills this automatically for manual use; an AI/agent caller MUST pass the active game's slug (e.g. 'mini-gta'). Required." },
+    "assetPath": { "type": "string", "description": "Game-relative asset path (assets/3d/<slot>/<name>.glb)." },
+    "objective": {
+      "type": "object",
+      "description": "Client-computed objective scores (0–100 or null) from the loaded GLB.",
+      "properties": {
+        "geometry": { "type": ["number", "null"] },
+        "topology": { "type": ["number", "null"] },
+        "texture": { "type": ["number", "null"] },
+        "pbr": { "type": ["number", "null"] }
+      },
+      "additionalProperties": false
+    },
+    "aiPass": { "type": "boolean", "default": false, "description": "Trigger AI vision scoring. Mock stub this round (returns usedMock, no values)." },
+    "manual": {
+      "type": "object",
+      "description": "Manual overrides (0–100 or null) + notes. Overridden dims are marked source=manual.",
+      "properties": {
+        "geometry": { "type": ["number", "null"] },
+        "topology": { "type": ["number", "null"] },
+        "texture": { "type": ["number", "null"] },
+        "pbr": { "type": ["number", "null"] },
+        "prompt_fidelity": { "type": ["number", "null"] },
+        "notes": { "type": "string" }
+      },
+      "additionalProperties": false
+    }
+  },
+  "required": ["slug", "assetPath"],
+  "additionalProperties": false
+}

package/schemas/score-quality.returns.json

@@ -0,0 +1,12 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "gen3d:score-quality returns",
+  "type": "object",
+  "properties": {
+    "ok": { "const": true },
+    "usedMock": { "type": "boolean" },
+    "manifest": { "type": "object", "description": "Updated Gen3DAssetManifest (quality numbers surfaced)." }
+  },
+  "required": ["ok", "usedMock", "manifest"],
+  "additionalProperties": false
+}

package/schemas/set-credentials.args.json

@@ -0,0 +1,32 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "gen3d:set-credentials args",
+  "type": "object",
+  "properties": {
+    "GEN3D_ENABLE_REAL_PROVIDERS": {
+      "enum": ["0", "1"],
+      "description": "Master switch. \"1\" enables real provider calls via the 3D gateway; \"0\" forces the quota-safe mock path."
+    },
+    "COS_SECRET_ID": {
+      "type": "string",
+      "description": "Tencent COS SecretId. Empty string clears it."
+    },
+    "COS_SECRET_KEY": {
+      "type": "string",
+      "description": "Tencent COS SecretKey. Empty string clears it."
+    },
+    "COS_BUCKET": {
+      "type": "string",
+      "description": "COS bucket name (address, not a secret). Empty string clears it."
+    },
+    "COS_REGION": {
+      "type": "string",
+      "description": "COS region (address, not a secret). Empty string clears it."
+    },
+    "slug": {
+      "type": "string",
+      "description": "Active game slug auto-injected by the workbench host into every tool call; not a credential and ignored by this tool (dropped by the CRED_KEYS whitelist)."
+    }
+  },
+  "additionalProperties": false
+}

package/schemas/set-credentials.returns.json

@@ -0,0 +1,45 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "gen3d:set-credentials returns",
+  "type": "object",
+  "properties": {
+    "ok": { "const": true },
+    "realProvidersEnabled": {
+      "type": "boolean",
+      "description": "True when GEN3D_ENABLE_REAL_PROVIDERS resolves to \"1\" (process.env wins over the plugin .env)."
+    },
+    "litellmConfigured": {
+      "type": "boolean",
+      "description": "Read-only. True when Studio global .env has a 3D gateway key (priority FORGEAX_3D_GATEWAY_KEY > ANTHROPIC_API_KEY > LITELLM_PROXY_KEY)."
+    },
+    "litellmProxyKey": {
+      "type": ["string", "null"],
+      "description": "Read-only masked 3D gateway key from Studio Settings (first4...last4, or *** when <= 8 chars), or null when unset. Never plaintext. The plugin .env never holds this key."
+    },
+    "credentials": {
+      "type": "object",
+      "properties": {
+        "COS_SECRET_ID": {
+          "type": ["string", "null"],
+          "description": "Masked COS SecretId (first4...last4, or *** when <= 8 chars) or null when unset. Never plaintext."
+        },
+        "COS_SECRET_KEY": {
+          "type": ["string", "null"],
+          "description": "Masked COS SecretKey or null when unset. Never plaintext."
+        },
+        "COS_BUCKET": {
+          "type": ["string", "null"],
+          "description": "Plaintext COS bucket name (an address, not a secret) or null when unset."
+        },
+        "COS_REGION": {
+          "type": ["string", "null"],
+          "description": "Plaintext COS region (an address, not a secret) or null when unset."
+        }
+      },
+      "required": ["COS_SECRET_ID", "COS_SECRET_KEY", "COS_BUCKET", "COS_REGION"],
+      "additionalProperties": false
+    }
+  },
+  "required": ["ok", "realProvidersEnabled", "litellmConfigured", "litellmProxyKey", "credentials"],
+  "additionalProperties": false
+}

package/schemas/set-playable-motion-mapping.args.json

@@ -0,0 +1,25 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "gen3d:set-playable-motion-mapping args",
+  "type": "object",
+  "properties": {
+    "slug": { "type": "string" },
+    "assetPath": { "type": "string" },
+    "mappings": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "slotId": { "type": "string" },
+          "motionRefKey": { "type": ["string", "null"] },
+          "autoMatched": { "type": "boolean" }
+        },
+        "required": ["slotId", "motionRefKey", "autoMatched"],
+        "additionalProperties": false
+      }
+    },
+    "confirmed": { "type": "boolean" }
+  },
+  "required": ["slug", "assetPath", "mappings"],
+  "additionalProperties": false
+}

package/schemas/set-playable-motion-mapping.returns.json

@@ -0,0 +1,33 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "gen3d:set-playable-motion-mapping returns",
+  "type": "object",
+  "properties": {
+    "ok": { "const": true },
+    "mapping": {
+      "type": "object",
+      "properties": {
+        "schemaVersion": { "const": 1 },
+        "mappings": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "slotId": { "type": "string" },
+              "motionRefKey": { "type": ["string", "null"] },
+              "autoMatched": { "type": "boolean" }
+            },
+            "required": ["slotId", "motionRefKey", "autoMatched"],
+            "additionalProperties": false
+          }
+        },
+        "confirmed": { "type": "boolean" },
+        "updatedAt": { "type": "string" }
+      },
+      "required": ["schemaVersion", "mappings", "confirmed", "updatedAt"],
+      "additionalProperties": false
+    }
+  },
+  "required": ["ok", "mapping"],
+  "additionalProperties": false
+}

package/schemas/set-playable-profile.args.json

@@ -0,0 +1,32 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "gen3d:set-playable-profile args",
+  "type": "object",
+  "properties": {
+    "slug": { "type": "string" },
+    "assetPath": { "type": "string" },
+    "slots": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "properties": {
+          "slotId": { "type": "string" },
+          "displayName": { "type": "string" },
+          "required": { "type": "boolean" },
+          "playbackMode": { "enum": ["loop", "once", "freeze_frame"] },
+          "speed": { "type": "number", "exclusiveMinimum": 0 },
+          "matchKeywords": { "type": "array", "items": { "type": "string" } },
+          "rootMotion": { "enum": ["preserve", "remove_xz", "remove_xyz"] }
+        },
+        "required": ["slotId", "displayName", "required", "playbackMode", "speed", "matchKeywords", "rootMotion"],
+        "additionalProperties": false
+      }
+    },
+    "profileId": { "type": "string" },
+    "displayName": { "type": "string" },
+    "saveAsGameDefault": { "type": "boolean" }
+  },
+  "required": ["slug", "assetPath", "slots"],
+  "additionalProperties": false
+}