@forgeax-extension/character-3d 0.1.2

package/schemas/list-assets.returns.json

@@ -0,0 +1,296 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "gen3d:list-assets returns",
+  "type": "object",
+  "properties": {
+    "ok": {
+      "const": true
+    },
+    "assets": {
+      "type": "array",
+      "items": {
+        "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",
+    "assets"
+  ],
+  "additionalProperties": false
+}

package/schemas/list-motions.args.json

@@ -0,0 +1,29 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "gen3d:list-motions args",
+  "type": "object",
+  "description": "Discover selectable motions for the apply-motion step. Zero credits (a GET); quota-safe offline sample when Meshy is not configured. Callers narrow the ~680-entry catalog via query/category/rigType rather than enumerating it.",
+  "properties": {
+    "slug": {
+      "type": "string",
+      "description": "Active game slug. Injected by the workbench host; required."
+    },
+    "assetPath": {
+      "type": "string",
+      "description": "Optional. When given, the catalog matches that asset's rig system: a Hunyuan-rigged asset returns the v1 fixed 8; a Meshy-rigged asset returns its rig-compatible actions. Omit to browse the public Meshy catalog."
+    },
+    "query": {
+      "type": "string",
+      "description": "Case-insensitive substring match on the motion label or id."
+    },
+    "category": {
+      "type": "string",
+      "description": "Exact category filter (e.g. locomotion, gesture, expression)."
+    },
+    "rigType": {
+      "type": "string",
+      "description": "Exact rig/skeleton type filter (e.g. style_02)."
+    }
+  },
+  "additionalProperties": false
+}

package/schemas/list-motions.returns.json

@@ -0,0 +1,41 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "gen3d:list-motions returns",
+  "type": "object",
+  "properties": {
+    "ok": { "const": true },
+    "usedMock": {
+      "type": "boolean",
+      "description": "True when Meshy was not configured and a deterministic offline sample was returned (zero credits). Always false for the Hunyuan v1 fixed set."
+    },
+    "system": {
+      "type": "string",
+      "enum": ["hunyuan_v1", "hunyuan_v2", "meshy", "visvise"],
+      "description": "Which motion system the catalog belongs to (resolved from the asset's rig provider, default meshy)."
+    },
+    "total": {
+      "type": "integer",
+      "description": "Number of motions after filtering."
+    },
+    "motions": {
+      "type": "array",
+      "description": "Filtered motion options. Pass a chosen entry's id to gen3d:apply-motion (actionId for Meshy, motionType for Hunyuan v1).",
+      "items": {
+        "type": "object",
+        "properties": {
+          "system": { "type": "string", "enum": ["hunyuan_v1", "hunyuan_v2", "meshy", "visvise"] },
+          "id": { "type": ["integer", "string"] },
+          "label": { "type": "string" },
+          "category": { "type": ["string", "null"] },
+          "rigType": { "type": ["string", "null"] },
+          "isFree": { "type": "boolean" },
+          "previewGifUrl": { "type": ["string", "null"] }
+        },
+        "required": ["system", "id", "label", "isFree"],
+        "additionalProperties": true
+      }
+    }
+  },
+  "required": ["ok", "usedMock", "system", "total", "motions"],
+  "additionalProperties": false
+}

package/schemas/pose-standardization.args.json

@@ -0,0 +1,28 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "gen3d:pose-standardization args",
+  "type": "object",
+  "properties": {
+    "slug": {
+      "type": "string",
+      "description": "Active game slug. The standardized image is written to scratch under .forgeax/games/<slug>/.gen3d/tmp/ (a transfer artifact, not an asset). 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."
+    },
+    "imageUrl": {
+      "type": "string",
+      "minLength": 1,
+      "description": "URL of a full-body simple/cartoon character portrait to standardize to an A/T-pose. Only simple cartoon full-body images are supported by the provider."
+    },
+    "footnote": {
+      "type": "string",
+      "description": "Optional free-text note passed through to the provider request."
+    },
+    "provider": {
+      "type": "string",
+      "enum": ["hunyuan_rest", "visvise"],
+      "default": "hunyuan_rest",
+      "description": "Pose provider. Defaults to hunyuan_rest. Use visvise for VISVISE image-to-3d (visvise-image-pose). Rodin image-to-3d skips this step."
+    }
+  },
+  "required": ["slug", "imageUrl"],
+  "additionalProperties": false
+}

package/schemas/pose-standardization.returns.json

