refactor!: The method onLoad() now returns FutureOr<void>

[st-pasha]

Description

Before this PR, the return type of onLoad() was Future<void>?, after this PR the return type is FutureOr<void> -- both for classes Component and Game.

Reasons:

• The use of FutureOr is more idiomatic in Dart, this class was specifically created in order to be used in situations like ours.
• This makes learning Flame easier for beginners, since you no longer need to explain what asynchronous programming is from the start (and onLoad() is one of the first methods the user encounters in Flame).
• The code can be cleaner in case when onLoad doesn't need to be async.

With new approach, the onLoad() method can be overridden as either

@override
Future<void> onLoad() async { ... }

or

@override
void onLoad() { ... }

Of course, it can also be overridden as

@override
FutureOr<void> onLoad() { ... }

but this is rare, only for components that are designed to be further subclassed, or for mixins.

The documentation was updated to show the new recommended usage.

Checklist

• The title of my PR starts with a Conventional Commit prefix (fix:, feat:, docs: etc).
• I have followed the Contributor Guide when preparing my PR.
• [-] I have updated/added tests for ALL new/updated/fixed functionality.
• I have updated/added relevant documentation in docs and added dartdoc comments with ///.
• I have updated/added relevant examples in examples or docs.

Breaking Change?

• Yes, this PR is a breaking change (minor).

Migration instructions

Most of the existing code is expected to work as-is. In particular, the following patterns will continue to work:

• @override Future<void> onLoad() async { ... };
• @override Future<void> onLoad() async { await super.onLoad(); ... };
• @override Future<void> onLoad() { ...; return super.onLoad(); };
• @override Future<void>? onLoad() { ...; return null; };

However, the following pattern will no longer work:

• @override Future<void>? onLoad() { ...; return super.onLoad(); }

Instead, it will now produce a compile error, which can be fixed by changing the signature to one of

• @override void onLoad() { ...; } (in most cases the call to super.onLoad() is not needed);
• @override void onLoad() { ...; super.onLoad(); };
• @override FutureOr<void> onLoad() { ...; return super.onLoad(); };

Related Issues

[erickzanardo]

Is this really a breaking change? I don't think this will break any existing code right?

[st-pasha]

Is this really a breaking change? I don't think this will break any existing code right?

It's barely breaking. Like, the following example would no longer work, because FutureOr<void> cannot be returned from a method with return type Future<void>?:

  @override
  Future<void>? onLoad() {
    width = 200;
    height = 70;
    return super.onLoad();
  }

But then, these kind of examples are rare (there is no point in calling super.onLoad() since it's a noop), and are easily fixable.

[spydon]

Good idea!

[pdong15dth]

i can't find onLoad function in flame 1.6.0 version

[spydon]

i can't find onLoad function in flame 1.6.0 version

Please put questions in either on Discord, in issues or on StackOverflow.
This PR is unrelated to your question. :)

onLoad still exists on the Component, so you can override it in any Component (including the FlameGame).

[pdong15dth]

i can't find onLoad function in flame 1.6.0 version

Please put questions in either on Discord, in issues or on StackOverflow. This PR is unrelated to your question. :)

onLoad still exists on the Component, so you can override it in any Component (including the FlameGame).

Thanks. I found it, because android studio doesn't show recommended for onload function i thought it was removed from flame.