@forgeax-extension/character-3d 0.1.2

package/packages/external-asset-meta/src/normalize.ts

@@ -0,0 +1,101 @@
+/// <reference path="./draco3dgltf.d.ts" />
+import { NodeIO, VertexLayout } from '@gltf-transform/core';
+import { KHRDracoMeshCompression } from '@gltf-transform/extensions';
+import { prune, unpartition } from '@gltf-transform/functions';
+import draco3d from 'draco3dgltf';
+import type { NormalizeResult } from './types.ts';
+
+function parseGlbJson(glbBytes: Uint8Array): { extensionsRequired?: string[] } | null {
+  if (glbBytes.length < 20) return null;
+  const view = new DataView(glbBytes.buffer, glbBytes.byteOffset, glbBytes.byteLength);
+  if (view.getUint32(0, true) !== 0x46546c67) return null;
+  const jsonLen = view.getUint32(12, true);
+  if (jsonLen <= 0 || 20 + jsonLen > glbBytes.length) return null;
+  try {
+    return JSON.parse(new TextDecoder().decode(glbBytes.subarray(20, 20 + jsonLen))) as {
+      extensionsRequired?: string[];
+    };
+  } catch {
+    return null;
+  }
+}
+
+let decoderPromise: Promise<unknown> | undefined;
+function getDecoder(): Promise<unknown> {
+  if (decoderPromise === undefined) {
+    decoderPromise = draco3d.createDecoderModule();
+  }
+  return decoderPromise;
+}
+
+/**
+ * Decode Draco (if present) and rewrite a GLB the engine can ingest:
+ * VertexLayout.SEPARATE + prune + unpartition; no required KHR_draco_mesh_compression.
+ */
+export async function normalizeGlbForEngine(glbBytes: Uint8Array): Promise<NormalizeResult> {
+  const json = parseGlbJson(glbBytes);
+  if (json === null) {
+    return { ok: false, code: 'corrupt_glb', message: 'GLB header/JSON chunk is corrupt or not a GLB.' };
+  }
+
+  const required = json.extensionsRequired ?? [];
+  const needsDraco = required.includes('KHR_draco_mesh_compression');
+
+  try {
+    const io = new NodeIO()
+      .registerExtensions([KHRDracoMeshCompression])
+      .registerDependencies({
+        'draco3d.decoder': await getDecoder(),
+      });
+    io.setVertexLayout(VertexLayout.SEPARATE);
+
+    let document;
+    try {
+      document = await io.readBinary(glbBytes);
+    } catch (err) {
+      return {
+        ok: false,
+        code: 'decode_failed',
+        message: err instanceof Error ? err.message : 'Failed to decode GLB (Draco/corrupt).',
+      };
+    }
+
+    // Drop Draco extension so the written GLB does not require it.
+    for (const ext of [...document.getRoot().listExtensionsUsed()]) {
+      if (ext.extensionName === 'KHR_draco_mesh_compression') {
+        ext.dispose();
+      }
+    }
+
+    await document.transform(prune(), unpartition());
+
+    let out: Uint8Array;
+    try {
+      out = await io.writeBinary(document);
+    } catch (err) {
+      return {
+        ok: false,
+        code: 'write_failed',
+        message: err instanceof Error ? err.message : 'Failed to write normalized GLB.',
+      };
+    }
+
+    const outJson = parseGlbJson(out);
+    const stillRequired = outJson?.extensionsRequired?.includes('KHR_draco_mesh_compression') ?? false;
+    if (stillRequired) {
+      return {
+        ok: false,
+        code: 'write_failed',
+        message: 'Normalized GLB still lists KHR_draco_mesh_compression as required.',
+      };
+    }
+
+    return { ok: true, bytes: out, changed: needsDraco || out.length !== glbBytes.length };
+  } catch (err) {
+    return {
+      ok: false,
+      code: 'decode_failed',
+      message: err instanceof Error ? err.message : 'normalizeGlbForEngine failed',
+    };
+  }
+}

package/packages/external-asset-meta/src/types.ts

