ParallaxComponent

Parallax scrolling is a classic game development technique where background layers move at different speeds to create an illusion of depth. Objects closer to the camera appear to move faster than those far away. Just as when looking out a car window, nearby trees fly by while distant mountains barely move. This effect makes 2D game worlds feel more immersive and is commonly used in side-scrollers, platformers, and menu screens.

This Component can be used to render backgrounds with a depth feeling by drawing several transparent images on top of each other, where each image or animation (ParallaxRenderer) is moving with a different velocity.

The simplest ParallaxComponent is created like this:

@override
Future<void> onLoad() async {
  final parallaxComponent = await loadParallaxComponent([
    ParallaxImageData('bg.png'),
    ParallaxImageData('trees.png'),
  ]);
  add(parallaxComponent);
}

A ParallaxComponent can also “load itself” by implementing the onLoad method:

class MyParallaxComponent extends ParallaxComponent<MyGame> {
  @override
  Future<void> onLoad() async {
    parallax = await game.loadParallax([
      ParallaxImageData('bg.png'),
      ParallaxImageData('trees.png'),
    ]);
  }
}

class MyGame extends FlameGame {
  @override
  void onLoad() {
    add(MyParallaxComponent());
  }
}

This creates a static background. If you want a moving parallax (which is the whole point of a parallax), you can do it in a few different ways depending on how fine-grained you want to set the settings for each layer.

The simplest way is to set the named optional parameters baseVelocity and velocityMultiplierDelta in the load helper function. For example if you want to move your background images along the X-axis with a faster speed the “closer” the image is:

@override
Future<void> onLoad() async {
  final parallaxComponent = await loadParallaxComponent(
    _dataList,
    baseVelocity: Vector2(20, 0),
    velocityMultiplierDelta: Vector2(1.8, 1.0),
  );
}

You can set the baseSpeed and layerDelta at any time, for example if your character jumps or your game speeds up.

@override
void onLoad() {
  final parallax = parallaxComponent.parallax;
  parallax.baseSpeed = Vector2(100, 0);
  parallax.velocityMultiplierDelta = Vector2(2.0, 1.0);
}

By default, the images are aligned to the bottom left, repeated along the X-axis and scaled proportionally so that the image covers the height of the screen. If you want to change this behavior, for example if you are not making a side-scrolling game, you can set the repeat, alignment and fill parameters for each ParallaxRenderer and add them to ParallaxLayers that you then pass in to the ParallaxComponent’s constructor.

Advanced example:

final images = [
  loadParallaxImage(
    'stars.jpg',
    repeat: ImageRepeat.repeat,
    alignment: Alignment.center,
    fill: LayerFill.width,
  ),
  loadParallaxImage(
    'planets.jpg',
    repeat: ImageRepeat.repeatY,
    alignment: Alignment.bottomLeft,
    fill: LayerFill.none,
  ),
  loadParallaxImage(
    'dust.jpg',
    repeat: ImageRepeat.repeatX,
    alignment: Alignment.topRight,
    fill: LayerFill.height,
  ),
];

final layers = images.map(
  (image) => ParallaxLayer(
    await image,
    velocityMultiplier: images.indexOf(image) * 2.0,
  )
);

final parallaxComponent = ParallaxComponent.fromParallax(
  Parallax(
    await Future.wait(layers),
    baseVelocity: Vector2(50, 0),
  ),
);

• The stars image in this example will be repeatedly drawn in both axes, align in the center and be scaled to fill the screen width.

• The planets image will be repeated in Y-axis, aligned to the bottom left of the screen and not be scaled.

• The dust image will be repeated in X-axis, aligned to the top right and scaled to fill the screen height.

Once you are done setting up your ParallaxComponent, add it to the game like with any other component (game.add(parallaxComponent). Also, don’t forget to add your images to the pubspec.yaml file as assets or they won’t be found.

The Parallax file contains an extension of the game which adds loadParallax, loadParallaxLayer, loadParallaxImage and loadParallaxAnimation so that it automatically uses your game’s image cache instead of the global one. The same goes for the ParallaxComponent file, but that provides loadParallaxComponent.

If you want a fullscreen ParallaxComponent simply omit the size argument and it will take the size of the game, it will also resize to fullscreen when the game changes size or orientation.

Flame provides two kinds of ParallaxRenderer: ParallaxImage and ParallaxAnimation, ParallaxImage is a static image renderer and ParallaxAnimation is, as its name implies, an animation and frame based renderer. It is also possible to create custom renderers by extending the ParallaxRenderer class.

Three example implementations can be found in the examples directory.