Audio & content
Assets & storage
Load images, JSON, text and sounds through engine.assets, group and reference-count them, and keep data between runs with engine.cache.
engine.assets is the engine's AssetManager: it loads, caches and releases images, sounds, text, JSON and binary files. engine.cache is its CacheManager, which keeps strings, JSON and binary data between runs.
The asset manager
Each engine has its own AssetManager, reading from the Flutter asset bundle. It is ready as soon as the engine is made, before initialize(). Every file it loads must be listed under flutter: assets: in pubspec.yaml, by itself or through its folder; a folder entry does not include its subfolders.
import 'package:flutter/foundation.dart' show debugPrint;
import 'package:just_game_engine/just_game_engine.dart';
Future<void> loadLevelData(Engine engine) async {
final waves = await engine.assets.loadJson('assets/data/waves.json');
final sky = await engine.assets.loadImage('assets/images/sky.png');
debugPrint('${(waves.data as List).length} waves; sky ${sky.width}x${sky.height}');
// Later, anywhere: the same asset, already loaded.
final again = engine.assets.getImage('assets/images/sky.png');
debugPrint('still loaded: ${again?.isLoaded}');
}loadImage,loadAudio,loadText,loadJsonandloadBinaryload one file each;load(path, type)takes anAssetType, andloadMultiple(paths, type)loads several in parallel.- Loading a path that is already loaded returns the cached asset.
getImage,getJsonandget<T>(path)return what is loaded, or null. ImageAssethasimage(adart:uiimage),widthandheight;JsonAssethas the decodeddata;TextAssethascontent.unload(path)unloads every type loaded at that path, andunloadAll()everything.totalMemoryUsage,assetCountandcacheStatssay what is loaded.
Image, audio, text, JSON and binary loaders are built in. The atlas loader is registered the first time SpriteAtlas.fromAsset runs. Fonts and shaders have no loader until you add one with registerLoader(type, loader); loading one before that throws an AssetLoadException. Models get theirs from Graphics3D, which registers an AssetType.model loader as it starts; a 2-D game has none. Engine loaders that need the asset manager take it as a parameter, for example Sprite.fromAsset(path, assets: engine.assets); see Sprites.
Groups and reference counting
A GameAssetBundle is a named group of assets that load and unload together. It was called AssetBundle in 1.x, which clashed with Flutter's class of that name.
When several screens or levels share assets, count references instead. acquire(path, type) loads or reuses an asset and adds one to its count; release(path) takes one away and unloads the asset when the count reaches zero. An AssetScope releases everything it acquired in one dispose() call, which suits one scope per level or screen.
final menuAssets = GameAssetBundle(
name: 'menu',
assetPaths: ['assets/images/title.png', 'assets/audio/menu.ogg'],
assetTypes: [AssetType.image, AssetType.audio],
);
Future<void> showMenu(Engine engine) => menuAssets.load(engine.assets);
void leaveMenu(Engine engine) => menuAssets.unload(engine.assets);
/// One scope per level: leaving the level releases what it used.
Future<AssetScope> enterLevel(Engine engine) async {
final scope = AssetScope(engine.assets);
await scope.acquireImage('assets/images/cave_background.png');
await scope.acquireJson('assets/data/cave_waves.json');
return scope; // call scope.dispose() when the level ends
}engine.assets.createScope() makes a MemoryScope from just_memory instead. Pass it to acquireImageScoped(path, scope) and the other ...Scoped methods, and register any clean-up of your own with scope.own(callback). Disposing the scope runs everything it owns, newest first.
Tests and other bundles
The asset manager reads from the engine context's bundle, Flutter's rootBundle unless you say otherwise. To load from a bundle of your own, for example in a test, make the engine with Engine(context: EngineContext(bundle: myBundle)). A context you pass in is yours to dispose. See Testing.
The cache
engine.cache stores small amounts of data between runs: settings, progress, downloaded content.
Future<void> saveVolume(Engine engine, double volume) =>
engine.cache.setJson('settings', {'musicVolume': volume});
Future<double> loadVolume(Engine engine) async {
final json = await engine.cache.getJson('settings');
if (json is Map && json['musicVolume'] is num) {
return (json['musicVolume'] as num).toDouble();
}
return 1.0;
}setStringandgetString,setJsonandgetJson, andsetBinaryandgetBinary(aUint8List) store and read values. Any string is a valid key.remove(key)deletes one entry.clearAll()deletes the cache's own entries only: the rest of the store, including players' key bindings, is left alone.- Strings and JSON go to the engine's key-value store under the
just_game_engine.cache/prefix; binary data goes to a database of its own. - Where the key-value store cannot be opened (a test, a headless run), everything stays in memory for the run (
isUsingMemoryFallback). If only the database fails, binary data stays in memory (isBinaryInMemory).
The engine's storage file
The engine keeps its data apart from your app's. On desktop and mobile its key-value store is <application support>/just_game_engine/just_storage.json, beside the just_storage.json your app opens with JustStorage.standard(), not inside it: two writers on one file could drop each other's keys. On the web it is browser storage under the engine's own just_game_engine/ key prefix.
On the first launch of 2.0, the engine moves the keys it left in the shared file in 1.x into its own store, and removes the copies of bundle assets that 1.x cached. Assets from the bundle are never copied into the cache, so an app update's new images show at once.
Memory diagnostics
The engine re-exports the just_memory diagnostics it uses: MemoryProfiler, PoolManager and the snapshot types. engine.cache.captureProfile() returns a MemoryProfileSnapshot, and engine.assets.cacheStats reports loaded assets by type and their memory use. For the profiling tools and stats overlays, see Debugging.