feat: vmd-morph-c4d-tracks

Author: AiMiDi

dependency/libMMD

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-03-25

openspec/changes/archive/2026-03-25-vmd-morph-c4d-tracks/.openspec.yaml

@@ -0,0 +1,97 @@
+## Context
+
+当前 VMD 模式下表情动画的数据流是：
+
+```
+VMDFile::m_morphs → VMDAnimation::Add() → VMDMorphController (线性插值)
+    每帧 → VMDAnimation::Evaluate() → MMDMorph::SetWeight()
+         → PMXModel::UpdateMorphAnimation() → libMMD 内部处理
+         → MMDMeshManagerObject 从 libMMD 读 GetWeight() → 覆盖 Pose Morph Tag
+```
+
+- `MODEL_MORPH_GRP` 在 VMD 模式下被完全隐藏
+- `UpdateMorph()` 虽在所有模式下运行，但 mesh manager 的 VMD 路径会覆盖其效果
+- 用户无法在 C4D 时间线中查看或编辑表情关键帧
+
+代码中已有被注释掉的 `SetMeshMorphAnimation`（mmd_model_manager.cpp:1611-1649），使用 `CTrack`/`CKey` 在 `IMorph::m_strength_id` 上创建关键帧，是本次改造的直接参考。
+
+## Goals / Non-Goals
+
+**Goals:**
+- VMD 导入后，表情关键帧出现在 C4D 时间线中，用户可查看和编辑
+- 表情滑块在 VMD 模式下可见且实时反映动画值
+- Group/Flip morph 的传播语义与 MMD 原始行为一致（叠加而非覆写）
+- 清理 MeshManager 中不再使用的 VMD morph 数据结构
+- 未匹配的 morph 名称在导入报告中给出反馈
+
+**Non-Goals:**
+- 骨骼动画迁移到 C4D CTrack（留作第二步，涉及贝塞尔曲线转换）
+- Material/Impulse morph 的 UpdateMorph 实现（这两个当前为空实现，不在本次范围内）
+- 改动 libMMD 内部代码
+- 支持 VMD 导出时从 CTrack 读取表情数据（保持现有的 `VMDAnimation::Save` 路径）
+
+## Decisions
+
+### D1: CTrack 创建时机 — 在 LoadVMDMotion 中完成
+
+**选择**：在 `MMDModelManagerObject::LoadVMDMotion` 中，`VMDAnimation::Add` 完成后，遍历 `vmd_file.m_morphs` 直接创建 CTrack/CKey。
+
+**理由**：
+- `LoadVMDMotion` 已经持有 `vmd_file` 和完整的 `morph_name_` 映射
+- 一次性操作，不影响每帧性能
+- 注释代码 `SetMeshMorphAnimation` 正是这个模式
+
+**备选**：在 `RebuildRuntime` 中从 VMDAnimation 的 morph controller 提取数据。但这需要暴露 VMDAnimation 内部结构，增加 libMMD API 耦合。
+
+### D2: 保留 libMMD 的 VMDAnimation morph 评估
+
+**选择**：`VMDAnimation::Evaluate()` 仍然会设置所有 morph 权重（包括表情），不修改 libMMD。
+
+**理由**：
+- 骨骼 morph 的效果通过 `UpdateMorphAnimation()` 写入 `mmd_node_` 变换，`BoneTag` 在 VMD 模式下读取这些变换。如果移除 morph 评估，骨骼 morph 会失效。
+- libMMD 不需要改动，降低改造风险。
+- C4D 端的表情值和 libMMD 端的表情值会平行存在但互不干扰：mesh/UV morph 只看 C4D 路径（通过 `UpdateMorph → SetMorphStrength`），骨骼 morph 只看 libMMD 路径。
+
+### D3: Group/Flip Morph 叠加语义
+
+**选择**：将 `GroupMorph::UpdateMorph` 改为叠加（`SetStrength(node, GetStrength(node) + self * ratio)`），`FlipMorph::UpdateMorph` 类似。
+
+**理由**：
+- MMD 中 group morph 对子 morph 是叠加效果。如果 VMD 同时在 group morph 和其子 mesh morph 上都有关键帧，覆写会丢失子 morph 自身的关键帧值。
+- C4D 的 CTrack 会同时在 group morph 和子 morph 的 strength 参数上设置值，`UpdateMorph` 在 track 求值之后运行，必须是叠加才能正确合并。
+
+**注意**：`UpdateMorph` 的遍历顺序需要保证 group/flip morph 在其子 morph 的 `UpdateMorph` 之前执行。当前的 `morph_data_` 顺序（由 PMX 导入顺序决定）通常满足这个条件，因为 PMX 中 group/flip morph 通常排在引用的子 morph 之后。但在遍历时需要先处理 group/flip，再处理其余。实际上 PMX 中 group/flip morph 引用的是其他 morph 的 index，而 group/flip 本身可以在列表中任意位置。
+
+**具体实现**：分两轮遍历 — 第一轮只处理 group/flip morph（将叠加值写入子 morph），第二轮处理其余 morph（mesh/bone/UV 推送到 manager）。
+
+### D4: MeshManager VMD morph 数据结构清理
+
+**选择**：移除 `morph_manager_index_`、`mmd_morph_manager_` 成员、以及 `Execute` 中 `MESH_MODE_VMD` 的 morph 权重读取块。
+
+**理由**：
+- 这些结构仅用于从 libMMD 读取 morph 权重，改用 C4D 参数驱动后不再需要。
+- `SetMorphStrength(name, strength)` 通过名称查找 `mesh_morph_name_` 映射，功能完全覆盖。
+
+**保留**：`mesh_morph_name_`、`mesh_morph_data_`、`mesh_morph_mode_` 等结构仍然需要，它们是 Pose Morph Tag 的映射，与 VMD 无关。
+
+### D5: CKey 插值模式设为线性
+
+**选择**：创建 CKey 后显式设置为线性插值（`CINTERPOLATION_LINEAR`）。
+
+**理由**：C4D 默认使用样条插值，会在关键帧之间产生过冲。VMD 表情使用线性插值，必须匹配。
+
+### D6: VMD 模式下表情 UI 可见性策略
+
+**选择**：VMD 模式与 ANIM 模式使用相同的 UI 可见性逻辑 — 表情滑块可见，但隐藏"添加/删除/重命名"等编辑按钮。
+
+**理由**：
+- 用户需要能看到滑块来确认动画效果
+- 用户可以在时间线中修改关键帧，滑块应实时反映当前值
+- 不应允许在 VMD 模式下添加/删除 morph，避免与 VMD 动画数据不一致
+
+## Risks / Trade-offs
+
+- **[风险] CTrack 数量大**：复杂 VMD 可能有几十个 morph 关键帧通道。→ 缓解：C4D 时间线原生支持大量 CTrack，UI 上通过面板分类过滤。
+- **[风险] Group morph 遍历顺序**：如果 PMX 数据中 group morph 引用了排在其后的 morph，两轮遍历策略可以正确处理。→ 缓解：第一轮仅处理 group/flip，第二轮处理余下所有类型。
+- **[风险] 旧场景兼容性**：已保存的场景在 VMD 模式下没有 CTrack。→ 缓解：用户需要重新导入 VMD 文件；旧场景不会崩溃，只是表情不再自动播放。
+- **[权衡] libMMD 中 morph 评估冗余**：libMMD 仍然每帧评估所有 morph 权重，但 mesh/UV morph 结果不再使用。→ 这个开销很小（纯数值插值），且保障了骨骼 morph 的正确性。

