Decorators

Decorators are classes that can encapsulate certain visual effects and then apply those visual effects to a sequence of canvas drawing operations. Decorators are not Components, but they can be applied to components either manually or via the HasDecorator mixin. Likewise, decorators are not Effects, although they can be used to implement certain Effects.

There are a certain number of decorators available in Flame, and it is simple to add one’s own if necessary. We are planning to add shader-based decorators once Flutter fully supports them on the web.

Flame built-in decorators

PaintDecorator.blur

decorator_blur.dart

import 'package:doc_flame_examples/flower.dart';
import 'package:flame/game.dart';
import 'package:flame/rendering.dart';

class DecoratorBlurGame extends FlameGame {
  @override
  Future<void> onLoad() async {
    var step = 0;
    add(
      Flower(
        size: 100,
        position: canvasSize / 2,
        onTap: (flower) {
          final decorator = flower.decorator;
          step++;
          if (step == 1) {
            decorator.addLast(PaintDecorator.blur(3.0));
          } else if (step == 2) {
            decorator.replaceLast(PaintDecorator.blur(5.0));
          } else if (step == 3) {
            decorator.replaceLast(PaintDecorator.blur(0.0, 20.0));
          } else {
            decorator.replaceLast(null);
            step = 0;
          }
        },
      )..onTapUp(),
    );
  }
}

Code

This decorator applies a Gaussian blur to the underlying component. The amount of blur can be different in the X and Y direction, though this is not very common.

final decorator = PaintDecorator.blur(3.0);

Possible uses:

• soft shadows;

• “out-of-focus” objects in the distance or very close to the camera;

• motion blur effects;

• deemphasize/obscure content when showing a popup dialog;

• blurred vision when the character is drunk.

PaintDecorator.grayscale

decorator_grayscale.dart

import 'package:doc_flame_examples/flower.dart';
import 'package:flame/game.dart';
import 'package:flame/rendering.dart';

class DecoratorGrayscaleGame extends FlameGame {
  @override
  Future<void> onLoad() async {
    var step = 0;
    add(
      Flower(
        size: 100,
        position: canvasSize / 2,
        onTap: (flower) {
          final decorator = flower.decorator;
          step++;
          if (step == 1) {
            decorator.addLast(PaintDecorator.grayscale());
          } else if (step == 2) {
            decorator.replaceLast(PaintDecorator.grayscale(opacity: 0.5));
          } else if (step == 3) {
            decorator.replaceLast(PaintDecorator.grayscale(opacity: 0.2));
          } else if (step == 4) {
            decorator.replaceLast(PaintDecorator.grayscale(opacity: 0.1));
          } else {
            decorator.removeLast();
            step = 0;
          }
        },
      )..onTapUp(),
    );
  }
}

Code

This decorator converts the underlying image into the shades of grey, as if it was a black-and-white photograph. In addition, you can make the image semi-transparent to the desired level of opacity.

final decorator = PaintDecorator.grayscale(opacity: 0.5);

Possible uses:

• apply to an NPC to turn them into stone, or into a ghost!

• apply to a scene to indicate that it is a memory of the past;

• black-and-white photos.

PaintDecorator.tint

decorator_tint.dart

import 'dart:ui';

import 'package:doc_flame_examples/flower.dart';
import 'package:flame/game.dart';
import 'package:flame/rendering.dart';

class DecoratorTintGame extends FlameGame {
  @override
  Future<void> onLoad() async {
    var step = 0;
    add(
      Flower(
        size: 100,
        position: canvasSize / 2,
        onTap: (flower) {
          final decorator = flower.decorator;
          step++;
          if (step == 1) {
            decorator.addLast(PaintDecorator.tint(const Color(0x88FF0000)));
          } else if (step == 2) {
            decorator.replaceLast(PaintDecorator.tint(const Color(0x8800FF00)));
          } else if (step == 3) {
            decorator.replaceLast(PaintDecorator.tint(const Color(0x88000088)));
          } else if (step == 4) {
            decorator.replaceLast(PaintDecorator.tint(const Color(0x66FFFFFF)));
          } else if (step == 5) {
            decorator.replaceLast(PaintDecorator.tint(const Color(0xAA000000)));
          } else {
            decorator.removeLast();
            step = 0;
          }
        },
      )..onTapUp(),
    );
  }
}

Code

This decorator tints the underlying image with the specified color, as if watching it through a colored glass. It is recommended that the color used by this decorator was semi-transparent, so that you can see the details of the image below.

