17 releases (9 major breaking)
10.0.0 | Feb 19, 2024 |
---|---|
9.0.0 | Nov 4, 2023 |
8.0.0 | Aug 30, 2023 |
7.0.0 | Jul 9, 2023 |
1.2.0 | Mar 22, 2022 |
#581 in Game dev
324 downloads per month
Used in 6 crates
(2 directly)
39KB
197 lines
Bevy Scene hook
A proof of concept for adding components ad-hoc within code to entities
spawned through scenes (such as gltf
files) in the bevy game engine.
If you don't mind adding such a small dependency to your code rather than copy/pasting the code as a module, you can get it from crates.io.
Usage
- Add the crate to your dependencies
[dependencies]
bevy-scene-hook = "10.0.0"
- Add the plugin
.add_plugins(HookPlugin)
Example
use bevy::prelude::*;
use bevy_scene_hook::{SceneHook, HookedSceneBundle};
enum PileType { Drawing }
#[derive(Component)]
struct Pile(PileType);
#[derive(Component)]
struct Card;
fn load_scene(mut cmds: Commands, asset_server: Res<AssetServer>) {
cmds.spawn(HookedSceneBundle {
scene: SceneBundle { scene: asset_server.load("scene.glb#Scene0"), ..default() },
hook: SceneHook::new(|entity, cmds| {
match entity.get::<Name>().map(|t|t.as_str()) {
Some("Pile") => cmds.insert(Pile(PileType::Drawing)),
Some("Card") => cmds.insert(Card),
_ => cmds,
};
}),
});
}
It loads the scene.glb
file when the game starts. When the scene is fully loaded,
the closure passed to SceneHook::new
is ran for each entity
present in the scene. We add a Pile
component to entities
with a Name
component of value "Pile"
.
It is possible to name object in glb
scenes in blender using the Outliner
dock (the tree view at the top right) and double-clicking object names.
Note that SceneHook
hooks have access solely to one EntityRef
and
EntityCommands
at a time, and ignore asset reloading.
Consider using this crate's reload::Hook
for more advanced use-cases.
Implementation
bevy-scene-hook
is a tinny crate, here is copy/pastable code you can directly vendor
in your project:
use bevy::{
prelude::*,
scene::SceneInstance,
ecs::{world::EntityRef, system::EntityCommands},
};
#[derive(Component, Debug)]
pub struct SceneHooked;
#[derive(Component)]
pub struct SceneHook {
hook: Box<dyn Fn(&EntityRef, &mut EntityCommands) + Send + Sync + 'static>,
}
impl SceneHook {
pub fn new<F: Fn(&EntityRef, &mut EntityCommands) + Send + Sync + 'static>(hook: F) -> Self {
Self { hook: Box::new(hook) }
}
}
pub fn run_hooks(
unloaded_instances: Query<(Entity, &SceneInstance, &SceneHook), Without<SceneHooked>>,
scene_manager: Res<SceneSpawner>,
world: &World,
mut cmds: Commands,
) {
for (entity, instance, hooked) in unloaded_instances.iter() {
if scene_manager.instance_is_ready(**instance) {
cmds.entity(entity).insert(SceneHooked);
}
let entities = scene_manager
.iter_instance_entities(**instance)
.chain(std::iter::once(entity));
for entity_ref in entities.filter_map(|e| world.get_entity(e)) {
let mut cmd = cmds.entity(entity_ref.id());
(hooked.hook)(&entity_ref, &mut cmd);
}
}
}
pub struct HookPlugin;
impl Plugin for HookPlugin {
fn build(&self, app: &mut App) { app.add_systems(Update, run_hooks); }
}
Note that bevy-scene-hook
also has a few items defined for user convinience:
HookedSceneBundle
HookedSceneState
is_scene_hooked
Those extra items are all defined in lib.rs
.
Change log
1.1.0
: Addis_loaded
method toSceneInstance
1.2.0
: Add theworld
module containing aSceneHook
trait that has exclusive world access. Useful if you want access to assets for example.2.0.0
: Breaking: bump bevy version to0.7
(you should be able to upgrade from1.2.0
without changing your code)3.0.0
: Breaking: completely rework the crate.- Remove the
world
module, as the base hook method has become much more powerful. - Rename
SceneHook
toHook
, nowHook
has a unique method to implement. - You don't have to add any system yourself, now you have to add the
HookPlugin
plugin to your app. - Move the API exclusively to a new
SystemParam
:HookingSceneSpawner
. Please use that parameter to add and remove scenes that contain hooks. (please tell if you you accidentally spell itHonkingSceneSpawner
more than once 🦆) - Moved the
when_spawned
run criteria to theis_scene_hooked
function exposed at the root of the crate, theHookedSceneState
system parameter or theSceneLoaded
component. Please use any of those three instead ofwhen_spawned
. - Now supports passing closures as hooks, instead of having to define a trait each time.
- Now supports adding multiple of the same scene! Doesn't handle hot-reloading, but that's alright since bevy's scene hot-reloading is currently broken anyway :D
- Remove the
3.1.0
: makerun_hooks
system public so that it's possible to add it to any stage you want in relation to any other system you want.4.0.0
: Breaking: bump bevy version to0.8
- Uses the new scene bundle system
- Rename
SceneLoaded
toSceneHooked
. - Removed the
Hook
trait, nowSceneHook::new
accepts a closure. - Instead of using
HookingSceneSpawner
, usesHookedSceneBundle
and spawn it into an entity.
4.1.0
: AddHookedDynamicSceneBundle
to use withDynamicScene
s. Thanks Shatur (https://github.com/nicopap/bevy-scene-hook/pull/3)5.0.0
: Breaking: bump bevy version to0.9
5.1.1
: My bad, I accidentally published to version5.1.0
instead of5.0.0
5.1.2
: Fix scenes never triggering hooks due to a missing check. Thanks sdfgeoff (#5) If you depend onbevy-scene-hook
as a cargo dependency, you must runcargo update
to get this fix.5.2.0
: Add thereload
module, definingreload::Hook
, a variant ofSceneHook
that handles gracefully reloads and unloads.6.0.0
: Breaking: bump bevy version to0.10
.7.0.0
: Breaking: bump bevy version to0.11
.8.0.0
: Add the root entity of the scene to the list of traversed scene entities.- May be breaking if you were blanket-adding components to entities & were relying on the root not being part of them.
- Also if somehow the root has a property you were testing when adding components.
- Thanks ickk (https://github.com/nicopap/bevy-scene-hook/pull/7)
9.0.0
: Breaking: bump bevy version to0.12
.- Move
hook
functions to theSpawnScene
schedule
- Move
10.0.0
: Breaking: bump bevy version to0.13
.- Remove the
file_path
reload::Hook
field in favor of theHandle::path
method. - Add an example and test the Readme.
- Remove the
Version matrix
bevy | latest supporting version |
---|---|
0.13 | 10.0.0 |
0.12 | 9.0.0 |
0.11 | 8.0.0 |
0.10 | 6.0.0 |
0.9 | 5.2.0 |
0.8 | 4.1.0 |
0.7 | 3.1.0 |
0.6 | 1.2.0 |
License
This library is licensed under Apache 2.0.
Dependencies
~22–57MB
~1M SLoC