{"id":14964006,"url":"https://github.com/colinvella/phaser-tilemap-plus","last_synced_at":"2025-07-28T09:33:17.476Z","repository":{"id":57322893,"uuid":"108369608","full_name":"colinvella/phaser-tilemap-plus","owner":"colinvella","description":"Tilemap animations, physics, events and custom property enhancements for Tiled JSON map files","archived":false,"fork":false,"pushed_at":"2017-12-10T19:39:45.000Z","size":253,"stargazers_count":71,"open_issues_count":6,"forks_count":5,"subscribers_count":6,"default_branch":"master","last_synced_at":"2025-01-31T05:33:34.342Z","etag":null,"topics":["animation","collision","phaser","physics","slopes","sprites","tiled","tiled-json-files","tilemap","tilemap-animations"],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/colinvella.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-10-26T06:16:33.000Z","updated_at":"2024-10-17T16:24:43.000Z","dependencies_parsed_at":"2022-08-25T20:00:11.485Z","dependency_job_id":null,"html_url":"https://github.com/colinvella/phaser-tilemap-plus","commit_stats":null,"previous_names":[],"tags_count":21,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/colinvella%2Fphaser-tilemap-plus","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/colinvella%2Fphaser-tilemap-plus/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/colinvella%2Fphaser-tilemap-plus/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/colinvella%2Fphaser-tilemap-plus/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/colinvella","download_url":"https://codeload.github.com/colinvella/phaser-tilemap-plus/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":238075281,"owners_count":19412307,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["animation","collision","phaser","physics","slopes","sprites","tiled","tiled-json-files","tilemap","tilemap-animations"],"created_at":"2024-09-24T13:32:27.591Z","updated_at":"2025-02-10T07:31:08.620Z","avatar_url":"https://github.com/colinvella.png","language":"JavaScript","readme":"# phaser-tilemap-plus [![Build Status](https://travis-ci.org/colinvella/phaser-tilemap-plus.svg?branch=master)](https://travis-ci.org/colinvella/phaser-tilemap-plus)\n\nA [Phaser](http://phaser.io) game framework plugin that implements tile animation, sloped tile physics, events and custom property enhancements for tilemaps loaded from [Tiled](http://www.mapeditor.org) JSON map files within the [Phaser](http://phaser.io) game framework.\n\n**Check out the interactive [demo](https://colinvella.github.io/phaser-tilemap-plus-demo/)**. :video_game:\n\n![phaser-tilemap-plus-demo](https://user-images.githubusercontent.com/1244038/32296653-17530fd6-bf4d-11e7-80f2-c2d82bbed151.gif)\n\nThis is a Phaser plugin that leverages the map editing capabilities of the [Tiled](http://www.mapeditor.org) map editor. It allows the developer to selectively enable the following features:\n* tile animation as defined in the [Tiled](http://www.mapeditor.org) map editor\n* object layer based collision with support for sloped and curved tiles\n* custom properties for tilemaps, tilesets and layers\n* event handling for sprite to map collisions and region-triggered events\n\nThe plugin is designed to facilitate integration into existing code bases with minimal code changes.\n\n## How It Works\nThe plugin injects code into Phaser's loader mechanism to load the underlying Tiled JSON files in a separate cache key, extracting information currently ignored by the tilemap loader. It also injects a custom factory function to enhance the loaded tilemap object with additional functionality, such as animation, physics, custom properties and event handling.\n\n## Supported Formats\nWhen exporting a Tiled map to JSON format for use with the library, make sure to set one of the following formats in Maps \u003e Properties \u003e Tile Layer Format:\n* XML\n* Base 64 Uncompressed\n* CSV\n\n## Installation :hammer:\n```shell\nnpm install phaser-tilemap-plus -S\n```\n\n## Code Import\nThere are several options for importing the code\n\n### Modular\n```js\nrequire(\"phaser-tilemap-plus\"); // ES5 require() function\n```\nor\n```es6\nimport \"phaser-tilemap-plus\"; // ES6 import keyword\n```\n\n### Script Reference\nIf you're not working in a NodeJS environment, copy the distribution script phaser-tilemap-plus.js from the\n[latest release](https://github.com/colinvella/phaser-tilemap-plus/releases)\nand include it after Phaser.\n\n```html\n\u003cscript src=\"phaser.min.js\"\u003e\u003c/script\u003e\n\u003cscript src=\"phaser-tilemap-plus.js\"\u003e\u003c/script\u003e\n```\n\n## Usage :book:\n\nFor a complete working example, check out the source code of the [demo game](https://github.com/colinvella/phaser-tilemap-plus-demo).\n\n### Install Plugin\nWithin the `create()` function or method of your game state, add the plugin to the Phaser framework. If you have multiple states, this can be done in your booting state.\n\n```js\n  game.plugins.add(Phaser.Plugin.TilemapPlus); // ES5  \n```\nor\n```es6\n  this.game.plugins.add(Phaser.Plugin.TilemapPlus); // ES6 if create() is a method override\n```\n\nLoad the tilemap and corresponding tilemap layers as you normally would. The plugin will transparently enhance the tilemap to support the additional features.\n\n*NOTE:* In general, the difference between ES5 and ES6 code is that in ES6, the `game` object is a property of the game state object and must be prefixed by `this`. The next examples will quote only ES5 code for the sake of brevity.\n\n### Enable Tile Animations\nIf you have defined tile animations within Tiled prior to exporting the map to JSON format, you can enable them by adding the following code after adding the tilemap and corresponding tilemap layers in your `create()` function:\n\n```js\ngame.tilemap.plus.animation.enable();\n```\n\n![image](https://user-images.githubusercontent.com/1244038/32300241-dfa24bc2-bf58-11e7-83d8-1aaa6e7c99d1.png)\n\nAnimations can be disabled by calling `tilemap.plus.animation.disable()`.\n\n### Enable Physics\nYou can add an object layer to your Tiled map and add polygons and rectangles to define collidable boundaries in your map, independently from the tiles used. This allows the use of sloped or curved floors, walls and ceilings, against which sprites can interact accordingly, such as sliding down or bouncing accurately. Object layer-based collision also allows the implementation of hidden passages and platforms.\n\nThe physics engine uses a fast quadtree-based broad phase collision detection, coupled with a separation axis\ntheorem (SAT) implementation for the narrow phase collision detection on the polygon objects defined in the object layer. On initialisation, the physics engine decomposes all concave polygons into convex polygons, to allow use of SAT. \n\n![image](https://user-images.githubusercontent.com/1244038/32300160-874d7096-bf58-11e7-9d22-d808a2b672b5.png)\n\nTo enable collision against an object layer, call the `enableObjectLayer` method, passing in the name of the object layer within the map, like this:\n```js\ngame.tilemap.plus.physics.enableObjectLayer(\"Collision\");\n```\n\nTo collide sprites against the map, call the following in your `update()` method:\n```js\ngame.tilemap.plus.physics.collideWith(sprite);\n```\n\n#### Surface Interaction\n\nWhenever a sprite is touching the collision layer, its body will have a `plus` object attached with a number of collision related properties:\n\n* `contactNormal`: a value of type `Vector` indicating the overall direction away from the contact surfaces. The contact normal is a unit vector (a vector of length 1.0)\n* `contactNormals`: an array of `Vector` types containing contact normals for every contact surface\n* `penetration`: a value of type `Vector` indicating the overall penetration into the contact surfaces. This is used by the physics engine to correct the sprite's position after it penetrates the tile map\n* `penetrations`: an array of `Vector` types containing penetration vectors for every contact surface. The sum of these vectors equals the value of `penetration`\n\n These properties can be used to determine when and in what direction to jump off the surface. For example, a sprite is allowed to jump only when `sprite.body.plus.contactNormal.y \u003c 0`, that is has a component pointing upwards.\n\n#### Surface Rebound\n\nTo make sprites rebound off surfaces, add a `bounce` custom property to an object in the object layer, with a value that is a fraction\nof the rebound velocity. For example. if you want a sprite to bounce back with half the incoming velocity, set `bounce` to `0.5`. To\nmake Sonic-style springs, you can assign a value higher than `1.0`.\n\n\u003cp align=\"center\"\u003e\u003cimg src=\"https://user-images.githubusercontent.com/1244038/32395807-f74aa41e-c0e2-11e7-90cf-5f7e882fb724.gif\" alt=\"phaser-tilemap-plus physics bounce\"\u003e\u003c/p\u003e\n\n#### One Way Platforms\n\nMany games implement platforms that the player can jump on from underneath. To implement a platform\nwith this behaviour, add a custom property `collideOnly = down` to the platform's shape in the object layer.\nThis will cause the physics engine to ignore collisions where the sprite's velocity doesn't have a downward\ncomponent, effectively allowing the sprite to pass through the platform from underneath.\n\nIn a similar manner, it is possible to make passthrough ceilings that impede upward motion by setting `collideOnly = up`. One way walls or entrances can similarly be implemented by setting `collideOnly = right` or\n`collideOnly = left`.\n\n### Custom Properties\n\nTiled allows the level designer to define custom properties at the map, layer and tileset level, that can be used to define meta data such as the player's starting position, exit point, level effects and so on. \nThe plugin exposes these properties in the corresponding `tilemap`, `tilemapLayer`s and `tileset`s instanciated in the `create()` function of the game state.\n\n#### Tilemap Custom Properties\n\nTilemap custom properties can be accessed as follows:\n\n```js\n// get player start position from tilemap custom properties\nvar mapProperties = tilemap.plus.properties;\nplayer.x = mapProperties.playerStartX;\nplayer.y = mapProperties.playerStartY;\n```\n\n#### Layer Custom Properties\n\nCustom properties defined at the tilemap layer level can be accessed as follows:\n\n```js\n// get layer effects from custom properties\nvar layerProperties = tilemapLayer.plus.properties;\nvar rainEffect = layerProperties.rain;\nvar windEffect = layerProperties.wind;\n```\n\n#### Tileset Custom Properties\n\nTileset custom properties can be accessed as follows:\n\n```js\n// get loot probability from custom properties\nvar tilesetProperties = tileset.plus.properties;\nvar lootProbability = tilesetProperties.lootProbability;\n```\n\n### Event Handling\n\nThe event system allows event handlers, in the form of callback functions, to be hooked to specific events in the\ngame, such as when a sprite collides with the tilemap's collision layer if enabled. It is also possible to set up\na specific object layer, independent of the collision layer, to contain shapes that act as event triggers.\n\n#### Collision Events\n\nTo listen to sprite against object layer collision events, listener functions can be mapped on a per sprite basis:\n\n```js\n// listen to player collisions against the tilemap\nvar playerListener = tilemap.plus.events.collisions.add(player,\n  function(shape, oldVelocity, newVelocity, contactNormal) {\n    // if the tilemap has a strong bounce property, play spring sound\n    if (shape.properties.bounce \u003e 1) {\n        springAudio.play();\n    }\n    // if the downward velocity lessened drastically, play thud sound\n    if (oldVelocity.y - newVelocity.y \u003e 300) {\n        thudAudio.play();                \n    }\n  }\n);\n```\n\nThe listener function is invoked whenever the sprite hits a shape from the collision layer. The function's\nparameters consist of the shape, the old (pre-collision) and new (post-collision) velocity vectors of the sprite and\nthe contact normal vector (a vector of length 1 that points away at 90 degrees from the surface). These parameters\ncan be used to apply behaviours and/or effects as needed.\n\nIf a reference to a listener function is maintained, it can eventually be removed from the event system like this:\n\n```js\n// remove playerListener listener from player collision event list\ntilemap.plus.events.collisions.remove(player, playerListener);\n```\n\n#### Region Based Events\n\nJust as Tiled's object layers can be used to define physical boundaries within the map, they can also be used to\ndefine event triggering regions, using a separate object layer dedicated for this purpose. Events can be set up\nfor any given sprite entering and/or leaving a region (a polygon or rectangle shape) in the object layer. This\nis useful for setting up area-specific effects, trigger enemy spawning, set save points and so on.\n\nTo enable a specific object layer to handle region events, add the following code in the `create()` function:\n\n```js\n// enable region events using object layer named \"Events\"\ntilemap.plus.events.regions.enableObjectLayer(\"Events\");\n```\n\nAfter enabling region evemts, bind an `onEnter` listener function to a sprite:\n\n```js\n// simulate entering a poorly lit area if region has custom property isDark = true\nvar playerInside = tilemap.plus.events.regions.onEnterAdd(player, function(region) {\n  if (region.properties.isDark) {\n    // tween dark mask sprite to 50% alpha\n    game.add.tween(lightSprite).to( { alpha: 0.5 }, 250, \"Linear\", true);\n  }\n});\n```\n\nAn `onLeave` listener can be bound to a sprite in a similar way:\n\n```js\n// simulate leaving a poorly lit area\nvar playerOutside = tilemap.plus.events.regions.onLeaveAdd(player, function(region) {\n  if (region.properties.isDark) {\n    // tween dark mask sprite to transparent\n    game.add.tween(lightSprite).to( { alpha: 0.0 }, 250, \"Linear\", true);\n  }\n});\n```\n\nTo process region events, the `triggerWith(...)` function must be called for every frame by\ninvoking it from within the `update()` function:\n\n```js\n// trigger region events against player sprite\ntilemap.plus.events.regions.triggerWith(player);\n```\n\nFinally, listeners can be unbound from a sprite using the `onEnterRemove(..)` and\n`onLeaveRemove` functions, provided references to the listener functions are kept:\n\n```js\n// unhook enter and leave listeners from player sprite\ntilemap.plus.events.regions.onEnterRemove(player, playerInside);\ntilemap.plus.events.regions.onLeaveRemove(player, playerOutside);\n```\n\n## Further Information :point_left:\n\nIf you find bugs within the plugin or need help to incorporate it in your game, please raise an\n[issue](https://github.com/colinvella/phaser-tilemap-plus/issues/new) on\n[GitHub](https://github.com/colinvella/phaser-tilemap-plus). I will try to help you out as best\nas I can.\n\n## Thanks :heart:\n\nA thank you note for those who made this plugin possible:\n\n- [Richard Davey](https://twitter.com/photonstorm) - for Phaser :rocket:\n- [Stefan Hedman (schteppe)](https://github.com/schteppe) - for the manual port of [Poly Decomp](https://github.com/schteppe/poly-decomp.js) by Mark Bayazit :bookmark_tabs:\n- [Chris Andrew (@hexus)](https://github.com/hexus) - for the [phaser-arcade-slopes](https://github.com/hexus/phaser-arcade-slopes) library :triangular_ruler:, which was the source of inspiration for *phaser-arcade-plus* :thumbsup:\n\n","funding_links":[],"categories":["JavaScript","Uncategorized"],"sub_categories":["Uncategorized"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcolinvella%2Fphaser-tilemap-plus","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcolinvella%2Fphaser-tilemap-plus","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcolinvella%2Fphaser-tilemap-plus/lists"}