From 16823fd851b1c061e3accfa518a02dd7f8e63750 Mon Sep 17 00:00:00 2001 From: Adrien BON <63343541+adrien-bon@users.noreply.github.com> Date: Fri, 13 Sep 2024 15:42:42 +0000 Subject: [PATCH] doc: initialize bevy_ecs_tiled book --- .github/workflows/publish-book.yml | 28 +++++++++++++++ CHANGELOG.md | 4 +++ README.md | 22 +++++++++--- book/.gitignore | 1 + book/book.toml | 6 ++++ book/src/FAQ.md | 34 ++++++++++++++++++ book/src/README.md | 31 ++++++++++++++++ book/src/SUMMARY.md | 29 +++++++++++++++ book/src/getting-started.md | 44 +++++++++++++++++++++++ book/src/guides/minimal.md | 3 ++ book/src/guides/physics.md | 3 ++ book/src/guides/properties.md | 3 ++ book/src/intro.md | 14 ++++++++ book/src/misc/api-reference.md | 1 + book/src/misc/contributing.md | 28 +++++++++++++++ book/src/misc/useful-links.md | 25 +++++++++++++ examples/README.md | 17 +++++++++ src/lib.rs | 57 ++++-------------------------- 18 files changed, 295 insertions(+), 55 deletions(-) create mode 100644 .github/workflows/publish-book.yml create mode 100644 book/.gitignore create mode 100644 book/book.toml create mode 100644 book/src/FAQ.md create mode 100644 book/src/README.md create mode 100644 book/src/SUMMARY.md create mode 100644 book/src/getting-started.md create mode 100644 book/src/guides/minimal.md create mode 100644 book/src/guides/physics.md create mode 100644 book/src/guides/properties.md create mode 100644 book/src/intro.md create mode 100644 book/src/misc/api-reference.md create mode 100644 book/src/misc/contributing.md create mode 100644 book/src/misc/useful-links.md diff --git a/.github/workflows/publish-book.yml b/.github/workflows/publish-book.yml new file mode 100644 index 0000000..c17f054 --- /dev/null +++ b/.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 \ No newline at end of file diff --git a/CHANGELOG.md b/CHANGELOG.md index d82870c..08fb3ed 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,10 @@ ## [unreleased] +### Documentation + +- Initialize `bevy_ecs_tiled` book (#15) + ## v0.3.9 ### Bugfixes diff --git a/README.md b/README.md index d5cc226..151083d 100644 --- a/README.md +++ b/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,6 +39,8 @@ 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" @@ -36,9 +48,9 @@ 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) { } ``` +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 diff --git a/book/.gitignore b/book/.gitignore new file mode 100644 index 0000000..7585238 --- /dev/null +++ b/book/.gitignore @@ -0,0 +1 @@ +book diff --git a/book/book.toml b/book/book.toml new file mode 100644 index 0000000..eb83905 --- /dev/null +++ b/book/book.toml @@ -0,0 +1,6 @@ +[book] +authors = ["Adrien BON"] +language = "en" +multilingual = false +src = "src" +title = "bevy_ecs_tiled Documentation" diff --git a/book/src/FAQ.md b/book/src/FAQ.md new file mode 100644 index 0000000..56811ab --- /dev/null +++ b/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) diff --git a/book/src/README.md b/book/src/README.md new file mode 100644 index 0000000..e539cfd --- /dev/null +++ b/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 ! :) diff --git a/book/src/SUMMARY.md b/book/src/SUMMARY.md new file mode 100644 index 0000000..14ddf31 --- /dev/null +++ b/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) \ No newline at end of file diff --git a/book/src/getting-started.md b/book/src/getting-started.md new file mode 100644 index 0000000..aae4951 --- /dev/null +++ b/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) { + // 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 = 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. diff --git a/book/src/guides/minimal.md b/book/src/guides/minimal.md new file mode 100644 index 0000000..0069ac6 --- /dev/null +++ b/book/src/guides/minimal.md @@ -0,0 +1,3 @@ +# Minimal working example + +{{ #include ../getting-started.md }} \ No newline at end of file diff --git a/book/src/guides/physics.md b/book/src/guides/physics.md new file mode 100644 index 0000000..8e2f86e --- /dev/null +++ b/book/src/guides/physics.md @@ -0,0 +1,3 @@ +# Use a physics backend + +TODO diff --git a/book/src/guides/properties.md b/book/src/guides/properties.md new file mode 100644 index 0000000..c18da1f --- /dev/null +++ b/book/src/guides/properties.md @@ -0,0 +1,3 @@ +# Use Tiled custom properties + +TODO diff --git a/book/src/intro.md b/book/src/intro.md new file mode 100644 index 0000000..60f1d7c --- /dev/null +++ b/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 diff --git a/book/src/misc/api-reference.md b/book/src/misc/api-reference.md new file mode 100644 index 0000000..a033278 --- /dev/null +++ b/book/src/misc/api-reference.md @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/book/src/misc/contributing.md b/book/src/misc/contributing.md new file mode 100644 index 0000000..6f09db9 --- /dev/null +++ b/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! :) diff --git a/book/src/misc/useful-links.md b/book/src/misc/useful-links.md new file mode 100644 index 0000000..3edd924 --- /dev/null +++ b/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/) diff --git a/examples/README.md b/examples/README.md index 4183bae..1db636b 100644 --- a/examples/README.md +++ b/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 | diff --git a/src/lib.rs b/src/lib.rs index 02d8704..098b77f 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -1,60 +1,15 @@ -//! [`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 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 -//! -//! ## Features -//! -//! - Orthogonal, isometric and hexagonal maps -//! - Finite and infinite maps -//! - Embedded and separate tileset -//! - Easily spawn / despawn maps -//! - Animated tiles -//! - Rapier and Avian colliders added from tilesets and object layers (`rapier` or `avian` feature flag) -//! - Tiled custom properties mapped to Bevy components (`user_properties` feature flag) +#![doc = include_str!("../book/src/intro.md")] //! //! ## Getting started //! -//! ```toml -//! [dependencies] -//! bevy = "0.14" -//! bevy_ecs_tiled = "0.3" -//! bevy_ecs_tilemap = "0.14" -//! ``` +#![doc = include_str!("../book/src/getting-started.md")] //! -//! Then add the plugin to your app: -//! -//! ```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) { -//! // Spawn a 2D camera -//! commands.spawn(Camera2dBundle::default()); +//! ## API reference //! -//! // Ensure any tile / tileset paths are relative to assets/ -//! let map_handle: Handle = asset_server.load("map.tmx"); -//! commands.spawn(TiledMapBundle { -//! tiled_map: map_handle, -//! ..Default::default() -//! }); -//! } -//! ``` +//! As the name implies, this API reference documentation purpose is to describe the API provided by `bevy_ecs_tiled`. +//! A good entry-point would be the [components::TiledMapBundle] component which is the component used to actually spawn a map. //! -//! See documentation for [components::TiledMapBundle] and the [examples](https://github.com/adrien-bon/bevy_ecs_tiled/examples/README.md) for more advanced use cases. +//! For a more use-cases oriented documentation please have a look to the [`bevy_ecs_tiled` book](https://adrien-bon.github.io/bevy_ecs_tiled/). //! pub mod components;