@forgeax-extension/character-3d 0.1.2

package/shared/playable-preview-url.test.ts

@@ -0,0 +1,14 @@
+import { expect, test } from 'bun:test';
+import { playableDeliveryLocalUrl } from './playable-preview-url';
+
+test('playableDeliveryLocalUrl uses engine /preview mount, not /api/game-assets/3d', () => {
+  expect(playableDeliveryLocalUrl('hellforge', 'assets/characters/gta-01-merged.glb')).toBe(
+    '/preview/.forgeax/games/hellforge/assets/characters/gta-01-merged.glb',
+  );
+});
+
+test('playableDeliveryLocalUrl encodes path segments', () => {
+  expect(playableDeliveryLocalUrl('my game', 'assets/characters/hero merged.glb')).toBe(
+    '/preview/.forgeax/games/my%20game/assets/characters/hero%20merged.glb',
+  );
+});

package/shared/playable-preview-url.ts

@@ -0,0 +1,13 @@
+// Preview URL for playable delivery GLBs (PLAN §5.8 PREV1).
+//
+// Delivery trio lives at `assets/characters/<stem>-merged.glb`, OUTSIDE the
+// server's `/api/game-assets/:slug/3d/**` mount (that route only serves gen3d
+// source assets under assets/3d/). The Play/Edit engine vite already exposes
+// the game tree at `/preview/.forgeax/games/<slug>/…` (proxied by Studio UI),
+// so ModelViewer must use that path — not /api/game-assets/…/characters/….
+
+export function playableDeliveryLocalUrl(slug: string, modelPath: string): string {
+  const cleaned = modelPath.replace(/^\/+/, '');
+  const parts = cleaned.split('/').filter(Boolean).map(encodeURIComponent);
+  return `/preview/.forgeax/games/${encodeURIComponent(slug)}/${parts.join('/')}`;
+}

package/shared/playable-profile.test.ts

