flame_splash_screen 使用指南为你的 Flame 游戏打造炫酷启动画面【免费下载链接】flameA Flutter based game engine.项目地址: https://gitcode.com/GitHub_Trending/fl/flameflame_splash_screen是 Flame 游戏引擎官方生态中的一款 Flutter 组件包它为游戏启动阶段提供一段带有火焰 Logo 展示的动画启动画面Splash Screen并支持完全自定义主题、前置/后置内容以及动画节奏控制。本文基于仓库中 packages/flame_splash_screen/README.md 展开并结合该包的源码实现splash.dart、controller.dart、theme.dart深入讲解每个配置项的真实行为读完本文你将能够在自己的 Flame 游戏中完整落地一套可定制、可控制时长的启动画面。一、包概况与安装flame_splash_screen的核心价值在于无需自己编写动画控制器与资源加载逻辑一个FlameSplashScreenWidget 即可呈现完整的 Logo 展示动画。从 pubspec.yaml 可以看到当前版本为0.3.13其依赖极轻——仅依赖flutterSDK 与meta包因此非常适合作为游戏首屏。安装时只需在项目的pubspec.yaml的dependencies中添加该包支持任意合法的 pub 依赖版本约束然后在 Dart 代码中导入import package:flame_splash_screen/flame_splash_screen.dart;需要注意当前仓库环境中该包要求 Dart SDK3.12.0 4.0.0、Flutter3.44.0见 pubspec.yaml请确认你的运行环境满足该前提。二、最简单用法两个必填参数FlameSplashScreen是一个 StatefulWidget使用它只需要两个必填参数参数类型说明onFinishValueChangedBuildContext所有动画步骤全部播放完毕后执行的回调通常在此跳转到游戏主界面themeFlameSplashTheme主题可直接使用内置的FlameSplashTheme.dark或FlameSplashTheme.white最小可用示例FlameSplashScreen( theme: FlameSplashTheme.dark, onFinish: (BuildContext context) Navigator.pushNamed(context, /your-game-initial-screen), );动画结束后onFinish会收到当前的BuildContext你可以借此执行页面跳转。从 splash.dart 的源码可以看到onFinish实际是在initState阶段通过controller.setup(steps.length, () widget.onFinish(context))注入到控制器中的控制器内部走完所有步骤后才会触发它。三、在 Logo 前后插入自定义内容启动画面本质上是一连串步骤的依次展示。从源码 splash.dart 的_computeSteps可以看到动画步骤队列的构成是steps [ if (widget.showBefore ! null) widget.showBefore!, // 前置内容可选 widget.theme.logoBuilder, // 火焰 Logo必有的核心步骤 if (widget.showAfter ! null) widget.showAfter!, // 后置内容可选 ];3.1 showBefore在火焰 Logo 之前展示FlameSplashScreen( theme: FlameSplashTheme.dark, showBefore: (BuildContext context) { return Text(To be shown before flame animation); }, onFinish: (BuildContext context) Navigator.pushNamed(context, /your-game-initial-screen), );3.2 showAfter在火焰 Logo 之后展示FlameSplashScreen( theme: FlameSplashTheme.dark, showAfter: (BuildContext context) { return Text(To be shown after flame animation); }, onFinish: (BuildContext context) Navigator.pushNamed(context, /your-game-initial-screen), );两个参数都是WidgetBuilder?类型返回值可以是任意 Widget——比如你自己的游戏 Logo、版本号、版权信息或加载中提示。也可以同时指定showBefore与showAfter此时启动画面会依次播放前置内容 → 火焰 Logo → 后置内容 → 触发onFinish。FlameSplashScreenState.didUpdateWidgetsplash.dart还支持在动画尚未开始时动态更新这两块内容并重新开始播放。四、主题定制从内置暗/亮主题到完全自定义4.1 内置主题默认主题为深色背景FlameSplashTheme.dark适合深色系游戏切换为FlameSplashTheme.white即可获得白色背景适合浅色系应用FlameSplashScreen( theme: FlameSplashTheme.white, onFinish: (BuildContext context) Navigator.pushNamed(context, /your-game-initial-screen), );从 theme.dart 可以看到两个内置主题的真实定义darkbackgroundDecoration为BoxDecoration(color: Color(0xFF000000))即纯黑背景whitebackgroundDecoration为BoxDecoration(color: Color(0xFFFFFFFF))即纯白背景两者共用同一个默认logoBuilder由_logoBuilder构建的三层火焰 Logo 动画与constraints: BoxConstraints.expand()。这些默认值同样在 theme_test.dart 中有单元测试逐一断言可作为事实依据。4.2 自定义主题FlameSplashTheme的构造方法接收三个字段字段类型默认值作用backgroundDecorationBoxDecoration必填无位于 Logo 之下的背景装饰可设置背景色、渐变、图片等logoBuilderWidgetBuilder必填无构建主步骤Logo 的 lambda可替换成你自己的品牌 LogoconstraintsBoxConstraintsBoxConstraints.expand()外层容器约束默认铺满可用空间自定义示例更换 Logo 并设置渐变背景FlameSplashScreen( theme: FlameSplashTheme( backgroundDecoration: const BoxDecoration( gradient: LinearGradient( colors: [Color(0xFF1A237E), Color(0xFF4A148C)], ), ), logoBuilder: (BuildContext context) Image.asset(assets/my_logo.png), ), onFinish: (BuildContext context) Navigator.pushNamed(context, /your-game-initial-screen), );backgroundDecoration是标准BoxDecoration因此支持颜色、渐变、边框、阴影、背景图等全部能力logoBuilder返回的 Widget 会成为动画主步骤同样经历淡入 → 停留 → 淡出的完整动画周期。五、Controller 高级用法掌控时长与启动时机默认情况下动画在 Widget 挂载后立即自动开始。如果希望手动控制启动时机或精细调节每一段动画的时长就需要使用FlameSplashController。它允许将FlameSplashScreen的动画节奏定制化——控制器应存活与 Widget 状态相同的生命周期。5.1 控制器参数FlameSplashController构造方法controller.dart提供了 4 个参数参数默认值说明fadeInDurationDuration(milliseconds: 750)每个步骤的淡入显示时长waitDurationDuration(seconds: 2)每个步骤淡入完成后的停留时长fadeOutDurationDuration(milliseconds: 450)每个步骤的淡出隐藏时长autoStarttrue是否在 Widget 挂载后自动开始播放设为false后可手动调用start()从源码可以看到三段时长会被封装进FlameSplashDurationscontroller.dart并提供totalgetter三段时间之和。每个步骤动画__SplashScreenStepState.startAnimation见 splash.dart的执行流程为fadeInDuration内透明度从 0 淡入到 1 →waitDuration停留 →fadeOutDuration内淡出随后控制器在等待一个total周期后进入下一步骤controller.dart直至最后一个步骤结束触发onFinish。5.2 完整示例手动控制 前后内容 生命周期管理class SplashScreenGameState extends StateSplashScreenGame { FlameSplashController controller; override void initState() { super.initState(); controller FlameSplashController( fadeInDuration: Duration(seconds: 1), fadeOutDuration: Duration(milliseconds: 250), waitDuration: Duration(seconds: 2), autoStart: false, ); } override void dispose() { controller.dispose(); // dispose it when necessary super.dispose(); } override Widget build(BuildContext context) { return Scaffold( body: FlameSplashScreen( showBefore: (BuildContext context) { return Text(Before the logo); }, showAfter: (BuildContext context) { return Text(After the logo); }, theme: FlameSplashTheme.white, onFinish: (context) Navigator.pushNamed(context, /the-game-initial-screen), controller: controller, ), ); } }5.3 autoStart 与手动 start 的行为细节控制器内部维护一个三态状态机FlameSplashControllerStatecontroller.dartidle尚未开始但已就绪。若设置了autoStart该阶段会被跳过started已开始正在按步骤播放finished全部步骤播放完毕onFinish已触发。当autoStart: false时你可以通过controller.start()在任意时机启动动画例如等待某个资源加载完成、等待用户点击开始按钮后再播放。start()方法内部带assert校验controller.dart一是控制器必须已被某个FlameSplashScreenWidget 使用即已调用过setup二是不能重复启动——这些约束同样在 controller_test.dart 中通过throwsAssertionError断言验证。另外注意当autoStart: true时切勿再手动调用start()否则会触发断言失败。需要特别强调的是生命周期请务必在dispose()中调用controller.dispose()。值得注意的是如果你把 controller 作为参数传入 Widget外部控制模式FlameSplashScreenState自身不会替你 dispose 它见 splash.dart释放职责完全落在你的 State 上只有内部自建控制器时 Widget 才会自动释放。六、动画原理三层 Logo 与步骤动画的实现细节6.1 火焰 Logo 的三层结构默认 Logo 动画由AnimatedLogotheme.dart渲染它把三张 PNG 资源以Stack叠加assets/layer1.png底层火焰assets/layer2.png中间层其透明度绑定动画值随动画在 0~1 之间往复assets/layer3.png顶层火焰。中间层的透明度由LogoComposite的AnimationController周期 500ms驱动播放完成后自动反向、归零后再正向从而形成火焰跳动/呼吸的循环视觉效果。整个 Logo 通过_logoBuilder包在LayoutBuilderFractionalTranslation(Offset(0, -0.25))ConstrainedBox(Size(300, 300))中theme.dart即默认居中略偏上、最大 300×300 的展示区域。相关资源位于 packages/flame_splash_screen/assets/ 目录并已在 pubspec.yaml 中声明为 Flutter assets。6.2 步骤播放的驱动方式FlameSplashScreenState.buildsplash.dart通过ValueListenableBuilder监听controller.stepController一个ValueNotifierint当前步骤索引变化时重建对应的_SplashScreenStep每个步骤都是一个独立的 StatefulWidget自带AnimationController完成淡入 → 停留 → 淡出三阶段。因此每新增一个showBefore/showAfter步骤总播放时长就会增加一个完整的fadeIn wait fadeOut周期。6.3 控制器的时序推进FlameSplashController._tickStepcontroller.dart以递归 Future.delayed(durations.total)的方式推进步骤索引每等待一个total周期后判断是否已到最后一个步骤是则置为finished并调用onFinish否则进入下一步。这也解释了为什么每个步骤会完整走完三阶段动画后控制器才推进到下一个。七、完整落地示例仓库自带的示例应用位于 example/lib/main.dart它演示了启动画面到主界面的完整流转MyApp启动后进入SplashScreenGame其中FlameSplashScreen同时使用了showBefore、showAfter与FlameSplashTheme.dark动画结束后通过Navigator.pushReplacement替换为OtherScreen且支持Come again按钮再次进入启动画面——说明FlameSplashScreen可以被重复创建与展示每次挂载都会重新走一遍完整动画class SplashScreenGameState extends StateSplashScreenGame { override Widget build(BuildContext context) { return Scaffold( body: FlameSplashScreen( showBefore: (BuildContext context) { return const Text(Before logo); }, showAfter: (BuildContext context) { return const Text(After logo); }, theme: FlameSplashTheme.dark, onFinish: (context) Navigator.pushReplacementvoid, void( context, MaterialPageRoute(builder: (context) const OtherScreen()), ), ), ); } }八、测试保障与进阶提醒该包为关键行为提供了单元测试可作为你排查问题时的参考controller_test.dart覆盖autoStart开/关两种模式下控制器的启动校验未挂载不可 start、不可重复 start、状态迁移idle → started → finished以及步骤结束后onFinish的触发theme_test.dart断言white与dark两个内置主题的背景色与约束的精确取值。进阶使用提醒汇总总时长预估每个步骤的完整周期为fadeInDuration waitDuration fadeOutDuration默认750ms 2s 450ms约 3.2 秒三个步骤含前后内容总耗时约 9.6 秒设计游戏体验时请务必考量该累计时长生命周期纪律外部传入的 controller 必须由你负责dispose()自动启动与手动启动互斥autoStart: true时不要再调用start()跳转时机onFinish是所有步骤结束后的唯一钩子在此处进行Navigator跳转pushReplacement可避免用户按返回键回到启动画面版本前提当前仓库版本要求 Dart3.12.0、Flutter3.44.0升级运行环境时注意兼容。至此从安装、基础使用、内容定制、主题定制到控制器精细控制你已经掌握了flame_splash_screen的全部核心能力可以立刻为你的 Flame 游戏接上一段专业的品牌启动动画。【免费下载链接】flameA Flutter based game engine.项目地址: https://gitcode.com/GitHub_Trending/fl/flame创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考