feat(flame_jenny): Allow removal of characters (#2715)

Allow characters to be removed from character storage, or character
storage to be cleared.

This is useful in large games where each scene may have different sets
of characters. They can be cleared between scenes, and new characters
loaded.

doc/other_modules/jenny/runtime/character_storage.md

@@ -5,3 +5,34 @@
 :symbol: CharacterStorage
 :file: src/character_storage.dart
 ```
+
+
+## Accessing character storage
+
+Character storage is accessed via the [YarnProject].
+
+```dart
+final characters = yarnProject.characters;
+```
+
+
+## Removing characters
+
+There may be situations where characters need to be removed from storage. For example, in a game
+with many scenes, characters could be removed after a scene and new characters loaded for the next
+scene.
+
+Remove all characters with `clear`.
+
+```dart
+yarnProject.characters.clear();
+```
+
+Use `remove` to remove a single character. Pass in the name of the character or any of its
+aliases. The character and all its aliases will be removed.
+
+```dart
+yarnProject.characters.remove('Jenny');
+```
+
+[YarnProject]: yarn_project.md

packages/flame_jenny/jenny/lib/src/character_storage.dart

@@ -28,4 +28,27 @@ class CharacterStorage {
       _cache[alias] = character;
     }
   }
+
+  /// Clear all characters from storage.
+  ///
+  /// This could be used between scenes in preparation for loading a new
+  /// set of characters. It would not generally be used while a dialog is
+  /// in progress.
+  void clear() {
+    _cache.clear();
+  }
+
+  /// Remove a character by name. Its aliases will also be removed.
+  ///
+  /// This could be used if you are certain a character is no longer required.
+  /// It would not generally be used while a dialog is in progress.
+  void remove(String name) {
+    final character = _cache[name];
+    if (character != null) {
+      for (final alias in character.aliases) {
+        _cache.remove(alias);
+      }
+      _cache.remove(character.name);
+    }
+  }
 }

packages/flame_jenny/jenny/test/character_storage_test.dart

@@ -0,0 +1,74 @@
+import 'package:jenny/src/character.dart';
+import 'package:jenny/src/character_storage.dart';
+import 'package:test/test.dart';
+
+void main() {
+  group('CharacterStorage', () {
+    test('Should store character', () {
+      final storage = CharacterStorage();
+
+      expect(storage.isEmpty, true);
+
+      final character = Character('Jenny');
+      storage.add(character);
+
+      expect(storage.isEmpty, false);
+      expect(storage.isNotEmpty, true);
+
+      expect(storage.contains(character.name), true);
+    });
+
+    test('Should store character aliases', () {
+      final storage = CharacterStorage();
+      final character = Character('Jenny', aliases: ['Jen', 'Jennifer']);
+      storage.add(character);
+
+      expect(storage.contains(character.name), true);
+      expect(storage.contains(character.aliases[0]), true);
+      expect(storage.contains(character.aliases[1]), true);
+    });
+
+    test('Should remove character and aliases by name', () {
+      final storage = CharacterStorage();
+      final character = Character('Jenny', aliases: ['Jen', 'Jennifer']);
+      storage.add(character);
+
+      expect(storage.contains(character.name), true);
+      expect(storage.contains(character.aliases[0]), true);
+      expect(storage.contains(character.aliases[1]), true);
+
+      storage.remove(character.name);
+
+      expect(storage.contains(character.name), false);
+      expect(storage.contains(character.aliases[0]), false);
+      expect(storage.contains(character.aliases[1]), false);
+    });
+
+    test('Should remove character and aliases by alias', () {
+      final storage = CharacterStorage();
+      final character = Character('Jenny', aliases: ['Jen', 'Jennifer']);
+      storage.add(character);
+
+      expect(storage.contains(character.name), true);
+      expect(storage.contains(character.aliases[0]), true);
+      expect(storage.contains(character.aliases[1]), true);
+
+      storage.remove(character.aliases[1]);
+
+      expect(storage.contains(character.name), false);
+      expect(storage.contains(character.aliases[0]), false);
+      expect(storage.contains(character.aliases[1]), false);
+    });
+
+    test('Should clear all characters', () {
+      final storage = CharacterStorage();
+      storage.add(Character('Jenny', aliases: ['Jen', 'Jennifer']));
+      storage.add(Character('Thomas'));
+      storage.add(Character('Leon'));
+
+      storage.clear();
+
+      expect(storage.isEmpty, true);
+    });
+  });
+}