final decorator = PaintDecorator.tint(const Color(0xAAFF0000);

Possible uses:

• NPCs affected by certain types of magic;

• items/characters in the shadows can be tinted black;

• tint the scene red to show bloodlust, or that the character is low on health;

• tint green to show that the character is poisoned or sick;

• tint the scene deep blue during the night time;

Rotate3DDecorator

decorator_rotate3d.dart

import 'package:doc_flame_examples/flower.dart';
import 'package:flame/game.dart';
import 'package:flame/rendering.dart';

class DecoratorRotate3DGame extends FlameGame {
  @override
  Future<void> onLoad() async {
    var step = 0;
    final decorator = Rotate3DDecorator()
      ..center = Vector2.all(50)
      ..perspective = 0.01;
    add(
      Flower(
        size: 100,
        position: canvasSize / 2,
        decorator: decorator,
        onTap: (flower) {
          step++;
          if (step == 1) {
            decorator.angleY = -0.8;
          } else if (step == 2) {
            decorator.angleX = 1.0;
          } else if (step == 3) {
            decorator.angleZ = 0.2;
          } else if (step == 4) {
            decorator.angleX = 10;
          } else if (step == 5) {
            decorator.angleY = 2;
          } else {
            decorator
              ..angleX = 0
              ..angleY = 0
              ..angleZ = 0;
            step = 0;
          }
        },
      )..onTapUp(),
    );
  }
}

Code

This decorator applies a 3D rotation to the underlying component. You can specify the angles of the rotation, as well as the pivot point and the amount of perspective distortion to apply.

The decorator also supplies the isFlipped property, which allows you to determine whether the component is currently being viewed from the front side or from the back. This is useful if you want to draw a component whose appearance is different in the front and in the back.

final decorator = Rotate3DDecorator(
  center: component.center,
  angleX: rotationAngle,
  perspective: 0.002,
);

Possible uses:

• a card that can be flipped over;

• pages in a book;

• transitions between app routes;

• 3d falling particles such as snowflakes or leaves.

Shadow3DDecorator

decorator_shadow3d.dart

import 'dart:ui';

import 'package:doc_flame_examples/flower.dart';
import 'package:flame/components.dart';
import 'package:flame/game.dart';
import 'package:flame/rendering.dart';

class DecoratorShadowGame extends FlameGame {
  @override
  Color backgroundColor() => const Color(0xFFC7C7C7);

  @override
  Future<void> onLoad() async {
    final decorator = Shadow3DDecorator(base: Vector2(0, 100));
    var step = 0;
    add(Grid());
    add(
      Flower(
        size: 100,
        position: canvasSize / 2,
        decorator: decorator,
        onTap: (flower) {
          step++;
          if (step == 1) {
            decorator.xShift = 200;
            decorator.opacity = 0.5;
          } else if (step == 2) {
            decorator.xShift = 400;
            decorator.yScale = 3;
            decorator.blur = 1;
          } else if (step == 3) {
            decorator.angle = 1.7;
            decorator.blur = 2;
          } else if (step == 4) {
            decorator.ascent = 20;
            decorator.angle = 1.7;
            decorator.blur = 2;
            flower.y -= 20;
          } else {
            decorator.ascent = 0;
            decorator.xShift = 0;
            decorator.yScale = 1;
            decorator.angle = -1.4;
            decorator.opacity = 0.8;
            decorator.blur = 0;
            flower.y += 20;
            step = 0;
          }
        },
      )..onTapUp(),
    );
  }
}

class Grid extends Component {
  final paint = Paint()
    ..color = const Color(0xffa9a9a9)
    ..style = PaintingStyle.stroke
    ..strokeWidth = 1;
  @override
  void render(Canvas canvas) {
    for (var i = 0; i < 50; i++) {
      canvas.drawLine(Offset(0, i * 25), Offset(500, i * 25), paint);
      canvas.drawLine(Offset(i * 25, 0), Offset(i * 25, 500), paint);
    }
  }
}

Code

This decorator renders a shadow underneath the component, as if the component was a 3D object standing on a plane. This effect works best for games that use isometric camera projection.

The shadow produced by this generator is quite flexible: you can control its angle, length, opacity, blur, etc. For a full description of what properties this decorator has and their meaning, see the class documentation.

final decorator = Shadow3DDecorator(
  base: Vector2(100, 150),
  angle: -1.4,
  xShift: 200,
  yScale: 1.5,
  opacity: 0.5,
  blur: 1.5,
);

The primary purpose of this decorator is to add shadows on the ground to your components. The main limitation is that the shadows are flat and cannot interact with the environment. For example, this decorator cannot handle shadows that fall onto walls or other vertical structures.

Using decorators

HasDecorator mixin

This Component mixin adds the decorator property, which is initially null. If you set this property to an actual Decorator object, then that decorator will apply its visual effect during the rendering of the component. In order to remove this visual effect, simply set the decorator property back to null.

PositionComponent

PositionComponent (and all the derived classes) already has a decorator property, so for these components the HasDecorator mixin is not needed.

In fact, the PositionComponent uses its decorator in order to properly position the component on the screen. Thus, any new decorators that you’d want to apply to the PositionComponent will need to be chained (see the Multiple decorators section below).

It is also possible to replace the root decorator of the PositionComponent, if you want to create an alternative logic for how the component shall be positioned on the screen.

Multiple decorators

It is possible to apply several decorators simultaneously to the same component: the Decorator class supports chaining. That is, if you have an existing decorator on a component and you want to add another one, then you can call component.decorator.addLast(newDecorator) – this will add the new decorator at the end of the existing chain. The method removeLast() can remove that decorator later.

Several decorators can be chain that way. For example, if A is an initial decorator, then A.addLast(B) can be followed by either A.addLast(C) or B.addLast(C) – and in both cases the chain A -> B -> C will be created. In practice, it means that the entire chain can be manipulated from its root, which usually is component.decorator.