kaplay-plugin-tiled/README.md

KAPLAY plugin for Tiled maps

# kaplay-plugin-tiled

[![NPM](https://nodei.co/npm/kaplay-plugin-tiled.svg)](https://www.npmjs.com/package/kaplay-plugin-tiled)

[![NPM version](https://img.shields.io/npm/v/kaplay-plugin-tiled.svg)](https://www.npmjs.com/package/kaplay-plugin-tiled)
[![build](https://github.com/remarkablegames/kaplay-plugin-tiled/actions/workflows/build.yml/badge.svg)](https://github.com/remarkablegames/kaplay-plugin-tiled/actions/workflows/build.yml)
[![codecov](https://codecov.io/gh/remarkablegames/kaplay-plugin-tiled/graph/badge.svg?token=WriHyIpFCh)](https://codecov.io/gh/remarkablegames/kaplay-plugin-tiled)

[KAPLAY](https://kaplayjs.com/) plugin for loading finite orthogonal [Tiled](https://www.mapeditor.org/) JSON maps.

## Prerequisites

Install [kaplay](https://www.npmjs.com/package/kaplay):

```sh
npm install kaplay
```

## Install

[NPM](https://www.npmjs.com/package/kaplay-plugin-tiled):

```sh
npm install kaplay-plugin-tiled
```

[CDN](https://unpkg.com/browse/kaplay-plugin-tiled/):

```html
<script src="https://unpkg.com/kaplay-plugin-tiled@latest/dist/plugin.umd.js"></script>
```

## Usage

Import the plugin:

```ts
import kaplay from 'kaplay';
import { tiledPlugin } from 'kaplay-plugin-tiled';

const k = kaplay({
  plugins: [tiledPlugin],
});
```

Use the plugin:

```ts
import level from './level.json';
import tilesetUrl from './tileset.png';

k.loadSprite('tileset', tilesetUrl);

k.onLoad(() => {
  k.addTiledMap(level, {
    sprite: 'tileset',
    objects: [
      {
        match: { properties: { collides: true } },
        comps: ({ width, height }) => [
          k.area({
            shape: new k.Rect(k.vec2(), width, height),
          }),
          k.body({ isStatic: true }),
        ],
      },
    ],
  });
});
```

If you use KAPLAY globals, load the ambient types explicitly:

```ts
import 'kaplay/global';
import 'kaplay-plugin-tiled/global';
```

This adds the ambient type for `addTiledMap(...)`. The runtime global still depends on KAPLAY's global setup.

The current implementation is intentionally small:

- finite orthogonal Tiled JSON only
- 1 tileset per map
- visible tile layers plus optional `tiles` and `objects` matchers for extra spawned components

To load the plugin using a script:

```html
<script src="https://unpkg.com/kaplay@latest/dist/kaplay.js"></script>
<script src="https://unpkg.com/kaplay-plugin-tiled@latest/dist/plugin.umd.js"></script>

<script>
  const k = kaplay({
    plugins: [KaplayPluginTiled.tiledPlugin],
  });
</script>
```

## Release

Release is automated with [Release Please](https://github.com/googleapis/release-please).

## License

[MIT](https://github.com/remarkablegames/kaplay-plugin-tiled/blob/master/LICENSE)