@forgeax-extension/character-3d 0.1.2

package/server/env.ts

@@ -0,0 +1,287 @@
+// Env + feature-gate resolution for gen3d providers.
+//
+// Real provider calls are OFF by default. They turn on ONLY when both:
+//   1. GEN3D_ENABLE_REAL_PROVIDERS === "1", and
+//   2. a 3D gateway key is present in Studio global .env (FORGEAX_3D_GATEWAY_KEY,
+//      ANTHROPIC_API_KEY, or LITELLM_PROXY_KEY — see pickLitellmFromEnv).
+// Otherwise generation falls back to the deterministic no-quota mock. Secrets
+// are read from process.env (server loads $FORGEAX_PROJECT_ROOT/.env) or, for
+// standalone smokes, from the plugin-local .env. Nothing here is logged.
+//
+// All 3D providers now route through the LiteLLM gateway — see AGENTS.md
+// «最优 > 兼容». Hunyuan / Rodin / VISVISE never read per-vendor keys.
+// Meshy production is gateway-only. A local recording override
+// (GEN3D_MESHY_DIRECT=1 + MESHY_API_KEY) may talk to api.meshy.ai; it is not
+// a production path and must not appear in the credentials UI.
+
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+let loaded = false;
+
+// Minimal .env parser for the plugin-local file. Does not override values
+// already present in process.env (the server's .env wins).
+function loadPluginEnvOnce(): void {
+  if (loaded) return;
+  loaded = true;
+  // Stable across runtimes: import.meta.dir is bun-specific, but
+  // import.meta.url + fileURLToPath works in bun, node, and tsc typecheck.
+  const envPath = resolve(dirname(fileURLToPath(import.meta.url)), '..', '.env');
+  if (!existsSync(envPath)) return;
+  for (const rawLine of readFileSync(envPath, 'utf8').split('\n')) {
+    const line = rawLine.trim();
+    if (!line || line.startsWith('#')) continue;
+    const eq = line.indexOf('=');
+    if (eq === -1) continue;
+    const key = line.slice(0, eq).trim();
+    if (key in process.env) continue;
+    let value = line.slice(eq + 1).trim();
+    if (
+      (value.startsWith('"') && value.endsWith('"')) ||
+      (value.startsWith("'") && value.endsWith("'"))
+    ) {
+      value = value.slice(1, -1);
+    }
+    process.env[key] = value;
+  }
+}
+
+function read(name: string): string | undefined {
+  loadPluginEnvOnce();
+  const value = process.env[name];
+  return value && value.trim() ? value.trim() : undefined;
+}
+
+export function realProvidersEnabled(): boolean {
+  return read('GEN3D_ENABLE_REAL_PROVIDERS') === '1';
+}
+
+export interface LitellmEnv {
+  apiKey: string;
+  baseUrl: string;
+}
+
+const DEFAULT_LITELLM_BASE = 'https://llm-proxy.forgeax.com';
+
+function normalizeProxyBase(raw: string): string {
+  return raw.replace(/\/+$/, '').replace(/\/v1$/, '');
+}
+
+// 3D gateway base URL is resolved SEPARATELY from the chat/image
+// LITELLM_PROXY_BASE_URL: that variable points at the chat proxy (e.g.
+// Moonshot) which does NOT host /v1/3d/generations. Priority:
+//   1. FORGEAX_3D_GATEWAY_BASE_URL — 3D-only override (shared by gen3d /
+//      ai-asset; ops pins a 3D-specific host)
+//   2. ANTHROPIC_BASE_URL         — the forgeax proxy (same host that serves 3D)
+//   3. DEFAULT_LITELLM_BASE       — https://llm-proxy.forgeax.com
+// LITELLM_PROXY_BASE_URL is intentionally NOT consulted for 3D.
+function resolveGatewayBaseUrl(env: Record<string, string | undefined>): string {
+  const dedicated = env.FORGEAX_3D_GATEWAY_BASE_URL?.trim();
+  if (dedicated) return normalizeProxyBase(dedicated);
+  const anthropic = env.ANTHROPIC_BASE_URL?.trim();
+  if (anthropic) return normalizeProxyBase(anthropic);
+  return DEFAULT_LITELLM_BASE;
+}
+
+/**
+ * Resolve LiteLLM gateway credentials for 3D generation. The 3D gateway is
+ * decoupled from the chat/image LITELLM_PROXY_* vars, which may point at a
+ * different proxy (e.g. Moonshot) that does not host /v1/3d/generations.
+ *
+ * Key priority:
+ *   1. FORGEAX_3D_GATEWAY_KEY — 3D-only override (shared by all 3D plugins)
+ *   2. ANTHROPIC_API_KEY      — the forgeax proxy key (default 3D gateway auth)
+ *   3. LITELLM_PROXY_KEY      — legacy fallback (kept for pre-decouple configs)
+ * Base URL priority: FORGEAX_3D_GATEWAY_BASE_URL > ANTHROPIC_BASE_URL > default.
+ * Plugin-local .env must NOT hold a separate gateway key — configure in
+ * Studio Settings → API Keys.
+ */
+export function pickLitellmFromEnv(env: Record<string, string | undefined>): LitellmEnv | null {
+  const dedicatedKey = env.FORGEAX_3D_GATEWAY_KEY?.trim();
+  if (dedicatedKey) {
+    return { apiKey: dedicatedKey, baseUrl: resolveGatewayBaseUrl(env) };
+  }
+  const anthropicKey = env.ANTHROPIC_API_KEY?.trim();
+  if (anthropicKey) {
+    return { apiKey: anthropicKey, baseUrl: resolveGatewayBaseUrl(env) };
+  }
+  const proxyKey = env.LITELLM_PROXY_KEY?.trim();
+  if (proxyKey) {
+    return { apiKey: proxyKey, baseUrl: resolveGatewayBaseUrl(env) };
+  }
+  return null;
+}
+
+// Returns the LiteLLM gateway credentials, or null when not configured.
+// All 3D providers now route through this single gateway key.
+export function getLitellmEnv(): LitellmEnv | null {
+  loadPluginEnvOnce();
+  return pickLitellmFromEnv(process.env);
+}
+
+export interface HunyuanEnv {
+  apiKey: string;
+  baseUrl: string;
+  defaultFaceCount: number;
+  pollIntervalMs: number;
+  pollTimeoutMs: number;
+  rateLimitPerMin: number;
+}
+
+// Returns null when the real Hunyuan path is not fully configured. Now reads the
+// LiteLLM gateway key instead of the direct HUNYUAN_API_KEY. Callers must fall
+// back to mock when this is null — never throw a quota path on by accident.
+export function getHunyuanEnv(): HunyuanEnv | null {
+  if (!realProvidersEnabled()) return null;
+  const litellm = getLitellmEnv();
+  if (!litellm) return null;
+  return {
+    apiKey: litellm.apiKey,
+    baseUrl: litellm.baseUrl,
+    defaultFaceCount: toInt(read('HUNYUAN_DEFAULT_FACE_COUNT'), 30000),
+    pollIntervalMs: toInt(read('HUNYUAN_POLL_INTERVAL_MS'), 5000),
+    pollTimeoutMs: toInt(read('HUNYUAN_POLL_TIMEOUT_MS'), 600000),
+    rateLimitPerMin: toInt(read('HUNYUAN_RATE_LIMIT_PER_MIN'), 3),
+  };
+}
+
+export type MeshyTransport = 'gateway' | 'direct';
+
+export interface MeshyEnv {
+  apiKey: string;
+  baseUrl: string;
+  /** Default gateway. `direct` is a local recording override (own Meshy key). */
+  transport: MeshyTransport;
+  defaultPolycount: number;
+  pollIntervalMs: number;
+  pollTimeoutMs: number;
+  rateLimitPerMin: number;
+}
+
+const DEFAULT_MESHY_DIRECT_BASE = 'https://api.meshy.ai';
+
+function meshyTuning(env: Record<string, string | undefined>): Pick<
+  MeshyEnv,
+  'defaultPolycount' | 'pollIntervalMs' | 'pollTimeoutMs' | 'rateLimitPerMin'
+> {
+  return {
+    defaultPolycount: toInt(env.MESHY_DEFAULT_POLYCOUNT, 30000),
+    pollIntervalMs: toInt(env.MESHY_POLL_INTERVAL_MS, 5000),
+    pollTimeoutMs: toInt(env.MESHY_POLL_TIMEOUT_MS, 600000),
+    rateLimitPerMin: toInt(env.MESHY_RATE_LIMIT_PER_MIN, 3),
+  };
+}
+
+/**
+ * Meshy credentials. Production stays on the LiteLLM gateway.
+ *
+ * Local recording override (no UI): `GEN3D_MESHY_DIRECT=1` + `MESHY_API_KEY`
+ * talks to api.meshy.ai with the operator's own credits. When the override
+ * switch is on but the key is missing, return null — do not silently spend
+ * the team gateway quota.
+ */
+export function pickMeshyFromEnv(env: Record<string, string | undefined>): MeshyEnv | null {
+  if (env.GEN3D_ENABLE_REAL_PROVIDERS !== '1') return null;
+  if (env.GEN3D_MESHY_DIRECT === '1') {
+    const key = env.MESHY_API_KEY?.trim();
+    if (!key) return null;
+    const rawBase = env.MESHY_BASE_URL?.trim() || DEFAULT_MESHY_DIRECT_BASE;
+    return {
+      apiKey: key,
+      baseUrl: rawBase.replace(/\/+$/, ''),
+      transport: 'direct',
+      ...meshyTuning(env),
+    };
+  }
+  const litellm = pickLitellmFromEnv(env);
+  if (!litellm) return null;
+  return {
+    apiKey: litellm.apiKey,
+    baseUrl: litellm.baseUrl,
+    transport: 'gateway',
+    ...meshyTuning(env),
+  };
+}
+
+export function getMeshyEnv(): MeshyEnv | null {
+  loadPluginEnvOnce();
+  return pickMeshyFromEnv(process.env);
+}
+
+export interface RodinEnv {
+  apiKey: string;
+  baseUrl: string;
+  pollIntervalMs: number;
+  pollTimeoutMs: number;
+  rateLimitPerMin: number;
+}
+
+// Rodin on the LiteLLM gateway (`rodin-3d`). Same key as Meshy/Hunyuan.
+// Never reads RODIN_API_KEY (old Hyper3D). Callers must not import rodin.ts.
+export function getRodinEnv(): RodinEnv | null {
+  if (!realProvidersEnabled()) return null;
+  const litellm = getLitellmEnv();
+  if (!litellm) return null;
+  return {
+    apiKey: litellm.apiKey,
+    baseUrl: litellm.baseUrl,
+    pollIntervalMs: toInt(read('RODIN_POLL_INTERVAL_MS'), 5000),
+    pollTimeoutMs: toInt(read('RODIN_POLL_TIMEOUT_MS'), 600000),
+    rateLimitPerMin: toInt(read('RODIN_RATE_LIMIT_PER_MIN'), 3),
+  };
+}
+
+export interface VisviseEnv {
+  apiKey: string;
+  baseUrl: string;
+  pollIntervalMs: number;
+  pollTimeoutMs: number;
+  rateLimitPerMin: number;
+}
+
+export function getVisviseEnv(): VisviseEnv | null {
+  if (!realProvidersEnabled()) return null;
+  const litellm = getLitellmEnv();
+  if (!litellm) return null;
+  return {
+    apiKey: litellm.apiKey,
+    baseUrl: litellm.baseUrl,
+    pollIntervalMs: toInt(read('VISVISE_POLL_INTERVAL_MS'), 5000),
+    pollTimeoutMs: toInt(read('VISVISE_POLL_TIMEOUT_MS'), 600000),
+    rateLimitPerMin: toInt(read('VISVISE_RATE_LIMIT_PER_MIN'), 3),
+  };
+}
+
+function toInt(value: string | undefined, fallback: number): number {
+  const n = value ? Number.parseInt(value, 10) : NaN;
+  return Number.isFinite(n) && n > 0 ? n : fallback;
+}
+
+export interface CosEnv {
+  secretId: string;
+  secretKey: string;
+  bucket: string;
+  region: string;
+  // Presigned URL lifetime in seconds (input images are transfer artifacts).
+  signExpiresSec: number;
+}
+
+// Returns null when COS upload is not fully configured. Unlike provider envs,
+// COS upload is a transport convenience and is NOT gated by
+// GEN3D_ENABLE_REAL_PROVIDERS: a user can upload a local image to host it even
+// in mock mode. Callers fall back to "URL only" when this is null.
+export function getCosEnv(): CosEnv | null {
+  const secretId = read('COS_SECRET_ID');
+  const secretKey = read('COS_SECRET_KEY');
+  const bucket = read('COS_BUCKET');
+  const region = read('COS_REGION');
+  if (!secretId || !secretKey || !bucket || !region) return null;
+  return {
+    secretId,
+    secretKey,
+    bucket,
+    region,
+    signExpiresSec: toInt(read('COS_SIGN_EXPIRES_SEC'), 24 * 3600),
+  };
+}

