Welcome to the Grid Engine plugin! This Phaser 3 plugin adds grid-based movement to your tilemap game. Your characters will be able to only move in whole tile sizes, locked to the x-y grid!

Features

Basic

• Grid-based movement, of course!
• Tile-based collision detection
• NEW! - Headless mode (allows running it independently of Phaser)
• Diagonal movement (8 directions)
• Isometric maps
• Multiple character layers
• Multi-tile characters

Movement / Pathfinding

• Pathfinding (for both NPCs and the player)
• Random movement (can also limit to a radius)
• Following other characters
• Collision groups

📖 Read our most current documentation.

➡️ You can try/download a list of examples.

👾 Join our discord.

🛠 Also check out the Chrome DevTools plugin.

Installation

Installing the Grid Engine plugin is simple.

NOTE: For TypeScript check out this example repository.

NPM

npm i --save grid-engine

And then import via:

import { GridEngine } from "grid-engine";

Web

<!-- Download the .zip and copy GridEngine.min.js from dist directory -->
<script src="GridEngine.min.js"></script>

Then, inside your Phaser game config...

const gameConfig = {
  // ...

  plugins: {
    scene: [
      {
        key: "gridEngine",
        plugin: GridEngine,
        mapping: "gridEngine",
      },
    ],
  },

  // ...
};

const game = new Phaser.Game(gameConfig);

Now you're all set to start using Grid Engine in your scenes!

function create() {
  // ...

  const gridEngineConfig = {
    characters: [
      {
        id: "player",
        sprite: playerSprite,
        walkingAnimationMapping: 6,
      },
    ],
  };

  this.gridEngine.create(tilemap, gridEngineConfig);

  // ...
}

Import Helpers

Besides the GridEngine main class, you can also import several helpers. For example there is the directionFromPos helper function that gives you a Direction from a source to a target position.

If you are importing the NPM module you can import it like:

import {
  GridEngine, // GridEngine main class
  directionFromPos, // One of the GridEngine helpers,
  // ...
} from "grid-engine";

If you are using the web version (import via <script>), all exported functions and classes besides GridEngine are stored in a global variable GridEngineImports.

So you would use it as follows:

GridEngineImports.directionFromPos(/*...*/);

Projects using Grid Engine

• Build a Snowman
• Defynia
• Fallout Clone [Play] [Repo]

If you have a project that is using Grid Engine and that you would like to see in this list, post it in the #showcase channel on our Discord.

Special Thanks

Raiper34, splashsky, therebelrobot, xLink,

License

Apache 2.0