Grid Engine

Grid Engine is a library for managing object positioning and movement on a 2-dimensional square grid using JavaScript or TypeScript. It separates the underlying grid logic from the visual representation.

Key abstractions include:

• Tiles and Tile Positions: The grid is composed of tiles (squares/fields). A tile position refers to the specific coordinate of an object on the grid, as opposed to its pixel-based position.
• Characters: All game objects managed by the engine are called characters. This is a generic term that includes moving entities (like players), items, or stationary objects that block movement.
• Renderers: A renderer is the software layer that visualizes the grid logic. Grid Engine is renderer-agnostic. It provides a Phaser.js plugin, but can be used with custom renderers (e.g., ASCII for terminals, Three.js for 3D, or Vue.js for web UIs) or in a headless mode (no renderer) for server-side logic via Node.js.

A renderer is a piece of software that visualizes the state of Grid Engine. To create one, you typically implement a class that:

1. Holds a reference to the GridEngineHeadless instance and the Tilemap.
2. Iterates through the tilemap dimensions using tilemap.getHeight() and tilemap.getWidth().
3. Queries the engine state for each position using gridEngine.getCharactersAt(pos) and gridEngine.isTileBlocked(pos).
4. Updates a DOM element (or other output) with the resulting representation.

import { GridEngineHeadless, Tilemap } from "grid-engine";

export class AsciiRenderer {
  constructor(
    private containerId: string,
    private gridEngine: GridEngineHeadless,
    private tilemap: Tilemap
  ) {}

  render(): void {
    const strArr: string[] = [];
    for (let r = 0; r < this.tilemap.getHeight(); r++) {
      for (let c = 0; c < this.tilemap.getWidth(); c++) {
        const pos = { x: c, y: r };
        if (this.gridEngine.getCharactersAt(pos).length > 0) {
          strArr.push("c");
        } else if (this.gridEngine.isTileBlocked(pos)) {
          strArr.push("#");
        } else {
          strArr.push(".");
        }
      }
      strArr.push("\n");
    }
    this.renderStr(strArr.join(""));
  }

  private renderStr(str: string): void {
    const container = document?.getElementById(this.containerId);
    if (container) {
      container.innerHTML = `<pre>${str}</pre>`;
    }
  }
}

Collision layers are a technique used to separate collision logic from graphical tiles. Instead of assigning collision properties directly to your visual tileset, you create a dedicated 'collision tileset' containing tiles that represent different collision boundaries (e.g., 4-direction or 8-direction blocking).

Workflow:

1. Create a Collision Tileset: Design a tileset where tile properties (like red borders) indicate which directions are blocked.
2. Assign Tile Properties: In your map editor (like Tiled), assign the corresponding collision properties to these tiles.
3. Add a Collision Layer: Create a new layer in your map specifically for these collision tiles.
4. Configure Layer Visibility: Set the layer opacity (e.g., to 0.5) to help visualize collisions during development, or hide the layer entirely when you don't need to see them.
5. Placement: Fill the layer with tiles to define the walkable/non-walkable areas of your map. This allows you to use the same visual tile in different collision contexts by simply placing different collision tiles in the collision layer.

Grid Engine supports four algorithms. Your choice depends on your specific needs:

Important Note on 8-Directional Movement: Avoid JPS for 8-directional movement as it is currently the slowest option and may not provide correct results. Use BFS or Bidirectional Search instead if you do not require tile weights.

The headless version of Grid Engine does not require Phaser.js but requires a tilemap that implements the Tilemap interface.

Using ArrayTilemap

You can create a simple tilemap from an array of integers where 0 is non-blocking and 1 is blocking.

import { GridEngineHeadless, ArrayTilemap } from "grid-engine";

const gridEngineHeadless = new GridEngineHeadless();

const tilemap = new ArrayTilemap({
  someLayer: {
    data: [
      [0, 0, 0, 0],
      [0, 1, 1, 0],
      [0, 1, 1, 0],
      [0, 0, 0, 0],
    ],
  },
});

gridEngineHeadless.create(tilemap, { characters: [{ id: "player" }] });

Using TiledTilemap

To use maps exported from the Tiled map editor, use the TiledTilemap implementation.

import { GridEngineHeadless, TiledTilemap } from "grid-engine";
import * as someTilemap from "./path/to/tilemap.json";

const gridEngineHeadless = new GridEngineHeadless();
const tilemap = new TiledTilemap(someTilemap);

gridEngineHeadless.create(tilemap, { characters: [{ id: "player" }] });

Note: If using the web version via <script>, access these classes via GridEngineImports.GridEngineHeadless and GridEngineImports.ArrayTilemap or GridEngineImports.TiledTilemap.