@@ -0,0 +1,82 @@
+/** Engine external-asset-package meta shape (clean; no plugin-private fields). */
+
+export interface ExternalAssetSubAsset {
+  readonly guid: string;
+  readonly sourceIndex: number;
+  readonly kind: string;
+  readonly name?: string;
+}
+
+export interface ExternalAssetMeta {
+  schemaVersion: 1;
+  kind: 'external-asset-package';
+  importer: 'gltf';
+  source?: string;
+  importSettings: {
+    defaultSceneIndex?: number;
+    diagnostics?: {
+      nodeNames: ReadonlyArray<string>;
+      unsupportedExtensions: ReadonlyArray<string>;
+      matrixTrsCoexistNodes: ReadonlyArray<string>;
+    };
+    colorSpace?: 'srgb' | 'linear';
+    mipmap?: 'auto' | 'none';
+  };
+  subAssets: ReadonlyArray<ExternalAssetSubAsset>;
+}
+
+/** Engine v1 required-extension allowlist (gltf khr-extensions.test). */
+export const ENGINE_REQUIRED_EXTENSION_ALLOWLIST = ['EXT_mesh_gpu_instancing'] as const;
+
+export type CookErrorCode =
+  | 'corrupt_glb'
+  | 'no_meshes'
+  | 'engine_unsupported_extension'
+  | 'read_failed';
+
+export interface CookSuccess {
+  readonly ok: true;
+  readonly meta: ExternalAssetMeta;
+}
+
+export interface CookFailure {
+  readonly ok: false;
+  readonly code: CookErrorCode;
+  readonly message: string;
+  readonly unsupportedExtensions?: ReadonlyArray<string>;
+}
+
+export type CookResult = CookSuccess | CookFailure;
+
+export interface CookOptions {
+  /** Previously written clean engine meta — reuse GUIDs by (kind, sourceIndex). */
+  readonly existingMeta?: ExternalAssetMeta | null;
+  /**
+   * Semantic GUID registry for animation-clip rows (slotKey → guid).
+   * When `animationSlotKeys[i]` is set, prefer registry[slotKey] over
+   * existingMeta / deterministic hash for that clip's GUID.
+   */
+  readonly slotGuidRegistry?: Readonly<Record<string, string>>;
+  /** Parallel to glTF animations[] order; entry may be undefined/omitted. */
+  readonly animationSlotKeys?: ReadonlyArray<string | undefined>;
+}
+
+export type NormalizeErrorCode =
+  | 'corrupt_glb'
+  | 'decode_failed'
+  | 'write_failed';
+
+export interface NormalizeSuccess {
+  readonly ok: true;
+  readonly bytes: Uint8Array;
+  /** True when input already had no required Draco / was rewritten. */
+  readonly changed: boolean;
+}
+
+export interface NormalizeFailure {
+  readonly ok: false;
+  readonly code: NormalizeErrorCode;
+  readonly message: string;
+}
+
+export type NormalizeResult = NormalizeSuccess | NormalizeFailure;

package/schemas/adopt-playable-character.args.json

@@ -0,0 +1,26 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "gen3d:adopt-playable-character args",
+  "type": "object",
+  "properties": {
+    "slug": { "type": "string" },
+    "assetPath": { "type": "string" },
+    "slotMappings": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "slotId": { "type": "string" },
+          "clipName": { "type": ["string", "null"] },
+          "sourceIndex": { "type": ["integer", "null"], "minimum": 0 },
+          "guid": { "type": ["string", "null"] }
+        },
+        "required": ["slotId"],
+        "additionalProperties": false
+      }
+    },
+    "confirmed": { "type": "boolean" }
+  },
+  "required": ["slug", "assetPath", "slotMappings"],
+  "additionalProperties": false
+}

package/schemas/adopt-playable-character.returns.json

@@ -0,0 +1,31 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "gen3d:adopt-playable-character returns",
+  "oneOf": [
+    {
+      "type": "object",
+      "properties": {
+        "ok": { "const": true },
+        "modelPath": { "type": "string" },
+        "playablePath": { "type": "string" },
+        "localUrl": { "type": "string" },
+        "reusedGuidCount": { "type": "integer", "minimum": 0 },
+        "clipCount": { "type": "integer", "minimum": 0 },
+        "message": { "type": "string" }
+      },
+      "required": ["ok", "modelPath", "playablePath", "localUrl", "reusedGuidCount", "clipCount", "message"],
+      "additionalProperties": false
+    },
+    {
+      "type": "object",
+      "properties": {
+        "ok": { "const": false },
+        "code": { "type": "string" },
+        "message": { "type": "string" },
+        "retryable": { "type": "boolean" }
+      },
+      "required": ["ok", "code", "message", "retryable"],
+      "additionalProperties": false
+    }
+  ]
+}

