Color Effects

Color effects are used to change the color of a component over time. They can be used to tint a component, change its opacity, or apply a color filter.

ColorEffect

This effect will change the base color of the paint, causing the rendered component to be tinted by the provided color between a provided range.

Usage example:

color_effect.dart

import 'package:doc_flame_examples/ember.dart';
import 'package:flame/components.dart';
import 'package:flame/effects.dart';
import 'package:flame/game.dart';
import 'package:flutter/animation.dart';
import 'package:flutter/cupertino.dart';

class ColorEffectExample extends FlameGame {
  bool reset = false;

  @override
  Future<void> onLoad() async {
    final ember = EmberPlayer(
      position: size / 2,
      size: size / 4,
      onTap: (ember) {
        ember.add(
          ColorEffect(
            reset ? const Color(0xFF1039DB) : const Color(0xFF00FF00),
            EffectController(duration: 1.5),
            opacityTo: 0.6,
          ),
        );
        reset = !reset;
      },
    )..anchor = Anchor.center;

    add(ember);
  }
}

Code

final effect = ColorEffect(
  const Color(0xFF00FF00),
  EffectController(duration: 1.5),
  opacityFrom: 0.2,
  opacityTo: 0.8,
);

The opacityFrom and opacityTo arguments will determine “how much” of the color that will be applied to the component. In this example the effect will start with 20% and will go up to 80%.

Note: Due to how this effect is implemented, and how Flutter’s ColorFilter class works, this effect can’t be mixed with other ColorEffects, when more than one is added to the component, only the last one will have effect.

OpacityToEffect

This effect will change the opacity of the target over time to the specified alpha-value. It can only be applied to components that implement the OpacityProvider.

opacity_to_effect.dart

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

class OpacityToEffectGame extends FlameGame {
  bool reset = false;

  @override
  Future<void> onLoad() async {
    final flower = Flower(
      position: size / 2,
      size: 60,
      onTap: _onTap,
    )..anchor = Anchor.center;

    add(flower);
  }

  void _onTap(Flower flower) {
    if (reset) {
      flower.add(
        OpacityEffect.fadeIn(
          EffectController(duration: 0.75),
        ),
      );
    } else {
      flower.add(
        OpacityEffect.to(
          0.2,
          EffectController(duration: 0.75),
        ),
      );
    }
    reset = !reset;
  }
}

Code

final effect = OpacityEffect.to(
  0.2,
  EffectController(duration: 0.75),
);

If the component uses multiple paints, the effect can target one more more of those paints using the target parameter. The HasPaint mixin implements OpacityProvider and exposes APIs to easily create providers for desired paintIds. For single paintId opacityProviderOf can be used and for multiple paintIds and opacityProviderOfList can be used.

opacity_effect_with_target.dart

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

class OpacityEffectWithTargetGame extends FlameGame {
  bool reset = false;

  // This reference needs to be stored because every new instance of
  // OpacityProvider caches the opacity ratios at the time on creation.
  late OpacityProvider _borderOpacityProvider;

  @override
  Future<void> onLoad() async {
    final flower = Flower(
      position: size / 2,
      size: 60,
      onTap: _onTap,
    )..anchor = Anchor.center;

    _borderOpacityProvider = flower.opacityProviderOfList(
      paintIds: const [FlowerPaint.paintId1, FlowerPaint.paintId2],
    );

    add(flower);
  }

  void _onTap(Flower flower) {
    if (reset = !reset) {
      flower.add(
        OpacityEffect.fadeIn(
          EffectController(duration: 0.75),
          target: _borderOpacityProvider,
        ),
      );
    } else {
      flower.add(
        OpacityEffect.to(
          0.2,
          EffectController(duration: 0.75),
          target: _borderOpacityProvider,
        ),
      );
    }
    reset = !reset;
  }
}

Code

final effect = OpacityEffect.to(
  0.2,
  EffectController(duration: 0.75),
  target: component.opacityProviderOfList(
    paintIds: const [paintId1, paintId2],
  ),
);

The opacity value of 0 corresponds to a fully transparent component, and the opacity value of 1 is fully opaque. Convenience constructors OpacityEffect.fadeOut() and OpacityEffect.fadeIn() will animate the target into full transparency / full visibility respectively.

OpacityByEffect

This effect will change the opacity of the target relative to the specified alpha-value. For example, the following effect will change the opacity of the target by 90%:

opacity_by_effect.dart

import 'package:doc_flame_examples/ember.dart';
import 'package:flame/components.dart';
import 'package:flame/effects.dart';
import 'package:flame/game.dart';

class OpacityByEffectGame extends FlameGame {
  bool reset = false;

  @override
  Future<void> onLoad() async {
    final ember = EmberPlayer(
      position: size / 2,
      size: size / 4,
      onTap: (ember) {
        ember.add(
          OpacityEffect.by(
            reset ? 0.9 : -0.9,
            EffectController(duration: 0.75),
          ),
        );
        reset = !reset;
      },
    )..anchor = Anchor.center;

    add(ember);
  }
}

Code

final effect = OpacityEffect.by(
  0.9,
  EffectController(duration: 0.75),
);

Currently this effect can only be applied to components that have a HasPaint mixin. If the target component uses multiple paints, the effect can target any individual color using the paintId parameter.

GlowEffect

Note

This effect is currently experimental, and its API may change in the future.

This effect will apply the glowing shade around target relative to the specified glow-strength. The color of shade will be targets paint color. For example, the following effect will apply the glowing shade around target by strength of 10:

glow_effect.dart

import 'package:flame/components.dart';
import 'package:flame/effects.dart';
import 'package:flame/game.dart';

import 'package:flutter/material.dart';

class GlowEffectExample extends FlameGame {
  @override
  Future<void> onLoad() async {
    final paint = Paint()..color = const Color(0xff39FF14);

    add(
      CircleComponent(
        radius: size.y / 4,
        position: size / 2,
        anchor: Anchor.center,
        paint: paint,
      )..add(
        GlowEffect(
          10.0,
          EffectController(
            duration: 2,
            infinite: true,
          ),
        ),
      ),
    );
  }
}

Code

final effect = GlowEffect(
  10.0,
  EffectController(duration: 3),
);

Currently this effect can only be applied to components that have a HasPaint mixin.