Skip to content

Commit

Permalink
docs: reference book in API ref and README.md, replacing redundant se…
Browse files Browse the repository at this point in the history 
…ctions (#282)

Now that the "introductory chapters" of the book are complete, the book
can now be referenced by other repository documentation. In particular -
the getting started guide and explanation of "game logic integration"
were both already existing in a lesser form in the API ref and
README.md. These sections have been replaced by references to the books
documentation, and the *tile-based game tutorial*/*game logic
integration* chapters respectively.
  • Loading branch information
@Trouv
Trouv authored Jan 31, 2024
1 parent 49a94f3 commit e7afdad
Show file tree
Hide file tree
Showing 5 changed files with 40 additions and 136 deletions.
3 changes: 3 additions & 0 deletions .github/workflows/release-please.yml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -17,3 +17,6 @@ jobs:
changelog-types: '[{"type":"feat","section":"Features","hidden":false},{"type":"fix","section":"Bug Fixes","hidden":false},{"type":"docs","section":"Documentation Changes","hidden":false},{"type":"example","section":"Example Changes","hidden":false},{"type":"refactor","section":"Code Refactors","hidden":true},{"type":"ci","section":"CI Changes","hidden":true}]'
extra-files: |
book/src/README.md
README.md
src/lib.rs
book/src/explanation/game-logic-integration.md
76 changes: 18 additions & 58 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,15 +6,17 @@
[![Bevy tracking](https://img.shields.io/badge/Bevy%20tracking-released%20version-lightblue)](https://github.com/bevyengine/bevy/blob/main/docs/plugins_guidelines.md#main-branch-tracking)
[![CI](https://github.com/Trouv/bevy_ecs_ldtk/actions/workflows/ci.yml/badge.svg)](https://github.com/Trouv/bevy_ecs_ldtk/actions/workflows/ci.yml)

An ECS-friendly [LDtk](https://ldtk.io/) plugin for [bevy](https://github.com/bevyengine/bevy).
Uses [bevy_ecs_tilemap](https://github.com/StarArawn/bevy_ecs_tilemap) as a
base.
[`bevy_ecs_ldtk`](https://crates.io/crates/bevy_ecs_ldtk) is an ECS-friendly [LDtk](https://ldtk.io/) plugin for [Bevy](https://bevyengine.org/).
It allows you to use LDtk projects as an asset, spawn levels, and insert bevy components/bundles on LDtk entities/tiles.
This plugin is ECS-friendly, partly for its internal usage of ECS that provides extra functionality to users, and partly for its usage of [`bevy_ecs_tilemap`](https://crates.io/crates/bevy_ecs_tilemap) for rendering tilemaps.
This is all behind an ergonomic API, providing low-boilerplate solutions to common use cases.
For less common use cases, strategies that leverage this plugin's ECS constructs are also available.

![platformer-example](repo/platformer-example.gif)

`cargo run --example platformer --release`

### Features
## Features
- Support for all layer types
- Support for loading external levels
- Hot reloading
Expand All @@ -26,63 +28,21 @@ base.
improvements
- Support for Wasm (and tile spacing) through "atlas" feature

### Getting Started
The goal of this plugin is to make it as easy as possible to use LDtk with bevy
for common use cases, while providing solutions to handle more difficult cases.
You only need a few things to get started:
1. Add the `LdtkPlugin` to the `App`
2. Insert the `LevelSelection` resource into the `App` to pick your level
3. Spawn an `LdtkWorldBundle`
4. Optionally, use `#[derive(LdtkEntity)]` and `#[derive(LdtkIntCell)]` on
bundles and register them to the `App` to automatically spawn those bundles
on Entity and IntGrid layers.
## Documentation
Documentation for this plugin is available in two main places.
- API reference on [docs.rs](https://docs.rs/bevy_ecs_ldtk/0.8.0/bevy_ecs_ldtk/) <!-- x-release-please-version -->
- Tutorials, Explanation, and Guides in the [`bevy_ecs_ldtk` book](https://trouv.github.io/bevy_ecs_ldtk/main/index.html) <!-- x-release-please-version -->

```rust
use bevy::prelude::*;
use bevy_ecs_ldtk::prelude::*;
In the book, the following chapters are good jumping-off points for beginners:
- [*Tile-based Game* tutorial](https://trouv.github.io/bevy_ecs_ldtk/main/tutorials/tile-based-game/index.html) <!-- x-release-please-version -->
- [*Game Logic Integration* explanation](https://trouv.github.io/bevy_ecs_ldtk/main/explanation/game-logic-integration.html) <!-- x-release-please-version -->

fn main() {
App::new()
.add_plugins(DefaultPlugins)
.add_plugins(LdtkPlugin)
.add_system(Startup, setup)
.insert_resource(LevelSelection::index(0))
.register_ldtk_entity::<MyBundle>("MyEntityIdentifier")
.run();
}

fn setup(mut commands: Commands, asset_server: Res<AssetServer>) {
commands.spawn(Camera2dBundle::default());

commands.spawn(LdtkWorldBundle {
ldtk_handle: asset_server.load("my_project.ldtk"),
..Default::default()
});
}

#[derive(Default, Bundle, LdtkEntity)]
pub struct MyBundle {
a: ComponentA,
b: ComponentB,
#[sprite_sheet_bundle]
sprite_bundle: SpriteSheetBundle,
}
Cargo examples are also available in this repository:
```sh
$ cargo run --example example-name
```

There are other attributes available to `#[derive(LdtkEntity)]` and `#[derive(LdtkIntCell)]`, see the documentation for more details.

By default, LDtk Entities and IntGrid tiles get spawned with `EntityInstance`
and `IntGridCell` components respectfully.
So, you can flesh out these entities in a system that queries for
`Added<EntityInstance>` or `Added<IntGridCell>` if you need more access to the
world, or if you just don't want to use the `LdtkEntity` and `LdtkIntCell`
traits.

To load a new level, you can just update the `LevelSelection` resource.
Be sure to check out the `LdtkSettings` resource and the `LevelSet` component
for additional level-loading options.

### Compatibility
## Compatibility
| bevy | bevy_ecs_tilemap | LDtk | bevy_ecs_ldtk |
| --- | --- | --- | --- |
| 0.12 | main | 1.5.3 | main |
Expand All @@ -95,7 +55,7 @@ for additional level-loading options.
| 0.6 | 0.5 | 0.9 | 0.2 |
| 0.6 | 0.5 | 0.9 | 0.1 |

### Asset Credits
## Asset Credits
- [SunnyLand](https://ansimuz.itch.io/sunny-land-pixel-game-art), a texture pack by Ansimuz, licensed under [CC0 1.0](https://creativecommons.org/publicdomain/zero/1.0/)
- [PIXEL FANTASY RPG ICONS](https://cazwolf.itch.io/caz-pixel-free), an icon pack by Caz, licensed under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/)
- [Nuclear Blaze](https://github.com/deepnight/ldtk/blob/master/app/extraFiles/samples/atlas/NuclearBlaze_by_deepnight.aseprite), a tileset by Deepnight, licensed under [CC BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/). Tileset was exported from aseprite to png, but no other modifications were made.
6 changes: 1 addition & 5 deletions book/src/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,11 +2,7 @@

## `bevy_ecs_ldtk`

[`bevy_ecs_ldtk`](https://crates.io/crates/bevy_ecs_ldtk) is an ECS-friendly [LDtk](https://ldtk.io/) plugin for [Bevy](https://bevyengine.org/).
It allows you to use LDtk projects as an asset, spawn levels, and insert bevy components/bundles on LDtk entities/tiles.
This plugin is ECS-friendly, partly for its internal usage of ECS that provides extra functionality to users, and partly for its usage of [`bevy_ecs_tilemap`](https://crates.io/crates/bevy_ecs_tilemap) for rendering tilemaps.
This is all behind an ergonomic API, providing low-boilerplate solutions to common use cases.
For less common use cases, strategies that leverage this plugin's ECS constructs are also available.
{{ #include blurb.md }}

## This book
This book is a work in progress, but aims to provide the following pieces of documentation:
Expand Down
5 changes: 5 additions & 0 deletions book/src/blurb.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
[`bevy_ecs_ldtk`](https://crates.io/crates/bevy_ecs_ldtk) is an ECS-friendly [LDtk](https://ldtk.io/) plugin for [Bevy](https://bevyengine.org/).
It allows you to use LDtk projects as an asset, spawn levels, and insert bevy components/bundles on LDtk entities/tiles.
This plugin is ECS-friendly, partly for its internal usage of ECS that provides extra functionality to users, and partly for its usage of [`bevy_ecs_tilemap`](https://crates.io/crates/bevy_ecs_tilemap) for rendering tilemaps.
This is all behind an ergonomic API, providing low-boilerplate solutions to common use cases.
For less common use cases, strategies that leverage this plugin's ECS constructs are also available.
86 changes: 13 additions & 73 deletions src/lib.rs
View file
Original file line number Diff line number Diff line change
@@ -1,79 +1,19 @@
//! An ECS-friendly [LDtk](https://ldtk.io/) plugin for
//! [bevy](https://github.com/bevyengine/bevy). Uses
//! [bevy_ecs_tilemap](https://github.com/StarArawn/bevy_ecs_tilemap) as a base.
//! # `bevy_ecs_ldtk`
#![doc = include_str!("../book/src/blurb.md")]
//!
//! ### Getting Started
//! The goal of this plugin is to make it as easy as possible to use LDtk with bevy
//! for common use cases, while providing solutions to handle more difficult cases.
//! You only need a few things to get started:
//! 1. Add the [LdtkPlugin] to the [App]
//! 2. Insert the [LevelSelection] resource into the [App] to pick your level
//! 3. Spawn an [LdtkWorldBundle]
//! 4. Optionally, use `#[derive(LdtkEntity)]` and `#[derive(LdtkIntCell)]` on
//! bundles and register them to the [App] to automatically spawn those bundles
//! on Entity and IntGrid layers.
//! ## This API Reference
//! The purpose of this API reference is to describe the API provided by this plugin.
//! More explanation-oriented documentation, tutorials, and guides are available in the
//! [`bevy_ecs_ldtk` book](https://trouv.github.io/bevy_ecs_ldtk/v0.8.0). <!-- x-release-please-version -->
//!
//! ```no_run
//! use bevy::prelude::*;
//! use bevy_ecs_ldtk::prelude::*;
//! The following chapters are good jumping-off points for beginners:
//! - [*Tile-based Game* tutorial](https://trouv.github.io/bevy_ecs_ldtk/v0.8.0/tutorials/tile-based-game/index.html) <!-- x-release-please-version -->
//! - [*Game Logic Integration* explanation](https://trouv.github.io/bevy_ecs_ldtk/v0.8.0/explanation/game-logic-integration.html) <!-- x-release-please-version -->
//!
//! fn main() {
//! App::new()
//! .add_plugins(DefaultPlugins)
//! .add_plugins(LdtkPlugin)
//! .add_systems(Startup, setup)
//! .insert_resource(LevelSelection::index(0))
//! .register_ldtk_entity::<MyBundle>("MyEntityIdentifier")
//! .run();
//! }
//! Cargo examples are also available in this plugin's
//! [github repository](https://github.com/Trouv/bevy_ecs_ldtk/tree/v0.8.0/examples). <!-- x-release-please-version -->
//!
//! fn setup(mut commands: Commands, asset_server: Res<AssetServer>) {
//! commands.spawn(Camera2dBundle::default());
//!
//! commands.spawn(LdtkWorldBundle {
//! ldtk_handle: asset_server.load("my_project.ldtk"),
//! ..Default::default()
//! });
//! }
//!
//! # #[derive(Default, Component)]
//! # struct ComponentA;
//! #
//! # #[derive(Default, Component)]
//! # struct ComponentB;
//! #
//! #[derive(Default, Bundle, LdtkEntity)]
//! pub struct MyBundle {
//! a: ComponentA,
//! b: ComponentB,
//! #[sprite_sheet_bundle]
//! sprite_bundle: SpriteSheetBundle,
//! }
//! ```
//!
//! ### `Entity` and `IntGrid` layers
//! You have two options for interacting with `Entity` and `IntGrid` LDtk layers.
//! 1. As mentioned above, you can use `#[derive(LdtkEntity)]` and `#[derive(LdtkIntCell)]` on your
//! bundles to hook into the entity/intgrid-tile spawning process.
//! Of course, you can also implement these traits manually.
//! There are some field attribute macros available to these derives to handle the most common
//! use cases.
//! See [app::LdtkEntity] and [app::LdtkIntCell] for more details.
//! 2. You can query for `Added<EntityInstance>` and `Added<IntGridCell>` components in a system.
//! This works because, if an LDtk entity or intgrid tile does not match any of your
//! registrations, they are spawned with these components by default.
//! Then, you can use [Commands] to flesh out these entities like you would normally.
//!
//! The first option can be convenient and fast, while the second is good if you need more access
//! to the world than the [app] trait methods provide.
//!
//! Regardless of your choice, the spawned entities will have an appropriate [Transform].
//! They will also be spawned and despawned along with the levels they belong to, unless otherwise
//! specified with a [Worldly] component.
//! This is because, by default, the entities are spawned as children of their layer entities,
//! which in turn are children of level entities.
//!
//! ### Worlds and Levels
//! ## Worlds and Levels
//!
//! When you spawn an [LdtkWorldBundle], level entities are automatically spawned as children to
//! the world based off your level selection.
Expand All @@ -97,7 +37,7 @@
//! You can make them spawn according to their world location in LDtk by setting
//! [LevelSpawnBehavior::UseWorldTranslation].
//!
//! ### Feature flags
//! ## Feature flags
//!
//! This crate uses the following set of [feature flags]:
//! - `internal_levels`: Enable support for projects that store levels internally.
Expand Down

0 comments on commit e7afdad

Please sign in to comment.