pluviora 0.1.0

高性能 Flutter 平台 Milthm 铺面预览器。

Pluviora

高性能 Flutter 平台 Milthm 铺面预览器。

Pluviora 使用独立 C++20 核心解析并计算 Milthm 归档运行时铺面，Flutter 只负责音频主时钟、素材解码和 Canvas 绘制。首版支持 Android 与 iOS 自动预览，不包含触控判定、计分系统、Web、桌面端或 .milthm 文件。

文档：快速开始 · API 指南 · 架构与 ABI

输入文件

Pluviora 读取 milthm-archive-main 中的运行时产物，而不是 .milthm：

milthm-archive-main/
├── assets/Audio/*.ogg
└── code/chart/
    ├── json/*.json     # 必需
    └── js/*.js         # 可选、同名

• JSON 与音乐是必需输入。
• JS 只扫描字面量 n(line, ...) 调用，以恢复导出时丢失的音符全局顺序；不会执行 JavaScript。
• 曲绘支持 AVIF、PNG、JPEG 等格式。
• 自定义 Storyboard 图片通过 storyboardAssets 按铺面中的 data 名称提供；缺失素材会被跳过并返回警告。

解析核心覆盖 0–23 动画键、数值与节拍时间、全部 Milthm 缓动、Bezier、自定义采样、t/x/PI 表达式、颜色动画（含 OKLCH）、图片/文字三层 Storyboard 和四角变形。

快速开始

环境基线为 Flutter 3.38+、Dart 3.10.8+、Android API 24+、iOS 13+。

在 Flutter 项目中安装：

flutter pub add pluviora

或手动写入 pubspec.yaml：

dependencies:
  pluviora: ^0.1.0

引入包并创建播放器：

import 'package:pluviora/pluviora.dart';

final controller = PluvioraController();

final source = PluvioraSource.files(
  chart: '/path/code/chart/json/Cloudburst_La Fouldre.json',
  archiveJs: '/path/code/chart/js/Cloudburst_La Fouldre.js',
  music: '/path/assets/Audio/La Fouldre.ogg',
  illustration: '/path/illustration.avif',
  storyboardAssets: {
    'custom.png': '/path/custom.png',
  },
);

PluvioraPlayer(
  source: source,
  controller: controller,
  autoplay: true,
  onLoaded: (result) {
    print('${result.metadata.title}: ${result.metadata.noteCount} notes');
    for (final warning in result.warnings) {
      print(warning.message);
    }
  },
);

PluvioraPlayer 会自动初始化音频、以音乐播放位置为唯一时钟，并填满父组件提供的空间。请为它提供有界尺寸，例如放入 Expanded、SizedBox 或页面 body。

控制器支持播放、暂停、跳转、倍速、音乐/音效音量、音符缩放、换谱和释放：

await controller.pause();
await controller.seek(const Duration(seconds: 42));
await controller.setPlaybackRate(1.25);
await controller.setMusicVolume(0.8);
await controller.setSfxVolume(0.6);
await controller.setNoteScale(1.1);
await controller.reload(nextSource);

播放器加载完成前调用控制方法会抛出 StateError。可以通过 controller.loadState 或 onLoaded 判断是否就绪。页面销毁时释放自行创建的控制器：

@override
void dispose() {
  controller.dispose();
  super.dispose();
}

高级使用者可以绕过 Widget，直接创建多个独立的 PluvioraEngine，调用 load 与 render 获取原生零拷贝 PluvioraFrameView。帧缓冲区只保证存活到同一实例下一次渲染或释放。

文件选择、内存输入、错误处理和高级引擎示例见快速开始，完整类型说明见 API 指南。

示例应用

示例允许一次选择或分别指定 JSON、同名 JS、音乐、曲绘和 Storyboard 素材，并按同名 stem 自动配对：

cd example
flutter run

架构

归档 JSON + 可选 JS
        │
        ▼
C++20 / yyjson 0.12.0
解析、缓动、状态推进、裁剪、确定性粒子
        │ 每显示帧一次同步 FFI，ABI v1
        ▼
原生持有的动态绘制指令缓冲区
        │ 零整块复制
        ▼
CustomPainter + drawRawAtlas + drawVertices + Fragment Shader
        ▲
flutter_soloud 音乐位置（唯一主时钟）

与固定缓冲区或全局播放器实现不同，C ABI 使用独立句柄，可同时创建多个引擎；所有 C++ 异常在 ABI 边界转为状态码。Hold 粒子按当前时间窗和谱面 FNV-1a 64 位哈希即时生成，不会为长 Hold 预存数万粒子。原始高分辨率素材保留为源文件，运行时使用 223 KB 移动图集。

二进制指令格式和生命周期详见架构文档。

验证

flutter analyze
flutter test
dart pub publish --dry-run

归档批量测试：

clang++ -std=c++20 -O3 -DNDEBUG -Isrc -Isrc/third_party/yyjson \
  test/native/pluviora_archive_test.cpp src/pluviora.cpp \
  src/yyjson_bridge.cpp -o /tmp/pluviora_archive_test

/tmp/pluviora_archive_test /path/code/chart/json /path/code/chart/js

当前实现已在完整归档的 382 份 JSON、382 份 JS 上通过批量加载和抽帧测试；128 首音乐均验证为 48 kHz 双声道 Opus。

许可

代码采用 MIT License。第三方库与随包素材说明见第三方许可清单。