README

Map

This component provides basic DTOs for storing, analyzing and transmitting game maps data, as well as loaders for loading this data from arbitrary formats.

Installation

PewPew Map is available as Composer repository and can be installed using the following command in a root of your project:

$ composer require pew-pew/map

More detailed installation instructions are here.

Usage

Below is a list of available component value objects, their parameters and methods.

Size

The size object is responsible for the physical two-dimensional dimensions of arbitrary objects.

$size = new \PewPew\Map\Data\Size\IntSize(
    width: 100, // optional, default = 1
    height: 50, // optional, default = 1
);

Size Area

Get the total area of an object provided by size.

$size = new \PewPew\Map\Data\Size\IntSize(100, 50);

echo $size->getArea(); // 5000

Position By ID

In particular, any 3x3 object can be represented in the following form, where each number denotes the corresponding identifier:

┌─────┬─────┬─────┐   ┌─────┬─────┬─────┐
│ 0x0 │ 1x0 │ 2x0 │   │  0  │  2  │  3  │
├─────┼─────┼─────┤   ├─────┼─────┼─────┤
│ 0x1 │ 1x1 │ 2x1 │ → │  4  │  5  │  6  │
├─────┼─────┼─────┤   ├─────┼─────┼─────┤
│ 0x2 │ 1x2 │ 2x2 │   │  7  │  8  │  9  │
└─────┴─────┴─────┘   └─────┴─────┴─────┘

Any coordinates can be represented as a scalar ID. To obtain a position by this ID, you can use the following methods.

$size = new \PewPew\Map\Data\Size\IntSize(3, 3);

echo $size->getX(id: 1); // X = 1
echo $size->getY(id: 1); // Y = 0

echo $size->getPosition(id: 1); // object<Position> { x: 1, y: 0 }

Position

A position is a primitive object that provides coordinates within an object.

The object does not provide any additional methods.

$position = new \PewPew\Map\Data\Position\IntPosition(
    x: 1, // optional, default = 0
    y: 0, // optional, default = 0
);

Layers

A layer is one of the map elements that can define a set of objects to draw, a set of collisions, a set of triggers, or anything else.

Each layer contains a position within the map and its own size.

$layer = new \PewPew\Map\Data\Layer(
    // optional, default = { width: 1, height: 1 }
    size: new \PewPew\Map\Data\Size\IntSize(
        width: 3,
        height: 3,
    ),
    // optional, default = { x: 0, y: 0 }
    position: new \PewPew\Map\Data\Position\IntPosition(
        x: 0, 
        y: 0,
    ),
);

Tiles Layer

For a layer containing tiles, you should create a corresponding PewPew\Map\Data\TilesLayer object. In addition to size and position, it also contains an array of tile IDs.

The size of the tiles array directly depends on the size of the layer and can be obtained using the Size::getArea() method.

Note

For the 3x3 layer, the number of used tile elements corresponds to 9. If there are extra tiles, they are not used.

Note

If any tile ID is missing, then it corresponds to 0, that means no tile.

$layer = new \PewPew\Map\Data\Layer\TilesLayer(
    tiles: [
        0, 2, 1,
        1, 2, 1,
        0, 0, 1,
    ],
    size: new \PewPew\Map\Data\Size\IntSize(3, 3),
);

TileSet

A tile set is an object containing information about an image containing a set of other images (tiles).

$tileSet = new \PewPew\Map\Data\TileSet(
    // required
    pathname: __DIR__ . '/tiles.png',
    // optional, default = 1
    tileIdStartsAt: 1,
    // optional, default = { width: 1, height: 1 }
    size: new \PewPew\Map\Data\Size\IntSize(
        width: 3,
        height: 3,
    ),
);

The tileIdStartsAt constructor parameter is responsible for the starting ID of the tile, so a 2x2 tile set with tileIdStartsAt: 42 will contains 42, 43, 44 and 45 tile IDs.

Warning

The "tileIdStartsAt" cannot be less than 1.

Tile ID Availability

To check the availability of a tile ID, you can use the containsId() method.

$set = new \PewPew\Map\Data\TileSet(
    pathname: ...,
    tileIdStartsAt: 1,
    size: new \PewPew\Map\Data\Size\IntSize(1, 1),
);

$set->containsId(tileId: 0); // bool(false)
$set->containsId(tileId: 1); // bool(true)
$set->containsId(tileId: 2); // bool(false)

Position Of A Tile

$set = new \PewPew\Map\Data\TileSet( ... );

$set->getX(tileId: 1);          // X = 0
$set->getY(tileId: 1);          // Y = 0

$set->getPosition(tileId: 1);   // object<Position> { x: 0, y: 0 }

Updating Tile Pathname

$previous = new \PewPew\Map\Data\TileSet(
    pathname: __DIR__ . '/tiles-1.png',
);

$new = $previous->withPathname(
    pathname: __DIR__ . '/tiles-2.png',
);

echo $previous->pathname; // string(".../tiles-1.png")
echo $new->pathname; // string(".../tiles-2.png")

Examples

Example map

use PewPew\Map\Data\Layer\TilesLayer;
use PewPew\Map\Data\Size\IntSize;
use PewPew\Map\Data\TileSet;
use PewPew\Map\Map;

$map = new Map(
    layers: [
        new TilesLayer(
            tiles: [
                0, 1, 2,
                0, 1, 1,
                1, 2, 1,
            ],
            size: new IntSize(3, 3),
        ),
    ],
    tileSets: [
        new TileSet(
            pathname: __DIR__ . '/tiles.png',
            size: new IntSize(2, 2),
        ),
    ],
    size: new IntSize(3, 3),
);

echo \json_encode($map);

Expected output:

{
    "layers": [
        {
            "size": { "width": 3, "height": 3 },
            "position": { "x": 0, "y": 0 },
            "tiles": [
                0, 1, 2,
                0, 1, 1,
                1, 2, 1
            ]
        }
    ],
    "tileSets": [
        {
            "pathname": "..path/to/map/tiles.png",
            "tileIdStartsAt": 1,
            "size": { "width": 2, "height": 2 }
        }
    ],
    "size": { "width": 3, "height": 3 }
}