Plugins + Scripts FunTimeline: Funscript Timeline Driver for VaM

Scripts embedded within the plugin deliver more realistic OSR movements.



Drive character movements with real‑motion funscripts to avoid mechanical repetitive motions.

Overview​

FunTimeline loads funscript files and drives character bone motion through a lightweight timeline‑keyframe system within VaM. Funscripts are community‑made timed motion curves originally designed for interactive hardware. Unlike traditional Timeline animations baked into the scene, FunTimeline lets you build a motion timeline from funscripts with editable keyframes, smooth parameter interpolation, and automatic no‑action period skipping — all in real time.

Who this plugin is for​

1. VaM Scene Creators
   If you want to reuse community funscripts to drive character motion without authoring Timeline animations from scratch, FunTimeline provides a streamlined keyframe‑based timeline. Each keyframe stores drive parameters (axis range, direction, drive mode, etc.), and parameters are smoothly interpolated between keyframes. You can combine funscript‑driven motion with Timeline animations for hands, facial expressions and secondary body motion.
   
   
2. Users pursuing high‑quality visuals from funscript‑driven motion
   FunTimeline adopts a "one‑timeline‑per‑funscript" model. Load a funscript, configure keyframe motion parameters, select the target controller, and click play to achieve funscript‑driven scene generation.

Core Features​

• Import funscript files by click Load Funscript from Player
• Timeline‑keyframe system: add keyframes at any time position, each storing independent drive parameters (direction, axis range, drive mode, auto gain)
• Automatic no‑action period detection and skipping for cleaner playback
• Three physical drive modes: Physics Link / Force / Direct
• Six‑axis independent control: stroke, surge, sway, twist, roll, pitch
• Natural Motion secondary follow system: adds linked subtle movement for head, shoulders, chest, arms, hips and limbs
• Auto Takeover Timeline: automatically yields Timeline controller weight on play, restores on stop
• Without Video mode: run funscript‑driven motion without any video file
• Script Curve visualization: real‑time stroke curve display
• Built‑in OFS WebSocket output: forward multi‑axis funscript data to MultiFunPlayer
• Integrated audio extractor to export matched audio clips from source video
• All timeline configurations persist directly within your scene file

Usage Guide​

First run PlayerBridge.exe to enable linkage between the plugin and PotPlayer. Place AudioExtractor.exe into the custom directory (this file is unnecessary if you do not require audio extraction).
Note: Due to strict review policies for executable files on the Hub community, no EXE files are included within this plugin archive. Users may compile PlayerBridge.exe and AudioExtractor.exe themselves by building PlayerBridge\PlayerBridge.cs and AudioExtractor\AudioExtractor.cs contained in the archive. Pre‑compiled binaries are also available for download on GitHub: nb‑VaMTools

1. Load the plugin onto your character atom.
2. Open your script‑enabled video within PotPlayer.
3. Open the plugin UI and click Load Funscript from Player to load the funscript into the plugin.
4. Add keyframes at desired timeline positions and configure drive parameters for each keyframe.
5. Hit Play. The plugin will automatically take over Timeline control of the target controller, with motions driven by the funscript.

Other common settings:

‑ Target Controller: Body part driven by the script
‑ KF L0 Direction: Principal‑axis orientation. For example, set to Down for dance animations; set to Back for dual‑interactive combat‑style scenes.
‑ KF L0 ~ KF R2: Six‑axis range of motion per keyframe
‑ KF Auto Gain: Adaptive amplitude compensation for more consistent motion
‑ Natural Motion: Enables natural follow‑through movements for the head, shoulders and hands. This produces stochastic secondary motion. Disable this option if your scene already has pre‑configured head‑shoulder‑hand animations. It is recommended to enable it under frozen or static‑pose conditions.
‑ Auto Takeover Timeline: When enabled, automatically sets Timeline controller weight to 0 on play and restores to 1 on stop.
‑ Without Video: Run funscript‑driven motion independently without opening any video file.
‑ Debug: Toggle this on to diagnose motion‑related anomalies.

OSR driving modes:
‑ Plugin playback position is synced with PotPlayer, allowing PotPlayer to feed into MFP for OSR driving.
‑ The plugin can also drive OSR via the WS protocol: enable WS Output on the plugin side, and select OFS as the input source within MFP.

Save & Portability
All timeline parameters (keyframes, triggers, drive settings) are automatically saved with the scene file. Manual Save/Load to JSON is also supported for cross‑scene sharing. Audio extraction from video is supported, so you can publish your finished scenes.

Notes​

When using video files stored on network SMB/UNC shared paths: You may encounter compatibility issues in Video Sync preview mode and audio extraction. For audio extraction, it's recommended to copy the generated batch command and run it manually in CMD to avoid access failures.

---

中文版​

FunTimeline​

