@forgeax-extension/character-3d 0.1.2

package/schemas/get-playable-profile.returns.json

@@ -0,0 +1,188 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "gen3d:get-playable-profile returns",
+  "type": "object",
+  "properties": {
+    "ok": { "const": true },
+    "presets": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "profileId": { "type": "string" },
+          "displayName": { "type": "string" },
+          "slots": {
+            "type": "array",
+            "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
+            }
+          }
+        },
+        "required": ["profileId", "displayName", "slots"],
+        "additionalProperties": false
+      }
+    },
+    "gameProfile": {
+      "type": ["object", "null"],
+      "properties": {
+        "schemaVersion": { "const": 1 },
+        "profileId": { "type": "string" },
+        "profileVersion": { "type": "integer", "minimum": 1 },
+        "displayName": { "type": "string" },
+        "slots": {
+          "type": "array",
+          "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
+          }
+        },
+        "updatedAt": { "type": "string" }
+      },
+      "required": ["schemaVersion", "profileId", "profileVersion", "displayName", "slots", "updatedAt"],
+      "additionalProperties": false
+    },
+    "effectiveSlots": {
+      "type": "array",
+      "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
+      }
+    },
+    "override": {
+      "type": ["object", "null"],
+      "properties": {
+        "schemaVersion": { "const": 1 },
+        "slots": {
+          "type": "array",
+          "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
+          }
+        },
+        "basedOnProfileId": { "type": "string" },
+        "basedOnProfileVersion": { "type": "integer", "minimum": 1 },
+        "updatedAt": { "type": "string" }
+      },
+      "required": ["schemaVersion", "slots", "basedOnProfileId", "basedOnProfileVersion", "updatedAt"],
+      "additionalProperties": false
+    },
+    "mapping": {
+      "type": ["object", "null"],
+      "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
+    },
+    "delivery": {
+      "type": ["object", "null"],
+      "properties": {
+        "modelPath": { "type": "string" },
+        "playablePath": { "type": "string" },
+        "profileId": { "type": "string" },
+        "profileVersion": { "type": "integer", "minimum": 1 },
+        "clipSlotIds": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "slotGuidRegistry": {
+          "type": "object",
+          "additionalProperties": { "type": "string" }
+        },
+        "mappingFingerprint": { "type": "string" },
+        "exportedAt": { "type": "string" },
+        "localUrl": { "type": "string" }
+      },
+      "required": ["modelPath", "playablePath", "profileId", "profileVersion", "slotGuidRegistry", "mappingFingerprint", "exportedAt", "localUrl"],
+      "additionalProperties": false
+    },
+    "oneClickReady": {
+      "type": "boolean"
+    },
+    "migrationNeeded": {
+      "type": "boolean"
+    },
+    "adoptCandidate": {
+      "type": ["object", "null"],
+      "properties": {
+        "modelPath": { "type": "string" },
+        "metaPath": { "type": "string" },
+        "playablePath": { "type": "string" },
+        "localUrl": { "type": "string" },
+        "clips": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "name": { "type": "string" },
+              "guid": { "type": "string" },
+              "sourceIndex": { "type": "integer", "minimum": 0 }
+            },
+            "required": ["name", "guid", "sourceIndex"],
+            "additionalProperties": false
+          }
+        }
+      },
+      "required": ["modelPath", "metaPath", "playablePath", "localUrl", "clips"],
+      "additionalProperties": false
+    }
+  },
+  "required": ["ok", "presets", "gameProfile", "effectiveSlots", "override", "mapping", "delivery", "oneClickReady", "migrationNeeded", "adoptCandidate"],
+  "additionalProperties": false
+}

package/schemas/image-to-3d.args.json

@@ -0,0 +1,47 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "gen3d:image-to-3d args",
+  "type": "object",
+  "properties": {
+    "slug": {
+      "type": "string",
+      "description": "Active game slug. Assets are stored per game under .forgeax/games/<slug>/assets/3d/. 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."
+    },
+    "imageUrl": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Source image: a public http(s) URL, a studio-local turnaround URL, a chat-upload filename (e.g. 0cb8531d-….png), /api/sessions/<sid>/uploads/<file>, or the absolute path from [Attached image: /abs/path]. The handler finds session uploads on disk and re-hosts them before a real provider runs. Do not send base64. Do not ask the user to re-attach when a filename is already in the conversation."
+    },
+    "provider": {
+      "type": "string",
+      "enum": ["hunyuan_workflow", "meshy", "rodin", "visvise"],
+      "default": "hunyuan_workflow",
+      "description": "Generation provider. Defaults to hunyuan_workflow. Rodin uses LiteLLM rodin-3d with image_url. VISVISE uses visvise-3d / mid / low. Meshy stays in the enum but is hidden in the UI."
+    },
+    "enablePbr": { "type": "boolean", "default": true },
+    "enableFbxUrl": { "type": "boolean", "default": false },
+    "targetPolycount": {
+      "type": "integer",
+      "minimum": 1000,
+      "maximum": 300000,
+      "default": 30000
+    },
+    "providerParams": {
+      "type": "object",
+      "additionalProperties": true,
+      "description": "Provider-specific native params (validated server-side against shared/provider-params.ts; unverified/inapplicable fields are dropped). Rodin keys: mesh_mode, subdivisionlevel, material, TAPose, hd_texture, addons, use_original_alpha — same bag as the sidebar; server appends --flags to prompt. No quality_override. See docs/PROVIDER_PARAMS.md."
+    }
+  },
+  "required": ["slug", "imageUrl"],
+  "additionalProperties": false
+}

package/schemas/image-to-3d.returns.json

@@ -0,0 +1,306 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "gen3d:image-to-3d returns",
+  "type": "object",
+  "properties": {
+    "ok": {
+      "const": true
+    },
+    "cacheKey": {
+      "type": "string"
+    },
+    "cacheHit": {
+      "type": "boolean"
+    },
+    "usedMock": {
+      "type": "boolean",
+      "description": "True when the real provider 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/import-to-engine.args.json

@@ -0,0 +1,18 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "gen3d:import-to-engine args",
+  "type": "object",
+  "properties": {
+    "slug": {
+      "type": "string"
+    },
+    "assetPath": {
+      "type": "string"
+    }
+  },
+  "required": [
+    "slug",
+    "assetPath"
+  ],
+  "additionalProperties": false
+}

package/schemas/import-to-engine.returns.json

@@ -0,0 +1,35 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "gen3d:import-to-engine returns",
+  "type": "object",
+  "properties": {
+    "ok": {
+      "type": "boolean"
+    },
+    "firstImport": {
+      "type": "boolean"
+    },
+    "normalizedDraco": {
+      "type": "boolean"
+    },
+    "reusedGuidCount": {
+      "type": "integer"
+    },
+    "engineMetaPath": {
+      "type": "string"
+    },
+    "assetPath": {
+      "type": "string"
+    },
+    "message": {
+      "type": "string"
+    },
+    "code": {
+      "type": "string"
+    },
+    "retryable": {
+      "type": "boolean"
+    }
+  },
+  "additionalProperties": true
+}

package/schemas/list-assets.args.json

@@ -0,0 +1,22 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "gen3d:list-assets 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"],
+      "description": "Optional slot filter (subdir under assets/3d/). Omit to list all slots."
+    },
+    "provider": {
+      "enum": ["all", "meshy", "hunyuan_workflow", "hunyuan_rest", "rodin", "visvise"],
+      "default": "all"
+    }
+  },
+  "required": ["slug"],
+  "additionalProperties": false
+}