feat(编辑器): 支持导入 GLB/GLTF 模型并驱动角色动画

- 新增 GLB/GLTF 模型加载与渲染,支持内嵌动画播放
- 通过 IndexedDB 持久化大体积模型二进制,规避 localStorage 限制
- 新增动作片段序列,时间轴可添加、编辑与编排多段动作
- 优化机位视角相机同步,修复角度修改不生效问题
- 扩展骨骼识别,兼容 Mixamo 前缀及 UE4 骨架
This commit is contained in:
tongtong committed 2026-09-18 18:23:13 +08:00
1 parent 9d3a5b9bea
commit 38dc27501a
36 files changed
+1899 -427

No files matched your search

+272 -6
View File
@@ -10,6 +10,7 @@ import type {
DirectorAssetRef,
DirectorAssetSource,
CharacterBodyType,
CharacterRigState,
DirectorAssetKind,
DirectorCameraCapture,
DirectorCameraShot,
@@ -19,6 +20,7 @@ import type {
DirectorTrajectoryPointRef,
DirectorTransform,
GeometryPrimitiveType,
MotionClip,
MotionKind,
PanoramaProjectionMode,
SceneSettings,
@@ -26,6 +28,7 @@ import type {
} from "../schema/directorProject";
import type { PosePresetId } from "../schema/poseSchema";
import { getDirectorObjectFocusTarget } from "../schema/cameraTarget";
import { deleteModelBinary, loadModelBinary } from "../loaders/modelBinaryStore";
import { DEFAULT_CHARACTER_BODY_TYPE, normalizeBodyType } from "../runtime/mannequin/bodyTypes";
import {
DEFAULT_DIRECTOR_CAMERA_VIEW_SNAPSHOT,
@@ -72,6 +75,8 @@ export interface ImportedAssetInput {
name: string;
fileName: string;
url: string;
/** GLB/GLTF 二进制在 IndexedDB 中的存储 id(可选,仅二进制模型有)。 */
binaryId?: string;
addToScene?: boolean;
assetSource?: DirectorAssetSource;
projectionMode?: PanoramaProjectionMode;
@@ -103,6 +108,8 @@ export interface DirectorUiState {
selectedCrowdId: string | null;
/** 当前选中的轨迹点(决定右侧显示「轨迹点」卡片) */
selectedTrajectoryPoint: DirectorTrajectoryPointRef | null;
/** 当前选中的动作片段 id(决定动作轨道上高亮哪段、右侧动作参数卡片编辑哪段) */
selectedMotionClipId: string | null;
/** 轨迹打点模式的目标角色 id;非空时画布不可选取其它对象,双击地面即落一个轨迹点 */
trajectoryPlacementObjectId: string | null;
directorInspectorMode: "auto" | "scene";
@@ -179,6 +186,20 @@ export interface DirectorActions {
setMotionClipTrimStart: (objectId: string, startTime: number) => void;
/** 设置动作片段的结束时间(拖动作条右端把手):动作播放到这一刻停止,起点不动 */
setMotionClipEnd: (objectId: string, endTime: number) => void;
/** 在动作轨道上添加一个动作片段(动作序列);默认从 options.start 开始、到时间轴末尾。 */
addMotionClip: (objectId: string, options?: { kind?: MotionKind; start?: number; end?: number }) => void;
/** 更新某个动作片段的属性(种类 / 速度 / 幅度 / 启用)。 */
updateMotionClip: (
objectId: string,
clipId: string,
patch: Partial<Pick<MotionClip, "kind" | "speed" | "amplitude" | "enabled">>
) => void;
/** 整体平移 / 缩放某个动作片段的时间区间(拖拽条本体或两端把手时写入)。 */
updateMotionClipTime: (objectId: string, clipId: string, start: number, end: number, oldStart?: number) => void;
/** 删除某个动作片段。 */
removeMotionClip: (objectId: string, clipId: string) => void;
/** 选中 / 取消选中某个动作片段;clipId 为 null 表示取消。 */
selectMotionClip: (clipId: string | null) => void;
removeTrajectoryPoint: (objectId: string, pointId: string) => void;
/** 选中某个轨迹点;传 null 表示取消选中(点到轨道空白处 / 面板其它地方时清掉轨迹关键帧的选中态) */
selectTrajectoryPoint: (objectId: string | null, pointId: string | null) => void;
@@ -195,7 +216,9 @@ export interface DirectorActions {
updateUniformScale: (id: string, scale: number) => void;
updateCrowdUniformScale: (crowdId: string, scale: number) => void;
addImportedAsset: (input: ImportedAssetInput) => void;
addObjectFromAsset: (assetId: string) => string | null;
/** 启动时把持久化的 GLB/GLTF 二进制从 IndexedDB 还原成 objectURL(localStorage 不存大文件)。 */
hydratePersistedModelBinaries: () => Promise<void>;
addObjectFromAsset: (assetId: string, options?: { asCharacter?: boolean }) => string | null;
addPresetCharacter: (bodyType?: CharacterBodyType) => void;
addCrowdCharacters: (input: CrowdCharactersInput) => string[];
addGeometryPrimitive: (geometryType: GeometryPrimitiveType) => void;
@@ -302,6 +325,7 @@ const DEFAULT_UI_STATE: DirectorUiState = {
selectedObjectIds: [],
selectedCrowdId: null,
selectedTrajectoryPoint: null,
selectedMotionClipId: null,
trajectoryPlacementObjectId: null,
directorInspectorMode: "auto",
transformMode: "translate",
@@ -356,7 +380,7 @@ function roundTransformTuple(values: [number, number, number]): [number, number,
return values.map((value) => roundTransformValue(value)) as [number, number, number];
}
function formatSceneItemName(prefix: "角色" | "机位", index: number) {
function formatSceneItemName(prefix: "角色" | "机位" | "导入角色", index: number) {
return `${prefix}${String(index).padStart(2, "0")}`;
}
@@ -433,7 +457,10 @@ function persistLocalModelAsset(asset: DirectorAssetRef) {
if (!isLocalModelLibraryAsset(asset)) return;
const persistedAssets = readPersistedLocalModelAssets().filter((item) => item.id !== asset.id);
writePersistedLocalModelAssets([...persistedAssets, asset]);
// GLB/GLTF 二进制走 IndexedDB:localStorage 只保留轻量元数据,url 置空避免 base64 撑爆配额。
// 运行时通过 hydratePersistedModelBinaries 用 binaryId 还原 objectURL。
const persisted: DirectorAssetRef = asset.binaryId ? { ...asset, url: "" } : asset;
writePersistedLocalModelAssets([...persistedAssets, persisted]);
}
function readPersistedTrajectoryPointRef(value: unknown): DirectorTrajectoryPointRef | null {
@@ -453,6 +480,8 @@ function readPersistedStringArray(value: unknown): string[] {
function removePersistedLocalModelAsset(assetId: string) {
writePersistedLocalModelAssets(readPersistedLocalModelAssets().filter((asset) => asset.id !== assetId));
// 一并清理 IndexedDB 中的二进制(GLB 有 binaryId 才需要;失败静默忽略)。
void deleteModelBinary(assetId).catch(() => {});
}
function isDirectorProjectShape(value: unknown): value is DirectorProject {
@@ -577,6 +606,37 @@ function migrateLegacyCameraKeyframeValue(value: {
};
}
/** 把旧工程的单一 motion 字段转换为动作片段数组(动作序列的基础)。群众成员保持单一 motion,不生成片段。 */
function legacyMotionToClips(rig: CharacterRigState | undefined, object: DirectorObject): MotionClip[] | undefined {
const motion = rig?.motion;
if (!motion || motion.kind === "none") return undefined;
return [
{
id: createKeyframeId(),
kind: motion.kind,
speed: motion.speed ?? 1,
amplitude: motion.amplitude ?? 1,
enabled: motion.enabled !== false,
start: Number.isFinite(object.motionStartTime) ? Math.max(object.motionStartTime ?? 0, 0) : 0,
end: Number.isFinite(object.motionEndTime) ? (object.motionEndTime ?? 0) : Number.POSITIVE_INFINITY,
},
];
}
/** 把角色的 motionClips 字段补齐(旧工程可能没有):已有片段则保留,否则从单一 motion 迁移。 */
function migrateCharacterMotionClips(object: DirectorObject): DirectorObject {
const rig = object.characterRig;
if (!rig) return object;
// 群众成员由 setCrowdMotion 统一驱动单一 motion,不生成片段,避免与群体动作冲突。
if (object.crowdId) {
return rig.motionClips && rig.motionClips.length
? object
: { ...object, characterRig: { ...rig, motionClips: undefined } };
}
const clips = rig.motionClips && rig.motionClips.length ? rig.motionClips : legacyMotionToClips(rig, object);
return { ...object, characterRig: { ...rig, motionClips: clips } };
}
function migrateDirectorProject(project: DirectorProject): DirectorProject {
const withTimelineProject = withSceneDefaults(withCameraLookRotations(withTimeline(project)));
return {
@@ -585,7 +645,9 @@ function migrateDirectorProject(project: DirectorProject): DirectorProject {
if (object.kind !== "character") return object;
const rig = object.characterRig;
if (rig?.rigType === "ue4-mannequin") return object;
if (rig?.rigType === "ue4-mannequin") {
return migrateCharacterMotionClips(object);
}
return {
...object,
@@ -593,6 +655,9 @@ function migrateDirectorProject(project: DirectorProject): DirectorProject {
rigType: "ue4-mannequin",
posePresetId: rig?.posePresetId ?? "stand",
controls: rig?.controls ?? {},
// 保留旧 motion 作为 fallback,并迁移成动作片段数组支持多段动作序列。
motion: rig?.motion,
motionClips: rig?.motionClips ?? legacyMotionToClips(rig, object),
},
};
}),
@@ -626,6 +691,7 @@ function extractPersistedDirectorState(state: DirectorRuntimeState): DirectorSta
selectedObjectIds: state.selectedObjectIds,
selectedCrowdId: state.selectedCrowdId,
selectedTrajectoryPoint: state.selectedTrajectoryPoint,
selectedMotionClipId: typeof state.selectedMotionClipId === "string" ? state.selectedMotionClipId : null,
trajectoryPlacementObjectId: state.trajectoryPlacementObjectId,
directorInspectorMode: state.directorInspectorMode,
transformMode: state.transformMode,
@@ -686,6 +752,7 @@ function readPersistedDirectorState(options: DirectorStateOptions = {}): Directo
: [],
selectedCrowdId: typeof state.selectedCrowdId === "string" ? state.selectedCrowdId : null,
selectedTrajectoryPoint: readPersistedTrajectoryPointRef(state.selectedTrajectoryPoint),
selectedMotionClipId: typeof state.selectedMotionClipId === "string" ? state.selectedMotionClipId : null,
trajectoryPlacementObjectId:
typeof state.trajectoryPlacementObjectId === "string" ? state.trajectoryPlacementObjectId : null,
directorInspectorMode: state.directorInspectorMode === "scene" ? "scene" : "auto",
@@ -983,6 +1050,37 @@ function createSceneObjectFromAsset(asset: DirectorAssetRef, existingObjects: Di
} satisfies DirectorObject;
}
/**
* 从导入的 GLB/GLTF 资产创建一个「人形角色」对象:几何来自资产 url,动作由通用人形骨骼映射驱动。
* 注意:不设置 assetRefId(否则会被当成道具渲染),而是把资产 id 放进 characterRig.modelAssetId。
*/
function createCharacterFromAsset(asset: DirectorAssetRef, existingObjects: DirectorObject[]) {
const characterCount = existingObjects.filter((item) => item.kind === "character").length;
const characterIndex = characterCount + 1;
const objectId = getNextSequentialId(
existingObjects.map((item) => item.id),
"char_imported_",
characterIndex
);
return {
id: objectId,
name: formatSceneItemName("导入角色", characterIndex),
kind: "character" as const,
visible: true,
locked: false,
transform: createTransform([0, 0, 0]),
characterRig: {
rigType: "custom-humanoid" as const,
posePresetId: "stand",
controls: {},
modelAssetId: asset.id,
motion: { kind: "walk", speed: 1, amplitude: 1, enabled: true },
},
color: getNextCharacterColor(existingObjects),
} satisfies DirectorObject;
}
function refreshCamerasFocusedOnObject(cameras: DirectorCameraShot[], object: DirectorObject) {
return cameras.map((camera) =>
camera.targetMode === "object" && camera.targetObjectId === object.id
@@ -1968,6 +2066,143 @@ export const useDirectorStore = create<DirectorStore>((set, get) => {
}),
},
})),
addMotionClip: (objectId, options) =>
commitMutation((state) => {
const duration = state.project.timeline.duration;
const start = Number.isFinite(options?.start) ? Math.max(options?.start ?? 0, 0) : 0;
const end = Number.isFinite(options?.end) ? (options?.end ?? Number.POSITIVE_INFINITY) : Number.POSITIVE_INFINITY;
const kind = options?.kind ?? "walk";
const newClip: MotionClip = {
id: createKeyframeId(),
kind,
speed: 1,
amplitude: 1,
enabled: true,
start,
end,
};
return {
...state,
selectedMotionClipId: newClip.id,
project: {
...state.project,
objects: updateObjectById(state.project.objects, objectId, (item) => {
if (!item.characterRig) return item;
const existing = item.characterRig.motionClips ?? [];
// 自动把紧邻的前一个「到末尾」片段截断到新片段起点,形成连续序列(后者胜)。
const nextClips = existing.map((clip) =>
clip.end === Number.POSITIVE_INFINITY && clip.start < start ? { ...clip, end: start } : clip
);
return {
...item,
characterRig: { ...item.characterRig, motionClips: [...nextClips, newClip] },
};
}),
},
};
}),
updateMotionClip: (objectId, clipId, patch) =>
commitMutation((state) => ({
...state,
project: {
...state.project,
objects: updateObjectById(state.project.objects, objectId, (item) => {
if (!item.characterRig?.motionClips) return item;
return {
...item,
characterRig: {
...item.characterRig,
motionClips: item.characterRig.motionClips.map((clip) =>
clip.id === clipId ? { ...clip, ...patch } : clip
),
},
};
}),
},
})),
updateMotionClipTime: (objectId, clipId, start, end, oldStart) =>
commitMutation((state) => {
const duration = state.project.timeline.duration;
// 先把起点限制在时间轴内,再保证终点不早于起点(避免拖出时间轴后区间倒挂)。
const clampedStart = Math.min(Math.max(start, 0), Math.max(duration - MOTION_CLIP_MIN_DURATION, 0));
const clampedEnd = Number.isFinite(end)
? Math.min(Math.max(end, clampedStart + MOTION_CLIP_MIN_DURATION), duration)
: Number.POSITIVE_INFINITY;
// 拖拽开始前的起点,用于判断拖动方向(右移 / 左移)。
const oldS = oldStart !== undefined && Number.isFinite(oldStart) ? Math.max(oldStart, 0) : null;
return {
...state,
project: {
...state.project,
objects: updateObjectById(state.project.objects, objectId, (item) => {
if (!item.characterRig?.motionClips) return item;
let clips = item.characterRig.motionClips.map((clip) =>
clip.id === clipId ? { ...clip, start: clampedStart, end: clampedEnd } : clip
);
// 拖动导致与另一片段重叠时,保证不重叠:把被压住的片段「推」到当前片段的另一侧贴边,
// 从而自然实现「交换位置」——把一段拖过另一段时,两者互换先后,且全程不重叠。
if (oldS !== null) {
const overlap = clips.find(
(c) => c.id !== clipId && c.start < clampedEnd && c.end > clampedStart
);
if (overlap) {
const overlapFinite = Number.isFinite(overlap.end);
const overlapLen = overlapFinite ? overlap.end - overlap.start : 0;
// 起点是否变化:整段平移 / 左端把手会动起点;仅右端把手(终点扩张)起点不动。
const startChanged = Math.abs(clampedStart - oldS) > 1e-6;
if (!startChanged) {
// 仅拖动右端把手(终点向右扩张):右侧重叠片段被挤到当前片段右侧。
const s = clampedEnd;
const e = overlapFinite
? Math.min(clampedEnd + overlapLen, duration)
: Number.POSITIVE_INFINITY;
clips = clips.map((c) => (c.id === overlap.id ? { ...c, start: s, end: e } : c));
} else if (clampedStart >= oldS) {
// 向右拖(整段或左端把手右移):重叠片段推到当前片段左侧(紧贴其左端)。
const s = overlapFinite ? Math.max(0, clampedStart - overlapLen) : 0;
const e = clampedStart;
clips = clips.map((c) => (c.id === overlap.id ? { ...c, start: s, end: e } : c));
} else {
// 向左拖:重叠片段推到当前片段右侧(紧贴其右端,必要时延伸到末尾)。
const s = clampedEnd;
const e = overlapFinite
? Math.min(clampedEnd + overlapLen, duration)
: Number.POSITIVE_INFINITY;
clips = clips.map((c) => (c.id === overlap.id ? { ...c, start: s, end: e } : c));
}
}
}
return {
...item,
characterRig: { ...item.characterRig, motionClips: clips },
};
}),
},
};
}),
removeMotionClip: (objectId, clipId) =>
commitMutation((state) => ({
...state,
selectedMotionClipId: state.selectedMotionClipId === clipId ? null : state.selectedMotionClipId,
project: {
...state.project,
objects: updateObjectById(state.project.objects, objectId, (item) => {
if (!item.characterRig?.motionClips) return item;
return {
...item,
characterRig: {
...item.characterRig,
motionClips: item.characterRig.motionClips.filter((clip) => clip.id !== clipId),
},
};
}),
},
})),
selectMotionClip: (clipId) =>
commitUiMutation((state) => ({
...state,
selectedMotionClipId: clipId,
})),
removeTrajectoryPoint: (objectId, pointId) =>
commitMutation((state) => ({
...state,
@@ -2270,6 +2505,7 @@ export const useDirectorStore = create<DirectorStore>((set, get) => {
fileName: input.fileName,
name: input.name,
url: input.url,
binaryId: input.binaryId,
assetSource: input.kind === "panorama" ? undefined : (input.assetSource ?? "local"),
projectionMode: input.projectionMode,
} satisfies DirectorAssetRef;
@@ -2316,14 +2552,44 @@ export const useDirectorStore = create<DirectorStore>((set, get) => {
},
};
}),
addObjectFromAsset: (assetId) => {
hydratePersistedModelBinaries: async () => {
const assets = get().project.assets;
const needsHydration = assets.filter((asset) => asset.binaryId && !asset.url);
if (!needsHydration.length) return;
await Promise.all(
needsHydration.map(async (asset) => {
try {
const blob = await loadModelBinary(asset.binaryId!);
if (!blob) return;
const url = URL.createObjectURL(blob);
commitMutation((state) => ({
...state,
project: {
...state.project,
assets: state.project.assets.map((item) => (item.id === asset.id ? { ...item, url } : item)),
},
}));
} catch {
// 单个还原失败不影响其余资产
}
})
);
},
addObjectFromAsset: (assetId, options) => {
let nextObjectId: string | null = null;
commitMutation((state) => {
const asset = state.project.assets.find((item) => item.id === assetId);
if (!asset || asset.sourceType !== "model" || asset.kind === "panorama") return state;
const nextObject = createSceneObjectFromAsset(asset, state.project.objects);
// 「作为角色导入」仅对 GLB/GLTF 等可识别人形的资产有意义(FBX/OBJ 忽略该选项)。
const asCharacter = options?.asCharacter === true && /\.(glb|gltf)$/i.test(asset.fileName);
const nextObject = asCharacter
? createCharacterFromAsset(asset, state.project.objects)
: createSceneObjectFromAsset(asset, state.project.objects);
nextObjectId = nextObject.id;
return {