@@ -0,0 +1,127 @@
+import { test, expect } from 'bun:test';
+import {
+  BUILTIN_PROFILE_PRESETS,
+  autoMatchMotionMapping,
+  effectiveSlots,
+  findPreset,
+  gameProfileFromPreset,
+  type CharacterMotionOverride,
+} from './playable-profile';
+
+test('four built-in presets exist with the exact PROF2 ids', () => {
+  const ids = BUILTIN_PROFILE_PRESETS.map((p) => p.profileId);
+  expect(ids).toEqual([
+    'basic-character-v1',
+    'action-adventure-v1',
+    'platformer-v1',
+    'blank-custom-v1',
+  ]);
+});
+
+test('blank-custom-v1 has zero slots (PROF5 enforced at export time, not here)', () => {
+  const preset = findPreset('blank-custom-v1');
+  expect(preset?.slots).toEqual([]);
+});
+
+test('basic-character-v1 has idle+move both required, move defaults remove_xz', () => {
+  const preset = findPreset('basic-character-v1');
+  const idle = preset?.slots.find((s) => s.slotId === 'idle');
+  const move = preset?.slots.find((s) => s.slotId === 'move');
+  expect(idle?.required).toBe(true);
+  expect(idle?.rootMotion).toBe('preserve');
+  expect(move?.required).toBe(true);
+  expect(move?.rootMotion).toBe('remove_xz');
+});
+
+test('action-adventure-v1: idle/move/attack required, hit/death optional', () => {
+  const preset = findPreset('action-adventure-v1')!;
+  const required = preset.slots.filter((s) => s.required).map((s) => s.slotId);
+  const optional = preset.slots.filter((s) => !s.required).map((s) => s.slotId);
+  expect(required.sort()).toEqual(['attack', 'idle', 'move']);
+  expect(optional.sort()).toEqual(['death', 'hit']);
+});
+
+test('platformer-v1: idle/move/jump required, fall/land optional', () => {
+  const preset = findPreset('platformer-v1')!;
+  const required = preset.slots.filter((s) => s.required).map((s) => s.slotId);
+  const optional = preset.slots.filter((s) => !s.required).map((s) => s.slotId);
+  expect(required.sort()).toEqual(['idle', 'jump', 'move']);
+  expect(optional.sort()).toEqual(['fall', 'land']);
+});
+
+test('findPreset returns null for an unknown id', () => {
+  expect(findPreset('nonexistent-v1')).toBeNull();
+});
+
+test('gameProfileFromPreset starts at profileVersion 1 and clones preset slots (no shared references)', () => {
+  const now = '2026-07-13T00:00:00.000Z';
+  const profile = gameProfileFromPreset('basic-character-v1', now);
+  expect(profile.profileVersion).toBe(1);
+  expect(profile.profileId).toBe('basic-character-v1');
+  expect(profile.updatedAt).toBe(now);
+  profile.slots[0].displayName = 'mutated';
+  expect(findPreset('basic-character-v1')!.slots[0].displayName).not.toBe('mutated');
+});
+
+test('gameProfileFromPreset clones matchKeywords arrays too, not just the slot object', () => {
+  const profile = gameProfileFromPreset('basic-character-v1', '2026-07-13T00:00:00.000Z');
+  profile.slots[0].matchKeywords.push('leaked');
+  expect(findPreset('basic-character-v1')!.slots[0].matchKeywords).not.toContain('leaked');
+});
+
+test('gameProfileFromPreset falls back to the first preset for an unknown id', () => {
+  const profile = gameProfileFromPreset('nonexistent-v1', '2026-07-13T00:00:00.000Z');
+  expect(profile.profileId).toBe(BUILTIN_PROFILE_PRESETS[0].profileId);
+});
+
+test('effectiveSlots: no override → game profile slots', () => {
+  const profile = gameProfileFromPreset('action-adventure-v1', '2026-07-13T00:00:00.000Z');
+  expect(effectiveSlots(profile, null)).toBe(profile.slots);
+});
+
+test('effectiveSlots: override REPLACES wholesale, does not merge by slotId', () => {
+  const profile = gameProfileFromPreset('action-adventure-v1', '2026-07-13T00:00:00.000Z');
+  const override: CharacterMotionOverride = {
+    schemaVersion: 1,
+    // Deliberately drops 'hit'/'death' present in the game default — a merge-
+    // by-slotId implementation would resurrect them; effectiveSlots must not.
+    slots: [
+      { slotId: 'idle', displayName: '待机', required: true, playbackMode: 'loop', speed: 1, matchKeywords: ['idle'], rootMotion: 'preserve' },
+    ],
+    basedOnProfileId: profile.profileId,
+    basedOnProfileVersion: profile.profileVersion,
+    updatedAt: '2026-07-13T00:00:00.000Z',
+  };
+  const result = effectiveSlots(profile, override);
+  expect(result).toEqual(override.slots);
+  expect(result.some((s) => s.slotId === 'hit')).toBe(false);
+});
+
+test('autoMatchMotionMapping: matches by case-insensitive keyword substring', () => {
+  const preset = findPreset('basic-character-v1')!;
+  const result = autoMatchMotionMapping(preset.slots, [
+    { motionRefKey: 'meshy:1', label: 'Idle_Breathing' },
+    { motionRefKey: 'meshy:2', label: 'Walking_Move_Forward' },
+  ]);
+  expect(result.find((r) => r.slotId === 'idle')?.motionRefKey).toBe('meshy:1');
+  expect(result.find((r) => r.slotId === 'move')?.motionRefKey).toBe('meshy:2');
+  expect(result.every((r) => r.autoMatched)).toBe(true);
+});
+
+test('autoMatchMotionMapping: unmatched slot gets null motionRefKey', () => {
+  const preset = findPreset('basic-character-v1')!;
+  const result = autoMatchMotionMapping(preset.slots, [
+    { motionRefKey: 'meshy:9', label: 'Totally_Unrelated_Clip' },
+  ]);
+  expect(result.find((r) => r.slotId === 'idle')?.motionRefKey).toBeNull();
+});
+
+test('autoMatchMotionMapping: MAP3 allows the same candidate to fill multiple slots', () => {
+  const slots = [
+    { slotId: 'idle', displayName: '待机', required: true, playbackMode: 'loop' as const, speed: 1, matchKeywords: ['generic'], rootMotion: 'preserve' as const },
+    { slotId: 'move', displayName: '移动', required: true, playbackMode: 'loop' as const, speed: 1, matchKeywords: ['generic'], rootMotion: 'remove_xz' as const },
+  ];
+  const result = autoMatchMotionMapping(slots, [{ motionRefKey: 'meshy:1', label: 'Generic_Clip' }]);
+  expect(result[0].motionRefKey).toBe('meshy:1');
+  expect(result[1].motionRefKey).toBe('meshy:1');
+});

