Plugins + Scripts MFPButtDriver: MultiFunPlayer drive Person hip/butt bone movement

MFP Butt Driver​

MultiFunPlayer 6-Axis Bone Driver for VAM

Receive data via WebSocket (WS) or UDP from MultiFunPlayer, and drive character bone movement inside VAM. Compatible with funscript playback in MultiFunPlayer / OpenFunscripter.

Who this plugin is for​

1. OSR hardware users: Existing OSR VAM drivers rely on physical motion capture, which often results in repetitive or overly extreme movement. Hundreds of manually crafted openscript funscripts from community creators deliver smooth, comfortable and stimulating motion patterns. This plugin lets you play those funscripts inside MultiFunPlayer, stream motion data over WS/UDP, and animate your VAM character. MultiFunPlayer is one of the most feature-rich funscript players available. It accepts inputs from many upstream sources, so this driver works not only with openscripts but also streams from OpenFunscripter.
2. VAM scene creators: There is a similar existing plugin: JustADude.FunscriptPlayer. It requires predefined animation sets before use. I lack experience building custom animation profiles, so I implemented a Timeline-style interpolation method instead. No pre-built animation clips are required to generate movement.

Usage​

1. Select connection mode: WS or UDP
2. Set port (default: 18888)
3. Click Start server
4. Select target Person Atom
5. Assign Controller A (bottom) and Controller B (top)
6. Pause any other running animations (Timeline, AnimationPattern, etc.)
7. Click Play

Tips for setup: Motion output is heavily affected by your target controller bone choice and L0 principal‑axis orientation setting.

Click to expand...

Atom Triggers​

• Atom Stop/Start Trigger: Assign custom actions
• Triggers fire automatically when MFP Butt Driver starts / stops
• Example usage: Pause / unpause Timeline
• If you are unsure how to configure trigger actions, use VAM's built-in freeze options.

Limitations & Todo List​

1. Motion reconstruction quality needs further optimization.
   → Partially addressed in V3: Physics‑Link and Force drive modes deliver near‑ideal motion reconstruction results.
2. This plugin only drives hip/butt related bones by default. Hands, head and other limbs remain static, which can look unnatural. I have conceptual ideas for follow-limb motion linked to hip movement, but limited scene-making experience means results may not be satisfactory.
   → Partially addressed in V3/V4: The Natural Motion system generates subtle follow‑through secondary movements for head, shoulders, wrists and other limbs linked to main‑body motion.
3. Future idea: Extract and replace only hip motion from existing Timeline scenes. Keep original Timeline animation for head, arms and other parts while overlaying funscript-driven hip movement. I am unaware of existing plugins that implement this feature.
   → Completed in V3/V4 via the Auto Takeover Timeline feature.

----------------------------------------​

V2 Update

1. Reworked motion calculation logic. Previously rotation pivoted around the center of Controller A and B with symmetrical swing. Now Controller B serves as the fixed pivot, and Controller A moves along an arc around B.
2. Added six gain parameters and an adaptive gain mechanism to offset weakened motion caused by joint pulling effects.
3. Added new Spring mode. This brings 12 extra adjustable parameters. Parameter templates will be implemented later after suitable configurations are determined.
4. Optimized debug visualization, referenced the display style from ToySerialController.
5. Various UI improvements to help users understand plugin workflow more easily, along with new automation features.

------------------------------------------------
V4 Update (Version V3 was taken down accidentally due to included executable files; updates from both versions have been merged into this release.)

1. Referencing the BusDriver plugin, two additional drive modes have been added, including the Physics Link mode. Its behavior is similar to the rope‑driven solution from the early MFPButtDriver, with greatly improved stability.
2. Simplified bone configuration; only a single controlled joint is required.
3. Ported the Origin Box visual origin feature from the BusDriver plugin, allowing the motion reference position to be displayed intuitively.
4. Added customizable setting for the L0 principal‑axis orientation.
5. Natural Motion system: Inspired by CLS (CompleteLocomotionSystemRemake), it generates subtle follow‑through movements for hips, chest, head, shoulders and wrists based on main‑body motion for more lifelike and natural animations.
6. Video player control, supporting play/pause, forward/rewind, seek‑to‑position, and script preview rendering (PlayerBridge.exe must be running beforehand).
7. Added the Auto Takeover Timeline feature. It can automatically take over the Timeline animation of the specified Controller, enabling script‑driven main motion while preserving head, hand and shoulder movements.

Note: VAM's MVRScript blocks P/Invoke and external‑process creation. This feature relies on a bridge program to enable interaction between players. You can build PlayerBridge.exe by compiling PlayerBridge\PlayerBridge.cc from the archive, or download the pre‑built binary from GitHub: https://github.com/nbnb9527/nb-VaMTools/releases/tag/v1.0

