Package Exports

@telazer/phaser-image-helper
@telazer/phaser-image-helper/dist/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@telazer/phaser-image-helper) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

Phaser Image Helper

A helper library for Phaser image manipulation that provides utilities for handling image loading, nine-slice operations, and image data URL generation.

Installation

npm install phaser-image-helper

Configure

You can import the ImageHelper in different ways:

Best way to use this helper is using LoaderScene approach

LoaderScene

// Import
import ImageHelper from "phaser-image-helper";

// Initialize the helper with your Phaser scene and image data
export class InitScene extends Phaser.Scene {
  constructor() {
    super({ key: SCENE_KEYS.INIT });
  }

  preload() {
    // Use init() inside a phaser preload() of the LoaderScene
    await ImageHelper.init(scene, [
      {
        key: "ball",
        url: "assets/ball.png",
      },
      {
        key: "hero",
        url: "assets/hero.png",
      },
    ]);
  }

  async create() {
    // Wait for initialization to complete
    // phaser preload is not supporting async
    // this way you can check if it's ready
    await ImageHelper.isReady();
    this.scene.start("game-scene");
  }
}

GameScene

import ImageHelper from "phaser-image-helper";

export class GameScene extends Phaser.Scene {
  constructor() {
    super({ key: SCENE_KEYS.GAME });
  }

  init() {
    // Update the scene of the ImageHelper if the scene has changed
    ImageHelper.updateScene(this);
  }
}

Usage

Basic Image Loading

// As phaser sprite
this.scene.add(0, 0, "ball");

// Get image data URL to use in DOM
const imageEl = document.createElement("img");
imageEl.src = ImageHelper.url("ball");

Parsing

If you have spritesheet file where multiple assets bundled in a single image, you can add more configuration inside the init() function.

await ImageHelper.init(scene, [
  {
    key: "spritesheet",
    url: "assets/spritesheet.png",
    grid: [16, 16], // Default grid to use in parse
    parse: [
      { key: "extracted_image_1", slice: { pos: 0 } },
      { key: "extracted_image_2", slice: { pos: 1 } },
      { key: "extracted_image_3", slice: { pos: 2 } },
    ],
  },
]);

Selecting rectangular area by positions.

Assume that you have 64px, 64px spritesheet where the grid is 16px, 16px. The grid will parse the image and use the positions as their grid order.

 0  1  2  3
 4  5  6  7
 8  9 10 11
12 13 14 15

pos can take numbers array where the first item the starting position of the area and the second is end position.

Using 5 to 10 will result as the central 2x2 area of the image. 5, 6, 9 and 10 included

await ImageHelper.init(scene, [
  {
    key: "spritesheet",
    url: "assets/spritesheet.png",
    grid: [16, 16], // Default grid to use in parse
    parse: [{ key: "extracted_area_1", slice: { pos: [5, 10] } }],
  },
]);

Now you have another key to use as you like extracted_area_1

You can define different grid options inside the parse definition. The parent grid will be inherited and the parse item grid will override the options.

await ImageHelper.init(scene, [
  {
    key: "spritesheet",
    url: "assets/spritesheet.png",
    grid: [32, 32],
    parse: [
      {
        key: "extracted_area_1",
        slice: {
          grid: [16, 16], // this will be used just for the extracted_area_1
          pos: [5, 10],
        },
      },
      {
        key: "extracted_area_2",
        slice: {
          pos: 3, // no grid supported, [32, 32] will be used as default
        },
      },
    ],
  },
]);

Instead of using grid and position, rectangle can be defined directly

await ImageHelper.init(scene, [
  {
    key: "spritesheet",
    url: "assets/spritesheet.png",
    grid: [16, 16], // Default grid to use in parse
    parse: [
      {
        key: "extracted_rect",
        rect: { x: 16, y: 16, width: 32, height: 32 },
      },
    ],
  },
]);

NineSlice

await ImageHelper.init(scene, [
  {
    key: "nineslice_button",
    url: "./assets/images/nineslice_button.png",
    nineSlice: {
      topHeight: 3,
      centerHeight: 1,
      bottomHeight: 6,
      leftWidth: 2,
      centerWidth: 1,
      rightWidth: 2,
      fill: "repeat",
      scale: "10px",
      pixelated: true,
    },
  },
]);

// This will return phaser nineslice object
ImageHelper.nineSlice("nineslice_button", {
  x: 600,
  y: 100,
  width: 100,
  height: 50,
});

// Or this will provide src[] where all the parsed images inside
// and all the other parameters that can be used to structure the nineslice
//
// src[]: string[];
// topHeight: number;
// centerHeight: number;
// bottomHeight: number;
// leftWidth: number;
// centerWidth: number;
// rightWidth: number;
// pixelated?: boolean;
// fill?: 'repeat' | 'stretch';
// scale?: string;

MewImageHelper.nineSliceData("nineslice_button");

If you have nineslice images in a spritesheet, parse option can be used as well

{
    key: 'ns_all',
    url: './assets/images/ns_all.png',
    nineSlice: {
        topHeight: 3,
        centerHeight: 1,
        bottomHeight: 6,
        leftWidth: 2,
        centerWidth: 1,
        rightWidth: 2,
    },
    grid: [5, 10],
    parse: [
        {
            key: 'ns_green',
            slice: { pos: 0 },
            nineSlice: true,
        },
        {
            key: 'ns_blue',
            slice: { pos: 0 },
            nineSlice: {
                topHeight: 3,
                centerHeight: 1,
                bottomHeight: 6,
                leftWidth: 2,
                centerWidth: 1,
                rightWidth: 2,
                pixelated: true,
            },
        },
    ]
}

As before, nineSlice: true will flag the object to parse it into nineslice with using parent options where specific options can be supported within the object itself.

Extruded and Normal

Instead of creating separated definition for the related base64 images, you can collect them under the same key. This will automatically create keys with suffix _extruded or _normal

await ImageHelper.init(scene, [
  {
    key: "spritesheet",
    url: "assets/spritesheet.png",
    extruded: "assets/spritesheet_extruded.png",
    normal: "assets/spritesheet_normal.png",
  },
]);

Features

Asynchronous image loading
Nine-slice image support
Image data URL generation
Support for extruded and normal map textures
Grid-based image slicing
DOM-friendly data URLs

Development

Clone the repository
Install dependencies:
```
npm install
```
Build the project:
```
npm run build
```
Run tests:
```
npm test
```

License

ISC