README.md

bevy_proto

Spawn entities in Bevy with a simple configuration file, similar to Unity's prefabs.

This crate can be used for:

• Quick prototyping
• Modding support
• Data-defined behaviors

📋 Features

• Define entities easily with config files:

  (
    name: "player",
     schematics: {
      "game::creature::Health": (
        value: 100,
      ),
    },
  )

• Inherit functionality from other prototypes:

  (
    name: "Skeleton",
    templates: ["Enemy", "Creature"],
    // ...
  )

• Setup entire entity hierarchies:

  (
    name: "Blaster",
    schematics: {
      "game::weapon::AmmoEntity": (
        // Even reference other entities in the tree:
        entity: EntityPath("./@1"),
      ),
    },
    children: ["Scope", "AmmoPack"]
  )

• Load assets automatically:

  (
    name: "Puppy",
    schematics: {
      "game::level::Level": (
        // Load by path:
        background: AssetPath("textures/bg.png"),
        // Or define assets inline:
        map: Asset((
          name: "Level 1",
          size: (20, 20),
          // ...
        ))
      ),
    },
  )

• Spawn!

  fn spawn_player(mut commands: ProtoCommands) {
    commands.spawn("player");
  }

📲 Installation

Add the following to your [dependencies] section in Cargo.toml:

bevy_proto = "0.11"

Or use cargo add:

cargo add bevy_proto

📓 Examples

Check out the examples folder for examples and tutorials for using the crate.

🕊 Bevy Compatibility

bevy	bevy_proto
0.11.0	0.11.0
0.10.1	0.10.0

For previous versions of this crate, see the Previous Versions section below.

🥅 Goals

This crate is mostly feature-complete.

There are a few more things I think would be really nice to add. Below is a list of my current goals and what's been accomplished thus far:

Goal	Status
Reflection support	✅
Nested prototypes	✅
Package-specifier	🚧
Configurable schematics filtering and processing	✅
Prototype arguments	🚧
Entity-less prototypes	✅
Value access	🚧
Custom file format support	✅
Improved documentation	🚧
Benchmarks	🚧

🕰 Previous Versions

Before version 0.8 of bevy_proto, this crate relied on the typetag crate. This allowed us to accomplish similar goals by using serde' s Deserialize instead of bevy's FromReflect. This was nice in that it meant we could avoid having to register every type, but it had a few drawbacks.

For one, it had issues working on WASM, which made its usage platform-specific. Additionally, its life-before-main behavior is not guaranteed to exist or work as intended by the Rust compiler, meaning it could suddenly stop working at some future point in time.

Lastly, and most importantly, is that it's not the direction Bevy itself is currently taking. Bevy is building upon its reflection library, and much of the community is following the same. As this becomes more and more standard (especially with an editor), it will just be better to lean into reflection.

However, in the interest of allowing users to decide if they also want to make the switch, I have preserved the original typetag-based code under a new crate:

bevy_proto_typetag

I imagine the crate won't see many updates outside those to bump the Bevy version. I may come back to it to create a similar flow as this crate, but I'm not going to make any promises on that as I want this crate to be the main focus.