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
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138

//! Define and spawn entities with simple configuration files.
//!
//! # Capabilities
//!
//! * Define entities in configuration files called _[prototypes]_
//! * Inherit from other prototype files
//! * Establish entity hierarchies
//! * Load or preload assets
//!
//! This is all built on a backend crate called [`bevy_proto_backend`].
//! If you want to define your own prototype schema,
//! feel free to use that crate directly!
//!
//! # Example
//!
//! Prototypes can be defined using a RON file ending in `.prototype.ron`:
//!
//! ```text
//! // Player.prototype.ron
//! (
//!   name: "Player",
//!   schematics: {
//!     "bevy_proto::custom::SpriteBundle": (
//!       texture: AssetPath("textures/player.png"),
//!     ),
//!   }
//! )
//! ```
//!
//! Then they can be loaded and spawned from any system:
//!
//! ```
//! use bevy_proto::prelude::*;
//!
//! fn load_player(mut prototypes: PrototypesMut) {
//!   prototypes.load("prototypes/Player.prototype.ron");
//! }
//!
//! fn spawn_player(mut commands: ProtoCommands) {
//!   commands.spawn("Player");
//! }
//! ```
//!
//! # Cargo Features
//!
//! | Feature           | Default | Description                                                    |
//! | ----------------- | ------- | -------------------------------------------------------------- |
//! | auto_name         | ✅      | Automatically insert [`Name`] components on spawned prototypes |
//! | custom_schematics | ✅      | Enables some [custom schematics] defined by this crate         |
//! | ron               | ✅      | Enables RON deserialization                                    |
//! | yaml              | ❌      | Enables YAML deserialization                                   |
//! | bevy_animation    | ✅      | Registers types under Bevy's `bevy_animation` feature          |
//! | bevy_audio        | ✅      | Registers types under Bevy's `bevy_audio` feature              |
//! | bevy_gltf         | ✅      | Registers types under Bevy's `bevy_gltf` feature               |
//! | bevy_pbr          | ✅      | Registers types under Bevy's `bevy_pbr` feature                |
//! | bevy_render       | ✅      | Registers types under Bevy's `bevy_render` feature             |
//! | bevy_scene        | ✅      | Registers types under Bevy's `bevy_scene` feature              |
//! | bevy_sprite       | ✅      | Registers types under Bevy's `bevy_sprite` feature             |
//! | bevy_text         | ✅      | Registers types under Bevy's `bevy_text` feature               |
//!
//! [prototypes]: proto::Prototype
//! [`Name`]: bevy::core::Name
//! [custom schematics]: custom

mod conditions;
pub mod config;
#[cfg(feature = "custom_schematics")]
pub mod custom;
pub mod de;
pub mod hooks;
pub mod loader;
mod plugin;
pub mod proto;
mod schematics;

/// Provides the basics needed to use this crate.
///
/// This is meant to be used like:
/// ```
/// use bevy_proto::prelude::*;
/// ```
pub mod prelude {
    pub use crate::config::ProtoConfig;
    pub use bevy_proto_backend::deps::DependenciesBuilder;
    pub use bevy_proto_backend::proto::Prototypical;
    pub use bevy_proto_backend::schematics::{ReflectSchematic, Schematic, SchematicContext};

    pub use super::conditions::*;
    pub use super::plugin::ProtoPlugin;
    pub use super::proto::{Prototype, PrototypeError};

    /// A helper SystemParam for managing [prototypes].
    ///
    /// For the mutable version, see [`PrototypesMut`].
    ///
    /// [prototypes]: Prototype
    pub type Prototypes<'w, C = ProtoConfig> =
        bevy_proto_backend::proto::Prototypes<'w, Prototype, C>;

    /// A helper SystemParam for managing [prototypes].
    ///
    /// For the immutable version, see [`Prototypes`].
    ///
    /// [prototypes]: Prototype
    pub type PrototypesMut<'w, C = ProtoConfig> =
        bevy_proto_backend::proto::PrototypesMut<'w, Prototype, C>;

    /// A system parameter similar to [`Commands`], but catered towards [prototypes].
    ///
    /// [`Commands`]: bevy::prelude::Commands
    /// [prototypes]: Prototype
    pub type ProtoCommands<'w, 's, C = ProtoConfig> =
        bevy_proto_backend::proto::ProtoCommands<'w, 's, Prototype, C>;

    /// A struct similar to [`EntityCommands`], but catered towards [prototypes].
    ///
    /// [`EntityCommands`]: bevy::ecs::system::EntityCommands
    /// [prototypes]: Prototype
    pub type ProtoEntityCommands<'w, 's, 'a, C = ProtoConfig> =
        bevy_proto_backend::proto::ProtoEntityCommands<'w, 's, 'a, Prototype, C>;

    /// Asset lifecycle events for [prototype] assets.
    ///
    /// This is analogous to [`AssetEvent`], but accounts for prototype
    /// caching and registration.
    /// This event should be preferred over using the `AssetEvent` directly.
    ///
    /// [prototype]: Prototype
    /// [`AssetEvent`]: bevy::asset::AssetEvent
    pub type ProtoAssetEvent = bevy_proto_backend::proto::ProtoAssetEvent<Prototype>;
}

/// Provides access to the [backend crate] that `bevy_proto` is built on.
///
/// [backend crate]: bevy_proto_backend
pub mod backend {
    pub use bevy_proto_backend::*;
}