doc: initialize bevy_ecs_tiled book

.github/workflows/publish-book.yml

@@ -0,0 +1,28 @@
+name: Publish book
+
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  deploy:
+    runs-on: ubuntu-20.04
+    concurrency:
+      group: ${{ github.workflow }}-${{ github.ref }}
+    steps:
+      - uses: actions/checkout@v2
+
+      - name: Setup mdBook
+        uses: peaceiris/actions-mdbook@v2
+        with:
+          mdbook-version: '0.4.10'
+
+      - run: CARGO_MANIFEST_DIR=. mdbook build book
+
+      - name: Deploy
+        uses: peaceiris/actions-gh-pages@v3
+        if: ${{ github.ref == 'refs/heads/main' }}
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./book/book

CHANGELOG.md

@@ -2,6 +2,10 @@
 
 ## [unreleased]
 
+### Documentation
+
+- Initialize `bevy_ecs_tiled` book (#15)
+
 ## v0.3.9
 
 ### Bugfixes

README.md

@@ -6,15 +6,25 @@
 [![Crates.io](https://img.shields.io/crates/d/bevy_ecs_tiled)](https://crates.io/crates/bevy_ecs_tiled)
 [![Following released Bevy versions](https://img.shields.io/badge/Bevy%20tracking-released%20version-lightblue)](https://bevyengine.org/learn/quick-start/plugin-development/#main-branch-tracking)
 
-[`bevy_ecs_tiled`](https://github.com/adrien-bon/bevy_ecs_tiled) is a [`Bevy`](https://bevyengine.org/) plugin for working with 2D tilemaps created with the [Tiled](https://www.mapeditor.org/) map editor.
+[`bevy_ecs_tiled`](https://github.com/adrien-bon/bevy_ecs_tiled) is a [Bevy](https://bevyengine.org/) plugin for working with 2D tilemaps created with the [Tiled](https://www.mapeditor.org/) map editor.
 
-It uses the [`bevy_ecs_tilemap`](https://github.com/StarArawn/bevy_ecs_tilemap) crate to perform rendering, so each tile or object is represented by a Bevy entity:
+It relies upon:
+
+- the official [Tiled Rust bindings](https://github.com/mapeditor/rs-tiled) to parse Tiled maps
+- the [`bevy_ecs_tilemap` crate](https://github.com/StarArawn/bevy_ecs_tilemap) to perform rendering
+
+Each tile or object is represented by a Bevy entity:
 
 - layers are children of the tilemap entity
 - tiles and objects are children of layers
 
 `Visibility` and `Transform` are inherited: map -> layer -> tile / object
 
+Documentation:
+
+- [`bevy_ecs_tiled` book](https://adrien-bon.github.io/bevy_ecs_tiled/)
+- [API reference](https://docs.rs/bevy_ecs_tiled/latest/bevy_ecs_tiled/)
+
 ![screenshot](./res/screenshot.gif)
 
 ## Features
@@ -29,16 +39,18 @@ It uses the [`bevy_ecs_tilemap`](https://github.com/StarArawn/bevy_ecs_tilemap)
 
 ## Getting started
 
+Add dependencies to your `Cargo.toml` file:
+
 ```toml
 [dependencies]
 bevy = "0.14"
 bevy_ecs_tiled = "0.3"
 bevy_ecs_tilemap = "0.14"
 ```
 
-Then add the plugin to your app:
+Then add the plugin to your app and spawn a map:
 
-```rust
+```rust no_run
 use bevy::prelude::*;
 use bevy_ecs_tiled::prelude::*;
 use bevy_ecs_tilemap::prelude::*;
@@ -65,6 +77,8 @@ fn startup(mut commands: Commands, asset_server: Res<AssetServer>) {
 }
 ```
 
+Please note that you should have the `map.tmx` file in your local `assets/` folder (as well as required dependencies, for instance associated tilesets).
+
 See the [examples](./examples/README.md) for more advanced use cases.
 
 ## Bevy Compatibility

book/.gitignore

@@ -0,0 +1 @@
+book

book/book.toml

@@ -0,0 +1,6 @@
+[book]
+authors = ["Adrien BON"]
+language = "en"
+multilingual = false
+src = "src"
+title = "bevy_ecs_tiled Documentation"

book/src/FAQ.md

@@ -0,0 +1,34 @@
+# FAQ
+
+## What kind of maps are supported ?
+
+Currently, we support :
+
+- orthogonal maps
+- (mostly) isometric "diamond" maps
+- hexagonal "flat-top" maps
+- hexagonal "pointy-top" maps
+
+Isometric "diamond" maps currently have an issue with colliders not having the proper shape (see [GH issue #32](https://github.com/adrien-bon/bevy_ecs_tiled/issues/32)).
+
+Isometric "staggered" maps are not supported at all (see [GH issue #31](https://github.com/adrien-bon/bevy_ecs_tiled/issues/31)).
+
+## Is it possible to automatically add physics colliders ?
+
+Yes, see the [dedicated guide](guides/physics.md).
+
+We currently support both [Avian](https://github.com/Jondolf/avian) and [Rapier](https://github.com/dimforge/bevy_rapier) physics backend.
+
+
+## Is it possible to use Tiled "custom properties" ?
+
+Yes, see the [dedicated guide](guides/properties.md).
+
+## I found a bug! What should I do ?
+
+Please have a look to [already openned issues](https://github.com/adrien-bon/bevy_ecs_tiled/issues) and if it does not already exists, please fill a new one !
+
+## I want to add a new feature that's not yet in the crate!
+
+Great news!
+Please have a look to [the dedicated section](misc/contributing.md)

book/src/README.md

@@ -0,0 +1,31 @@
+# Introduction
+
+{{ #include intro.md }}
+
+---
+
+**Disclaimer:** both this book and the whole crate have been heavilly inspired by the [`bevy_ecs_ldtk` crate](https://github.com/Trouv/bevy_ecs_ldtk), which is basically the equivalent of `bevy_ecs_tiled` but for the [LDTK](https://ldtk.io/) map editor.
+Thanks for the inspiration! :)
+
+---
+
+## Purpose of this book
+
+This book aims to give you a better understanding of how [`bevy_ecs_tiled`](https://github.com/adrien-bon/bevy_ecs_tiled) works, what you can achieve with it and how you can do it.
+
+It will focus more on concepts and design concerns.
+If you need an API reference, please have a look at the [`bevy_ecs_tiled` API reference](https://docs.rs/bevy_ecs_tiled/latest/bevy_ecs_tiled/).
+
+Finally, this book assume you already have some sort of knowledge about [Bevy](https://bevyengine.org/) and [Tiled](https://www.mapeditor.org/) map editor.
+There are already some good documentations available on these topics and some resources are referenced [in the dedicated section](misc/useful-links.md).
+
+## Architecture of this book
+
+This book is divided in several categories:
+
+- **Design and explanation**: how does the plugin works and why some technical choices have been made;
+- **How-To's**: in-depth tutorials about a specific aspect of  the plugin;
+- **Migration guides**: migration guides for specific versions;
+- **Miscellaneous**: other topics that did not fit in other categories.
+
+Good reading ! :)

book/src/SUMMARY.md

@@ -0,0 +1,29 @@
+# Summary
+
+[Introduction](README.md)
+[FAQ](FAQ.md)
+
+# Design and explanation
+
+- [Why using Tiled ?]()
+- [Entities tree and component markers]()
+- [Layers Z-ordering]()
+
+# How-To's
+
+- [Minimal working example](guides/minimal.md)
+- [Spawn / Despawn / Reload a map]()
+- [Use a physics backend](guides/physics.md)
+- [Use Tiled custom properties](guides/properties.md)
+- [Animate tiles]()
+- [Debug your project]()
+
+# Migration guides
+
+- [From v0.3.X to v0.4.X]()
+
+# Miscellaneous
+
+- [Useful links](misc/useful-links.md)
+- [Contributing](misc/contributing.md)
+- [API reference](misc/api-reference.md)

book/src/getting-started.md

@@ -0,0 +1,44 @@
+
+Add dependencies to your `Cargo.toml` file:
+
+```toml
+[dependencies]
+bevy = "0.14"
+bevy_ecs_tiled = "0.3"
+bevy_ecs_tilemap = "0.14"
+```
+
+Then add the plugin to your app and spawn a map:
+
+```rust no_run
+use bevy::prelude::*;
+use bevy_ecs_tiled::prelude::*;
+use bevy_ecs_tilemap::prelude::*;
+
+fn main() {
+    App::new()
+        .add_plugins(DefaultPlugins)
+        .add_plugins(TilemapPlugin)
+        .add_plugins(TiledMapPlugin)
+        .add_systems(Startup, startup)
+        .run();
+}
+
+fn startup(mut commands: Commands, asset_server: Res<AssetServer>) {
+    // Spawn a 2D camera
+    commands.spawn(Camera2dBundle::default());
+
+    // Load the map: ensure any tile / tileset paths are relative to assets/ folder
+    let map_handle: Handle<TiledMap> = asset_server.load("map.tmx");
+
+    // Spawn the map with default options
+    commands.spawn(TiledMapBundle {
+        tiled_map: map_handle,
+        ..Default::default()
+    });
+}
+```
+
+Please note that you should have the `map.tmx` file in your local `assets/` folder (as well as required dependencies, for instance associated tilesets).
+
+See the [examples](https://github.com/adrien-bon/bevy_ecs_tiled/tree/main/examples/README.md) for more advanced use cases.

book/src/guides/minimal.md

@@ -0,0 +1,3 @@
+# Minimal working example
+
+{{ #include ../getting-started.md }}

book/src/guides/physics.md

@@ -0,0 +1,3 @@
+# Use a physics backend
+
+TODO

book/src/guides/properties.md

@@ -0,0 +1,3 @@
+# Use Tiled custom properties
+
+TODO

book/src/intro.md

@@ -0,0 +1,14 @@
+
+[`bevy_ecs_tiled`](https://github.com/adrien-bon/bevy_ecs_tiled) is a [Bevy](https://bevyengine.org/) plugin for working with 2D tilemaps created with the [Tiled](https://www.mapeditor.org/) map editor.
+
+It relies upon:
+
+- the official [Tiled Rust bindings](https://github.com/mapeditor/rs-tiled) to parse Tiled maps
+- the [`bevy_ecs_tilemap` crate](https://github.com/StarArawn/bevy_ecs_tilemap) to perform rendering
+
+Each tile or object is represented by a Bevy entity:
+
+- layers are children of the tilemap entity
+- tiles and objects are children of layers
+
+`Visibility` and `Transform` are inherited: map -> layer -> tile / object

book/src/misc/api-reference.md

@@ -0,0 +1 @@
+<meta http-equiv="Refresh" content="0; url='https://docs.rs/bevy_ecs_tiled/'" />

book/src/misc/contributing.md

@@ -0,0 +1,28 @@
+# Contributing
+
+If you would like to contribute but you're unsure where to start, here is a short wishlist and some notes on how to get started.
+
+First, you can have a look at [GH issues](https://github.com/adrien-bon/bevy_ecs_tiled/issues).
+More specifically, the ones that are:
+
+- [tagged with `enhancement` label](https://github.com/adrien-bon/bevy_ecs_tiled/issues?q=is%3Aopen+is%3Aissue+label%3Aenhancement)
+- [tagged with `limitation` label](https://github.com/adrien-bon/bevy_ecs_tiled/issues?q=is%3Aopen+is%3Aissue+label%3Alimitation)
+
+If you feel like you can tackle on of these, please, feel free to submit a PR!
+
+Helping other users, respond to issues, help review PRs or just openning new issues is also very helpful !
+
+Also, another way of helping is to contribute on crates we rely on, namely [`rs-tiled`](https://github.com/mapeditor/rs-tiled) and [`bevy_ecs_tilemap`](https://github.com/StarArawn/bevy_ecs_tilemap), or anything else in the Bevy ecosystem.
+
+## Contribution guidelines
+
+If you submit a PR, please make sure that:
+
+- the CI is green
+- you add proper in-code documentation
+- you update the `CHANGELOG.md` file with a description of your fix
+- if you add a new example, update the `examples/README.md` file with a description of your example and the `Cargo.toml` file with your example name (and any feature it may need)
+- if you add a new map, update the `assets/README.md` file with your map characteristics
+- if you add a new asset, update the "Assets credits" section of the `README.md` file and make sure that you actually have the right to use it!
+
+Thanks in advance! :)

book/src/misc/useful-links.md

@@ -0,0 +1,25 @@
+# Useful links
+
+Here is an unordered list of useful resources that may help when working on a 2D tile-base game.
+
+Feel free to suggest any other link!
+
+## Notable crates
+
+- [`bevy`](https://github.com/bevyengine/bevy): the Bevy engine
+- [`bevy_ecs_tilemap`](https://github.com/StarArawn/bevy_ecs_tilemap): the crate we use for rendering our tiles
+- [`rs-tiled`](https://github.com/mapeditor/rs-tiled): official Tiled rust bindings
+- [`bevy_ecs_ldtk`](https://github.com/Trouv/bevy_ecs_ldtk): an equivalent of `bevy_ecs_tiled` but for the [LDTK](https://ldtk.io/) map editor
+- [`hexx`](https://github.com/ManevilleF/hexx): an hexagonal tools lib for stuff like path-finding or hex coordinates manipulation
+- [`bevy_mod_picking`](https://github.com/aevyrie/bevy_mod_picking/): a flexible set of plugins that add picking functionality to your bevy app
+- [`bevy_picking_tilemap`](https://github.com/zacryol/bevy_picking_tilemap): provides a [`bevy_mod_picking`](https://github.com/aevyrie/bevy_mod_picking/) backend to add integration with [`bevy_ecs_tilemap`](https://github.com/StarArawn/bevy_ecs_tilemap), enabling individual Tile entities to receive the picking events
+- [`avian`](https://github.com/Jondolf/avian): Avian physic backend
+- [`bevy_rapier`](https://github.com/dimforge/bevy_rapier): Rapier physic backend
+
+## Notable resources
+
+- [Bevy official website](https://bevyengine.org/): lots of examples and learning materials
+- [Bevy API reference](https://docs.rs/bevy/latest/bevy/)
+- [Unofficial Bevy Cheat Book](https://bevy-cheatbook.github.io/): one the best resource to learn Bevy
+- [Tiled official website](https://www.mapeditor.org/): to get the latest Tiled version and read associated documentation
+- [Red Blob Games](https://www.redblobgames.com/): collections of tutorials on various gamedev topics, especially the [hexagonal grids reference](https://www.redblobgames.com/grids/hexagons/)

examples/README.md

@@ -1,5 +1,18 @@
 # Examples
 
+This directory provides a list of examples which demonstrate how to use the crate.
+
+To run an example, you can run the following command, where XXX is the example name:
+
+```bash
+cargo run --example XXX
+```
+
+Be advised that some of the examples require to enable one or multiple feature.
+In that case, cargo will return an error and print the proper command to run.
+
+Please note that if you want a more in-depth explanation of some of the crate concepts, there is a [dedicated book](https://adrien-bon.github.io/bevy_ecs_tiled/) to cover that.
+
 ## Keyboard controls
 
 In most of the examples, you can use the following action keys:
@@ -8,6 +21,10 @@ In most of the examples, you can use the following action keys:
 - **Z/X**: to zoom out / zoom in
 - **A/E**: to rotate the map (not only the camera)
 
+Note: some of on the key can be differents for "non-QWERTY" keyboard layout.
+
+For instance, on an "AZERTY" keyboard, you must use `A` instead of `Q` and `Z` instead of `W`.
+
 ## Examples list
 
 | Name | Required features | Description |