package/schemas/apply-motion.args.json

@@ -0,0 +1,47 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "gen3d:apply-motion 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 a RIGGED asset (from gen3d:auto-rig). The animated GLB+FBX for this motion are appended to THIS asset. Dispatch is by the asset's recorded rig system (Meshy public default, Hunyuan dev fallback)."
+    },
+    "actionId": {
+      "type": "integer",
+      "minimum": 1,
+      "description": "Meshy path (public-beta default): a positive action_id chosen from gen3d:list-motions. Drives Meshy /animations via the asset's OWN rig_task_id. Idempotent per motion; required when the asset was Meshy-rigged."
+    },
+    "label": {
+      "type": "string",
+      "description": "Optional display label for the chosen motion (the UI passes the action name it showed). Stored on the clip; the catalog is not re-queried. Defaults to \"动作 <id>\"."
+    },
+    "autoReRig": {
+      "type": "boolean",
+      "description": "Meshy only: when the rig task has expired (~3 days), re-rig first (+credits) instead of failing with rig_expired. Default false."
+    },
+    "motionType": {
+      "type": "integer",
+      "minimum": 9,
+      "maximum": 16,
+      "description": "Hunyuan path only: v1 fixed motion 9–16. Required when the asset was Hunyuan-rigged."
+    },
+    "prompt": {
+      "type": "string",
+      "minLength": 1,
+      "description": "VISVISE text-motion prompt. Required (xor videoUrl) when the asset was VISVISE-rigged."
+    },
+    "videoUrl": {
+      "type": "string",
+      "minLength": 1,
+      "description": "VISVISE video-motion URL (after gen3d:upload-video PUT, or an existing URL). Required (xor prompt) when the asset was VISVISE-rigged."
+    }
+  },
+  "required": ["assetPath"],
+  "additionalProperties": false
+}

package/schemas/apply-motion.returns.json

@@ -0,0 +1,23 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "gen3d:apply-motion returns",
+  "type": "object",
+  "properties": {
+    "ok": { "const": true },
+    "usedMock": {
+      "type": "boolean",
+      "description": "True when no real Hunyuan provider was configured and deterministic placeholder model bytes were appended (quota-safe fallback)."
+    },
+    "assetPath": {
+      "type": "string",
+      "description": "Game-relative path of the animated asset (unchanged from input; the main GLB identity is stable)."
+    },
+    "manifest": {
+      "type": "object",
+      "description": "Updated manifest after the animated_model GLB+FBX for this motion were appended and readiness.animated flipped true. Multiple motions coexist as separate animated_model files (each tagged with its motionType).",
+      "additionalProperties": true
+    }
+  },
+  "required": ["ok", "usedMock", "assetPath", "manifest"],
+  "additionalProperties": false
+}

package/schemas/auto-rig.args.json

@@ -0,0 +1,35 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "gen3d:auto-rig 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 textured high-poly mesh asset (its main GLB) to rig. Humanoid characters only. The rigged GLB+FBX are appended to THIS asset; the main GLB identity is unchanged."
+    },
+    "rigProvider": {
+      "type": "string",
+      "enum": ["auto", "meshy", "hunyuan_rest", "visvise"],
+      "default": "auto",
+      "description": "Which LiteLLM rig route to use. auto prefers Hunyuan REST, then VISVISE, then mock. Meshy is no longer first. Explicit meshy/hunyuan_rest/visvise force that route and fail with provider_not_configured when that env is missing."
+    },
+    "force": {
+      "type": "boolean",
+      "default": false,
+      "description": "When the asset is already rigged: strip prior rigged_model + animated_model files and custom.rig, then re-run auto-rig on the chosen rigProvider (burns fresh credits; use to switch Meshy ↔ Hunyuan). Default false keeps the idempotent no-op."
+    },
+    "heightMeters": {
+      "type": "number",
+      "minimum": 0.1,
+      "maximum": 5,
+      "description": "Meshy auto-rig only: approximate character height in meters (aids pose estimation / scale). Omit to use Meshy default (~1.7). Ignored for Hunyuan."
+    }
+  },
+  "required": ["assetPath"],
+  "additionalProperties": false
+}

