[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-80709":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":10,"language":11,"languages":10,"totalLinesOfCode":10,"stars":12,"forks":13,"watchers":14,"openIssues":15,"contributorsCount":15,"subscribersCount":15,"size":15,"stars1d":15,"stars7d":16,"stars30d":17,"stars90d":15,"forks30d":15,"starsTrendScore":15,"compositeScore":18,"rankGlobal":10,"rankLanguage":10,"license":19,"archived":20,"fork":20,"defaultBranch":21,"hasWiki":22,"hasPages":20,"topics":23,"createdAt":10,"pushedAt":10,"updatedAt":24,"readmeContent":25,"aiSummary":26,"trendingCount":15,"starSnapshotCount":15,"syncStatus":13,"lastSyncTime":27,"discoverSource":28},80709,"MikuMikuPhysics","chris0214\u002FMikuMikuPhysics","chris0214","适用于Blender4.2+版本的MMD实时物理模拟插件","",null,"Python",49,2,44,0,3,5,1.43,"GNU General Public License v3.0",false,"main",true,[],"2026-06-12 02:04:05","# MikuMikuPhysics 2.2\n\n> 本插件使用 GPT-5.5 辅助编写、调试与文档整理。\n\nMikuMikuPhysics 是一个 Blender 4.2+ 插件，用于直接模拟由 mmd_tools 导入的 PMX\u002FMMD 模型刚体物理。插件通过外部 `pmx_bullet.dll` 使用 Bullet 2.82 r2704，不依赖 Blender 内置 Bullet，目标是尽量接近 MMD 与 PMXEditor TransformView 的物理行为。\n\n- 项目地址：\u003Chttps:\u002F\u002Fgithub.com\u002Fchris0214\u002FMikuMikuPhysics>\n- 作者 \u002F 维护者：克里斯提亚娜\n- 插件类型：Blender Add-on \u002F Extension\n- 许可证：GPL-3.0-or-later\n- 插件包名：`MikuMikuPhysics`\n\n## 主要功能\n\n- 直接读取 mmd_tools 导入后的 PMX 模型根对象、骨架、刚体、关节、碰撞组与骨骼绑定。\n- 使用外部 Bullet 2.82 native DLL 进行物理解算。\n- 实时 Timer 物理预览，不依赖 Blender 时间线播放。\n- 时间线模式，支持按帧检查物理结果与 VMD 动作。\n- 物理结果烘焙为 Blender 骨骼关键帧。\n- 多模型预览：独立世界、影子碰撞、完全共享世界。\n- 彩色半透明刚体 \u002F 关节调试可视化。\n- 性能统计面板，显示 Bullet、读回、骨骼写回与 depsgraph 刷新耗时。\n- 高速拖动保护（Fast Drag Protection），减少拖动模型时的滞后和穿模。\n- 姿态模式交互作用域（Interaction Scope），拖动手臂等骨骼时，头发 \u002F 裙摆等无关物理不受影响，行为接近 MMD 本体。\n- 针对头发、裙摆、尾巴、链条等结构的名称规则参数。\n\n## 安装\n\n推荐把 `MikuMikuPhysics` 文件夹作为 Blender 插件安装。目录结构如下：\n\n```text\nMikuMikuPhysics\u002F\n  __init__.py\n  blender_manifest.toml\n  config.py\n  localization.py\n  native\u002F\n  operators\u002F\n  panels\u002F\n  physics\u002F\n```\n\n安装方式：\n\n1. 打开 Blender 4.2 或更新版本。\n2. 进入 `Edit > Preferences > Add-ons`。\n3. 点击 `Install...`，选择打包好的 zip，或把 `MikuMikuPhysics` 文件夹放入 Blender 插件目录。\n4. 启用 `MikuMikuPhysics`。\n5. 在 3D View 右侧 Sidebar 中打开 `MMP` 面板。\n\n传统插件目录示例：\n\n```text\n%APPDATA%\\Blender Foundation\\Blender\\4.2\\scripts\\addons\\MikuMikuPhysics\n```\n\n## 使用前准备\n\n本插件不负责导入 PMX 模型。请先安装并启用 mmd_tools，然后：\n\n1. 使用 mmd_tools 导入 PMX 模型。\n2. 确认模型在 Outliner 中包含 `armature`、`rigidbodies`、`joints` 等对象。\n3. 如需导入动作，可以先用 mmd_tools 导入 VMD，也可以使用本插件面板中的 `Import VMD Motion` 调用 mmd_tools。\n\n注意：\n\n- 开始模拟时，插件会临时停用 Blender 内置 rigid body world，避免双重物理。\n- 插件会临时静音 mmd_tools 的物理跟随约束（`mmd_tools_rigid_track`），停止或重置后会恢复。\n- 如果刚体 \u002F 关节没有由 mmd_tools 正确创建，插件会提示 `Selected model has no mmd_tools rigid bodies`。\n\n## 快速开始\n\n### 实时预览\n\n1. 选择 PMX 模型根对象，或选择模型下任意对象。\n2. 点击 `Use Active Model`。\n3. 点击 `Scan Model` 检查刚体、关节、碰撞数据。\n4. 选择质量预设：\n   - `Preview`：低配视口预览，速度优先。\n   - `Default`：默认平衡档。\n   - `Mid`：默认 MMD 风格档（120 Hz × 8 substeps），推荐。\n   - `Hard`：更强约束、更多子步，适合复杂链条。\n5. 点击 `Start` 开始实时模拟。\n6. 点击 `Stop` 停止。\n7. 点击 `Reset` 恢复开始模拟前捕获的状态。\n\n实时模式使用 Blender Timer，不依赖时间线播放。时间线停止时，物理仍可继续运行。\n\n### 姿态模式拖动（接近 MMD 本体）\n\n打开 `Interaction Response`（推荐 `Immediate`）后：\n\n- 在姿态模式选中需要操作的骨骼（如左肩 \u002F 左腕）。\n- 拖动该骨骼时，只有手臂方向的物理跟手；头发、裙摆等无关物理不会被父链矩阵传染而抖动。\n- 松开后头发 \u002F 裙摆从当前姿态自然恢复摆动。\n- 整个过程中，所有动力学刚体仍在持续模拟，不会被冻结。\n\n如需打开作用域调试，勾选 `Show Interaction Debug`，在面板下查看 `interaction_debug_scope` 当前的骨骼集合。\n\n### 时间线模式\n\n勾选 `Timeline Mode` 后，插件按 Blender 帧变化进行模拟。适合：\n\n- 按帧检查物理结果。\n- 与 VMD 动作一起检查指定帧效果。\n- 烘焙前做确定性测试。\n\n实时预览和时间线模式不要同时混用。切换模式前建议先停止模拟并重置。\n\n### 多模型\n\n`Multi Model Mode` 控制 `Start All` 的行为：\n\n- `Independent Worlds`：每个模型一个独立 Bullet 世界，最稳定，模型之间不碰撞。\n- `Root Isolated`：独立世界兼容模式。\n- `Shadow Collision`：默认推荐的多模型碰撞模式。每个模型保留自己的 Bullet 世界，其他模型作为运动学影子碰撞体插入，能够互相碰撞且避免远距离动态岛互相拖拽。\n- `Full Shared World`：实验模式。所有模型进入同一个动态 Bullet 世界，物理耦合最强，也最容易相互带动。\n\n建议：\n\n- 多角色但不需要碰撞：`Independent Worlds`。\n- 需要角色之间碰撞：`Shadow Collision`（默认）。\n- `Full Shared World` 主要用于调试和对比。\n\n### 烘焙\n\n1. 设置 `Start` 和 `End`。\n2. 设置 `Preroll`，让物理在写关键帧前先稳定。\n3. 根据需要勾选 `Restore After Bake`。\n4. 点击 `Bake`。\n\n烘焙会把动态物理骨骼结果写入 Blender 骨骼关键帧。烘焙完成后，可以关闭实时物理并直接播放 Blender 动画。\n\n## 参数建议\n\n### Bullet 设置\n\n- `Fixed Step`：默认 `120 Hz`（接近 MMD 本体）。可选 `60 Hz` \u002F `90 Hz` \u002F `240 Hz`。数值越高越精细，也越慢。\n- `Max Substeps`：默认 8。每次 Timer tick 最多补多少个物理步；提高可减少掉步，但会降低视口帧率。\n- `Solver Iterations`：约束求解迭代次数。提高可增强稳定性。\n- `Gravity \u002F Gravity Scale`：重力方向和倍率。\n- `Time Scale`：物理时间倍率。\n\n### 交互响应\n\n`Interaction Response` 控制姿态模式拖动时的实时响应行为：\n\n- `Off`：使用普通定时器步进。\n- `Balanced`：拖动后追加一次轻量响应步。\n- `Immediate`（推荐）：拖动后追加多次响应步并对作用域内的动态骨刚体执行 snap，几乎零延迟跟手。\n\n`Show Interaction Debug` 打开后可以查看：\n\n- `interaction_debug_kind`：当前判定的交互类型（`POSE` \u002F `TRANSFORM` \u002F `NONE`）。\n- `interaction_debug_scope`：当前作用域内的骨骼名。\n- `interaction_debug_static_bodies` \u002F `interaction_debug_dynamic_bodies`：作用域影响到的刚体名。\n\n### 高速拖动保护\n\n`Realtime Performance` 中的高速拖动选项用于减少拖动模型时的滞后和穿模：\n\n- `Fast Drag Protection`：总开关。\n- `Static Body Compensation`：静态 \u002F 运动学刚体拖动时拆分成更细物理段。\n- `Dynamic Bone Compensation`：动态骨刚体拖动时提高自适应分段。\n- `Max Drag Segments`：一次快速拖动最多拆成多少段。默认 32，可按性能提高到 48。\n- `Extreme Drag Resync`：拖动跳变过大时做一次物理重同步。\n- `Resync Threshold`：触发极限重同步的模型空间位移阈值。\n- `Clear Velocity On Resync`：重同步时清速度。更稳定，但惯性更弱。\n\n推荐默认：\n\n```text\nFast Drag Protection: On\nStatic Body Compensation: On\nDynamic Bone Compensation: On\nMax Drag Segments: 32\nExtreme Drag Resync: On\nResync Threshold: 0.5\nClear Velocity On Resync: Off\n```\n\n如果快速拖动仍明显穿模，可以把 `Max Drag Segments` 调到 48，或把 `Resync Threshold` 降到 0.25。\n\n### 性能优化\n\n如果视口帧率很低：\n\n- 质量预设切到 `Preview`。\n- 关闭 `Update Rigid Objects`。\n- 保持 `Skip Unchanged Bones` 开启。\n- 关闭调试可视化。\n- 降低 `Solver Iterations` 与 `Max Substeps`。\n- 多模型时优先使用 `Independent Worlds` 或 `Shadow Collision`。\n\n性能面板中常见瓶颈：\n\n- `Native Bullet` 高：物理解算本身重，降低子步、迭代或刚体数量。\n- `Apply Bones` 高：骨骼写回重，保持跳过未变骨骼开启。\n- `Depsgraph` 高：Blender 主线程刷新重，降低视口显示复杂度。\n- `Object Writes` 高：关闭 `Update Rigid Objects`。\n\n## 技术设计\n\n插件分为三层：\n\n1. Blender UI \u002F 控制层\n   - `config.py`\n   - `operators\u002FAddonOperators.py`\n   - `panels\u002FAddonPanels.py`\n\n2. Python 同步层\n   - `physics\u002Fpmx_data_reader.py`\n   - `physics\u002Fphysics_world.py`\n   - `physics\u002Fphysics_sync.py`\n   - `physics\u002Fbake.py`\n   - `physics\u002Fhybrid_physics_world.py`\n   - `physics\u002Fshadow_physics_world.py`\n   - `physics\u002Fshared_physics_world.py`\n\n3. Native Bullet 物理层\n   - `physics\u002Fbullet_native.py`\n   - `native\u002Fpmx_bullet_api.h`\n   - `native\u002Fpmx_bullet_api.cpp`\n   - `native\u002Fpmx_bullet.dll`\n\n数据流：\n\n```text\nmmd_tools PMX model\n  -> pmx_data_reader.read_model()\n  -> PmxModelData \u002F RigidBodyData \u002F JointData\n  -> ctypes bridge\n  -> native\u002Fpmx_bullet.dll (Bullet 2.82 r2704)\n  -> body transform readback\n  -> Pose Bone \u002F rigid object writeback\n  -> Blender viewport or baked keyframes\n```\n\n核心设计：\n\n- 独立物理引擎：不依赖 Blender 内置 Bullet。\n- 模型本地坐标：物理空间以 PMX 模型根对象为基准，模型在场景中移动 \u002F 旋转不会破坏解算。\n- 骨骼–物理双向同步：静态刚体每帧从骨骼获取位置，动态 \u002F 动态骨刚体从物理结果回写骨骼。\n- Temporal Kinematic 初始化：动态刚体初始化时先以 kinematic 状态对齐骨骼，再恢复 dynamic，减少初始爆炸。\n- Timer 实时预览：实时模式独立于 Blender 时间线播放。\n- 影子碰撞：多模型碰撞时参考 Babylon-MMD 的 shadow body 思路，减少远距离动态岛互相拖拽。\n- 交互作用域：姿态模式拖动时只让用户实际选中 \u002F 激活的骨骼进入作用域，drag protection 仅作用于该作用域，避免父链矩阵传染让无关动力学被牵动。\n\n## 已知限制\n\n- Blender Python 与 depsgraph 刷新存在主线程开销，实时手感无法完全等同 MMD 本体。\n- 高速拖动时，离散 Bullet 碰撞仍可能穿模；可通过高速拖动保护缓解。\n- 多模型烘焙和完全物理耦合仍属于后续计划。\n- `Full Shared World` 是实验模式，不建议作为默认生产流程。\n- 交互作用域依赖 Blender 当前选中 \u002F 激活的骨骼。如果在物体模式下拖整根骨架，作用域会回退到旧逻辑。\n\n## 参考与借物说明\n\n本项目实现过程中参考了以下项目或软件的行为、设计和公开代码结构。感谢这些项目的作者与维护者。\n\n- mmd_tools：参考其 PMX 模型数据组织、根对象查找、刚体 \u002F 关节归属、骨骼同步方式。本插件不直接包含 mmd_tools 源码。\n  - GitHub：\u003Chttps:\u002F\u002Fgithub.com\u002FMMD-Blender\u002Fblender_mmd_tools>\n  - 原始仓库：\u003Chttps:\u002F\u002Fgithub.com\u002Fpowroupi\u002Fblender_mmd_tools>\n- Babylon-MMD：参考其多物理世界、`worldId`、rigid body bundle、shadow body、Immediate \u002F Buffered 更新链路等设计。作者：noname0310。\n  - 作者 GitHub：\u003Chttps:\u002F\u002Fgithub.com\u002Fnoname0310>\n  - 项目 GitHub：\u003Chttps:\u002F\u002Fgithub.com\u002Fnoname0310\u002Fbabylon-mmd>\n- Saba：参考其 MMD\u002FPMX 运行时和 Bullet 物理处理思路。\n  - 作者 GitHub：\u003Chttps:\u002F\u002Fgithub.com\u002Fbenikabocha>\n  - 项目 GitHub：\u003Chttps:\u002F\u002Fgithub.com\u002Fbenikabocha\u002Fsaba>\n- MMD \u002F MikuMikuDance：作为目标物理行为参考。\n- PMXEditor \u002F TransformView：作为模型编辑器内实时物理解算行为参考。\n- MMD Bridge：参考其 MMD 本体物理与烘焙流程。\n- NexGiMa：参考其 PMX\u002FMMD 物理表现和参数风格。\n- MikuMikuDayo：参考其 MMD 模型与物理运行逻辑。\n- Bullet Physics：本插件 native 层使用 Bullet 2.82 r2704 进行物理解算。\n\n如开源发布，请同时保留本 README、`LICENSE`、`COPYING`，并遵守各参考项目自身许可证。本文中的\"参考\"表示行为和架构层面的兼容性研究，不表示这些项目为本插件背书。\n\n## 更新日志\n\n### 2.2.0\n\n- 修复姿态模式拖动手臂时头发 \u002F 裙摆等无关物理被牵动的问题。原因是单模型 `PhysicsWorld` 未暴露 `root` 属性，导致交互作用域链路在单模型路径下失效，回退到\"任意骨骼矩阵变化\"的全局判定，被父链传染的远端骨骼也被算进作用域并触发 drag protection。\n- 修复拖动手臂导致下游 STATIC 锚点（手肘 \u002F 手 \u002F 手指）滞后引发的\"骨骼炸开\"问题。所有 STATIC 刚体每帧都跟随当前骨骼矩阵，作用域只用于约束 drag protection。\n- 修复使用作用域时部分动力学刚体被冻结导致头发 \u002F 裙摆\"卡住\"的问题。作用域外的动力学保持自由模拟，整个流程接近 MMD 本体的\"拖一边、其他依然在跑\"。\n- 修复作用域为空集时所有 STATIC 被锁死的边界情况，例如选中 IK 控制骨等未绑刚体的骨骼。\n- `_iter_world_roots` 增加从 `world.model` \u002F `world.models` 派生 root 的兜底逻辑，避免后续新世界类未暴露 `root` 又再次出现作用域失效。\n- 默认 `Multi Model Mode` 由 `Root Isolated` 改为 `Shadow Collision`，开箱即获得多模型互相碰撞。\n- 默认 `Fixed Step` 由 `60 Hz` 改为 `120 Hz`，`Max Substeps` 由 `2` 改为 `8`，更接近 MMD 本体的精度，并改善大幅拖动时裙摆 \u002F 头发\"摆动变弱\"的现象。\n- 文档同步更新。\n\n### 2.1.0\n\n- 新增 `Apply All Debug Visuals`，可同时显示多模型列表中所有启用模型的彩色半透明刚体 \u002F 关节预览。\n- 新增 `Interaction Response` 交互即时响应模式，提供保守的 `Balanced` 选项，用于降低拖动模型或骨架时的实时物理滞后。\n\n### 2.0.0\n\n- 插件包名改为 `MikuMikuPhysics`，Blender N 面板标签缩写为 `MMP`。\n- 使用外部 Bullet 2.82 r2704 DLL 进行 PMX\u002FMMD 刚体与关节模拟。\n- 支持实时 Timer 物理预览、时间线模式、单步、停止、强制停止与重置。\n- 支持 mmd_tools PMX 刚体 \u002F 关节读取、VMD 导入入口和物理烘焙。\n- 支持多模型模拟：独立世界、影子碰撞、共享世界等模式。\n- 增加高速拖动保护、极限重同步、静态 \u002F 动态骨补偿等交互稳定化选项。\n- 增加彩色半透明物理调试可视化与性能统计面板。\n- 整理 README、GPL 许可证、参考项目与借物说明，作为首次公开版本。\n\n## 后续计划\n\n- 更完善的多模型碰撞烘焙。\n- 更细粒度的性能模式和视口降级策略。\n- 更完善的物理结果对比工具。\n- 把交互作用域的\"用户选中骨骼判定\"扩展到物体模式下的整骨架拖动。\n","MikuMikuPhysics 是一个适用于 Blender 4.2+ 版本的插件，用于实时模拟由 mmd_tools 导入的 PMX\u002FMMD 模型刚体物理。该插件通过外部 `pmx_bullet.dll` 使用 Bullet 2.82 r2704 进行物理解算，不依赖于 Blender 内置的 Bullet 引擎，旨在尽量接近 MMD 和 PMXEditor TransformView 的物理行为。其核心功能包括直接读取 PMX 模型的根对象、骨架、刚体和关节等信息，提供实时 Timer 物理预览和时间线模式支持，并能将物理结果烘焙为 Blender 骨骼关键帧。此外，它还具备多模型预览、彩色半透明刚体\u002F关节调试可视化以及性能统计面板等功能。MikuMikuPhysics 适合需要在 Blender 中进行高质量 MMD 模型物理模拟的场景，如动画制作、角色动作设计等。","2026-06-11 04:01:43","CREATED_QUERY"]