@forgeax-extension/character-3d 0.1.2

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

@@ -0,0 +1,67 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "gen3d:set-playable-profile returns",
+  "type": "object",
+  "properties": {
+    "ok": { "const": true },
+    "gameProfile": {
+      "type": "object",
+      "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
+    },
+    "override": {
+      "type": "object",
+      "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
+    }
+  },
+  "required": ["ok", "gameProfile", "override"],
+  "additionalProperties": false
+}

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

@@ -0,0 +1,51 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "gen3d:text-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/). characters for playable/NPC bodies, meshes for props/environment."
+    },
+    "assetName": {
+      "type": "string",
+      "description": "Desired base file name (without extension). Sanitized + de-duplicated by the store. Defaults to a name derived from the prompt."
+    },
+    "prompt": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Text prompt describing the 3D asset. Meshy rejects over 800 characters with HTTP 400 before any mesh is billed — compress the same spec first; do not switch vendor. Hunyuan/Rodin are not bound to this cap."
+    },
+    "provider": {
+      "type": "string",
+      "enum": ["hunyuan_workflow", "meshy", "rodin", "visvise"],
+      "default": "hunyuan_workflow",
+      "description": "Generation provider. Defaults to hunyuan_workflow. Rodin uses LiteLLM rodin-3d (not Hyper3D). VISVISE uses visvise-3d / mid / low via providerParams.quality. Meshy remains in the enum but is hidden in the UI."
+    },
+    "enablePbr": { "type": "boolean", "default": true },
+    "enableFbxUrl": {
+      "type": "boolean",
+      "default": false,
+      "description": "Request an FBX output URL in addition to GLB."
+    },
+    "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", "prompt"],
+  "additionalProperties": false
+}

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

@@ -0,0 +1,306 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "gen3d:text-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/upload-image.args.json

@@ -0,0 +1,19 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "gen3d:upload-image args",
+  "type": "object",
+  "properties": {
+    "base64": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Base64-encoded image bytes (a leading data: URL prefix is tolerated). Decoded image is hard-capped at 8MB. This is a transfer artifact (hosted so URL-fetching providers can reach a local file), not a 3D asset."
+    },
+    "mimetype": {
+      "type": "string",
+      "enum": ["image/png", "image/jpeg", "image/jpg", "image/webp", "image/gif"],
+      "description": "Image MIME type. Used for the COS object Content-Type and key extension."
+    }
+  },
+  "required": ["base64", "mimetype"],
+  "additionalProperties": false
+}

package/schemas/upload-image.returns.json

@@ -0,0 +1,21 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "gen3d:upload-image returns",
+  "type": "object",
+  "properties": {
+    "ok": { "const": true },
+    "url": {
+      "type": "string",
+      "description": "Time-limited presigned COS URL of the hosted image. Feed into gen3d:image-to-3d / views-to-3d / pose-standardization. Expires after expiresInSec."
+    },
+    "bytes": { "type": "integer", "minimum": 1 },
+    "sha256": { "type": "string" },
+    "expiresInSec": {
+      "type": "integer",
+      "minimum": 1,
+      "description": "Seconds until the presigned URL expires (from upload time; default 24h)."
+    }
+  },
+  "required": ["ok", "url", "bytes", "sha256", "expiresInSec"],
+  "additionalProperties": false
+}

package/schemas/upload-video.args.json

@@ -0,0 +1,14 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "gen3d:upload-video args",
+  "type": "object",
+  "properties": {
+    "mimetype": {
+      "type": "string",
+      "enum": ["video/mp4", "video/webm"],
+      "description": "Video MIME type for the COS PUT. Browser uploads bytes directly; the server never accepts 100MB base64."
+    }
+  },
+  "required": ["mimetype"],
+  "additionalProperties": false
+}

package/schemas/upload-video.returns.json

@@ -0,0 +1,14 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "gen3d:upload-video returns",
+  "type": "object",
+  "properties": {
+    "ok": { "type": "boolean", "const": true },
+    "uploadUrl": { "type": "string", "description": "Presigned PUT URL for the browser." },
+    "publicUrl": { "type": "string", "description": "Presigned GET URL to pass as apply-motion.videoUrl after PUT." },
+    "expiresInSec": { "type": "integer" },
+    "maxBytes": { "type": "integer", "description": "Hard cap (~100MB). Enforce in the browser before PUT." }
+  },
+  "required": ["ok", "uploadUrl", "publicUrl", "expiresInSec", "maxBytes"],
+  "additionalProperties": false
+}

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

@@ -0,0 +1,58 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "gen3d:views-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."
+    },
+    "views": {
+      "type": "object",
+      "description": "Named view-slot image URLs. front_image_url is required; others optional.",
+      "properties": {
+        "front_image_url": { "type": "string", "minLength": 1 },
+        "back_image_url": { "type": "string" },
+        "left_image_url": { "type": "string" },
+        "right_image_url": { "type": "string" },
+        "top_image_url": { "type": "string" },
+        "bottom_image_url": { "type": "string" },
+        "front_left_image_url": { "type": "string" },
+        "front_right_image_url": { "type": "string" }
+      },
+      "required": ["front_image_url"],
+      "additionalProperties": false
+    },
+    "provider": {
+      "type": "string",
+      "enum": ["hunyuan_workflow", "meshy", "rodin", "visvise"],
+      "default": "hunyuan_workflow",
+      "description": "Generation provider. Defaults to hunyuan_workflow. Rodin views uses rodin-3d image_urls (front first). VISVISE views is rejected with views_not_supported."
+    },
+    "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). See docs/PROVIDER_PARAMS.md."
+    }
+  },
+  "required": ["slug", "views"],
+  "additionalProperties": false
+}