util.md

Util

Some stuff just doesn't fit anywhere else.

Position

Throughout the variety of modules needed to build a game, Dart and Flutter have a few different classes to handle the concept of a 2D double point; specially common in the APIs are math.Point and ui.Offset.

The Position class is an utility class that helps by allowing easy conversions to and from these type.

It also differs from the default implementations provided (math.Point and ui.Offset) as it's mutable and offers some useful methods for manipulation.

Util Class

This class, accessible via Flame.util, has some sparse functions that are independent and good to have.

It is recommended that the functions in this class be called via the Flame.util getter to utilize a single instance prepared by the Flame engine.

Flame.util.fullScreen()

When called, this disables all SystemUiOverlay making the app full screen. When called in the main method, makes your app full screen (no top nor bottom bars)

Flame.util.setLandscape()

This method sets the orientation of the whole application (effectively, also the game) to landscape and depending on operating system and device setting, should allow both left and right landscape orientations. To set the app orientation to landscape on a specific direction, use either Flame.util.setLandscapeLeftOnly or Flame.util.setLandscapeRightOnly.

Flame.util.setPortrait()

This method sets the orientation of the whole application (effectively, also the game) to portrait and depending on operating system and device setting, should allow both up and down landscape orientations. To set the app orientation to portrait on a specific direction, use either Flame.util.setPortraitUpOnly or Flame.util.setPortraitDownOnly.

Flame.util.setOrientation() and Flame.util.setOrientations()

If a finer control on the allowed orientations is required (without having to deal with SystemChrome directly), setOrientation (accepts a single DeviceOrientation as a parameter) and setOrientations (accepts a List<DeviceOrientation> for possible orientations) can be used.

Flame.util.initialDimensions()

Returns a Future with the dimension (Size) of the screen. This has to be done in a hacky way because of the reasons described in the code. If you are using BaseGame, you probably won't need to use these, as very Component will receive this information.

Note: Call this function first thing in an asynchronous main and await its value to avoid the "size bug" that affects certain devices when building for production.

Flame.util.addGestureRecognizer() and Flame.util.removeGestureRecognizer()

These two functions help with registering (and de-registering) gesture recognizers so that the game can accept input. More about these two functions here.

Other functions

• text: discussed here
• drawWhere: a very simple function that manually applies an offset to the Canvas, render stuff given via a function and then reset the Canvas, without using the Canvas' built-in save/restore functionality. This might be useful because BaseGame uses the state of the canvas, and you should not mess with it.

Timer

Flame provides a simple utility class to help you handle countdowns and event like events.

Countdown example:

import 'dart:ui';

import 'package:flame/game.dart';
import 'package:flame/position.dart';
import 'package:flame/text_config.dart';
import 'package:flame/time.dart';

class MyGame extends Game {
  final TextConfig textConfig = TextConfig(color: const Color(0xFFFFFFFF));
  final countdown = Timer(2);

  MyGame() {
    countdown.start();
  }

  @override
  void update(double dt) {
    countdown.update(dt);
    if (countdown.isFinished()) {
      // do something ...
    }
  }

  @override
  void render(Canvas canvas) {
    textConfig.render(canvas, "Countdown: ${countdown.current.toString()}",
        Position(10, 100));
  }
}

Interval example:

import 'dart:ui';

import 'package:flame/game.dart';
import 'package:flame/position.dart';
import 'package:flame/text_config.dart';
import 'package:flame/time.dart';

class MyGame extends Game {
  final TextConfig textConfig = TextConfig(color: const Color(0xFFFFFFFF));
  Timer interval;

  int elapsedSecs = 0;

  MyGame() {
    interval = Timer(1, repeat: true, callback: () {
      elapsedSecs += 1;
    });
    interval.start();
  }

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

  @override
  void render(Canvas canvas) {
    textConfig.render(canvas, "Elapsed time: $elapsedSecs", Position(10, 150));
  }
}

Timer instances can also be used inside a BaseGame game by using the TimerComponent class.

Timer Component

import 'package:flame/time.dart';
import 'package:flame/components/timer_component.dart';
import 'package:flame/game.dart';

class MyBaseGame extends BaseGame {
  MyBaseGame() {
    add(
      TimerComponent(
        Timer(10, repeat: true, callback: () {
          print("10 seconds elapsed");
        })
        ..start()
      )
    );
  }
}