New Tiled Plugin Features per User Feedback (#485)

New tile methods for convenience, all of these methods are also available at the layer level
* `TiledResource.getTilesByPoint` - Returns any excalibur Tile instances and any metadata for a tile below the world space point provided
* `TiledResource.getTileMetadataByClassName` - renamed from `getTilesByClassname`. This returns the Tiled metadata for a tile by classname.
* `TiledResource.getTileMetadataByProperty` - renamed from `getTilesByProperty`. This returns returns the Tiled metadata for a tile by property.
* `TiledResource.getTilesByGid` - get the Excalibur Tile instances and any Tiled metadata for a matching tile by global id
* `TiledResource.getTilesByClassName` - get the Excalibur Tile instances and any Tiled metadata for a mathcing tile by classname
* `TiledResource.getTilesByProperty` - get the Excalibur Tile instances and and any Tile metadata for a matching property.

* Entity factories can now be defined after load, but before adding to the scene!

This PR adds

* [x] The ability to run entity factories after load
* [x] Getting all Excalibur Tile instances that match a gid
* [x] Getting all Excalibur Tile instances that match a class name
* [x] Getting all Excalibur Tile instances that match a property

.github/workflows/release.yml

@@ -0,0 +1,30 @@
+name: Release to NPM
+on:
+ release:
+ types: [published]
+
+env:
+ GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+ NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+
+jobs:
+ build:
+ uses: ./.github/workflows/build.yml
+ deploy_release:
+ name: Publish npm package
+ needs: [build]
+ runs-on: [ubuntu-latest]
+
+ steps:
+ - uses: actions/checkout@v4
+ with:
+ submodules: true
+ fetch-depth: 100
+ - uses: actions/setup-node@v4
+ with:
+ node-version-file: '.nvmrc'
+ registry-url: 'https://registry.npmjs.org'
+ cache: npm
+ - run: npm ci
+ - run: npm run build
+ - run: npm publish --access public

README.md

@@ -31,7 +31,7 @@ game.start(loader).then(() => {
 
 ## Documentation
 
-For information on how to use the plugin visit https://beta.excaliburjs.com/docs/plugin/tiled-plugin
+For information on how to use the plugin visit https://excaliburjs.com/docs/plugin/tiled-plugin
 
 ## Contributing
 

example/formats/formats.ts

@@ -101,6 +101,7 @@ const start = (mapFile: string) => {
  const map = new TiledResource(mapFile, { 
  startZIndex: -2
  });
+ (window as any).tiledMap = map;
  const playercube = new ImageSource('./player-cube.png', true, ImageFiltering.Blended);
  const loader = new ex.Loader([map, playercube]);
 

package.json

@@ -1,6 +1,6 @@
 {
  "name": "@excaliburjs/plugin-tiled",
- "version": "0.29.0-alpha.1",
+ "version": "0.29.0-alpha.2",
  "description": "excalibur-tiled provides Tiled map editor integration with Excalibur.js",
  "main": "dist/excalibur-tiled.min.js",
  "typings": "dist/src/index.d.ts",
@@ -50,7 +50,7 @@
  "@types/pako": "1.0.7",
  "@types/webpack-env": "1.18.4",
  "cross-env": "7.0.3",
- "excalibur": "~0.28.5",
+ "excalibur": "~0.29.0-alpha.870",
  "http-server": "14.1.1",
  "jasmine-core": "5.1.1",
  "json-diff": "1.0.6",
@@ -76,7 +76,7 @@
  "zstddec": "0.1.0"
  },
  "peerDependencies": {
- "excalibur": "~0.28.5"
+ "excalibur": "~0.29.0-alpha.870"
  },
  "optionalDependencies": {
  "jsdom": "^23.2.0"

src/deprecated/tiled-layer-component.ts

@@ -4,6 +4,7 @@ import { TiledLayer } from "./tiled-layer";
 /**
  * @deprecated
  */
+// @ts-ignore
 export class TiledLayerComponent extends Component<'ex.tiledlayer'> {
  public readonly type = "ex.tiledlayer";
  constructor(public layer: TiledLayer) {

src/deprecated/tiled-map-resource.ts

@@ -184,6 +184,7 @@ export class TiledMapResource implements Loadable<TiledMap> {
  // FIXME no ellipse support yet for colliders in isometric
  actor.collider.useCircleCollider(collider.radius);
  }
+ // @ts-ignore
  actor.addComponent(new TiledObjectComponent(collider.tiled));
  scene.add(actor);
  if (collider.zIndex) {
@@ -238,6 +239,7 @@ export class TiledMapResource implements Loadable<TiledMap> {
  label.color = Color.fromHex(text.text?.color ?? '#000000');
  label.collider.set(Shape.Box(text.width ?? 0, text.height ?? 0));
  label.body.collisionType = CollisionType.PreventCollision;
+ // @ts-ignore
  label.addComponent(new TiledObjectComponent(text));
 
  label.z = this._calculateZIndex(text, objectLayer);
@@ -293,6 +295,7 @@ export class TiledMapResource implements Loadable<TiledMap> {
  actor.collider.clear();
  actor.collider.set(new CompositeCollider(colliders));
  }
+ // @ts-ignore
  actor.addComponent(new TiledObjectComponent(tile));
  actor.graphics.anchor = this.isIsometric() ? vec(.5, 1) : vec(0, 1);
  // respect tile size on sprite
@@ -710,6 +713,7 @@ export class TiledMapResource implements Loadable<TiledMap> {
  columns: this.data.width,
  rows: this.data.height
  });
+ // @ts-ignore
  tileMapLayer.addComponent(new TiledLayerComponent(layer));
  if (layer.rawLayer.parallaxx || layer.rawLayer.parallaxy) {
  const factor = vec(layer.rawLayer.parallaxx ?? 1.0, layer.rawLayer.parallaxy ?? 1.0);

src/deprecated/tiled-object-component.ts

@@ -4,6 +4,7 @@ import { TiledObject } from "./tiled-object";
 /**
  * @deprecated
  */
+// @ts-ignore
 export class TiledObjectComponent extends Component<'ex.tiledobject'> {
  public readonly type = "ex.tiledobject";
  constructor(public object: TiledObject) {

src/resource/excalibur-properties.ts

@@ -3,6 +3,9 @@
  * Special excalibur properties
  */
 export const ExcaliburTiledProperties = {
+ TileData: {
+ Tiled: 'ex-tiled'
+ },
  ZIndex: {
  /**
  * Override the default z-index based on the ordering in Tiled

src/resource/iso-tile-layer.ts

@@ -8,6 +8,7 @@ import { ExcaliburTiledProperties } from "./excalibur-properties";
 import { TiledLayerDataComponent } from "./tiled-layer-component";
 import { Layer } from "./layer";
 import { Tile } from "./tileset";
+import { byClassCaseInsensitive, byPropertyCaseInsensitive } from "./filter-util";
 
 export interface IsometricTileInfo {
  /**
@@ -44,6 +45,9 @@ export class IsoTileLayer implements Layer {
  * Excalibur IsometricMap structure for drawing in excalibur
  */
  isometricMap!: IsometricMap;
+
+ private _gidToTileInfo = new Map<number, IsometricTileInfo[]>();
+
  constructor(public tiledTileLayer: TiledTileLayer, public resource: TiledResource, public readonly order: number) {
  this.name = tiledTileLayer.name;
  this.class = tiledTileLayer.class;
@@ -52,6 +56,52 @@ export class IsoTileLayer implements Layer {
  mapProps(this, tiledTileLayer.properties);
  }
 
+ /**
+ * Returns the excalibur tiles that match a tiled gid
+ */
+ getTilesByGid(gid: number): IsometricTileInfo[] {
+ return this._gidToTileInfo.get(gid) ?? [];
+ }
+
+ /**
+ * Returns the excalibur tiles that match a tiled class name
+ * @param className
+ */
+ getTilesByClassName(className: string): IsometricTileInfo[] {
+ const tiles = this.isometricMap.tiles.filter(t => {
+ const maybeTiled = t.data.get(ExcaliburTiledProperties.TileData.Tiled) as Tile | undefined;
+ if (maybeTiled) {
+ return byClassCaseInsensitive(className)(maybeTiled);
+ }
+ return false;
+ });
+
+ return tiles.map(t => ({
+ exTile: t,
+ tiledTile: t.data.get(ExcaliburTiledProperties.TileData.Tiled)
+ }))
+ }
+
+ /**
+ * Returns the excalibur tiles that match a tiled property and optional value
+ * @param name
+ * @param value
+ */
+ getTilesByProperty(name: string, value?: any): IsometricTileInfo[] {
+ const tiles = this.isometricMap.tiles.filter(t => {
+ const maybeTiled = t.data.get(ExcaliburTiledProperties.TileData.Tiled) as Tile | undefined;
+ if (maybeTiled) {
+ return byPropertyCaseInsensitive(name, value)(maybeTiled);
+ }
+ return false;
+ });
+
+ return tiles.map(t => ({
+ exTile: t,
+ tiledTile: t.data.get(ExcaliburTiledProperties.TileData.Tiled)
+ }))
+ }
+
  getTileByPoint(worldPos: Vector): IsometricTileInfo | null {
  if (!this.isometricMap) {
  this.logger.warn('IsometricMap has not yet been loaded! getTileByPoint() will only return null');
@@ -75,7 +125,21 @@ export class IsoTileLayer implements Layer {
  return null;
  }
 
+ private _recordTileData(gid: number, tile: IsometricTile) {
+ let tiles: IsometricTileInfo[] | undefined = this._gidToTileInfo.get(gid);
+ let tileset = this.resource.getTilesetForTileGid(gid);
+ let maybeTile = tileset.getTileByGid(gid);
+ if (!tiles) {
+ tiles = [{exTile: tile, tiledTile: maybeTile}];
+ } else {
+ tiles.push({exTile: tile, tiledTile: maybeTile});
+ }
+ this._gidToTileInfo.set(gid, tiles);
+ tile.data.set(ExcaliburTiledProperties.TileData.Tiled, maybeTile);
+ }
+
  private updateTile(tile: IsometricTile, gid: number, hasTint: boolean, tint: Color, isSolidLayer: boolean) {
+ this._recordTileData(gid, tile);
  if (this.resource.useExcaliburWiring && isSolidLayer) {
  tile.solid = true;
  }
@@ -105,7 +169,7 @@ export class IsoTileLayer implements Layer {
 
  // the whole tilemap uses a giant composite collider relative to the Tilemap
  // not individual tiles
- const colliders = tileset.getCollidersForGid(gid, {offset});
+ const colliders = tileset.getCollidersForGid(gid, { offset });
  for (let collider of colliders) {
  tile.addCollider(collider);
  }
@@ -168,7 +232,7 @@ export class IsoTileLayer implements Layer {
  if (typeof zoverride === 'number') {
  order = zoverride;
  }
- 
+
 
 
  if (this.resource.map.infinite && isInfiniteLayer(this.tiledTileLayer)) {