nightshade-api 0.45.0

//! Saving and loading the whole scene. The spawn-and-forget API builds a world
//! once; a tool has to write it to disk and read it back, so this captures the
//! world to bytes and respawns it.

use nightshade::ecs::scene::commands::save_scene_binary_to_bytes;
use nightshade::ecs::scene::{
    SceneError, SceneSettings, apply_scene_settings, capture_scene_settings,
    embed_referenced_meshes, embed_referenced_textures, load_scene_binary_from_bytes, spawn_scene,
    spawn_scene_with_deserializer, world_to_scene, world_to_scene_with_serializer,
};
use nightshade::prelude::*;

/// Register a custom component type and serialize game-side state into a scene.
/// A game that keeps its own data in a second world stores it through these
/// hooks so [`save_scene_with`] and [`load_scene_with`] round-trip it alongside
/// the engine entities.
pub use nightshade::ecs::scene::{
    ComponentDescriptor, ComponentTypeRegistry, FieldDescriptor, FieldKind, Persistence,
    SceneDeserializer, SceneSerializer, TypedComponent, TypedPayload,
    register_component_descriptor,
};

/// Captures the world to a compressed binary scene, embedding the meshes and
/// textures its entities reference so the bytes are self contained.
pub fn save_scene(world: &World, name: &str) -> Result<Vec<u8>, SceneError> {
    let mut scene = world_to_scene(world, name);
    embed_referenced_meshes(world, &mut scene);
    embed_referenced_textures(world, &mut scene);
    save_scene_binary_to_bytes(&mut scene)
}

/// Spawns a scene saved by [`save_scene`] into the world, returning the root
/// entities it created.
pub fn load_scene(world: &mut World, bytes: &[u8]) -> Result<Vec<Entity>, SceneError> {
    let scene = load_scene_binary_from_bytes(bytes)?;
    let result = spawn_scene(world, &scene, None)?;
    Ok(result.root_entities)
}

/// Saves the world like [`save_scene`], also running a [`SceneSerializer`] so a
/// game's own components (registered with [`register_component_descriptor`]) are
/// written into the scene's typed payloads.
pub fn save_scene_with(
    world: &World,
    name: &str,
    serializer: &dyn SceneSerializer,
) -> Result<Vec<u8>, SceneError> {
    let mut scene = world_to_scene_with_serializer(world, name, Some(serializer));
    embed_referenced_meshes(world, &mut scene);
    embed_referenced_textures(world, &mut scene);
    save_scene_binary_to_bytes(&mut scene)
}

/// Loads a scene like [`load_scene`], also running a [`SceneDeserializer`] so a
/// game's own components are reconstructed from the scene's typed payloads.
pub fn load_scene_with(
    world: &mut World,
    bytes: &[u8],
    deserializer: &mut dyn SceneDeserializer,
) -> Result<Vec<Entity>, SceneError> {
    let scene = load_scene_binary_from_bytes(bytes)?;
    let result = spawn_scene_with_deserializer(world, &scene, None, Some(deserializer))?;
    Ok(result.root_entities)
}

/// Snapshots the world's scene-level settings (atmosphere, fog, post
/// processing). Pair with [`apply_settings`] to restore them around an
/// operation that would otherwise reset them.
pub fn capture_settings(world: &World) -> SceneSettings {
    capture_scene_settings(world)
}

/// Applies scene-level settings captured by [`capture_settings`].
pub fn apply_settings(world: &mut World, settings: &SceneSettings) {
    apply_scene_settings(world, settings);
}