#501 add depth offset

src/GridEngine.test.ts

@@ -275,6 +275,21 @@ describe("GridEngine", () => {
     expect(gridEngine.getOffsetY("player")).toEqual(offsetY);
   });
 
+  it("should use depth offset", () => {
+    const depthOffset = -5;
+    gridEngine.create(createDefaultMockWithLayer(undefined), {
+      characters: [
+        {
+          id: "player",
+          sprite: playerSpriteMock,
+          walkingAnimationMapping: 3,
+          depthOffset,
+        },
+      ],
+    });
+    expect(gridEngine.getDepthOffset("player")).toEqual(depthOffset);
+  });
+
   describe("collision config", () => {
     it("should use config collides", () => {
       gridEngine.create(createDefaultMockWithLayer(undefined), {

src/GridEngine.ts

@@ -245,6 +245,23 @@ export interface CharacterData extends CharacterDataHeadless {
    * @defaultValue `0`
    */
   offsetY?: number;
+
+  /**
+   * A custom y-offset for the sprite/container depth. In GridEngine the depth
+   * sorting of characters depends on their character layer and on their y pixel
+   * position. By setting a depthOffset you can change the y pixel position for
+   * the depth sorting without changing the actual y pixel position.
+   *
+   * For example: Consider two characters A and B that are on the same character
+   * layer. If char A is on y pixel position 100 and char B is on y pixel
+   * position 120, then char B would be rendered in front of char A. If you set
+   * `depthOffset = -50` for char B then char A would be rendered on top of char
+   * B instead (because the depth relevant y pos of char B is 120 - 50 = 80 and
+   * that of char A is 100).
+   *
+   * @defaultValue `0`
+   */
+  depthOffset?: number;
 }
 
 /**
@@ -476,6 +493,18 @@ export class GridEngine implements IGridEngine {
     gridChar.setOffsetY(offsetY);
   }
 
+  /**
+   * @returns depth-offset for a character.
+   *
+   * @category Character
+   */
+  getDepthOffset(charId: string): number {
+    this.initGuard();
+    const gridChar = this.gridCharacters?.get(charId);
+    if (!gridChar) throw this.createCharUnknownErr(charId);
+    return gridChar.getDepthOffset();
+  }
+
   /**
    * {@inheritDoc IGridEngine.collidesWithTiles}
    *

src/GridEnginePhaser/GridCharacterPhaser/GridCharacterPhaser.test.ts

@@ -701,6 +701,33 @@ describe("GridCharacterPhaser", () => {
       );
     });
 
+    it("sets depth of sprite with offset", () => {
+      const depthOffset = -5;
+      const startPos = { x: 2, y: 2 };
+      const charData = {
+        startPosition: startPos,
+        numberOfDirections: NumberOfDirections.EIGHT,
+        charLayer: "testCharLayer",
+        depthOffset,
+      };
+      const charLayerDepth = 1;
+      const { gridCharPhaser } = createChar(charData, false, true);
+
+      gridEngineHeadless.move("charID", Direction.RIGHT);
+      gridEngineHeadless.update(1000, 10);
+      gridCharPhaser.update(10);
+
+      checkSpriteDepth(
+        spriteMock,
+        spriteMock.displayHeight,
+        charLayerDepth,
+        "0000",
+        depthOffset,
+      );
+
+      expect(gridCharPhaser.getDepthOffset()).toBe(depthOffset);
+    });
+
     it("should set depth of sprite on char layer", () => {
       const startPos = { x: 2, y: 2 };
       const charData = {
@@ -882,8 +909,9 @@ function checkSpriteDepth(
   height: number,
   charLayerDepth: number,
   zeroPrefix: string,
+  depthOffset = 0,
 ) {
-  const pixelDepth = gameObject.y + height;
+  const pixelDepth = gameObject.y + height + depthOffset;
   expect(gameObject.setDepth).toHaveBeenCalledWith(
     +`${charLayerDepth}.${zeroPrefix}${pixelDepth}`,
   );

src/GridEnginePhaser/GridCharacterPhaser/GridCharacterPhaser.ts

@@ -19,6 +19,7 @@ import { LayerVecPos } from "../../Utils/LayerPositionUtils/LayerPositionUtils.j
 
 export class GridCharacterPhaser {
   private customOffset = new Vector2(0, 0);
+  private depthOffset = 0;
 
   private sprite?: Phaser.GameObjects.Sprite;
   private layerOverlaySprite?: Phaser.GameObjects.Sprite;
@@ -48,6 +49,8 @@ export class GridCharacterPhaser {
       charData.offsetY || 0,
     );
 
+    this.depthOffset = charData.depthOffset ?? 0;
+
     this.sprite = charData.sprite;
     this.container = charData.container;
     this.cachedContainerHeight = charData.container?.getBounds().height ?? 0;
@@ -151,6 +154,10 @@ export class GridCharacterPhaser {
     this.updateGridChar();
   }
 
+  getDepthOffset(): number {
+    return this.depthOffset;
+  }
+
   private getEngineOffset(): Vector2 {
     if (!this.sprite) {
       return Vector2.ZERO;
@@ -302,7 +309,7 @@ export class GridCharacterPhaser {
 
   private getPaddedPixelDepthSprite(sprite: Phaser.GameObjects.Sprite): number {
     return Utils.shiftPad(
-      sprite.y + sprite.displayHeight,
+      sprite.y + sprite.displayHeight + this.depthOffset,
       GridTilemapPhaser.Z_INDEX_PADDING,
     );
   }