Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: reference book in API ref and README.md, replacing redundant sections #282

Merged
merged 11 commits into from
Jan 31, 2024
Prev Previous commit
Next Next commit
docs: replace getting-started guide and explanation in README.md with…
… book reference
  • Loading branch information
Trouv committed Dec 21, 2023
commit 4669b9cbdeb195ce0a1b22cc4af6be5a97107ce1
68 changes: 13 additions & 55 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ base.

`cargo run --example platformer --release`

### Features
## Features
- Support for all layer types
- Support for loading external levels
- Hot reloading
Expand All @@ -26,63 +26,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/v0.8.0/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/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/tutorials/tile-based-game/index.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.11 | 0.11 | 1.4.1 | main |
Expand All @@ -95,7 +53,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.