README

地图

此组件提供了用于存储、分析和传输游戏地图数据的基本DTO，以及从任意格式加载数据的加载器。

安装

PewPew Map 以Composer存储库的形式提供，可以在项目的根目录下使用以下命令进行安装：

$ composer require pew-pew/map

更详细的安装说明请在此处查看。

用法

以下是一个可用的组件值对象列表、它们的参数和方法。

大小

大小对象负责任意对象的物理二维尺寸。

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

大小面积

获取由大小提供对象的总体面积。

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

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

按ID定位

特别是，任何3x3对象都可以以下列形式表示，其中每个数字表示相应的标识符

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

任何坐标都可以表示为一个标量ID。要按此ID获取位置，您可以使用以下方法。

$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 = new \PewPew\Map\Data\Position\IntPosition(
    x: 1, // optional, default = 0
    y: 0, // optional, default = 0
);

层

层是地图元素之一，可以定义要绘制的对象集、碰撞集、触发集或其他任何内容。

每个层包含地图内的位置及其自己的大小。

$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,
    ),
);

瓦片层

对于包含瓦片的层，您应该创建相应的 PewPew\Map\Data\TilesLayer 对象。除了 size 和 position 之外，它还包含一个瓦片ID数组。

瓦片数组的尺寸直接依赖于层的尺寸，可以使用 Size::getArea() 方法获取。

注意

对于3x3层，使用的瓦片元素数量对应于9。如果有多余的瓦片，则它们不会被使用。

注意

如果任何瓦片ID缺失，则它对应于0，表示没有瓦片。

$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 = 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,
    ),
);

tileIdStartsAt 构造函数参数负责瓦片的起始ID，因此具有 tileIdStartsAt: 42 的2x2瓦片集将包含 42、43、44 和 45 瓦片ID。

警告

"tileIdStartsAt" 不能小于1。

瓦片ID可用性

要检查瓦片ID的可用性，您可以使用 containsId() 方法。

$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)

瓦片位置

$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 }

更新瓦片路径名

$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")

示例

示例地图

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);

预期输出

{
    "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 }
}