package/server/export-playable-character.ts

@@ -0,0 +1,364 @@
+// exportPlayableCharacter — merge + cook + write delivery trio (PLAN §5.5–§5.7).
+import { createHash } from 'node:crypto';
+import { access, mkdir, readFile, rename, rm, writeFile } from 'node:fs/promises';
+import { dirname } from 'node:path';
+import {
+  cookExternalAssetMeta,
+  type ExternalAssetMeta,
+} from '@forgeax-extension/external-asset-meta';
+import {
+  effectiveSlots,
+  gameProfileFromPreset,
+  type GameMotionProfile,
+  type MotionSlotDef,
+  type RootMotionStrategy,
+} from '../shared/playable-profile';
+import { motionRefKey, type Gen3DAssetManifest } from '../shared/manifest';
+import type { PerGameAssetStore } from './per-game-store';
+import { mergePlayableCharacter, resolveExportSlots } from './merge-playable-character';
+import { playableDeliveryLocalUrl } from '../shared/playable-preview-url';
+
+export interface PlayableClipDelivery {
+  guid: string;
+  sourceIndex: number;
+  loop: boolean;
+  speed: number;
+  rootMotion: RootMotionStrategy;
+}
+
+export interface PlayableDeliveryJson {
+  schemaVersion: 1;
+  kind: 'playable-character-delivery';
+  sourceAssetPath: string;
+  modelPath: string;
+  profileId: string;
+  profileVersion: number;
+  sceneGuid: string;
+  clips: Record<string, PlayableClipDelivery>;
+}
+
+export type ExportPlayableResult =
+  | {
+      ok: true;
+      firstExport: boolean;
+      modelPath: string;
+      metaPath: string;
+      playablePath: string;
+      localUrl: string;
+      clipCount: number;
+      reusedGuidCount: number;
+      message: string;
+    }
+  | {
+      ok: false;
+      code: string;
+      message: string;
+      missingSlots?: string[];
+      retryable: boolean;
+    };
+
+function sha256Hex(data: Uint8Array): string {
+  return createHash('sha256').update(data).digest('hex');
+}
+
+export function mappingFingerprint(
+  slots: readonly MotionSlotDef[],
+  mappings: readonly { slotId: string; motionRefKey: string | null }[],
+  profileId: string,
+  profileVersion: number,
+): string {
+  const map = Object.fromEntries(mappings.map((m) => [m.slotId, m.motionRefKey]));
+  const body = {
+    profileId,
+    profileVersion,
+    slots: slots.map((s) => ({
+      id: s.slotId,
+      required: s.required,
+      rootMotion: s.rootMotion,
+      speed: s.speed,
+      playbackMode: s.playbackMode,
+      motion: map[s.slotId] ?? null,
+    })),
+  };
+  return sha256Hex(new TextEncoder().encode(JSON.stringify(body)));
+}
+
+async function exists(path: string): Promise<boolean> {
+  try {
+    await access(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function stemFromAssetPath(assetPath: string): string {
+  const base = assetPath.split('/').pop() ?? 'character.glb';
+  return base.replace(/\.glb$/i, '') || 'character';
+}
+
+export async function exportPlayableCharacter(
+  store: PerGameAssetStore,
+  args: { slug: string; assetPath: string; forceWizardConfirm?: boolean },
+): Promise<ExportPlayableResult> {
+  const { slug, assetPath } = args;
+  const manifest = await store.getAsset(slug, assetPath);
+  if (!manifest) {
+    return { ok: false, code: 'asset_not_found', message: 'Character asset not found.', retryable: false };
+  }
+  if (manifest.assetSlot !== 'characters') {
+    return {
+      ok: false,
+      code: 'not_a_character',
+      message: 'Export Playable Character is only for characters (ROLE1).',
+      retryable: false,
+    };
+  }
+  if (!manifest.readiness.rigged) {
+    return {
+      ok: false,
+      code: 'not_rigged',
+      message: 'Character is not rigged yet — finish auto-rig before export.',
+      retryable: false,
+    };
+  }
+
+  const gameProfileStored = await store.getGameMotionProfile(slug);
+  const gameProfile: GameMotionProfile =
+    gameProfileStored ?? gameProfileFromPreset('basic-character-v1', new Date(0).toISOString());
+  const state = await store.getCharacterPlayableState(slug, assetPath);
+  const override = state?.override ?? null;
+  const mapping = state?.mapping ?? null;
+  if (!mapping || !mapping.confirmed) {
+    return {
+      ok: false,
+      code: 'mapping_not_confirmed',
+      message: 'Motion mapping is not confirmed yet — open the export wizard and confirm slots.',
+      retryable: false,
+    };
+  }
+
+  const slots = effectiveSlots(gameProfile, override);
+  const resolved = resolveExportSlots({
+    slots,
+    mappings: mapping.mappings,
+  });
+  if (!resolved.ok) {
+    return {
+      ok: false,
+      code: resolved.code,
+      message: resolved.message,
+      missingSlots: resolved.missingSlots,
+      retryable: false,
+    };
+  }
+
+  const rigged = await store.readAssetFile(slug, assetPath, 'rigged_model', 'glb');
+  if (!rigged) {
+    return {
+      ok: false,
+      code: 'missing_rigged_glb',
+      message: 'No rigged_model.glb dependency found for this character.',
+      retryable: false,
+    };
+  }
+
+  // Index animated_model files by motionRefKey.
+  const motionFiles = manifest.files.filter((f) => f.role === 'animated_model' && f.format === 'glb' && f.motionRef);
+  const byKey = new Map<string, (typeof motionFiles)[number]>();
+  for (const f of motionFiles) {
+    if (f.motionRef) byKey.set(motionRefKey(f.motionRef), f);
+  }
+
+  const mergeSlots: { slotId: string; motionGlbBytes: Uint8Array; rootMotion: RootMotionStrategy }[] = [];
+  for (const slotId of resolved.exportSlotIds) {
+    const key = resolved.mappingBySlot.get(slotId)!;
+    const file = byKey.get(key);
+    if (!file) {
+      return {
+        ok: false,
+        code: 'motion_file_missing',
+        message: `Mapped motion ${key} for slot ${slotId} is not on disk.`,
+        missingSlots: [slotId],
+        retryable: false,
+      };
+    }
+    const { data } = await readSpecificFile(store, slug, file.storageKey);
+    if (!data) {
+      return {
+        ok: false,
+        code: 'motion_file_missing',
+        message: `Cannot read motion file for slot ${slotId} (${file.storageKey}).`,
+        missingSlots: [slotId],
+        retryable: true,
+      };
+    }
+    const slotDef = slots.find((s) => s.slotId === slotId)!;
+    mergeSlots.push({ slotId, motionGlbBytes: data, rootMotion: slotDef.rootMotion });
+  }
+
+  const merged = await mergePlayableCharacter({
+    baseRiggedGlbBytes: rigged.data,
+    slots: mergeSlots,
+  });
+  if (!merged.ok) {
+    return { ok: false, code: merged.code, message: merged.message, retryable: true };
+  }
+
+  const stem = stemFromAssetPath(assetPath);
+  const modelRel = `assets/characters/${stem}-merged.glb`;
+  const metaRel = `${modelRel}.meta.json`;
+  const playableRel = `${modelRel}.playable.json`;
+  const glbAbs = store.resolveGameRelPath(slug, modelRel);
+  const metaAbs = store.resolveGameRelPath(slug, metaRel);
+  const playableAbs = store.resolveGameRelPath(slug, playableRel);
+
+  let existingMeta: ExternalAssetMeta | null = null;
+  let slotGuidRegistry: Record<string, string> = {};
+  const sidecarState = await readDeliverySnapshot(store, slug, assetPath);
+  if (sidecarState?.slotGuidRegistry) slotGuidRegistry = { ...sidecarState.slotGuidRegistry };
+  if (await exists(metaAbs)) {
+    try {
+      existingMeta = JSON.parse(await readFile(metaAbs, 'utf8')) as ExternalAssetMeta;
+      if (existingMeta.kind !== 'external-asset-package') existingMeta = null;
+    } catch {
+      existingMeta = null;
+    }
+  }
+  const firstExport = !(await exists(glbAbs)) || !sidecarState;
+
+  const contentHash = `sha256:${sha256Hex(merged.bytes)}`;
+  const cooked = await cookExternalAssetMeta(merged.bytes, contentHash, `${stem}-merged.glb`, {
+    existingMeta,
+    animationSlotKeys: resolved.exportSlotIds,
+    slotGuidRegistry,
+  });
+  if (!cooked.ok) {
+    return { ok: false, code: cooked.code, message: cooked.message, retryable: true };
+  }
+
+  const scene = cooked.meta.subAssets.find((s) => s.kind === 'scene');
+  const clipsMeta = cooked.meta.subAssets.filter((s) => s.kind === 'animation-clip');
+  const clips: PlayableDeliveryJson['clips'] = {};
+  const nextRegistry: Record<string, string> = { ...slotGuidRegistry };
+  let reusedGuidCount = 0;
+  for (let i = 0; i < resolved.exportSlotIds.length; i++) {
+    const slotId = resolved.exportSlotIds[i]!;
+    const slotDef = slots.find((s) => s.slotId === slotId)!;
+    const clipSub = clipsMeta.find((c) => c.sourceIndex === i) ?? clipsMeta[i];
+    if (!clipSub) {
+      return {
+        ok: false,
+        code: 'cook_clip_mismatch',
+        message: `Cooked meta missing animation-clip for slot ${slotId}`,
+        retryable: true,
+      };
+    }
+    if (slotGuidRegistry[slotId] && slotGuidRegistry[slotId] === clipSub.guid) reusedGuidCount += 1;
+    nextRegistry[slotId] = clipSub.guid;
+    clips[slotId] = {
+      guid: clipSub.guid,
+      sourceIndex: clipSub.sourceIndex,
+      loop: slotDef.playbackMode === 'loop',
+      speed: slotDef.speed,
+      rootMotion: slotDef.rootMotion,
+    };
+  }
+
+  const playable: PlayableDeliveryJson = {
+    schemaVersion: 1,
+    kind: 'playable-character-delivery',
+    sourceAssetPath: assetPath,
+    modelPath: modelRel,
+    profileId: override?.basedOnProfileId ?? gameProfile.profileId,
+    profileVersion: override?.basedOnProfileVersion ?? gameProfile.profileVersion,
+    sceneGuid: scene?.guid ?? '',
+    clips,
+  };
+
+  // Atomic write: temp → validate → rename (PLAN §5.7).
+  await mkdir(dirname(glbAbs), { recursive: true });
+  const tmpGlb = `${glbAbs}.__export_tmp`;
+  const tmpMeta = `${metaAbs}.__export_tmp`;
+  const tmpPlayable = `${playableAbs}.__export_tmp`;
+  try {
+    await writeFile(tmpGlb, merged.bytes);
+    await writeFile(tmpMeta, `${JSON.stringify(cooked.meta, null, 2)}\n`, 'utf8');
+    await writeFile(tmpPlayable, `${JSON.stringify(playable, null, 2)}\n`, 'utf8');
+    // Basic validate temps exist + playable schema kind
+    const check = JSON.parse(await readFile(tmpPlayable, 'utf8')) as PlayableDeliveryJson;
+    if (check.kind !== 'playable-character-delivery') {
+      throw new Error('playable.json kind mismatch');
+    }
+    await rename(tmpGlb, glbAbs);
+    await rename(tmpMeta, metaAbs);
+    await rename(tmpPlayable, playableAbs);
+  } catch (err) {
+    await rm(tmpGlb, { force: true }).catch(() => undefined);
+    await rm(tmpMeta, { force: true }).catch(() => undefined);
+    await rm(tmpPlayable, { force: true }).catch(() => undefined);
+    return {
+      ok: false,
+      code: 'write_failed',
+      message: err instanceof Error ? err.message : 'Failed to write playable delivery trio',
+      retryable: true,
+    };
+  }
+
+  const fp = mappingFingerprint(slots, mapping.mappings, playable.profileId, playable.profileVersion);
+  await store.updatePlayableDeliverySnapshot(slug, assetPath, {
+    modelPath: modelRel,
+    playablePath: playableRel,
+    profileId: playable.profileId,
+    profileVersion: playable.profileVersion,
+    clipSlotIds: resolved.exportSlotIds,
+    slotGuidRegistry: nextRegistry,
+    mappingFingerprint: fp,
+    exportedAt: new Date().toISOString(),
+  });
+
+  return {
+    ok: true,
+    firstExport,
+    modelPath: modelRel,
+    metaPath: metaRel,
+    playablePath: playableRel,
+    localUrl: playableDeliveryLocalUrl(slug, modelRel),
+    clipCount: resolved.exportSlotIds.length,
+    reusedGuidCount,
+    message:
+      'Playable character exported to Edit asset catalog. This does not auto-replace the game protagonist or modify gameplay code.',
+  };
+}
+
+async function readSpecificFile(
+  store: PerGameAssetStore,
+  slug: string,
+  storageKey: string,
+): Promise<{ data: Uint8Array | null }> {
+  // storageKey like assets/3d/characters/hero.animated_model.motion-meshy-1.glb
+  const abs = store.resolveGameRelPath(slug, storageKey);
+  try {
+    const data = new Uint8Array(await readFile(abs));
+    return { data };
+  } catch {
+    return { data: null };
+  }
+}
+
+async function readDeliverySnapshot(
+  store: PerGameAssetStore,
+  slug: string,
+  assetPath: string,
+): Promise<NonNullable<Gen3DAssetManifest extends never ? never : import('../shared/manifest').AssetSidecar['custom']['playableDelivery']> | null> {
+  // Re-read via getAsset is insufficient (snapshot not on manifest). Use sidecar through resolveAssetFiles.
+  const resolved = store.resolveAssetFiles(slug, assetPath);
+  if (!resolved) return null;
+  try {
+    const raw = await readFile(resolved.sidecarAbs, 'utf8');
+    const sidecar = JSON.parse(raw) as { custom?: { playableDelivery?: { modelPath: string; playablePath: string; profileId: string; profileVersion: number; slotGuidRegistry: Record<string, string>; mappingFingerprint: string; exportedAt: string } } };
+    return sidecar.custom?.playableDelivery ?? null;
+  } catch {
+    return null;
+  }
+}