feat(GridEngine): charAdded subject and public characterShifted obs

src/GridEngine.test.ts

@@ -1487,6 +1487,50 @@ describe("GridEngine", () => {
       });
     });
 
+    it("should emit when a character is added or removed", () => {
+      const player1 = "player1";
+      const player2 = "player2";
+      const nextMock = jest.fn();
+
+      gridEngine.create(tileMapMock, {
+        characters: [
+          {
+            id: player1,
+            sprite: playerSpriteMock,
+          },
+        ],
+      });
+
+      gridEngine.characterShifted().subscribe({
+        complete: jest.fn(),
+        next: nextMock,
+      });
+
+      gridEngine.addCharacter({ id: player2, sprite: playerSpriteMock });
+      expect(nextMock).toHaveBeenCalledWith(
+        expect.objectContaining({
+          charId: player2,
+          action: "ADDED",
+        })
+      );
+
+      gridEngine.removeCharacter(player1);
+      expect(nextMock).toHaveBeenCalledWith(
+        expect.objectContaining({
+          charId: player1,
+          action: "REMOVED",
+        })
+      );
+
+      gridEngine.addCharacter({ id: player1, sprite: playerSpriteMock });
+      expect(nextMock).toHaveBeenCalledWith(
+        expect.objectContaining({
+          charId: player1,
+          action: "ADDED",
+        })
+      );
+    });
+
     it("should notify if any provided character stepped on any of the given tiles on specified layers", () => {
       const mockSubject = new Subject<PositionChange & { charId: string }>();
       mockGridCharacter.positionChangeFinished.mockReturnValue(mockSubject);

src/GridEngine.ts

@@ -22,7 +22,7 @@ import {
 import { GridTilemap } from "./GridTilemap/GridTilemap";
 import { RandomMovement } from "./Movement/RandomMovement/RandomMovement";
 import { Observable, Subject } from "rxjs";
-import { takeUntil, filter, map, take } from "rxjs/operators";
+import { takeUntil, filter, map, take, mergeWith } from "rxjs/operators";
 import { Vector2 } from "./Utils/Vector2/Vector2";
 import { NoPathFoundStrategy } from "./Pathfinding/NoPathFoundStrategy";
 import { PathBlockedStrategy } from "./Pathfinding/PathBlockedStrategy";
@@ -221,6 +221,26 @@ export interface CharacterData {
   charLayer?: string;
 }
 
+/**
+ * Result of a modification of the internal characters array
+ */
+export interface CharacterShift {
+  /** the modified character */
+  charId: string;
+  /** The action that was performed when modifying the character */
+  action: CharacterShiftAction;
+}
+
+/**
+ * Type of modification of grid engine characters
+ */
+export enum CharacterShiftAction {
+  /** removed existing character */
+  REMOVED = "REMOVED",
+  /** added new character */
+  ADDED = "ADDED",
+}
+
 export class GridEngine {
   private gridCharacters: Map<string, GridCharacter>;
   private gridTilemap: GridTilemap;
@@ -231,6 +251,7 @@ export class GridEngine {
   private positionChangeStarted$: Subject<{ charId: string } & PositionChange>;
   private positionChangeFinished$: Subject<{ charId: string } & PositionChange>;
   private charRemoved$: Subject<string>;
+  private charAdded$: Subject<string>;
 
   /**
    * Should only be called by Phaser and never directly.
@@ -257,6 +278,7 @@ export class GridEngine {
     this.positionChangeStarted$ = undefined;
     this.positionChangeFinished$ = undefined;
     this.charRemoved$ = undefined;
+    this.charAdded$ = undefined;
   }
 
   /**
@@ -332,6 +354,7 @@ export class GridEngine {
       { charId: string } & PositionChange
     >();
     this.charRemoved$ = new Subject<string>();
+    this.charAdded$ = new Subject<string>();
     this.gridTilemap = new GridTilemap(tilemap);
 
     this.addCharacters();
@@ -564,6 +587,8 @@ export class GridEngine {
           ...positionChange,
         });
       });
+
+    this.charAdded$.next(charData.id);
   }
 
   /** Checks whether a character with the given ID is registered. */
@@ -795,6 +820,26 @@ export class GridEngine {
     );
   }
 
+  /**
+   * @returns Observable that emits when a new character is added or an existing is removed.
+   */
+  characterShifted(): Observable<CharacterShift> {
+    return this.charAdded$.pipe(
+      map((c) => ({
+        charId: c,
+        action: CharacterShiftAction.ADDED,
+      })),
+      mergeWith(
+        this.charRemoved$.pipe(
+          map((c) => ({
+            charId: c,
+            action: CharacterShiftAction.REMOVED,
+          }))
+        )
+      )
+    );
+  }
+
   /**
    * @returns Observable that on each start of a movement will provide the
    *  character ID and the direction.

src/main-esm.ts

@@ -10,6 +10,7 @@ export {
   MoveToResult,
   NumberOfDirections,
   PathBlockedStrategy,
+  CharacterShiftAction
 } from "./GridEngine";
 
 export default GridEngine;