package/schemas/auto-rig.returns.json

@@ -0,0 +1,23 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "gen3d:auto-rig returns",
+  "type": "object",
+  "properties": {
+    "ok": { "const": true },
+    "usedMock": {
+      "type": "boolean",
+      "description": "True when no real Hunyuan provider was configured and deterministic placeholder model bytes were appended (quota-safe fallback)."
+    },
+    "assetPath": {
+      "type": "string",
+      "description": "Game-relative path of the rigged asset (unchanged from input; the main GLB identity is stable)."
+    },
+    "manifest": {
+      "type": "object",
+      "description": "Updated manifest of the asset after the rigged_model GLB+FBX were appended and readiness.rigged flipped true.",
+      "additionalProperties": true
+    }
+  },
+  "required": ["ok", "usedMock", "assetPath", "manifest"],
+  "additionalProperties": false
+}

package/schemas/delete-asset.args.json

@@ -0,0 +1,18 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "gen3d:delete-asset 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 asset to delete (e.g. assets/3d/characters/hero.glb). Destructive: removes the main GLB, its sidecar, and same-basename sidefiles, and tombstones the cacheKey so it never resurrects from a cache hit."
+    }
+  },
+  "required": ["assetPath"],
+  "additionalProperties": false
+}

package/schemas/delete-asset.returns.json

@@ -0,0 +1,18 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "gen3d:delete-asset returns",
+  "type": "object",
+  "properties": {
+    "ok": { "const": true },
+    "assetPath": {
+      "type": "string",
+      "description": "The game-relative path that was deleted."
+    },
+    "tombstoned": {
+      "type": "boolean",
+      "description": "True when the asset's sidecar carried a cacheKey that was tombstoned (so a later identical request will not cache-hit the deleted asset)."
+    }
+  },
+  "required": ["ok", "assetPath", "tombstoned"],
+  "additionalProperties": false
+}

package/schemas/engine-import-status.args.json

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

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

@@ -0,0 +1,50 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "gen3d:engine-import-status returns",
+  "type": "object",
+  "properties": {
+    "ok": {
+      "const": true
+    },
+    "imported": {
+      "type": "boolean"
+    },
+    "needsManualImport": {
+      "type": "boolean"
+    },
+    "needsDracoNormalize": {
+      "type": "boolean"
+    },
+    "engineMetaPath": {
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "sourceHash": {
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "importedAt": {
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "message": {
+      "type": "string"
+    },
+    "retryable": {
+      "type": "boolean"
+    }
+  },
+  "required": [
+    "ok",
+    "imported",
+    "needsManualImport",
+    "message"
+  ],
+  "additionalProperties": true
+}

package/schemas/export-playable-character.args.json

@@ -0,0 +1,21 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "gen3d:export-playable-character args",
+  "type": "object",
+  "properties": {
+    "slug": {
+      "type": "string"
+    },
+    "assetPath": {
+      "type": "string"
+    },
+    "forceWizardConfirm": {
+      "type": "boolean"
+    }
+  },
+  "required": [
+    "slug",
+    "assetPath"
+  ],
+  "additionalProperties": false
+}

package/schemas/export-playable-character.returns.json

@@ -0,0 +1,47 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "gen3d:export-playable-character returns",
+  "type": "object",
+  "properties": {
+    "ok": {
+      "type": "boolean"
+    },
+    "firstExport": {
+      "type": "boolean"
+    },
+    "modelPath": {
+      "type": "string"
+    },
+    "metaPath": {
+      "type": "string"
+    },
+    "playablePath": {
+      "type": "string"
+    },
+    "localUrl": {
+      "type": "string"
+    },
+    "clipCount": {
+      "type": "integer"
+    },
+    "reusedGuidCount": {
+      "type": "integer"
+    },
+    "message": {
+      "type": "string"
+    },
+    "code": {
+      "type": "string"
+    },
+    "missingSlots": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "retryable": {
+      "type": "boolean"
+    }
+  },
+  "additionalProperties": true
+}