package/shared/playable-profile.ts

@@ -0,0 +1,171 @@
+// Playable-character motion profile domain model (PLAN-2026-07-13 §4.1/§4.2,
+// ADR-0008). Four-layer model:
+//   built-in preset → game default profile → character override → motion mapping
+//
+// Storage (SSOT, PLAN §4.1 table):
+//   - presets: pure data, this file
+//   - game default profile: .forgeax/games/<slug>/.gen3d/playable-character-profile.json
+//   - character override + motion mapping: source character's own
+//     *.glb.gen3d-meta.json sidecar, under custom.playableOverride / custom.motionMapping
+//     (never the engine meta — MAP2)
+
+export type PlaybackMode = 'loop' | 'once' | 'freeze_frame';
+export type RootMotionStrategy = 'preserve' | 'remove_xz' | 'remove_xyz';
+
+export interface MotionSlotDef {
+  // Stable, code-facing id (PROF4). Display name may change freely.
+  slotId: string;
+  displayName: string;
+  required: boolean;
+  playbackMode: PlaybackMode;
+  speed: number;
+  matchKeywords: string[];
+  rootMotion: RootMotionStrategy;
+}
+
+export interface GameMotionProfile {
+  schemaVersion: 1;
+  profileId: string;
+  // Bumped on every structural save (PROF3 migration-review trigger for R10).
+  profileVersion: number;
+  displayName: string;
+  slots: MotionSlotDef[];
+  updatedAt: string;
+}
+
+export interface CharacterMotionOverride {
+  schemaVersion: 1;
+  // Full effective slot list for this character (PROF6: scoped to just this
+  // character, so this REPLACES the game default wholesale — never merged by
+  // slotId — else a slot the user deliberately dropped for this character
+  // would resurrect from the game default).
+  slots: MotionSlotDef[];
+  basedOnProfileId: string;
+  basedOnProfileVersion: number;
+  updatedAt: string;
+}
+
+export interface MotionMappingEntry {
+  slotId: string;
+  // motionRefKey() of the source clip filling this slot; null = unmapped.
+  motionRefKey: string | null;
+  // True until the user has reviewed/confirmed an auto-suggested mapping (MAP1).
+  autoMatched: boolean;
+}
+
+export interface MotionMappingDraft {
+  schemaVersion: 1;
+  mappings: MotionMappingEntry[];
+  confirmed: boolean;
+  updatedAt: string;
+}
+
+export interface ProfilePreset {
+  profileId: string;
+  displayName: string;
+  slots: MotionSlotDef[];
+}
+
+function slot(
+  slotId: string,
+  displayName: string,
+  required: boolean,
+  rootMotion: RootMotionStrategy,
+): MotionSlotDef {
+  return {
+    slotId,
+    displayName,
+    required,
+    playbackMode: 'loop',
+    speed: 1,
+    matchKeywords: [slotId],
+    rootMotion,
+  };
+}
+
+// PROF2: four built-in presets. blank-custom-v1 starts with zero slots; PROF5
+// requires the user add >=1 required slot before export (enforced at export
+// time, not here).
+export const BUILTIN_PROFILE_PRESETS: readonly ProfilePreset[] = [
+  {
+    profileId: 'basic-character-v1',
+    displayName: '基础角色',
+    slots: [slot('idle', '待机', true, 'preserve'), slot('move', '移动', true, 'remove_xz')],
+  },
+  {
+    profileId: 'action-adventure-v1',
+    displayName: '动作冒险',
+    slots: [
+      slot('idle', '待机', true, 'preserve'),
+      slot('move', '移动', true, 'remove_xz'),
+      slot('attack', '攻击', true, 'preserve'),
+      slot('hit', '受击', false, 'preserve'),
+      slot('death', '死亡', false, 'preserve'),
+    ],
+  },
+  {
+    profileId: 'platformer-v1',
+    displayName: '平台跳跃',
+    slots: [
+      slot('idle', '待机', true, 'preserve'),
+      slot('move', '移动', true, 'remove_xz'),
+      slot('jump', '跳跃', true, 'remove_xz'),
+      slot('fall', '下落', false, 'preserve'),
+      slot('land', '落地', false, 'preserve'),
+    ],
+  },
+  {
+    profileId: 'blank-custom-v1',
+    displayName: '空白自定义',
+    slots: [],
+  },
+] as const;
+
+export function findPreset(profileId: string): ProfilePreset | null {
+  return BUILTIN_PROFILE_PRESETS.find((p) => p.profileId === profileId) ?? null;
+}
+
+export function gameProfileFromPreset(profileId: string, now: string): GameMotionProfile {
+  const preset = findPreset(profileId) ?? BUILTIN_PROFILE_PRESETS[0];
+  return {
+    schemaVersion: 1,
+    profileId: preset.profileId,
+    profileVersion: 1,
+    displayName: preset.displayName,
+    slots: preset.slots.map((s) => ({ ...s, matchKeywords: [...s.matchKeywords] })),
+    updatedAt: now,
+  };
+}
+
+// Effective profile = game default (+) character override (PLAN §5.5). An
+// override present REPLACES the slot list wholesale (see CharacterMotionOverride
+// doc) rather than merging by slotId.
+export function effectiveSlots(
+  gameProfile: GameMotionProfile,
+  override: CharacterMotionOverride | null,
+): MotionSlotDef[] {
+  return override ? override.slots : gameProfile.slots;
+}
+
+export interface MotionCandidate {
+  motionRefKey: string;
+  label: string;
+}
+
+// MAP1: suggest a slot -> motion mapping by case-insensitive substring match of
+// a slot's keywords against each candidate's label. First unclaimed candidate
+// wins per slot, in slot order. MAP3 permits the same candidate to be suggested
+// for more than one slot (the user confirms/adjusts before saving).
+export function autoMatchMotionMapping(
+  slots: readonly MotionSlotDef[],
+  candidates: readonly MotionCandidate[],
+): MotionMappingEntry[] {
+  return slots.map((s) => {
+    const keywords = s.matchKeywords.map((k) => k.toLowerCase()).filter(Boolean);
+    const match = candidates.find((c) => {
+      const label = c.label.toLowerCase();
+      return keywords.some((k) => label.includes(k));
+    });
+    return { slotId: s.slotId, motionRefKey: match?.motionRefKey ?? null, autoMatched: true };
+  });
+}