--------中文版说明------​

接收 MultiFunPlayer 通过 WS/UDP 传输的数据，驱动 VAM 人物骨骼运动，支持 MultiFunPlayer、OpenFunscripter 播放 Funscript 脚本。

适用人群​

1. OSR 设备使用者现有的 OSR 驱动插件基于实体设备动作捕捉，动作容易单调重复或是幅度过激。社区大量精心制作的 openscript 脚本拥有自然舒适的律动。本插件实现通过 MultiFunPlayer 播放脚本，网络传输数据驱动 VAM 人物。MFP 生态丰富，上游来源不限于 openscript，OpenFunscripter 输出同样兼容。
2. VAM 场景制作者Hub 已有同类插件 JustADude.FunscriptPlayer，但它需要预先配置动画模板。本人缺少动画制作经验，因此采用类似 Timeline 插值方案，无需预先制作动画片段即可生成动作。

使用流程​

1. 选择连接模式：WS 或 UDP
2. 设置端口（默认 18888）
3. 点击 Start server
4. 选择人物 Person Atom
5. 指定 Controller A（底部）、Controller B（顶部）
6. 暂停其他正在运行的动画（Timeline、AnimationPattern 等）
7. 点击 Play

设置建议​

控制器骨骼选择与L0 主轴方向配置直接影响最终效果：

• 大幅度动作（舞蹈类）：选用髋部相关骨骼，调整 L0 主轴方向适配动作。
• 小幅舒缓动作（性行为）：选用髋 / 骨盆骨骼，微调各轴运动幅度参数。

原子触发器​

• Atom Stop/Start Trigger：绑定自定义动作
• 插件启动 / 停止时自动触发
• 参考用法：暂停、恢复原子的Timeline
• 不熟悉触发器配置时，可以直接使用 VAM 原生内置冻结功能。

当前局限 & 计划​

1. 动作插值还原效果有待优化
   → V3/V4版本已部分改善：Physics‑Link（物理链接）与Force（力）模式已经可以达到接近理想的动作还原效果。
2. 当前仅驱动髋 / 臀部骨骼，头、手等肢体保持静止，观感违和。已有跟随联动思路，但缺乏场景制作经验，难以保证效果。
   → V3/V4版本已部分改善：Natural Motion自然运动系统，可以根据主体动作生成头部、肩膀、手腕等部位的次级跟随微动。
3. 远期设想：分离 Timeline 场景局部动画，仅替换臀部动作为脚本驱动，保留头部、手部原有 Timeline 动画，暂未发现现成插件实现该功能。
   → V3/V4版本通过 Auto Takeover Timeline 功能完成实现。

-------------------------------------------------------
V2 更新

1. 重构动作计算逻辑，旧版本围绕 Controller A、B 中心点对称摆动，新版本以 Controller B 作为旋转枢轴，Controller A 围绕 B 进行圆弧摆动。
2. 新增 6 个增益参数与自适应增益机制，弥补关节牵引造成的动作幅度衰减。
3. 新增 Spring 弹簧模式，该模式附带 12 个可调参数。后续找到合适配置方案后会推出参数模板。
4. 优化调试信息显示，参考了 ToySerialController 的界面展示方式。
5. 多处 UI 优化，帮助用户理解插件运行逻辑，同时增加自动化功能。

-------------------------------------------------------
V4 更新（V3版本因为不小心包含了exe文件被下架，这两个版本的更新融合在一起了）

1. 参考 BusDriver插件,新增两套驱动模式，增加 Physics Link 模式，效果和早期 MFPButtDriver 的绳驱动方案接近，稳定性大幅提升。
2. 简化骨骼配置，仅需要单个受控关节。
3. 移植BusDriver插件Origin Box 可视化原点功能，可以直观显示运动基准位置。
4. 增加 L0 主轴方向自定义设置。
5. Natural Motion 自然运动系统，参考 CLS（CompleteLocomotionSystemRemake）思路，让臀部、胸腔、头部、肩膀、手腕跟随主体动作产生细微联动，动画更加生动自然。
6. 视频播放器控制，支持播放 / 暂停、前后快进、进度跳转、脚本预览绘制（需要先运行PlayerBridge.exe）。
7. 增加了 Auto Takeover Timeline 功能，可自动接管指定 Controller 的 Timeline 动画，在保留头、手、肩动作的同时，实现脚本驱动主动作。

注意：VAM 的 MVRScript 禁止 P/Invoke 与外部进程创建，该功能依赖桥接程序实现播放器间的交互。你可以通过编译压缩包内 PlayerBridge\PlayerBridge.cc 得到 PlayerBridge.exe，也可以到 github 上下载预编译的版本 https://github.com/nbnb9527/nb-VaMTools/releases/tag/v1.0