simai_flutter 0.4.1

A Flutter package for parsing, converting, and rendering simai format charts. Supports chart visualization with Flame engine and audio synchronization.

simai_flutter

用于解析、转换、渲染和游玩 simai 谱面的 Flutter 软件包，基于 Flame 引擎。

A Flame-based Flutter package for parsing, converting, rendering, and playing simai charts.

特性 | Features

• 谱面解析：将 simai 字符串或 .txt 文件转换为结构化对象。
• 谱面预览：提供 Flame 渲染、音频同步和播放控制。
• 谱面游玩：支持多指输入、音符判定、AstroDX 计分及完整游玩流程。
• 自定义：支持调整背景、控制按钮和 UI 组件。
• 跨平台：支持 Android、iOS、Linux、macOS、Web 和 Windows。
• 视频导出：Android/iOS 可导出 720p 或 1080p、60fps 的竖版 MP4。

快速开始 | Getting started

安装 | Installation

在你的 pubspec.yaml 中添加：

dependencies:
  simai_flutter: ^0.4.0

或者运行：

flutter pub add simai_flutter

使用方法 | Usage

1. 解析谱面 | Parsing a Chart

import 'package:simai_flutter/simai_flutter.dart';

final chart = SimaiConvert.deserialize('(140){4}1,2,3,4,E');

final fileContent = '...'; // maidata.txt 内容
final simaiFile = SimaiFile(fileContent);
final masterChart = simaiFile.getValue('inote_4');
if (masterChart != null) {
  final master = SimaiConvert.deserialize(masterChart);
}

2. 使用播放器 | Using the Player

import 'package:flutter/material.dart';
import 'package:simai_flutter/simai_flutter.dart';

class ChartPlayerPage extends StatefulWidget {
  const ChartPlayerPage({super.key});

  @override
  State<ChartPlayerPage> createState() => _ChartPlayerPageState();
}

class _ChartPlayerPageState extends State<ChartPlayerPage> {
  late final SimaiPlayerController _controller;

  @override
  void initState() {
    super.initState();

    final chart = SimaiConvert.deserialize('(140){4}1,2,3,4,E');
    _controller = SimaiPlayerController(
      chart: chart,
      audioAsset: 'assets/music.mp3',
      backgroundImageProvider: const AssetImage('assets/bg.png'),
    )..title = 'Sample Chart';
  }

  @override
  Widget build(BuildContext context) {
    return SimaiPlayerPage(controller: _controller);
  }
}

播放器会自动提供谱面游玩入口。传入 gameplayController 可复用游玩状态；传入 videoExportMetadata 可启用视频导出入口。

SimaiPlayerPage(
  controller: playerController,
  gameplayController: gameplayController,
  videoExportMetadata: videoMetadata,
);

在宿主应用的 pubspec.yaml 中声明资源：

flutter:
  assets:
    - assets/music.mp3
    - assets/bg.png

audioAsset 用于 Flutter asset，audioFilePath 用于本地文件，两者不能同时设置。 SimaiPlayerPage 默认释放控制器；使用 disposeController: false 时需自行调用 dispose()。

3. 谱面游玩 | Gameplay

SimaiGameplayFlowPage 包含游玩设置、横屏游玩和结算页面。

late final SimaiGameplayController gameplayController;

@override
void initState() {
  super.initState();
  gameplayController = SimaiGameplayController(
    chart: chart,
    audioAsset: 'assets/music.mp3',
    backgroundImageProvider: const AssetImage('assets/bg.png'),
    title: 'Sample Chart',
    settings: const SimaiGameplaySettings(
      noteSpeed: 8,
      judgementDisplayMode: SimaiJudgementDisplayMode.twoB,
    ),
  );
}

@override
Widget build(BuildContext context) {
  return SimaiGameplayFlowPage(controller: gameplayController);
}

也可以单独使用 SimaiGameplaySetupPage、SimaiGameplayPage 和 SimaiGameplayResultPage，接入自定义路由与状态管理。

4. 导出竖版视频 | Export portrait MP4

Android 24+ 和 iOS 13+ 可使用系统硬件编码器导出 720p 或 1080p、60fps 的竖版 H.264/AAC MP4，并离线混合音乐与打击音。

final metadata = SimaiVideoMetadata.fromSimaiFile(
  simaiFile,
  coverImageProvider: const AssetImage('assets/bg.png'),
  difficulty: SimaiChartDifficulty.master,
);

final exporter = SimaiVideoExporter.instance;
final task = exporter.export(
  controller: controller,
  metadata: metadata,
  options: const SimaiVideoExportOptions(
    quality: SimaiVideoQuality.fullHd1080,
    hitSoundEnabled: true,
    showCornerInfo: false,
  ),
);

final result = await task.result;
debugPrint('MP4: ${result.path}');

// 保存或分享后会删除原始导出文件，请只选择一项。
await exporter.saveToGallery(result);
// await exporter.share(result, text: metadata.title);

传入 videoExportMetadata 后，播放器会提供包含设置、预览、进度和取消功能的导出页。 关闭页面不会停止任务，可通过 activeTask、activeTaskChanges 和 cancel() 管理任务。

注意：

• 单进程只能运行一个导出任务，重复调用会返回 busy。
• 相册权限由宿主应用申请；iOS 需配置 NSPhotoLibraryAddUsageDescription，Android 24–28 需申请 WRITE_EXTERNAL_STORAGE。
• saveToGallery 或 share 成功后会删除 result.path，二者只能选择一项。
• outputPath 可指定输出位置；取消或失败不会覆盖已有文件。
• 应用进入后台时会取消任务。其他平台的 isSupported 返回 false。

示例项目 | Example

查看 example 目录以获取完整的演示应用。

贡献 | Contributing

欢迎提交 Issue 或 Pull Request 来完善此项目。

许可证 | License

本项目采用 MIT 许可证。详见 LICENSE 文件。