Support Rive 0.14.x

[dobean99]

What happened?

I have an issue when implement rive animation ver 0.14.x into flame engine game.
Can you help me!

What do you expect?

version to implement rive animation ver 0.14.x

How can we reproduce this?

No response

What steps should take to fix this?

No response

Do have an example of where the bug occurs?

No response

Relevant log output

Execute in a terminal and put output into the code block below

Output of: flutter doctor -v

Affected platforms

All

Other information

No response

Are you interested in working on a PR for this?

• I want to work on this

[spydon]

Rive 0.14.0 is still a pre-release in the flutter package, you can try doing a pubspec override with the pre-release version together with flame_rive and see if there are any breaking changes in the methods we are using.

[nhapham99]

Rive 0.14.0 has been released and includes many changes. Please check and update the flame_rive package.

[spydon]

If anyone is keen on tackling this ping me and I'll assign you to the issue.

[dovecheng]

2025-12-26.174911.mp4

I cloned the example code from the rive repository.
And added the flame dependency.
Then I created a new dart file to test rendering in the flutter way.

import 'dart:async';
import 'dart:developer';

import 'package:flame/components.dart';
import 'package:flame/events.dart';
import 'package:flutter/material.dart';
import 'package:flame/game.dart';
import 'package:rive/rive.dart';

Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await RiveNative.init();
  runApp(const GameApp());
}

class GameApp extends StatelessWidget {
  const GameApp({Key? key}) : super(key: key);

  @override
  Widget build(BuildContext context) {
    return const MaterialApp(
      home: GamePage(),
    );
  }
}

class GamePage extends StatelessWidget {
  const GamePage({Key? key}) : super(key: key);

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: const Text('Flame with Rive 0.14 Test'),
      ),
      body: GameWidget(game: MyGame()),
    );
  }
}

class MyGame extends FlameGame {
  MyGame()
      : super(

          camera: CameraComponent.withFixedResolution(width: 480, height: 640),
        );

  @override
  Future<void> onLoad() async {
    debugMode = true;
    camera.moveTo(size / 2);

    final file = await File.asset(
      // 'assets/rewards.riv',
      'assets/button.riv',
      riveFactory: Factory.flutter,
    );

    final controller = RiveWidgetController(file!);

    world.add(RiveComponent(
      controller: controller,
      size: Vector2(100, 100),
      position: Vector2(100, 100),
    ));

    world.add(
      FpsTextComponent()
        ..position.x = 16
        ..textRenderer = TextPaint(
          style: const TextStyle(color: Colors.red, fontSize: 14),
        ),
    );
  }

  @override
  Color backgroundColor() => Colors.transparent;
}

class RiveComponent extends PositionComponent with TapCallbacks {
  final RiveWidgetController controller;
  final RiveArtboardRenderer _renderer;
  late Size _renderSize;

  RiveComponent({
    required this.controller,
    BoxFit fit = BoxFit.contain,
    Alignment alignment = Alignment.center,

    // position component arguments
    super.position,

    /// The logical size of the component.
    /// Default value is ArtboardSize
    Vector2? size,
    super.scale,
    super.angle = 0.0,
    super.anchor,
    super.children,
    super.priority,
    super.key,
  })  : _renderer = RiveArtboardRenderer(
          controller: controller,
          fit: fit,
          alignment: alignment,
        ),
        super(
            size: size ??
                Vector2(
                  controller.artboard.bounds.width,
                  controller.artboard.bounds.height,
                )) {
    this.size.addListener(_updateRenderSize);
    _updateRenderSize();
  }

  @override
  Future<void> onLoad() async {
    await super.onLoad();
    controller.advance(0);
  }

  void _updateRenderSize() {
    _renderSize = size.toSize();
    _renderer.invalidateCache();
  }

  @override
  void render(Canvas canvas) {
    _renderer.render(canvas, _renderSize);
  }

  @override
  void update(double dt) {
    _renderer.advance(dt);
  }

  @override
  void onRemove() {
    controller.dispose();
    size.removeListener(_updateRenderSize);
    super.onRemove();
  }

  @override
  void onTapDown(TapDownEvent event) {
    final position =
        event.localPosition * ((controller.artboard.width) / width);
    final pointerDown = controller.stateMachine.pointerDown(
      Vec2D.fromOffset(position.toOffset()),
    );
    log('$pointerDown, $position, ${event.localPosition}');
  }
}

/// Rive Artboard 渲染器
///
/// 负责处理 Rive 动画的渲染逻辑，包括缩放、对齐和变换计算。
class RiveArtboardRenderer {
  /// Rive 控制器，用于管理 artboard 和 state machine
  final RiveWidgetController controller;

  /// 缓存的 artboard 尺寸，避免每帧重复计算
  Size? _cachedArtboardSize;

