diff --git a/site/docs/13-plugins/15-ldtk-plugin.mdx b/site/docs/13-plugins/15-ldtk-plugin.mdx new file mode 100644 index 000000000..f2bf932c7 --- /dev/null +++ b/site/docs/13-plugins/15-ldtk-plugin.mdx @@ -0,0 +1,186 @@ +--- +title: LDtk Plugin ✨New!✨ +slug: /ldtk-plugin +section: Plugins +--- + +[LDtk (level design toolkit)](https://ldtk.io/) is a free, open source, and super useful level design tool from the create of Dead Cells. It's goal is to be super user friendly and full featured. Currently only supports 2D tile maps. + +The current Excalibur plugin is designed to parse all data provided by the `.ldtk` format and make it available to users. Not all features may be supported directly in Excalibur but the majority are. + +The plugin officially supports the latest version of LDtk that has been published and will warn if you are using an older version. This is because there have been many breaking changes to the LDtk map format over time that are difficult to reconcile. + +## Installation + + +```sh +npm install @excaliburjs/plugin-ldtk +``` + +Create your resource, load it, then add it to your scene! + +```typescript + +const game = new ex.Engine({...}); + +const ldtkMap = new LdtkResource('./path/to/my/cool-map.ldtk'); + +const loader = new ex.Loader([ldtkMap]); + +game.start(loader).then(() => { + ldtkMap.addToScene(game.currentScene); +}); +``` + +## Plugin Philosophy + +* The plugin **STRICTLY** interprets the LDtk format by default, meaning if the plugin thinks the LDtk source files are corrupted/invalid it will throw while loading them. If this doesn't work for you you can set `strict: false` in the `LDtkResource` constructor, the plugin will do it's best with the data provided but there may be unexpected behavior. + +```typescript +const tiledMap = new LdtkResource('./path/to/my/cool-map.ldtk', { + strict: false +}); +``` + +* The plugin roughly has 2 data structures for each LDtk primitive. + + * First it dutifully recreates the types using the LDtk JSON as the source of truth. These types are prefixed with `ldtk` so for example `LdtkEntityInstance` or `LdtkLayerInstance` are the "raw" Ldtk representation matching casing and data as close as possible. + + * Second the built in `Tiled` prefixed types are often unfriendly, so the plugin provides it's own friendly abstraction over them that works nicely with Excalibur. Whenever the plugin provides a friendly abstraction, it also provides the underlying Tiled prefix types just in case you need that data. + +* Everything is lowercase/case-insensitive! When the plugin is searching for strings either as props keys or values, they are treated as lowercase/case-insensitive. + +* Certain Excalibur interpretations of Tiled features are guarded behind the constructor param `useExcaliburWiring`. By default this is `true`, but if you find this is unacceptable you can toggle it off. + +```typescript +const ldtkMap = new LdtkResource('./path/to/my/cool-map.ldtk', { + useExcaliburWiring: false +}); +``` + +## Map Features + +To add a loaded `LdtkResource` map to a scene + +```typescript +const ldtkMap = new LdtkResource(...); + +// Load tiledMap here + +ldtkMap.addToScene(game.currentScene); + +// Optionally specify a position +ldtkMap.addToScene(game.currentScene, {pos: ex.vec(100, 100)}); + +// Optionally list specific ldtk levels to add +ldtkMap.addToScene(game.currentScene, {levelFilter: ['level1']}); + +// Optionally disable level offsets, levels are by default spatially positioned in ldtk this can be useful with the level filtering +ldtkMap.addToScene(game.currentScene, {useLevelOffsets: false}); + +``` + +### Background Color + +The plugin supports pulling the `Background Color` from the LDtk level. Configure the `useMapBackgroundColor` in your constructor. Note it will use the background color from the first level in your LDtk world. + +```typescript +const tiledMap = new TiledResource('./isometric.tmx', { + useMapBackgroundColor: true +}); +``` + +![changing ldtk level background color](./ldtk/background.gif) + + +### Solid Layers + +In LDtk we use IntGrid layers to indicate whether a tile is solid or not. + +:::note +You can set IntGrid layer grid size to whatever you want to achieve half tile collisions. +::: + +By default the int value = 1 is treated as solid, otherwise you can give a number a name of "solid" and that will be a solid layer. + +![solid layer configuration](./ldtk/solid-layer.png) + +Then paint your solid layer tiles + +![paint solid layer](./ldtk/paint-solid.png) + +### Camera Positioning + +You can use an LDtk entity to position the excalibur camera. Specify 2 special custom properties to influence Excalibur's camera. + +* `camera = true` (Warning excalibur will use the first object it finds with this, so be sure to only tag one as a camera) +* `zoom = 5.0` Optionally specify a camera zoom level, only takes effect if `camera = true` is set on the entity + +![Setting camera properties](./ldtk/camera.png) + +Position your camera like so + +![Camera position](./ldtk/camera-position.png) + +### Entity Factories + +Sometimes it is useful to supply a custom type to have the plugin construct when it runs across a particular entity, this might be the player, a collectable, or an enemy. + +Given an entity identifier, in this case "PlayerStart" + +![player start](./ldtk/player-start.png) + +You can specify a factory to run and create your preferred type, once you've returned the [[Entity]] out of the factory it will automatically be added to the [[Scene]]. This is also a useful time to run any other custom code you want per [[Entity]]. + +```typescript +game.start(loader).then(() => { + console.log('Game start!'); + + ldtkResource.registerEntityIdentifierFactory('PlayerStart', (props) => { + const player = new Player({ + name: 'player', + anchor: ex.vec(props.entity.__pivot[0],props.entity.__pivot[1]), + width: props.entity.width, + height: props.entity.height, + pos: props.worldPos, + z: props.layer.order + }); + // Also run custom code + game.currentScene.camera.strategy.lockToActor(player); + return player; + }); + +}); + +``` + +![ldtk running](./ldtk/ldtk.gif) + +## Bundlers + +Excalibur provides a lot of samples to get you started with various bundlers + +* Vite https://github.com/excaliburjs/sample-tiled-vite +* Parcel https://github.com/excaliburjs/sample-tiled-parcel +* Webpack https://github.com/excaliburjs/sample-tiled-webpack + + +LDtk uses a lot of static assets and refers to them inside different LDtk source files, and often bundlers like to rearrange static assets in a final build. To work around this paths mapping issue, the plugin provides a `pathMap` to test file paths and redirect to whatever location your assets are stored. + +```typescript +const ldtkMap = new LdtkResource('./example-city.ldtk', { + pathMap: [ + // If the "path" is included in the source path, the output will be used + { path: 'someimage.png', output: '/static/assets/someimage.png' }, + // Regex matching with special [match] in output string that is replaced with the first match from the regex + { path: /(.*\..*$)/, output: '/static/assets/[match]'} + ] +}) +``` + +### Currently Unsupported + +PRs welcome! + +* Level Background Image +* Auto Tile Layers - these must be baked into normal tile layers for the plugin to support them \ No newline at end of file diff --git a/site/docs/13-plugins/15-spritefusion-plugin.mdx b/site/docs/13-plugins/15-spritefusion-plugin.mdx new file mode 100644 index 000000000..28148cc48 --- /dev/null +++ b/site/docs/13-plugins/15-spritefusion-plugin.mdx @@ -0,0 +1,77 @@ +--- +title: Sprite Fusion Plugin ✨New!✨ +slug: /spritefusion-plugin +section: Plugins +--- + +[Sprite Fusion](https://www.spritefusion.com/) is a new, exiting, and easy to use tile map editor based on the web! It's goal is to be lightweight and easy to use. + +The current Excalibur plugin is designed to parse all data provided by the Sprite Fusion JSON export format and make it available to users. Not all features may be supported directly in Excalibur but the majority are. + +The plugin officially supports the latest version of Sprite Fusion that has been published and will warn if you are using an older version. + +## Installation + +```sh +npm install @excaliburjs/plugin-spritefusion +``` + +Create your resource, load it, then add it to your scene! + +```typescript +const game = new ex.Engine({...}); + +const spriteFusionMap = new SpriteFusionResource({ + mapPath: './map/map.json', + spritesheetPath: './map/spritesheet.png' +}); + +const loader = new ex.Loader([spriteFusionMap]); + +game.start(loader).then(() => { + spriteFusionMap.addToScene(game.currentScene); +}); +``` + +![Sprite Fusion example](./spritefusion/sprite-fusion-example.png) + +## Solid Layers + +In order to create solid layers in Excalibur, use the Sprite Fusion collision layer check box. Any tiles in this layer will be treated as solid by Excalibur. + +![solid layer example](./spritefusion/solid-layer.png) + + +## Entity Factories + +Sometimes it is useful to supply a custom type to have the plugin construct when it runs across a particular entity, this might be the player, a collectable, or an enemy. + +You can specify a factory to run and create your preferred type, once you've returned the [[Entity]] out of the factory it will automatically be added to the [[Scene]]. This is also a useful time to run any other custom code you want per [[Entity]]. + +```typescript + +const spriteFusionMap = new SpriteFusionResource({ + mapPath: './map/map.json', + spritesheetPath: './map/spritesheet.png', + entityTileIdFactories: { + 0 : (props) => { + return new ex.Actor({ + pos: props.worldPos, + width: 16, + height: 16, + color: ex.Color.Red, + z: props.layer.order + 1 + }); + } + } +}); + +``` + +Currently you need to count the sprite id from the exported spritesheet.png. + +![count tile id](./spritefusion/tile-id.png) + +For example, now tile id `0` is replaced with a custom implementation that shows a red box. + +![factory custom implementation](./spritefusion/factory-result.png) \ No newline at end of file diff --git a/site/docs/13-plugins/15-tiled-plugin-old.mdx b/site/docs/13-plugins/16-tiled-plugin-old.mdx similarity index 100% rename from site/docs/13-plugins/15-tiled-plugin-old.mdx rename to site/docs/13-plugins/16-tiled-plugin-old.mdx diff --git a/site/docs/13-plugins/ldtk/background.gif b/site/docs/13-plugins/ldtk/background.gif new file mode 100644 index 000000000..842f43187 Binary files /dev/null and b/site/docs/13-plugins/ldtk/background.gif differ diff --git a/site/docs/13-plugins/ldtk/camera-position.png b/site/docs/13-plugins/ldtk/camera-position.png new file mode 100644 index 000000000..4bec664cc Binary files /dev/null and b/site/docs/13-plugins/ldtk/camera-position.png differ diff --git a/site/docs/13-plugins/ldtk/camera.png b/site/docs/13-plugins/ldtk/camera.png new file mode 100644 index 000000000..d334bf2e3 Binary files /dev/null and b/site/docs/13-plugins/ldtk/camera.png differ diff --git a/site/docs/13-plugins/ldtk/ldtk.gif b/site/docs/13-plugins/ldtk/ldtk.gif new file mode 100644 index 000000000..41c9aed2f Binary files /dev/null and b/site/docs/13-plugins/ldtk/ldtk.gif differ diff --git a/site/docs/13-plugins/ldtk/paint-solid.png b/site/docs/13-plugins/ldtk/paint-solid.png new file mode 100644 index 000000000..cca2ecdeb Binary files /dev/null and b/site/docs/13-plugins/ldtk/paint-solid.png differ diff --git a/site/docs/13-plugins/ldtk/player-start.png b/site/docs/13-plugins/ldtk/player-start.png new file mode 100644 index 000000000..bfdc728e0 Binary files /dev/null and b/site/docs/13-plugins/ldtk/player-start.png differ diff --git a/site/docs/13-plugins/ldtk/solid-layer.png b/site/docs/13-plugins/ldtk/solid-layer.png new file mode 100644 index 000000000..599279657 Binary files /dev/null and b/site/docs/13-plugins/ldtk/solid-layer.png differ diff --git a/site/docs/13-plugins/spritefusion/factory-result.png b/site/docs/13-plugins/spritefusion/factory-result.png new file mode 100644 index 000000000..300802334 Binary files /dev/null and b/site/docs/13-plugins/spritefusion/factory-result.png differ diff --git a/site/docs/13-plugins/spritefusion/solid-layer.png b/site/docs/13-plugins/spritefusion/solid-layer.png new file mode 100644 index 000000000..0855db03f Binary files /dev/null and b/site/docs/13-plugins/spritefusion/solid-layer.png differ diff --git a/site/docs/13-plugins/spritefusion/sprite-fusion-example.png b/site/docs/13-plugins/spritefusion/sprite-fusion-example.png new file mode 100644 index 000000000..ea8c966c3 Binary files /dev/null and b/site/docs/13-plugins/spritefusion/sprite-fusion-example.png differ diff --git a/site/docs/13-plugins/spritefusion/tile-id.png b/site/docs/13-plugins/spritefusion/tile-id.png new file mode 100644 index 000000000..1363fdcb9 Binary files /dev/null and b/site/docs/13-plugins/spritefusion/tile-id.png differ