Add 'labelGrid' property for cell-specific labels

Author: Perlkonig

README.md

@@ -6,11 +6,11 @@ This private NPM module graphically renders game states. This repository houses
 
 Currently the only supported output format is SVG. The library has been tested and works correctly in Chrome, Firefox, Opera, and Edge.
 
-[A playground/demo area is now available.](https://renderer.dev.abstractplay.com)
+[A playground/demo area is now available.](https://renderer.dev.abstractplay.com) The [Abstract Play Designer](https://designer.abstractplay.com/) is another place you can interact with the rendering engine.
 
 ## Usage
 
-In the browser, simply load `APRender.js` via a `<script>` tag. For a concrete example, [see the playground](https://renderer.dev.abstractplay.com). The [Abstract Play Designer](https://designer.abstractplay.com/) is another place you can interact with the rendering engine.
+In the browser, simply load `APRender.js` via a `<script>` tag. For a concrete example, [see the playground](https://renderer.dev.abstractplay.com).
 
 From within Node, simply import the variables and functions you need. Both methods give you access to the same API.
 

src/renderers/_base.ts

@@ -2967,7 +2967,6 @@ export abstract class RendererBase {
             offset = 1;
         }
 
-
         const myHex = defineHex({
             offset,
             orientation,
@@ -3053,6 +3052,11 @@ export abstract class RendererBase {
             rowLabels.reverse();
         }
 
+        let labelGrid: string[][]|undefined;
+        if ("labelGrid" in this.json.board && this.json.board.labelGrid !== undefined && this.json.board.labelGrid !== null && Array.isArray(this.json.board.labelGrid)) {
+            labelGrid = this.json.board.labelGrid.map(row => [...row]);
+        }
+
         let labelColour = this.options.colourContext.labels;
         if ( ("labelColour" in this.json.board) && (this.json.board.labelColour !== undefined) ) {
             labelColour = this.resolveColour(this.json.board.labelColour) as string;
@@ -3073,13 +3077,23 @@ export abstract class RendererBase {
             const { x, y } = hex;
             const used = cells.use(symbolPoly).size(cellsize, cellsize).translate(x, y);
             if ( ( (! this.json.options) || (! this.json.options.includes("hide-labels") ) ) && (labelStyle === "internal") ) {
-                const components: string[] = [];
-                components.push(columnLabels[hex.col]);
-                components.push(rowLabels[hex.row]);
-                if (/^\d+$/.test(components[0])) {
-                    components.reverse();
+                let label: string;
+                if (labelGrid === undefined) {
+                    const components: string[] = [];
+                    components.push(columnLabels[hex.col]);
+                    components.push(rowLabels[hex.row]);
+                    if (/^\d+$/.test(components[0])) {
+                        components.reverse();
+                    }
+                    label = components.join("");
+                } else {
+                    label = "?";
+                    if (hex.row < labelGrid.length) {
+                        if (hex.col < labelGrid[hex.row].length) {
+                            label = labelGrid[hex.row][hex.col];
+                        }
+                    }
                 }
-                const label = components.join("");
 
                 let labelX = corners[5].x;
                 let labelY = corners[5].y;
@@ -3118,7 +3132,7 @@ export abstract class RendererBase {
 
         // external labels, if requested
         // Add board labels
-        if (labelStyle === "external") {
+        if (labelStyle === "external" && labelGrid === undefined) {
             let hideHalf = false;
             if (this.json.options?.includes("hide-labels-half")) {
                 hideHalf = true;

src/schemas/schema.d.ts

@@ -362,7 +362,7 @@ export interface BoardBasic {
    */
   strokeWeight?: number;
   /**
-   * The opacity of lines drawn to construct the board.
+   * The opacity of lines drawn for board labels.
    */
   labelOpacity?: number;
   /**
@@ -432,6 +432,10 @@ export interface BoardBasic {
    * Only meaningful for `hex-of-*` boards and generates configurations where the sides alternate between two sizes. Mutually exclusive with `half`.
    */
   alternatingSymmetry?: boolean;
+  /**
+   * The only way of applying arbitrary labels to cells. Provide the labels in a grid, just as you would the pieces: top to bottom, left to right.
+   */
+  labelGrid?: string[][];
   /**
    * An optional array of strings to override the default column labeling.
    */

src/schemas/schema.json

@@ -1848,7 +1848,7 @@
                     "default": 1
                 },
                 "labelOpacity": {
-                    "description": "The opacity of lines drawn to construct the board.",
+                    "description": "The opacity of lines drawn for board labels.",
                     "type": "number",
                     "minimum": 0,
                     "maximum": 1,
@@ -1939,6 +1939,16 @@
                     "description": "Only meaningful for `hex-of-*` boards and generates configurations where the sides alternate between two sizes. Mutually exclusive with `half`.",
                     "type": "boolean"
                 },
+                "labelGrid": {
+                    "description": "The only way of applying arbitrary labels to cells. Provide the labels in a grid, just as you would the pieces: top to bottom, left to right.",
+                    "type": "array",
+                    "items": {
+                        "type": "array",
+                        "items": {
+                            "type": "string"
+                        }
+                    }
+                },
                 "columnLabels": {
                     "description": "An optional array of strings to override the default column labeling.",
                     "type": "array",