openspec/changes/archive/2026-03-25-vmd-morph-c4d-tracks/design.md

@@ -0,0 +1,28 @@
+## Why
+
+当前 VMD 模式下，表情（morph）动画完全由 libMMD 内部驱动：`VMDAnimation::Evaluate()` 每帧计算权重 → `MMDMeshManagerObject` 从 libMMD 读取权重覆盖 Pose Morph → 整个 `MODEL_MORPH_GRP` UI 被隐藏。用户无法在 C4D 时间线中看到、编辑或微调表情关键帧，可调性极差。VMD 表情关键帧使用纯线性插值，与 C4D 的 CTrack/CKey 系统完全兼容，可以直接移植。
+
+## What Changes
+
+- **VMD 导入时创建 C4D 关键帧**：在 `LoadVMDMotion` 中遍历 `VMDFile::m_morphs`，通过 `morph_name_` 匹配到 `morph_data_[]`，在对应的 `m_strength_id` 上创建 CTrack/CKey（线性插值），将 VMD 表情数据直接映射到模型属性管理器 UI 的强度属性。
+- **取消 VMD 模式下表情组隐藏**：移除 `GetDDescription` 中对 `MODEL_MORPH_GRP` 的 `DESC_HIDE` 设置，使用户在 VMD 模式下也能看到和编辑表情滑块。非编辑模式下仅隐藏"添加"相关按钮。
+- **移除 MeshManager 的 VMD 表情覆盖路径**：移除 `MMDMeshManagerObject::Execute` 中 `MESH_MODE_VMD` 下从 libMMD 读取 morph 权重的逻辑，改为完全依赖 `UpdateMorph()` → `SetMorphStrength()` 已有路径。
+- **Group/Flip Morph 改为叠加语义**：将 `GroupMorph::UpdateMorph` 从覆写改为叠加（`+=`），`FlipMorph::UpdateMorph` 同理，与 libMMD/MMD 原始行为保持一致。
+- **清理 MeshManager 中 VMD morph 相关数据结构**：移除不再需要的 `morph_manager_index_`、`mmd_morph_manager_` 等 VMD 表情相关的数据结构和初始化逻辑。
+- **记录未匹配 morph 名称到导入日志**：导入 VMD 时，将无法匹配到模型 morph 的名称记录到 `not_find_morph_name_list`，在导入报告中给用户反馈。
+
+## Capabilities
+
+### New Capabilities
+- `morph-c4d-track-animation`：VMD 导入时将表情关键帧数据写入 C4D CTrack，支持时间线查看和编辑
+
+### Modified Capabilities
+- `object-morph-system`：Group/Flip morph 的 UpdateMorph 语义从覆写改为叠加；VMD 模式下不再隐藏表情 UI
+- `motion-vmd-motion`：VMD 导入流程增加 CTrack 关键帧创建；不再使用 libMMD 每帧输出表情权重驱动 mesh；增加未匹配 morph 的日志反馈
+
+## Impact
+
+- **源文件**：`mmd_model_manager.cpp/h`（导入逻辑、UI 隐藏）、`mmd_morph.cpp`（Group/Flip UpdateMorph 语义）、`mmd_mesh_manager.cpp/h`（VMD morph 路径移除、数据结构清理）
+- **依赖**：libMMD 内部 VMD morph 评估仍保留（骨骼 morph 效果依赖其 node 变换计算），不改动 libMMD
+- **兼容性**：已存在的 VMD 模式场景文件加载后需要重新导入 VMD 动画以获得 CTrack 关键帧；旧场景的 morph 滑块数据不会丢失
+- **API 变化**：`MMDMeshManagerObject` 移除 `morph_manager_index_`、`mmd_morph_manager_` 成员和相关方法

