c2854a2a05
# Objective #13432 added proper reflection-based cloning. This is a better method than cloning via `clone_value` for reasons detailed in the description of that PR. However, it may not be immediately apparent to users why one should be used over the other, and what the gotchas of `clone_value` are. ## Solution This PR marks `PartialReflect::clone_value` as deprecated, with the deprecation notice pointing users to `PartialReflect::reflect_clone`. However, it also suggests using a new method introduced in this PR: `PartialReflect::to_dynamic`. `PartialReflect::to_dynamic` is essentially a renaming of `PartialReflect::clone_value`. By naming it `to_dynamic`, we make it very obvious that what's returned is a dynamic type. The one caveat to this is that opaque types still use `reflect_clone` as they have no corresponding dynamic type. Along with changing the name, the method is now optional, and comes with a default implementation that calls out to the respective reflection subtrait method. This was done because there was really no reason to require manual implementors provide a method that almost always calls out to a known set of methods. Lastly, to make this default implementation work, this PR also did a similar thing with the `clone_dynamic ` methods on the reflection subtraits. For example, `Struct::clone_dynamic` has been marked deprecated and is superseded by `Struct::to_dynamic_struct`. This was necessary to avoid the "multiple names in scope" issue. ### Open Questions This PR maintains the original signature of `clone_value` on `to_dynamic`. That is, it takes `&self` and returns `Box<dyn PartialReflect>`. However, in order for this to work, it introduces a panic if the value is opaque and doesn't override the default `reflect_clone` implementation. One thing we could do to avoid the panic would be to make the conversion fallible, either returning `Option<Box<dyn PartialReflect>>` or `Result<Box<dyn PartialReflect>, ReflectCloneError>`. This makes using the method a little more involved (i.e. users have to either unwrap or handle the rare possibility of an error), but it would set us up for a world where opaque types don't strictly need to be `Clone`. Right now this bound is sort of implied by the fact that `clone_value` is a required trait method, and the default behavior of the macro is to use `Clone` for opaque types. Alternatively, we could keep the signature but make the method required. This maintains that implied bound where manual implementors must provide some way of cloning the value (or YOLO it and just panic), but also makes the API simpler to use. Finally, we could just leave it with the panic. It's unlikely this would occur in practice since our macro still requires `Clone` for opaque types, and thus this would only ever be an issue if someone were to manually implement `PartialReflect` without a valid `to_dynamic` or `reflect_clone` method. ## Testing You can test locally using the following command: ``` cargo test --package bevy_reflect --all-features ``` --- ## Migration Guide `PartialReflect::clone_value` is being deprecated. Instead, use `PartialReflect::to_dynamic` if wanting to create a new dynamic instance of the reflected value. Alternatively, use `PartialReflect::reflect_clone` to attempt to create a true clone of the underlying value. Similarly, the following methods have been deprecated and should be replaced with these alternatives: - `Array::clone_dynamic` → `Array::to_dynamic_array` - `Enum::clone_dynamic` → `Enum::to_dynamic_enum` - `List::clone_dynamic` → `List::to_dynamic_list` - `Map::clone_dynamic` → `Map::to_dynamic_map` - `Set::clone_dynamic` → `Set::to_dynamic_set` - `Struct::clone_dynamic` → `Struct::to_dynamic_struct` - `Tuple::clone_dynamic` → `Tuple::to_dynamic_tuple` - `TupleStruct::clone_dynamic` → `TupleStruct::to_dynamic_tuple_struct`
109 lines
3.5 KiB
Rust
109 lines
3.5 KiB
Rust
#![cfg_attr(docsrs, feature(doc_auto_cfg))]
|
|
#![doc(
|
|
html_logo_url = "https://bevyengine.org/assets/icon.png",
|
|
html_favicon_url = "https://bevyengine.org/assets/icon.png"
|
|
)]
|
|
|
|
//! Provides scene definition, instantiation and serialization/deserialization.
|
|
//!
|
|
//! Scenes are collections of entities and their associated components that can be
|
|
//! instantiated or removed from a world to allow composition. Scenes can be serialized/deserialized,
|
|
//! for example to save part of the world state to a file.
|
|
|
|
extern crate alloc;
|
|
|
|
mod components;
|
|
mod dynamic_scene;
|
|
mod dynamic_scene_builder;
|
|
mod reflect_utils;
|
|
mod scene;
|
|
mod scene_filter;
|
|
mod scene_loader;
|
|
mod scene_spawner;
|
|
|
|
#[cfg(feature = "serialize")]
|
|
pub mod serde;
|
|
|
|
/// Rusty Object Notation, a crate used to serialize and deserialize bevy scenes.
|
|
pub use bevy_asset::ron;
|
|
|
|
use bevy_ecs::schedule::IntoScheduleConfigs;
|
|
pub use components::*;
|
|
pub use dynamic_scene::*;
|
|
pub use dynamic_scene_builder::*;
|
|
pub use scene::*;
|
|
pub use scene_filter::*;
|
|
pub use scene_loader::*;
|
|
pub use scene_spawner::*;
|
|
|
|
/// The scene prelude.
|
|
///
|
|
/// This includes the most common types in this crate, re-exported for your convenience.
|
|
pub mod prelude {
|
|
#[doc(hidden)]
|
|
pub use crate::{
|
|
DynamicScene, DynamicSceneBuilder, DynamicSceneRoot, Scene, SceneFilter, SceneRoot,
|
|
SceneSpawner,
|
|
};
|
|
}
|
|
|
|
use bevy_app::prelude::*;
|
|
use bevy_asset::AssetApp;
|
|
|
|
/// Plugin that provides scene functionality to an [`App`].
|
|
#[derive(Default)]
|
|
pub struct ScenePlugin;
|
|
|
|
#[cfg(feature = "serialize")]
|
|
impl Plugin for ScenePlugin {
|
|
fn build(&self, app: &mut App) {
|
|
app.init_asset::<DynamicScene>()
|
|
.init_asset::<Scene>()
|
|
.init_asset_loader::<SceneLoader>()
|
|
.init_resource::<SceneSpawner>()
|
|
.register_type::<SceneRoot>()
|
|
.register_type::<DynamicSceneRoot>()
|
|
.add_systems(SpawnScene, (scene_spawner, scene_spawner_system).chain());
|
|
|
|
// Register component hooks for DynamicSceneRoot
|
|
app.world_mut()
|
|
.register_component_hooks::<DynamicSceneRoot>()
|
|
.on_remove(|mut world, context| {
|
|
let Some(handle) = world.get::<DynamicSceneRoot>(context.entity) else {
|
|
return;
|
|
};
|
|
let id = handle.id();
|
|
if let Some(&SceneInstance(scene_instance)) =
|
|
world.get::<SceneInstance>(context.entity)
|
|
{
|
|
let Some(mut scene_spawner) = world.get_resource_mut::<SceneSpawner>() else {
|
|
return;
|
|
};
|
|
if let Some(instance_ids) = scene_spawner.spawned_dynamic_scenes.get_mut(&id) {
|
|
instance_ids.remove(&scene_instance);
|
|
}
|
|
scene_spawner.unregister_instance(scene_instance);
|
|
}
|
|
});
|
|
|
|
// Register component hooks for SceneRoot
|
|
app.world_mut()
|
|
.register_component_hooks::<SceneRoot>()
|
|
.on_remove(|mut world, context| {
|
|
if let Some(&SceneInstance(scene_instance)) =
|
|
world.get::<SceneInstance>(context.entity)
|
|
{
|
|
let Some(mut scene_spawner) = world.get_resource_mut::<SceneSpawner>() else {
|
|
return;
|
|
};
|
|
scene_spawner.unregister_instance(scene_instance);
|
|
}
|
|
});
|
|
}
|
|
}
|
|
|
|
#[cfg(not(feature = "serialize"))]
|
|
impl Plugin for ScenePlugin {
|
|
fn build(&self, _: &mut App) {}
|
|
}
|