Funscript 时序动作驱动插件 for VaM

概述​

FunTimeline 在 VaM 内通过轻量级时间轴‑关键帧系统加载 Funscript 脚本并实时生成角色骨骼运动。Funscript 是社区创作者制作的时序运动曲线，最初为互动体感设备设计。不同于场景内预烘焙的 Timeline 动画，FunTimeline 允许你从 funscript 构建可编辑关键帧的时间轴，关键帧间参数平滑插值，无动作区间自动跳过 —— 全部实时完成。

适合人群​

1. VaM 场景制作者
   如果你想复用社区 funscript 驱动角色动作，而不必从零制作 Timeline 动画，FunTimeline 提供了精简的关键帧时间轴方案。每个关键帧存储驱动参数（方向、各轴幅度、驱动模式、自动增益等），参数在关键帧间平滑过渡。你可以将脚本驱动的主体动作，搭配 Timeline 制作的手部、表情、次要肢体动画叠加使用。
   
   
2. 追求Funscript高质量视觉的用户
   FunTimeline 采用 "一个时间轴 = 一个脚本" 模型。加载 funscript，设置关键帧动作参数，选择目标控制器，点击播放。实现Funscript驱动的场景生成。

核心功能​

‑ 载入 Funscript；点击Load Funscript from Player通过 PlayerBridge 与 PotPlayer 联动自动加载
‑ 时间轴‑关键帧系统：在任意时间点添加关键帧，每个关键帧独立存储驱动参数（方向、各轴幅度、驱动模式、自动增益）
‑ 自动检测并跳过无动作区间，播放更流畅
‑ 三种物理驱动模式：Physics Link / Force / Direct
‑ 六轴独立调节：前后行程、进退、左右摆动、扭转、俯仰、横滚
‑ Natural Motion 次级跟随系统：为头部、肩、胸、手臂、髋部等添加联动微动
‑ Auto Takeover Timeline：播放时自动让出 Timeline 控制器权重，停止时自动恢复
‑ Without Video 模式：无需视频文件即可运行脚本驱动动作
‑ Script Curve 可视化：实时脚本曲线显示
‑ 支持 OFS WebSocket 输出，可向 MultiFunPlayer 转发多轴脚本数据
‑ 内置音频提取工具，可从源视频导出匹配的音频片段
‑ 所有时间轴配置直接保存在场景文件内

使用流程​

先运行 PlayerBridge.exe，用来插件和 PotPlayer 联动。将 AudioExtractor.exe 放到 custom 目录（如果不做音频提取就不需要这个文件）。
注意：因为 hub 社区对 exe 文件的审查较严，本插件压缩包中不提供 exe 文件，用户可通过编译压缩包内 PlayerBridge\PlayerBridge.cs 和 AudioExtractor\AudioExtractor.cs 自行编译，也可以到 GitHub 上下载预编译的版本：nb‑VaMTools

1. 将插件加载到人物原子
2. PotPlayer 打开带脚本视频
3. 打开插件界面，点击 Load Funscript from Player 加载脚本
4. 在时间轴上添加关键帧，配置各关键帧的驱动参数
5. 点击 Play，自动接管 Timeline 对目标控制器的控制，由脚本驱动动作

其它常见设置：
‑ Target Controller：脚本驱动部位
‑ KF L0 Direction：主轴方向，比如舞蹈是下，双人战斗可能要换成后
‑ KF L0 ~ KF R2：各关键帧的六轴活动范围
‑ KF Auto Gain：自适应幅度补偿，使动作更一致
‑ Natural Motion：随驱动部位联动的头、肩、手的自然动作。因为只是随机运动，如果场景本身配置好头、肩、手动作的，不要设这个。如果是冻结、静止状态，推荐打开。
‑ Auto Takeover Timeline：启用后，播放时自动将 Timeline 控制器权重设为 0，停止时恢复为 1。
‑ Without Video：无需打开视频文件，独立运行脚本驱动动作。
‑ Debug：动作出现异常时可以打开看看是哪里出问题了。

OSR 驱动方式：

‑ 插件播放进度和 PotPlayer 实现了联动，可以让 PotPlayer 接入 MFP 驱动 OSR
‑ 插件也可以通过 WS 协议驱动 OSR，插件端勾选 WS Output，MFP 输入端选择 OFS
保存与可移植性
所有时间轴参数（关键帧、触发器、驱动设置）随场景文件自动保存。也支持手动 Save/Load 到 JSON 文件，方便跨场景共享。支持从视频提取音频，可以把你制作好的场景发布出去。

注意事项​

视频文件存放于局域网 SMB 网络共享路径时：在视频同步预览模式以及音频提取功能中可能出现兼容性问题。进行音频提取时，建议复制生成的批处理命令，手动粘贴至 CMD 中运行，防止访问失败。