  /// 缓存的缩放值，使用 Vector2 以支持 BoxFit.fill 的分别缩放
  Vector2? _cachedScale;

  /// 缓存的偏移量，用于对齐计算
  Offset? _cachedOffset;

  /// 缓存的 Fit 值，用于判断是否需要重新计算
  Fit? _cachedFit;

  /// 缓存的 Alignment 值，用于判断是否需要重新计算
  Alignment? _cachedAlignment;

  /// 创建 RiveArtboardRenderer
  ///
  /// - [controller]: Rive 控制器
  /// - [fit]: 如何缩放 artboard 以适应渲染区域
  /// - [alignment]: artboard 在渲染区域中的对齐方式
  RiveArtboardRenderer({
    required this.controller,
    required BoxFit fit,
    required Alignment alignment,
  }) {
    // 设置 fit 和 alignment 到 controller
    controller.fit = _boxFitToFit(fit);
    controller.alignment = alignment;
  }

  /// 推进动画时间
  ///
  /// 调用 controller 的 advance 方法来更新动画状态。
  ///
  /// - [dt]: 自上一帧以来的时间差（秒）
  void advance(double dt) {
    controller.advance(dt);
  }

  /// 使缓存失效
  ///
  /// 清除所有缓存的计算结果，强制在下次渲染时重新计算。
  void invalidateCache() {
    // 清除缓存，强制重新计算
    _cachedArtboardSize = null;
    _cachedScale = null;
    _cachedOffset = null;
  }

  /// 将 Flutter 的 BoxFit 转换为 Rive 的 Fit
  ///
  /// - [boxFit]: Flutter 的 BoxFit 枚举值
  ///
  /// 返回对应的 Rive Fit 枚举值
  Fit _boxFitToFit(BoxFit boxFit) {
    switch (boxFit) {
      case BoxFit.fill:
        return Fit.fill;
      case BoxFit.contain:
        return Fit.contain;
      case BoxFit.cover:
        return Fit.cover;
      case BoxFit.fitWidth:
        return Fit.fitWidth;
      case BoxFit.fitHeight:
        return Fit.fitHeight;
      case BoxFit.none:
        return Fit.none;
      case BoxFit.scaleDown:
        return Fit.scaleDown;
    }
  }

  /// 计算缩放值
  ///
  /// 根据 artboard 尺寸、渲染尺寸和 fit 模式计算缩放值。
  /// 对于 BoxFit.fill，返回分别的 X 和 Y 缩放值；其他模式返回统一的缩放值。
  ///
  /// - [artboardSize]: artboard 的原始尺寸
  /// - [renderSize]: 渲染区域的尺寸
  /// - [fit]: 缩放模式
  ///
  /// 返回计算得到的缩放值（Vector2）
  Vector2 _calculateScale(Size artboardSize, Size renderSize, Fit fit) {
    if (artboardSize.width <= 0 || artboardSize.height <= 0) {
      return Vector2.all(1.0);
    }

    final scaleX = renderSize.width / artboardSize.width;
    final scaleY = renderSize.height / artboardSize.height;

    switch (fit) {
      case Fit.fill:
        // BoxFit.fill 需要分别处理 X 和 Y
        return Vector2(scaleX, scaleY);
      case Fit.contain:
        final minScale = scaleX < scaleY ? scaleX : scaleY;
        return Vector2.all(minScale);
      case Fit.cover:
        final maxScale = scaleX > scaleY ? scaleX : scaleY;
        return Vector2.all(maxScale);
      case Fit.fitWidth:
        return Vector2.all(scaleX);
      case Fit.fitHeight:
        return Vector2.all(scaleY);
      case Fit.none:
        return Vector2.all(1.0);
      case Fit.scaleDown:
        final minScale = scaleX < scaleY ? scaleX : scaleY;
        final finalScale = minScale < 1.0 ? minScale : 1.0;
        return Vector2.all(finalScale);
      case Fit.layout:
        return Vector2.all(1.0); // layout 模式使用原始尺寸
    }
  }

  /// 计算偏移量
  ///
  /// 根据 artboard 尺寸、渲染尺寸、缩放值和对齐方式计算偏移量。
  /// 用于将 artboard 定位到渲染区域中的正确位置。
  ///
  /// - [artboardSize]: artboard 的原始尺寸
  /// - [renderSize]: 渲染区域的尺寸
  /// - [scale]: 应用的缩放值
  /// - [alignment]: 对齐方式
  ///
  /// 返回计算得到的偏移量（Offset）
  Offset _calculateOffset(
      Size artboardSize, Size renderSize, Vector2 scale, Alignment alignment) {
    final scaledSize =
        Size(artboardSize.width * scale.x, artboardSize.height * scale.y);
    final dx = alignment.x * (renderSize.width - scaledSize.width) / 2;
    final dy = alignment.y * (renderSize.height - scaledSize.height) / 2;
    return Offset(dx, dy);
  }

