simai_flutter

一个用于解析、转换和渲染 simai 格式谱面的 Flutter 软件包。使用 Flame 引擎进行渲染。

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

特性 | Features

• 解析与转换：支持将 simai 字符串解析为结构化的 MaiChart 对象。
• 谱面文件支持：使用 SimaiFile 轻松读取包含多个难度和元数据的 .txt 谱面文件。
• 高性能渲染：基于 Flame 引擎，提供平滑的 60fps+ 谱面预览。
• 音频同步：内置 SimaiPlayerController，支持音频播放与谱面时间的精确同步。
• 全平台支持：支持 Android、iOS、Linux、macOS、Web 和 Windows。
• 高度可定制：支持自定义背景、控制按钮和 UI 组件。

快速开始 | Getting started

安装 | Installation

在你的 pubspec.yaml 中添加：

dependencies:
  simai_flutter: ^0.3.0

或者运行：

flutter pub add simai_flutter

使用方法 | Usage

1. 解析谱面 | Parsing a Chart

import 'package:simai_flutter/simai_flutter.dart';

// 解析单个谱面字符串
String chartData = "(140){4}1,2,3,4,E";
MaiChart chart = SimaiConvert.deserialize(chartData);

// 或者从 simai 文件（maidata.txt）中解析
String fileContent = "..."; // 读取文件内容
SimaiFile simaiFile = SimaiFile(fileContent);
String? masterChart = simaiFile.getValue("inote_4");
if (masterChart != null) {
  MaiChart chart = 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);
  }
}

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

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

音乐播放统一使用 flutter_soloud。audioAsset 用于 Flutter asset；播放本地文件时， 将其替换为 audioFilePath: '/path/to/music.mp3'。两者不能同时设置。 SimaiPlayerPage 默认会在销毁时释放控制器；设置 disposeController: false 时， 需要由调用方执行 _controller.dispose()。当前支持 Android、iOS、Linux、macOS、Web 和 Windows。

示例项目 | Example

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

贡献 | Contributing

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

许可证 | License

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