2 releases
0.2.1 | Dec 26, 2021 |
---|---|
0.2.0 | Dec 25, 2021 |
#15 in #prefab
74KB
1K
SLoC
Bevy Lazy Prefabs
A crate for simple human readable/writable prefab text files in bevy.
Note: This is not intended to be a flexible and long-term prefab solution, but should serve well for simple games and prototyping to avoid having to define your entities entirely in code.
.Prefab Files
First, write a .prefab file and put it in the assets/prefabs directory.
SomePrefab { // Prefab name is optional. Outer braces are required.
Transform { // Components are listed by type name.
translation : Vec3 { // Component fields can be initialized inside nested curly braces.
x: 15.0, y: 10.5, // Any omitted fields will be initialized to default.
},
},
Visible, // If you choose not to initialize any fields, the braces can be omitted entirely.
Draw,
SomeComponent { // Custom components are supported
some_int: 15,
},
}
In the above example we are authoring a prefab with Transform
, Visible
, Draw
, and SomeComponent
components.
In this case the entity's transform will be initialized to position (15.0,10.0,0.0) when entity is spawned.
Custom components will only work in prefabs if they derive Reflect
and Default
, and if they have the
#[reflect(Component)]
attribute. Most built in bevy types already meet this constraint. They must also be
registered with the [PrefabRegistry] during setup.
The above prefab isn't much use though - the entity won't be rendered since it has no mesh or material. For that we can use a build_commands::BuildPrefabCommand.
BuildPrefabCommands
Build commands allow you to include complex components that require extra steps to correctly initialize, such as meshes, materials, or bundles.
Custom commands can be authored, but there are several included for more common components:
InsertSpriteBundle
- Inserts aSpriteBundle
on an entity. Can specifycolor
andtexture_path
.SetColorMaterial
- Modify an existingColorMaterial
on the entity.LoadPrefab
- Load an existing prefab and perform it's build steps on the current entity.InsertPbrBundle
- Inserts aPbrBundle
. Can specify meshshape
,size
, andflip
.InsertOrthographicCameraBundle
- Inserts anOrthographicCameraBundle
. Can specifyscale
.InsertPerspectiveCameraBundle
- Inserts aPerspectiveCameraBundle
. Can specifyposition
andlooking_at
.
Example
{
InsertSpriteBundle! (
texture_path: "alien.png",
color: Color::RED,
),
}
The above .prefab file will result in an entity with all the components from a SpriteBundle
. The sprite bundle's
ColorMaterial
component will be initialized with the given texture and color.
Note these 'fields' are not referring directly to fields in the bundle, but are optional properties that get passed to the build command and used in the initialization process. How these properties get used is defined by every individual build command.
Spawning A Prefab
Once you have your .prefab file in the assets/prefabs directory you can spawn a prefab using the
[PrefabRegistry] and Commands
:
use bevy::prelude::*;
use bevy_lazy_prefabs::*;
fn setup(mut commands: Commands, mut registry: ResMut<PrefabRegistry>) {
let sprite = registry.load("sprite.prefab").unwrap();
commands.spawn().insert_prefab(sprite);
let cam = registry.load("cam_2d.prefab").unwrap();
commands.spawn().insert_prefab(cam);
}
Dependencies
~32–75MB
~643K SLoC