  /// 计算 artboard bounds 的偏移
  ///
  /// 根据 artboard 的 bounds（可能不是从 (0,0) 开始）和对齐方式
  /// 计算需要应用的偏移量，以确保 artboard 正确居中和对齐。
  ///
  /// - [bounds]: artboard 的边界框（AABB）
  ///
  /// 返回计算得到的偏移量（Offset）
  Offset _calculateBoundsOffset(AABB bounds) {
    final contentWidth = bounds[2] - bounds[0];
    final contentHeight = bounds[3] - bounds[1];

    final x = -1 * bounds[0] -
        contentWidth / 2.0 -
        (controller.alignment.x * contentWidth / 2.0);
    final y = -1 * bounds[1] -
        contentHeight / 2.0 -
        (controller.alignment.y * contentHeight / 2.0);

    return Offset(x, y);
  }

  /// 渲染 artboard 到画布
  ///
  /// 执行完整的渲染流程：
  /// 1. 验证尺寸有效性
  /// 2. 检查 controller 是否激活
  /// 3. 计算变换（缩放、对齐、偏移）
  /// 4. 应用变换并绘制 artboard
  ///
  /// - [canvas]: 目标画布
  /// - [size]: 渲染区域的尺寸
  void render(Canvas canvas, Size size) {
    // 检查尺寸是否有效
    if (size.width <= 0 || size.height <= 0) {
      log('renderSize is invalid: $size');
      // 绘制一个占位符以便调试
      canvas.drawRect(
        Offset.zero & size,
        Paint()..color = Colors.red.withValues(alpha: 0.3),
      );
      return;
    }

    // 检查 controller 是否激活
    if (!controller.active) {
      return;
    }

    // 参考 rive_widget.dart: 使用 Renderer.make(canvas) 创建 renderer
    final renderer = Renderer.make(canvas);

    canvas.save();

    try {
      // 缓存计算结果，只在必要时重新计算
      final artboardBounds = controller.artboard.bounds;
      final artboardSize = Size(artboardBounds.width, artboardBounds.height);

      // 检查内容尺寸是否有效
      final contentWidth = artboardBounds[2] - artboardBounds[0];
      final contentHeight = artboardBounds[3] - artboardBounds[1];
      if (contentWidth == 0 || contentHeight == 0) {
        canvas.restore();
        renderer.dispose();
        return;
      }

      // 注意：在 rive 0.14 中，artboard.clip 可能不再直接支持
      // 如果需要裁剪，可以手动添加：canvas.clipRect(Offset.zero & size);

      // 检查是否需要重新计算（size、fit 或 alignment 改变时）
      final needsRecalculate = _cachedArtboardSize != artboardSize ||
          _cachedFit != controller.fit ||
          _cachedAlignment != controller.alignment ||
          _cachedScale == null ||
          _cachedOffset == null;

      if (needsRecalculate) {
        _cachedArtboardSize = artboardSize;
        _cachedFit = controller.fit;
        _cachedAlignment = controller.alignment;
        _cachedScale = _calculateScale(artboardSize, size, controller.fit);
        _cachedOffset = _calculateOffset(
            artboardSize, size, _cachedScale!, controller.alignment);
      }

      final scale = _cachedScale!;
      final boundsOffset = _calculateBoundsOffset(artboardBounds);

      // 应用变换（参考 rive_component.dart 的变换顺序）
      // 1. 平移到组件中心并应用 alignment
      final centerX =
          size.width / 2.0 + (controller.alignment.x * size.width / 2.0);
      final centerY =
          size.height / 2.0 + (controller.alignment.y * size.height / 2.0);

      renderer.save();
      renderer.translate(centerX, centerY);
      renderer.scale(scale.x, scale.y);
      renderer.translate(boundsOffset.dx, boundsOffset.dy);

      // 绘制 artboard
      controller.artboard.draw(renderer);
      renderer.restore();
    } catch (e, stackTrace) {
      // 只在开发模式下记录错误
      assert(() {
        log('Error in artboard.draw(): $e\n$stackTrace');
        return true;
      }());
      // 绘制错误指示器
      canvas.drawRect(
        Offset.zero & size,
        Paint()..color = Colors.orange.withValues(alpha: 0.5),
      );
    }

    canvas.restore();

    // 释放 renderer 资源
    renderer.dispose();
  }
}

[BI1EQZ-BLUEGG]

This code uses Rive 0.14.0 to adapt Flame's flame_rive. Note that it only supports Rive's Factory.flutter rendering.

https://github.com/BI1EQZ-BLUEGG/flame_rive_0140