@@ -0,0 +1,29 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "gen3d:pose-standardization returns",
+  "type": "object",
+  "properties": {
+    "ok": { "const": true },
+    "usedMock": {
+      "type": "boolean",
+      "description": "True when no real provider was configured and a deterministic mock image was used (quota-safe fallback)."
+    },
+    "sourceJobId": {
+      "type": ["string", "null"],
+      "description": "Remote provider job id, for audit. Null in mock mode. Never a stored-asset reference."
+    },
+    "storageKey": {
+      "type": "string",
+      "description": "Scratch (transfer) key for the standardized image under .forgeax/games/<slug>/.gen3d/tmp/. NOT a 3D asset (no manifest, not in list-assets); use as the upstream input for a later gen3d:image-to-3d call."
+    },
+    "bytes": { "type": "integer", "minimum": 0 },
+    "sha256": { "type": "string" },
+    "localUrl": { "type": ["string", "null"] },
+    "sourceUrl": {
+      "type": ["string", "null"],
+      "description": "The provider's temporary output URL the image was downloaded from. Audit only; never the canonical reference."
+    }
+  },
+  "required": ["ok", "usedMock", "sourceJobId", "storageKey", "bytes", "sha256", "localUrl", "sourceUrl"],
+  "additionalProperties": false
+}

package/schemas/provider-status.args.json

@@ -0,0 +1,7 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "gen3d:provider-status args",
+  "type": "object",
+  "properties": {},
+  "additionalProperties": false
+}

package/schemas/provider-status.returns.json

@@ -0,0 +1,70 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "gen3d:provider-status returns",
+  "type": "object",
+  "properties": {
+    "ok": { "const": true },
+    "quotaSafe": {
+      "type": "boolean",
+      "description": "True when no real provider is configured, so all generation falls back to mock."
+    },
+    "realProvidersEnabled": {
+      "type": "boolean",
+      "description": "True when a real provider (e.g. Hunyuan workflow) is configured and the master switch is on."
+    },
+    "generatedAt": { "type": "string" },
+    "rubric": {
+      "type": "array",
+      "items": {
+        "enum": ["geometry", "topology", "texture", "pbr", "prompt_fidelity"]
+      }
+    },
+    "capabilities": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "providerId": {
+            "enum": ["meshy", "hunyuan_workflow", "hunyuan_rest", "rodin", "visvise"]
+          },
+          "providerName": { "type": "string" },
+          "capability": { "type": "string" },
+          "sourceStatus": { "type": "string" },
+          "exposure": {
+            "enum": ["planned", "mock-first", "experimental", "hidden", "blocked"]
+          },
+          "notes": { "type": "string" }
+        },
+        "required": ["providerId", "providerName", "capability", "sourceStatus", "exposure", "notes"],
+        "additionalProperties": false
+      }
+    },
+    "providers": {
+      "type": "array",
+      "description": "Runtime provider availability for the UI picker. Meshy is listed but selectable=false (UI hidden). Rodin and VISVISE are selectable when the LiteLLM 3D key is present.",
+      "items": {
+        "type": "object",
+        "properties": {
+          "providerId": {
+            "enum": ["meshy", "hunyuan_workflow", "rodin", "visvise"]
+          },
+          "providerName": { "type": "string" },
+          "configured": { "type": "boolean" },
+          "availability": {
+            "enum": ["configured", "available", "unavailable", "unknown"]
+          },
+          "selectable": { "type": "boolean" },
+          "reason": { "type": "string" },
+          "models": {
+            "type": "object",
+            "additionalProperties": { "type": "string" }
+          }
+        },
+        "required": ["providerId", "providerName", "configured", "availability", "selectable", "reason", "models"],
+        "additionalProperties": false
+      }
+    }
+  },
+  "required": ["ok", "quotaSafe", "realProvidersEnabled", "generatedAt", "rubric", "capabilities", "providers"],
+  "additionalProperties": false
+}

package/schemas/refine-mesh.args.json

@@ -0,0 +1,33 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "gen3d:refine-mesh 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."
+    },
+    "assetSlot": {
+      "type": "string",
+      "enum": ["characters", "meshes"],
+      "default": "meshes",
+      "description": "3D asset slot (subdir under assets/3d/)."
+    },
+    "assetName": {
+      "type": "string",
+      "description": "Desired base file name (without extension). Sanitized + de-duplicated by the store."
+    },
+    "previewTaskId": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Meshy preview (white-mesh) task id from manifest.meshyTaskRefs.previewTaskId — NOT the auto-refine resultTaskId / sourceJobId. Meshy-only second stage that adds or restyles texture."
+    },
+    "texturePrompt": {
+      "type": "string",
+      "description": "Optional text guidance for texture generation (<=600 chars)."
+    },
+    "enablePbr": { "type": "boolean", "default": true }
+  },
+  "required": ["slug", "previewTaskId"],
+  "additionalProperties": false
+}