bevy_elf 0.0.1

Serializable Bevy asset definitions that resolve string references into Handles
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90

# bevy_elf

[![Crates.io](https://img.shields.io/crates/v/bevy_elf.svg)](https://crates.io/crates/bevy_elf)
[![docs.rs](https://img.shields.io/docsrs/bevy_elf)](https://docs.rs/bevy_elf)
[![License](https://img.shields.io/badge/license-MIT%2FApache--2.0-blue.svg)](#license)

Load and resolve assets that reference other assets by name, in [Bevy](https://bevyengine.org/).

Hand-written asset types use `Handle<T>`, which isn't serializable. `bevy_elf` generates a
serializable "Def" counterpart of your asset struct — using plain strings in place of
`Handle`s — and a `FromDef` implementation that converts the Def back into your runtime type,
resolving each string into a `Handle` along the way.

```ron
// water_animation.ron
(
    frames: [1, 2, 3],
    frame_duration: (secs: 0, nanos: 128000000),
    spritesheet: "water",
)
```

```rust
use bevy_asset::prelude::*;
use bevy_elf::{FromDef, asset_spec};
use std::time::Duration;

#[derive(FromDef, Asset, TypePath)]
struct AnimationAsset {
    frames: Vec<usize>,
    frame_duration: Duration,
    spritesheet: Handle<Spritesheet>,
}

#[derive(FromDef, Asset, TypePath)]
#[asset_spec(base_path = "spritesheets", extension = "ron")]
struct Spritesheet {
    // fields omitted
}
```

The derive macro generates the `Def` struct, its `Deserialize` impl, and the resolution logic
that turns `"water"` into `Handle<Spritesheet>` by loading `spritesheets/water.ron`. Register
the loader with the `RonAssetPlugin`:

```rust
app.add_plugins((
    RonAssetPlugin::<AnimationAsset>::default(),
    RonAssetPlugin::<Spritesheet>::default(),
));
```

## Why

Bevy assets that reference other assets naturally want to hold a `Handle<T>`, but `Handle`
isn't something you can put in a `.ron`/`.toml`/`.json` file — there's nothing to point at
until the asset is loaded. The usual workaround is writing two versions of every asset type by
hand: a serializable "spec" version with string IDs, and a runtime version with `Handle`s, plus
the boilerplate to convert between them. `bevy_elf` generates that boilerplate for you.

## Features

| Feature   | Default | Adds                                                       |
|-----------|:-------:|--------------------------------------------------------------|
| `macros`  |    ✅   | The `FromDef` derive macro and `asset_spec` attribute (via `bevy_elf_macros`) |
| `math`    |    ✅   | `FromDef` impls for `bevy_math` types (`Vec2`, `Vec3`, `Quat`, `Rect`, ...) |
| `image`   |    ❌   | `FromDef` impl for `bevy_image::TextureAtlasLayout`          |

Without `macros`, you can still implement `FromDef`/`FromDefWithResolver` by hand for full
control over the conversion.

## More examples

Implicit fields, omitting empty def files, and resolving foreign types (types you don't own,
like `Handle<Image>`) are covered in the [crate documentation](https://docs.rs/bevy_elf).

## Bevy compatibility

| bevy   | bevy_elf |
|--------|----------|
| 0.19   | 0.1      |

## License

Dual-licensed under either

- MIT License ([LICENSE-MIT](LICENSE-MIT))
- Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE))

at your option.