openspec/changes/archive/2026-03-25-vmd-morph-c4d-tracks/proposal.md

@@ -0,0 +1,34 @@
+## ADDED Requirements
+
+### Requirement: VMD morph animation playback mechanism
+
+In VMD mode, morph animation playback SHALL be driven by C4D's CTrack system instead of per-frame reads from libMMD's morph weight output. The `MMDMeshManagerObject` SHALL NOT read morph weights from `libmmd::MorphManager` during VMD mode execution. Instead, morph strength values come from C4D parameters (set by CTrack evaluation), and `UpdateMorph()` dispatches them to mesh/bone managers through existing paths (`SetMorphStrength`, bone morph hubs).
+
+#### Scenario: Mesh morph strength comes from CTrack in VMD mode
+- **WHEN** the model is in `MODEL_MODE_VMD` and a mesh morph has CTrack keyframes
+- **THEN** `MMDMeshManagerObject::Execute()` does NOT read morph weights from `mmd_morph_manager_`
+- **THEN** mesh morph strength is applied through `MeshMorph::UpdateMorph()` → `SetMorphStrength()` using the CTrack-driven parameter value
+
+#### Scenario: Bone morph still works via libMMD node transforms
+- **WHEN** the model is in `MODEL_MODE_VMD` and bone morphs exist
+- **THEN** libMMD's `VMDAnimation::Evaluate()` still sets bone morph weights internally
+- **THEN** `UpdateMorphAnimation()` applies bone morph effects to `mmd_node_` transforms
+- **THEN** `MMDBoneTag` reads correct transforms from `mmd_node_` including bone morph effects
+
+### Requirement: Remove VMD morph weight reading from MeshManager
+
+The `MMDMeshManagerObject` SHALL NOT maintain `morph_manager_index_` or `mmd_morph_manager_` members. The `MESH_MODE_VMD` morph weight reading loop in `Execute()` SHALL be removed.
+
+#### Scenario: MeshManager Execute in VMD mode
+- **WHEN** `MMDMeshManagerObject::Execute()` runs in `MESH_MODE_VMD`
+- **THEN** no morph weight reading from libMMD's `MorphManager` occurs
+- **THEN** morph strength is applied solely through the `SetMorphStrength()` path called by `UpdateMorph()`
+
+### Requirement: Report unmatched VMD morph names
+
+The VMD import pipeline SHALL record morph names from the VMD file that do not match any morph in the target model's `morph_name_` map, and include them in the import log report.
+
+#### Scenario: Import report includes unmatched morph names
+- **WHEN** a VMD file is imported and some morph names cannot be matched
+- **THEN** `LoadVmdMotionLog::not_find_morph_name_list` contains the unmatched morph names
+- **THEN** the import report dialog displays these names when `detail_report` is enabled

