feat: Optional key for Images.load (flame-engine#1624)

packages/flame/lib/assets.dart

@@ -1,2 +1,4 @@
-export 'src/assets/assets_cache.dart';
-export 'src/assets/images.dart';
+@Deprecated('Use the cache.dart file instead')
+export 'src/cache/assets_cache.dart';
+@Deprecated('Use the cache.dart file instead')
+export 'src/cache/images.dart';

packages/flame/lib/cache.dart

@@ -1,2 +1,4 @@
+export 'src/cache/assets_cache.dart';
+export 'src/cache/images.dart';
 export 'src/cache/memory_cache.dart';
 export 'src/cache/value_cache.dart';

packages/flame/lib/src/assets/assets_cache.dart → packages/flame/lib/src/cache/assets_cache.dart

@@ -3,26 +3,26 @@ import 'dart:typed_data';
 
 import 'package:flutter/services.dart' show rootBundle;
 
-/// A class that loads, and cache files
+/// A class that loads, and caches files.
 ///
-/// it automatically looks for files on the assets folder
+/// It automatically looks for files in the `assets` directory.
 class AssetsCache {
  final String prefix;
  final Map<String, _Asset> _files = {};
 
  AssetsCache({this.prefix = 'assets/'});
 
- /// Removes the file from the cache
+ /// Removes the file from the cache.
  void clear(String file) {
  _files.remove(file);
  }
 
- /// Removes all the files from the cache
+ /// Removes all the files from the cache.
  void clearCache() {
  _files.clear();
  }
 
- /// Reads a file from assets folder
+ /// Reads a file from assets folder.
  Future<String> readFile(String fileName) async {
  if (!_files.containsKey(fileName)) {
  _files[fileName] = await _readFile(fileName);
@@ -36,7 +36,7 @@ class AssetsCache {
  return _files[fileName]!.value as String;
  }
 
- /// Reads a binary file from assets folder
+ /// Reads a binary file from assets folder.
  Future<List<int>> readBinaryFile(String fileName) async {
  if (!_files.containsKey(fileName)) {
  _files[fileName] = await _readBinary(fileName);
@@ -50,6 +50,7 @@ class AssetsCache {
  return _files[fileName]!.value as List<int>;
  }
 
+ /// Reads a json file from the assets folder.
  Future<Map<String, dynamic>> readJson(String fileName) async {
  final content = await readFile(fileName);
  return jsonDecode(content) as Map<String, dynamic>;

packages/flame/lib/src/assets/images.dart → packages/flame/lib/src/cache/images.dart

@@ -90,8 +90,11 @@ class Images {
  }
 
  /// Loads the specified image with [fileName] into the cache.
- Future<Image> load(String fileName) {
- return (_assets[fileName] ??= _ImageAsset.future(_fetchToMemory(fileName)))
+ /// By default the key in the cache is the [fileName], if another key is
+ /// desired, specify the optional [key] argument.
+ Future<Image> load(String fileName, {String? key}) {
+ return (_assets[key ?? fileName] ??=
+ _ImageAsset.future(_fetchToMemory(fileName)))
  .retrieveAsync();
  }
 
@@ -121,6 +124,9 @@ class Images {
  return loadAll(imagePaths.toList());
  }
 
+ /// Whether the cache contains the specified [key] or not.
+ bool containsKey(String key) => _assets.containsKey(key);
+
  /// Waits until all currently pending image loading operations complete.
  Future<void> ready() {
  return Future.wait(_assets.values.map((asset) => asset.retrieveAsync()));

packages/flame/lib/src/components/parallax_component.dart

@@ -5,7 +5,7 @@ import 'package:meta/meta.dart';
 
 import '../../components.dart';
 import '../../game.dart';
-import '../assets/images.dart';
+import '../cache/images.dart';
 import '../parallax.dart';
 
 extension ParallaxComponentExtension on FlameGame {

packages/flame/lib/src/flame.dart

@@ -2,8 +2,8 @@ library flame;
 
 import 'package:flutter/services.dart';
 
-import 'assets/assets_cache.dart';
-import 'assets/images.dart';
+import 'cache/assets_cache.dart';
+import 'cache/images.dart';
 import 'device.dart';
 
 /// This class holds static references to some useful objects to use in your

packages/flame/lib/src/game/mixins/game.dart

@@ -4,10 +4,9 @@ import 'package:flutter/rendering.dart';
 import 'package:flutter/widgets.dart';
 import 'package:meta/meta.dart';
 
+import '../../../cache.dart';
 import '../../../components.dart';
-import '../../assets/assets_cache.dart';
-import '../../assets/images.dart';
-import '../../extensions/offset.dart';
+import '../../../extensions.dart';
 import '../game_render_box.dart';
 import '../projector.dart';
 

packages/flame/lib/src/parallax.dart

@@ -4,10 +4,9 @@ import 'dart:ui';
 import 'package:collection/collection.dart';
 import 'package:flutter/painting.dart';
 
+import '../cache.dart';
+import '../extensions.dart';
 import '../game.dart';
-import 'assets/images.dart';
-import 'extensions/canvas.dart';
-import 'extensions/image.dart';
 import 'flame.dart';
 import 'sprite_animation.dart';
 

packages/flame/lib/src/sprite.dart

@@ -1,7 +1,7 @@
 import 'dart:ui';
 
 import 'anchor.dart';
-import 'assets/images.dart';
+import 'cache/images.dart';
 import 'flame.dart';
 import 'image_composition.dart';
 import 'palette.dart';

packages/flame/lib/src/sprite_animation.dart

@@ -1,7 +1,7 @@
 import 'dart:async';
 import 'dart:ui';
 
-import 'assets/images.dart';
+import 'cache/images.dart';
 import 'extensions/vector2.dart';
 import 'flame.dart';
 import 'sprite.dart';

packages/flame/lib/src/sprite_batch.dart

@@ -2,7 +2,7 @@ import 'dart:collection';
 import 'dart:ui';
 
 import '../game.dart';
-import 'assets/images.dart';
+import 'cache/images.dart';
 import 'extensions/image.dart';
 import 'flame.dart';
 

packages/flame/lib/src/widgets/animation_widget.dart

@@ -3,7 +3,7 @@ import 'dart:math';
 import 'package:flutter/material.dart' hide Animation;
 
 import '../anchor.dart';
-import '../assets/images.dart';
+import '../cache/images.dart';
 import '../sprite_animation.dart';
 import 'base_future_builder.dart';
 import 'sprite_painter.dart';

packages/flame/lib/src/widgets/nine_tile_box.dart

@@ -2,7 +2,7 @@ import 'dart:ui';
 
 import 'package:flutter/material.dart' hide Image;
 
-import '../../assets.dart';
+import '../../cache.dart';
 import '../../flame.dart';
 import '../nine_tile_box.dart' as non_widget;
 import '../sprite.dart';

packages/flame/lib/src/widgets/sprite_button.dart

@@ -1,6 +1,6 @@
 import 'package:flutter/widgets.dart';
 
-import '../../assets.dart';
+import '../../cache.dart';
 import '../extensions/size.dart';
 import '../extensions/vector2.dart';
 import '../sprite.dart';

packages/flame/lib/src/widgets/sprite_widget.dart

@@ -1,6 +1,6 @@
 import 'package:flutter/widgets.dart';
 
-import '../../assets.dart';
+import '../../cache.dart';
 import '../../extensions.dart';
 import '../anchor.dart';
 import 'animation_widget.dart';

packages/flame/test/assets/images_test.dart → packages/flame/test/cache/images_test.dart

@@ -1,6 +1,7 @@
 import 'dart:ui';
 
-import 'package:flame/assets.dart';
+import 'package:collection/collection.dart';
+import 'package:flame/cache.dart';
 import 'package:flame_test/flame_test.dart';
 import 'package:flutter_test/flutter_test.dart';
 import 'package:mocktail/mocktail.dart';
@@ -58,12 +59,23 @@ void main() {
  for (var i = 0; i < images.length; i++) {
  cache.add(i.toString(), images[i]);
  }
- expect(images.fold<int>(0, (agg, image) => agg + image.disposedCount), 0);
+ expect(images.map((image) => image.disposedCount).sum, 0);
  cache.clearCache();
- expect(
- images.fold<int>(0, (agg, image) => agg + image.disposedCount),
- images.length,
- );
+ expect(images.map((image) => image.disposedCount).sum, images.length);
+ });
+
+ test('contains', () {
+ final cache = Images();
+ final images = List.generate(10, (_) => _MockImage());
+ for (var i = 0; i < images.length; i++) {
+ final key = i.toString();
+ cache.add(key, images[i]);
+ expect(cache.containsKey(key), isTrue);
+ }
+ cache.clearCache();
+ for (var i = 0; i < images.length; i++) {
+ expect(cache.containsKey(i.toString()), isFalse);
+ }
  });
 
  testWithFlameGame(

packages/flame/test/components/parallax_test.dart

@@ -1,4 +1,4 @@
-import 'package:flame/assets.dart';
+import 'package:flame/cache.dart';
 import 'package:flame/components.dart';
 import 'package:flame/extensions.dart';
 import 'package:flame/game.dart';

packages/flame_fire_atlas/lib/flame_fire_atlas.dart

@@ -3,7 +3,7 @@ library flame_fire_atlas;
 import 'dart:convert';
 
 import 'package:archive/archive.dart';
-import 'package:flame/assets.dart';
+import 'package:flame/cache.dart';
 import 'package:flame/extensions.dart';
 import 'package:flame/flame.dart';
 import 'package:flame/game.dart';

packages/flame_fire_atlas/test/flame_fire_atlas_test.dart

@@ -1,7 +1,7 @@
 import 'dart:io';
 import 'dart:ui';
 
-import 'package:flame/assets.dart';
+import 'package:flame/cache.dart';
 import 'package:flame/flame.dart';
 import 'package:flame/game.dart';
 import 'package:flame_fire_atlas/flame_fire_atlas.dart';

packages/flame_svg/lib/svg.dart

@@ -1,6 +1,5 @@
 import 'dart:ui';
 
-import 'package:flame/assets.dart';
 import 'package:flame/cache.dart';
 import 'package:flame/extensions.dart';
 import 'package:flame/flame.dart';