Size Effects

Size effects are used to change the size of a component over time. They can be used to make a component grow, shrink, or change its size in a specific direction. The size is specified as a Vector2 value, where x represents the width and y represents the height. The effects can be applied to any component that implements the SizeProvider interface, such as the PositionComponent. The difference between size effects and scale effects is that size only changes the size of the target component, while scale changes the “size” of all children too.

SizeEffect.by

This effect will change the size of the target component, relative to its current size. For example, if the target has size Vector2(100, 100), then after the following effect is applied and runs its course, the new size will be Vector2(120, 50):

size_by_effect.dart
 1import 'package:doc_flame_examples/ember.dart';
 2import 'package:flame/components.dart';
 3import 'package:flame/effects.dart';
 4import 'package:flame/game.dart';
 5
 6class SizeByEffectGame extends FlameGame {
 7  bool reset = false;
 8  @override
 9  Future<void> onLoad() async {
10    final ember = EmberPlayer(
11      position: size / 2,
12      size: Vector2(45, 40),
13      onTap: (ember) {
14        ember.add(
15          SizeEffect.by(
16            reset ? Vector2(-15, 30) : Vector2(15, -30),
17            EffectController(duration: 0.75),
18          ),
19        );
20        reset = !reset;
21      },
22    )..anchor = Anchor.center;
23
24    add(ember);
25  }
26}
final effect = SizeEffect.by(
   Vector2(-15, 30),
   EffectController(duration: 1),
);

The size of a PositionComponent cannot be negative. If an effect attempts to set the size to a negative value, the size will be clamped at zero.

Note that for this effect to work, the target component must implement the SizeProvider interface and take its size into account when rendering. Only few of the built-in components implement this API, but you can always make your own component work with size effects by adding implements SizeEffect to the class declaration.

An alternative to SizeEffect is the ScaleEffect, which works more generally and scales both the target component and its children.

SizeEffect.to

Changes the size of the target component to the specified size. Target size cannot be negative:

size_to_effect.dart
 1import 'package:doc_flame_examples/ember.dart';
 2import 'package:flame/components.dart';
 3import 'package:flame/effects.dart';
 4import 'package:flame/game.dart';
 5
 6class SizeToEffectGame extends FlameGame {
 7  bool reset = false;
 8  @override
 9  Future<void> onLoad() async {
10    final ember = EmberPlayer(
11      position: size / 2,
12      size: Vector2(45, 40),
13      onTap: (ember) {
14        ember.add(
15          SizeEffect.to(
16            reset ? Vector2(45, 40) : Vector2(90, 80),
17            EffectController(duration: 0.75),
18          ),
19        );
20        reset = !reset;
21      },
22    )..anchor = Anchor.center;
23
24    add(ember);
25  }
26}
final effect = SizeEffect.to(
  Vector2(90, 80),
  EffectController(duration: 1),
);