openspec/changes/archive/2026-03-25-vmd-morph-c4d-tracks/specs/motion-vmd-motion/spec.md

@@ -0,0 +1,50 @@
+## ADDED Requirements
+
+### Requirement: Group morph propagation to sub-morphs
+
+GroupMorph SHALL propagate its strength to sub-morphs using additive semantics. When `UpdateMorph` is called, each sub-morph's strength SHALL be incremented by `group_strength * sub_morph_weight`, rather than being overwritten.
+
+#### Scenario: Group morph adds to sub-morph strength
+- **WHEN** a GroupMorph has strength 0.8 and references sub-morph A with weight 0.5
+- **AND** sub-morph A already has strength 0.3 (from its own CTrack or manual setting)
+- **THEN** after `GroupMorph::UpdateMorph`, sub-morph A's strength becomes 0.3 + (0.8 * 0.5) = 0.7
+
+#### Scenario: Group morph with zero strength does not affect sub-morphs
+- **WHEN** a GroupMorph has strength 0.0
+- **THEN** sub-morph strengths remain unchanged after `GroupMorph::UpdateMorph`
+
+### Requirement: Flip morph propagation to sub-morphs
+
+FlipMorph SHALL propagate its activation to sub-morphs using additive semantics. When `UpdateMorph` is called and the flip morph's strength is >= 0.5, each sub-morph's strength SHALL be incremented by the sub-morph's defined weight. When strength < 0.5, sub-morphs SHALL not be modified.
+
+#### Scenario: Flip morph activated adds to sub-morph strength
+- **WHEN** a FlipMorph has strength 0.7 (>= 0.5) and references sub-morph B with weight 1.0
+- **AND** sub-morph B already has strength 0.2
+- **THEN** after `FlipMorph::UpdateMorph`, sub-morph B's strength becomes 0.2 + 1.0 = 1.2
+
+#### Scenario: Flip morph not activated leaves sub-morphs unchanged
+- **WHEN** a FlipMorph has strength 0.3 (< 0.5)
+- **THEN** sub-morph strengths remain unchanged after `FlipMorph::UpdateMorph`
+
+### Requirement: UpdateMorph execution order for compound morphs
+
+The system SHALL process Group and Flip morphs before Mesh, UV, Bone, Material, and Impulse morphs during the `UpdateMorph` loop, ensuring compound morph propagation is complete before leaf morphs push values to their respective managers.
+
+#### Scenario: Group morph propagates before mesh morph applies
+- **WHEN** `Execute()` runs the UpdateMorph loop
+- **THEN** all Group and Flip morphs have their `UpdateMorph` called first (propagating strength to sub-morphs)
+- **THEN** all other morph types have their `UpdateMorph` called second (pushing final strength values to mesh/bone managers)
+
+### Requirement: Morph UI visible in VMD mode
+
+The `MODEL_MORPH_GRP` group SHALL be visible in VMD mode, allowing users to see morph strength sliders. Add/delete/rename/editor buttons for morphs SHALL be hidden in VMD mode (same as non-edit mode behavior).
+
+#### Scenario: Morph sliders visible during VMD playback
+- **WHEN** the model is in `MODEL_MODE_VMD`
+- **THEN** the `MODEL_MORPH_GRP` group is visible in the attribute manager
+- **THEN** morph strength sliders display current animated values
+- **THEN** morph add-name inputs and add/delete/rename buttons are hidden
+
+#### Scenario: Morph sliders reflect CTrack animation values
+- **WHEN** the model is in `MODEL_MODE_VMD` and the timeline is playing
+- **THEN** morph strength sliders update in real-time to reflect CTrack keyframe interpolation

