feat(renderer): Implement getPieceIndexAt Method

docs/API.md

@@ -126,28 +126,30 @@ This document provides a comprehensive guide to the API of the Tridecco Game Boa
       - [Example](#example-52)
     - [`getPieceCoordinates(index)`](#getpiececoordinatesindex)
       - [Example](#example-53)
-    - [`getHexagonCoordinates(col, row)`](#gethexagoncoordinatescol-row)
+    - [`getPieceIndexAt(x, y)`](#getpieceindexatx-y)
       - [Example](#example-54)
-    - [`getTexture(type, key)`](#gettexturetype-key)
+    - [`getHexagonCoordinates(col, row)`](#gethexagoncoordinatescol-row)
       - [Example](#example-55)
-    - [`updateBackground(backgroundUrl)`](#updatebackgroundbackgroundurl)
+    - [`getTexture(type, key)`](#gettexturetype-key)
       - [Example](#example-56)
-    - [`updateGrid(gridUrl)`](#updategridgridurl)
+    - [`updateBackground(backgroundUrl)`](#updatebackgroundbackgroundurl)
       - [Example](#example-57)
-    - [`updateTextures(texturesIndexUrl, texturesAtlasUrl)`](#updatetexturestexturesindexurl-texturesatlasurl)
+    - [`updateGrid(gridUrl)`](#updategridgridurl)
       - [Example](#example-58)
-    - [`updateMap(newMap)`](#updatemapnewmap)
+    - [`updateTextures(texturesIndexUrl, texturesAtlasUrl)`](#updatetexturestexturesindexurl-texturesatlasurl)
       - [Example](#example-59)
-    - [`updateBoard(newBoard)`](#updateboardnewboard)
+    - [`updateMap(newMap)`](#updatemapnewmap)
       - [Example](#example-60)
-    - [`addEventListener(eventType, listener, options)`](#addeventlistenereventtype-listener-options)
+    - [`updateBoard(newBoard)`](#updateboardnewboard)
       - [Example](#example-61)
-    - [`removeEventListener(eventType, listener)`](#removeeventlistenereventtype-listener)
+    - [`addEventListener(eventType, listener, options)`](#addeventlistenereventtype-listener-options)
       - [Example](#example-62)
-    - [`getFPS()`](#getfps)
+    - [`removeEventListener(eventType, listener)`](#removeeventlistenereventtype-listener)
       - [Example](#example-63)
-    - [`destroy()`](#destroy)
+    - [`getFPS()`](#getfps)
       - [Example](#example-64)
+    - [`destroy()`](#destroy)
+      - [Example](#example-65)
 
 ## Import the Library
 
@@ -1846,6 +1848,36 @@ console.log(
 );
 ```
 
+### `getPieceIndexAt(x, y)`
+
+```javascript
+getPieceIndexAt(x, y);
+```
+
+**Description:**
+
+Returns the board position index at the given canvas coordinates using the internal hitmap. If the coordinates do not intersect any position, `-1` is returned.
+
+**Parameters:**
+
+- `x` (number): The x-coordinate on the renderer canvas (in pixels).
+- `y` (number): The y-coordinate on the renderer canvas (in pixels).
+
+**Returns:**
+
+- `number`: The 0-based position index at the specified coordinates, or `-1` if none is found.
+
+#### Example
+
+```javascript
+const index = renderer.getPieceIndexAt(150, 220);
+if (index !== -1) {
+  console.log(`Found position at index: ${index}`);
+} else {
+  console.log('No position at these coordinates.');
+}
+```
+
 ### `getHexagonCoordinates(col, row)`
 
 ```javascript

src/renderer.js

@@ -1358,7 +1358,7 @@
    */
   _renderPreviewingPiecePositions(context) {
     for (const [index, value] of this._previewingPositions) {
       const [_, piece, fillColor = DEFAULT_PREVIEW_FILL_COLOR] = value;
       this._renderPreviewPiece(context, index, piece, fillColor);
     }
   }
@@ -1713,6 +1713,20 @@
     return this._getPieceCoordinates(index);
   }
 
+  /**
+   * @method getPieceIndexAt - Retrieves the index of a piece at the specified coordinates.
+   * @param {number} x - The x coordinate of the piece.
+   * @param {number} y - The y coordinate of the piece.
+   * @returns {number} - The index of the piece at the specified coordinates, or -1 if no piece is found.
+   */
+  getPieceIndexAt(x, y) {
+    return this._getPositionFromHitmap(
+      this._layersManager.getLayer('hitmap').context,
+      x,
+      y,
+    );
+  }
+
   /**
    * @method getHexagonCoordinates - Retrieves the coordinates of a hexagon on the board.
    * @param {number} col - The column index of the hexagon.
@@ -1922,10 +1936,10 @@
       this._layersManager.clear('pieces');
       this._renderPlacedPieces(context);
     });
     this._layersManager.requestAnimationFrame('preview-pieces', (context) => {
       this._layersManager.clear('preview-pieces');
     });
     this._layersManager.requestAnimationFrame('preview-hexagons', (context) => {
       this._layersManager.clear('preview-hexagons');
     });
   }
@@ -1993,14 +2007,14 @@
     if (this._resizeObserver) {
       try {
         this._resizeObserver.disconnect();
       } catch (e) {}
       this._resizeObserver = null;
     }
 
     if (this._mutationObserver) {
       try {
         this._mutationObserver.disconnect();
       } catch (e) {}
       this._mutationObserver = null;
     }
 
@@ -2058,7 +2072,7 @@
     ) {
       try {
         this._container.removeChild(this._canvas);
       } catch (e) {}
     }
     this._canvas = null;
     this._context = null;