package/shared/provider-params.test.ts

@@ -0,0 +1,172 @@
+import { test, expect } from 'bun:test';
+import {
+  applyRodinPromptFlags,
+  filterProviderParams,
+  providerParamSpec,
+  rodinSubdivisionLevelHelp,
+  RODIN_IMAGE_FLAG_STUB,
+  RODIN_PROMPT_CHAR_LIMIT,
+} from './provider-params';
+
+test('meshy text: keeps verified+applicable fields, drops unknown + deprecated', () => {
+  const out = filterProviderParams('meshy', 'text', {
+    ai_model: 'meshy-6',
+    topology: 'quad',
+    art_style: 'realistic', // deprecated → not in spec → dropped
+    bogus: 'x', // unknown → dropped
+  });
+  expect(out).toEqual({ ai_model: 'meshy-6', topology: 'quad' });
+});
+
+test('meshy model_type only applies to image mode', () => {
+  expect(filterProviderParams('meshy', 'text', { model_type: 'lowpoly' })).toEqual({});
+  expect(filterProviderParams('meshy', 'image', { model_type: 'lowpoly' })).toEqual({
+    model_type: 'lowpoly',
+  });
+});
+
+test('meshy image: smart-topology + t2 + hd_texture pass filter', () => {
+  expect(
+    filterProviderParams('meshy', 'image', {
+      model_type: 'smart-topology',
+      ai_model: 'meshy-t2',
+      hd_texture: true,
+    }),
+  ).toEqual({
+    model_type: 'smart-topology',
+    ai_model: 'meshy-t2',
+    hd_texture: true,
+  });
+});
+
+test('meshy P1 texture knobs pass filter for text/image', () => {
+  const knobs = {
+    texture_prompt: 'leather armor',
+    texture_image_url: 'https://example.com/tex.png',
+    remove_lighting: true,
+  };
+  expect(filterProviderParams('meshy', 'text', knobs)).toEqual(knobs);
+  expect(filterProviderParams('meshy', 'image', knobs)).toEqual(knobs);
+});
+
+test('enum rejects invalid values; bool rejects non-bool', () => {
+  expect(filterProviderParams('meshy', 'text', { ai_model: 'meshy-9' })).toEqual({});
+  expect(filterProviderParams('meshy', 'text', { should_remesh: 'yes' as unknown as boolean })).toEqual(
+    {},
+  );
+  expect(filterProviderParams('meshy', 'text', { should_remesh: true })).toEqual({
+    should_remesh: true,
+  });
+});
+
+test('rodin keeps official flag keys; drops old Hyper3D JSON knobs and quality_override', () => {
+  expect(providerParamSpec.rodin.some((f) => f.key === 'mesh_mode')).toBe(true);
+  expect(providerParamSpec.rodin.some((f) => f.key === 'quality_override')).toBe(false);
+  expect(filterProviderParams('rodin', 'text', { quality: 'high', tier: 'Gen-2', quality_override: 18000 })).toEqual(
+    {},
+  );
+  expect(
+    filterProviderParams('rodin', 'image', {
+      mesh_mode: 'Quad',
+      subdivisionlevel: 'medium',
+      material: 'PBR',
+      TAPose: true,
+      hd_texture: true,
+      addons: 'HighPack',
+      use_original_alpha: true,
+    }),
+  ).toEqual({
+    mesh_mode: 'Quad',
+    subdivisionlevel: 'medium',
+    material: 'PBR',
+    TAPose: true,
+    hd_texture: true,
+    addons: true,
+    use_original_alpha: true,
+  });
+  expect(filterProviderParams('rodin', 'text', { use_original_alpha: true })).toEqual({});
+  expect(filterProviderParams('rodin', 'views', { mesh_mode: 'Raw', use_original_alpha: true })).toEqual({
+    mesh_mode: 'Raw',
+    use_original_alpha: true,
+  });
+});
+
+test('rodinSubdivisionLevelHelp: short chips; numbers only after mesh', () => {
+  expect(providerParamSpec.rodin.find((f) => f.key === 'subdivisionlevel')?.options?.map((o) => o.label)).toEqual([
+    '高',
+    '中',
+    '低',
+  ]);
+  expect(rodinSubdivisionLevelHelp()).toMatch(/一般选中/);
+  expect(rodinSubdivisionLevelHelp('Quad')).toBe('大约 5万 / 1.8万 / 8千 面');
+  expect(rodinSubdivisionLevelHelp('Raw')).toBe('大约 50万 / 15万 / 2万 面');
+});
+
+test('applyRodinPromptFlags: unset omitted; image stub; sl not override; trim text', () => {
+  expect(applyRodinPromptFlags('a red fox', {}, 'text')).toBe('a red fox');
+  expect(applyRodinPromptFlags('a red fox', { mesh_mode: 'Quad', material: 'PBR' }, 'text')).toBe(
+    'a red fox --mesh_mode Quad --material PBR',
+  );
+  expect(applyRodinPromptFlags('', { mesh_mode: 'Raw' }, 'image')).toBe(
+    `${RODIN_IMAGE_FLAG_STUB} --mesh_mode Raw`,
+  );
+  expect(applyRodinPromptFlags('', {}, 'image')).toBe('');
+  expect(applyRodinPromptFlags('', { mesh_mode: 'Quad' }, 'views')).toBe(
+    `${RODIN_IMAGE_FLAG_STUB} --mesh_mode Quad`,
+  );
+  expect(applyRodinPromptFlags('fox', { subdivisionlevel: 'high' }, 'text')).toBe('fox --sl high');
+  expect(applyRodinPromptFlags('fox', { quality_override: 18000 }, 'text')).toBe('fox');
+  expect(applyRodinPromptFlags('fox', { TAPose: false, hd_texture: false }, 'text')).toBe('fox');
+  const long = 'x'.repeat(RODIN_PROMPT_CHAR_LIMIT);
+  const out = applyRodinPromptFlags(long, { mesh_mode: 'Quad' }, 'text');
+  expect(out.endsWith('--mesh_mode Quad')).toBe(true);
+  expect(out.length).toBeLessThanOrEqual(RODIN_PROMPT_CHAR_LIMIT);
+});
+
+test('hunyuan_workflow has no advanced params (empty spec → {})', () => {
+  expect(providerParamSpec.hunyuan_workflow).toEqual([]);
+  expect(filterProviderParams('hunyuan_workflow', 'text', { anything: 1 })).toEqual({});
+});
+
+test('undefined raw → {}', () => {
+  expect(filterProviderParams('meshy', 'text', undefined)).toEqual({});
+});
+
+test('visvise quality enum; mid is image-only; low is disabled', () => {
+  expect(filterProviderParams('visvise', 'text', { quality: 'standard' })).toEqual({ quality: 'standard' });
+  expect(filterProviderParams('visvise', 'text', { quality: 'low' })).toEqual({});
+  expect(filterProviderParams('visvise', 'text', { quality: 'high' })).toEqual({});
+  expect(filterProviderParams('visvise', 'image', { quality: 'mid' })).toEqual({ quality: 'mid' });
+  expect(filterProviderParams('visvise', 'views', { quality: 'standard' })).toEqual({});
+  expect(providerParamSpec.visvise.find((f) => f.key === 'quality')?.options?.find((o) => o.value === 'low')?.disabled).toBe(
+    true,
+  );
+});
+
+test('visvise extras pass filter; mid drops face_num and enable_pbr', () => {
+  expect(
+    filterProviderParams('visvise', 'image', {
+      quality: 'standard',
+      algorithm_model: ' hunyuan3D-3.5-0515 ',
+      enable_a_pose: true,
+      face_type: '2',
+      face_num: 20000,
+      enable_pbr: true,
+    }),
+  ).toEqual({
+    quality: 'standard',
+    algorithm_model: 'hunyuan3D-3.5-0515',
+    enable_a_pose: true,
+    face_type: '2',
+    face_num: 20000,
+    enable_pbr: true,
+  });
+  expect(
+    filterProviderParams('visvise', 'image', {
+      quality: 'mid',
+      face_num: 20000,
+      enable_pbr: true,
+      enable_a_pose: true,
+    }),
+  ).toEqual({ quality: 'mid', enable_a_pose: true });
+});