nightshade_api/
prefab.rs

1//! Runtime prefabs: capture a configured entity and its children once, then
2//! stamp copies of it anywhere. A prefab is a self-contained snapshot of a
3//! subtree with its meshes and textures embedded, so it survives a
4//! [`save_prefab`] round trip and instances independently of the original.
5
6use nightshade::ecs::scene::commands::{save_scene_binary_to_bytes, spawn_scene, subtree_to_scene};
7use nightshade::ecs::scene::{
8    Scene, SceneError, apply_scene_settings, capture_scene_settings, embed_referenced_meshes,
9    embed_referenced_textures, load_scene_binary_from_bytes,
10};
11use nightshade::prelude::{Entity, Vec3, World, tracing};
12
13/// A reusable template captured from a live entity subtree. Build one with
14/// [`make_prefab`] and place copies with [`spawn_prefab`].
15#[derive(Clone)]
16pub struct Prefab {
17    scene: Scene,
18}
19
20/// Captures `root` and everything parented under it into a prefab, embedding the
21/// meshes and textures it references so the template is self-contained.
22pub fn make_prefab(world: &World, root: Entity) -> Prefab {
23    let mut scene = subtree_to_scene(world, root, "prefab");
24    embed_referenced_meshes(world, &mut scene);
25    embed_referenced_textures(world, &mut scene);
26    Prefab { scene }
27}
28
29/// Stamps a fresh copy of `prefab` into the world with its root moved to
30/// `position`, returning the root entities of the new instance. Scene-level
31/// render settings are preserved across the spawn, which the underlying scene
32/// load would otherwise overwrite.
33pub fn spawn_prefab(world: &mut World, prefab: &Prefab, position: Vec3) -> Vec<Entity> {
34    let settings = capture_scene_settings(world);
35    let atmosphere = world.resources.render_settings.atmosphere;
36    let roots = match spawn_scene(world, &prefab.scene, None) {
37        Ok(result) => result.root_entities,
38        Err(error) => {
39            tracing::error!("Failed to spawn prefab: {error}");
40            Vec::new()
41        }
42    };
43    apply_scene_settings(world, &settings);
44    world.resources.render_settings.atmosphere = atmosphere;
45    for &root in &roots {
46        crate::placement::set_position(world, root, position);
47    }
48    roots
49}
50
51/// Serializes a prefab to self-contained bytes for storing on disk.
52pub fn save_prefab(prefab: &Prefab) -> Result<Vec<u8>, SceneError> {
53    let mut scene = prefab.scene.clone();
54    save_scene_binary_to_bytes(&mut scene)
55}
56
57/// Loads a prefab from bytes written by [`save_prefab`].
58pub fn load_prefab(bytes: &[u8]) -> Result<Prefab, SceneError> {
59    let scene = load_scene_binary_from_bytes(bytes)?;
60    Ok(Prefab { scene })
61}
nightshade_api/prefab.rs

nightshade_api/
prefab.rs