openspec/changes/archive/2026-03-25-vmd-morph-c4d-tracks/specs/object-morph-system/spec.md

@@ -0,0 +1,33 @@
+## 1. Group/Flip Morph 叠加语义改造
+
+- [x] 1.1 修改 `GroupMorph::UpdateMorph`（mmd_morph.cpp）：将 `SetStrength(node, GetStrength(node) * data.GetValue())` 改为叠加语义 `SetStrength(node, GetStrength(node) + self_strength * data.GetValue())`，先读取子 morph 当前值再加上 group 的贡献
+- [x] 1.2 修改 `FlipMorph::UpdateMorph`（mmd_morph.cpp）：将覆写改为叠加语义，当 `GetStrength >= 0.5` 时将 `data.GetValue()` 叠加到子 morph 当前强度上
+- [x] 1.3 修改 `MMDModelManagerObject::Execute` 中的 `UpdateMorph` 循环（mmd_model_manager.cpp:885-891）：分两轮遍历 — 第一轮只执行 Group/Flip 类型的 `UpdateMorph`（传播到子 morph），第二轮执行其余类型（Mesh/UV/Bone/Material/Impulse）
+
+## 2. VMD 导入时创建 CTrack 关键帧
+
+- [x] 2.1 在 `MMDModelManagerObject` 中实现 `SetMorphAnimation` 方法（参考注释代码 1611-1649 行），接受 morph 名称、帧号、权重，通过 `morph_name_` 查找 index → `morph_data_[index].GetStrengthDescID()` → 创建/复用 CTrack → 添加 CKey 并设置 `CINTERPOLATION_LINEAR`
+- [x] 2.2 在 `LoadVMDMotion` 中，`VMDAnimation::Add` 完成后，遍历 `vmd_file.m_morphs` 调用 `SetMorphAnimation`，将每个 morph 关键帧写入 CTrack
+- [x] 2.3 未匹配的 morph 名称收集到 `std::set` 或类似容器，导入完成后赋值给 `LoadVmdMotionLog::not_find_morph_name_list`
+
+## 3. 导入日志反馈
+
+- [x] 3.1 确认 `LoadVmdMotionLog::not_find_morph_name_list` 成员存在且类型合适，必要时调整或补充声明
+- [x] 3.2 在导入报告对话框中展示未匹配 morph 名称列表（当 `detail_report` 为 true 且列表非空时），参考已有的骨骼未匹配报告格式
+
+## 4. 取消 VMD 模式表情 UI 隐藏
+
+- [x] 4.1 修改 `MMDModelManagerObject::GetDDescription`（mmd_model_manager.cpp:2058-2062）：移除 `MODEL_MODE_VMD` 下对 `MODEL_MORPH_GRP` 的 `DESC_HIDE` 设置
+- [x] 4.2 将 VMD 模式的 morph UI 可见性逻辑与非编辑模式统一 — 隐藏添加/删除/重命名按钮，保留强度滑块可见
+
+## 5. 移除 MeshManager 的 VMD morph 覆盖路径
+
+- [x] 5.1 移除 `MMDMeshManagerObject::Execute` 中 `MESH_MODE_VMD && mmd_morph_manager_` 的 morph 权重读取块（mmd_mesh_manager.cpp:283-301）
+- [x] 5.2 移除 `mmd_morph_manager_` 成员变量及其赋值/初始化逻辑
+- [x] 5.3 移除 `morph_manager_index_` 成员变量及其在 `RefreshMeshMorphData` 等位置的构建逻辑
+- [x] 5.4 清理 `mmd_mesh_manager.h` 中对应的成员声明和相关 include
+
+## 6. 清理注释代码
+
+- [x] 6.1 移除 `SetMeshMorphAnimation` 的旧注释代码（mmd_model_manager.cpp:1611-1649），替换为新实现
+- [x] 6.2 移除 `SetModelControllerAnimation` 的旧注释代码（mmd_model_manager.cpp:1651+），如果不在本次范围内则保留但添加 TODO 注释