Flutter & shipping
Services & plugins
Run your own code beside the engine with EngineService, observe a running engine with EnginePlugin, and add achievements, currency and more from just_game_services.
Two hooks let code live beside the game. An EngineService starts when the engine initializes and stops when it is disposed. An EnginePlugin attaches to an engine to watch or extend it and is called every frame.
Engine services
A service implements two methods: start(ServiceContext context) and stop(). List it in EngineConfig(services: [...]), or add it later with engine.services.add(service).
import 'package:flutter/foundation.dart' show debugPrint;
import 'package:just_game_engine/just_game_engine.dart';
/// Counts the collisions the game has had, for the engine's whole life.
class CollisionCounter implements EngineService {
int count = 0;
EventSubscription? _subscription;
@override
Future<void> start(ServiceContext context) async {
_subscription = context.events.on<CollisionEnter2DEvent>((_) => count++);
}
@override
Future<void> stop() async {
_subscription?.cancel();
_subscription = null;
}
}
Future<Engine> boot() async {
final engine = Engine(
config: EngineConfig(
defaultSystems: DefaultSystems.all,
services: [CollisionCounter()],
),
);
await engine.initialize(); // starts the service
debugPrint('${engine.service<CollisionCounter>().count} collisions so far');
return engine;
}- Starting. Services start last in
initialize(), after the world exists, in the order they are listed. ListGraphics3Dbefore any service that loads models as it starts;Physics3Dstarts wherever you list it. A service added to an engine that is already initialized starts at once. - Failing. A
startthat throws failsinitialize()with anEngineInitExceptionwhosestageisservice:<Type>, and the services already started are stopped. - Stopping.
dispose()calls everystop(), last started first, before the world goes, and its Future completes once all of them have finished. A service must not touch the world after itsstop()is called. - Context.
ServiceContextgives the service itsengine, the engine'scontext, andevents, the world's event bus.eventsis read on each call, so never cache the world itself.engineis aGameEngine: the world, context, assets, rendering, camera, input, audio and the other services. Read the camera, input and audio once the engine is initialized; before that they throw. A service that needs more of its engine (its clock, music or storage) casts it:context.engine as Engine.
engine.service<T>() returns the service of type T, and throws a StateError that says how to add it when there is none. engine.maybeService<T>() returns null instead. engine.services also has has<T>(), all and remove(service). Adding a service whose runtime type is already there stops and replaces the old one.
Plugins
An EnginePlugin is for tools that observe or extend a running engine: an editor, a profiler, a replay recorder. Register it with engine.plugins.register(plugin). A plugin has an id; registering another with the same id detaches and replaces the first.
| Member | When it is called |
|---|---|
attach(engine) | Once, when the plugin is registered. |
update(dt) | Once per frame, with the unscaled frame time, even while the game is paused or its time scale is zero. |
renderOverlay(canvas, size) | Once per frame, in screen space, after the world has drawn. |
detach() | When the plugin is unregistered, or when the engine is disposed. |
/// Logs every frame that takes longer than 1/30 s.
class SlowFrameLogger extends EnginePlugin {
@override
String get id => 'slow_frame_logger';
@override
void update(double dt) {
if (dt > 1 / 30) {
debugPrint('Slow frame: ${(dt * 1000).toStringAsFixed(1)} ms');
}
}
}
// await engine.plugins.register(SlowFrameLogger());engine.plugins also has unregister(id), byId(id) and all. Simulation belongs in systems, which run on the fixed step; a plugin sees the engine on wall-clock time.
Achievements, currency and more
Achievements, sign-in, leaderboards, a currency wallet, an inventory and ads are services in a separate package, just_game_services. Nothing from it runs unless you list it.
dependencies:
just_game_engine: ^2.0.0
just_game_services: ^0.1.0import 'package:just_game_engine/just_game_engine.dart';
import 'package:just_game_services/just_game_services.dart';
Future<Engine> startGame() async {
final engine = Engine(
config: EngineConfig(
defaultSystems: DefaultSystems.all,
// Or GameServices.all() for all six.
services: [
AchievementManager()..define(
Achievement(
id: 'first_win',
name: 'First Win',
description: 'Beat level 1',
),
),
CurrencyManager(),
],
),
);
await engine.initialize(); // starts both services
engine.achievements.unlock('first_win');
engine.currency.add('coins', 10); // saved to disk by default
return engine;
}engine.achievements, engine.currency and the others are extension getters from the package, and each is engine.service<T>() under another name: asking for one the engine was not given throws a StateError naming the fix. AdsManager.initialize(consent: ...) is still yours to call. For a real sign-in or leaderboard backend, write an AuthProvider or LeaderboardProvider.