1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191
//! Save and load entities from various formats with serde.
//!
//! ## `WorldSerialize` / `WorldDeserialize`
//!
//! This module provides two `SystemData` implementors:
//!
//! * `SerializeComponents` and
//! * `DeserializeComponents`
//!
//! Reading those makes it very easy to serialize or deserialize
//! components.
//!
//! `SerializeComponents` implements `Serialize` and `DeserializeComponents`
//! implements `DeserializeOwned`, so serializing / deserializing should be very
//! easy.
//!
//! ## Markers
//!
//! Because you usually don't want to serialize everything, we use
//! markers to say which entities we're interested in. However, these markers
//! aren't just boolean values; we also have id spaces which allow us
//! to identify entities even if local ids are different. The allocation
//! of these ids is what `MarkerAllocator`s are responsible for. For an example,
//! see the docs for the `Marker` trait.
use std::convert::Infallible;
use serde::{de::DeserializeOwned, Deserialize, Serialize};
use crate::world::Entity;
mod de;
mod marker;
mod ser;
#[cfg(test)]
mod tests;
#[cfg(feature = "uuid_entity")]
mod uuid;
#[cfg(feature = "uuid_entity")]
pub use self::uuid::{UuidMarker, UuidMarkerAllocator};
pub use self::{
de::DeserializeComponents,
marker::{MarkedBuilder, Marker, MarkerAllocator, SimpleMarker, SimpleMarkerAllocator},
ser::SerializeComponents,
};
/// A struct used for deserializing entity data.
#[derive(Serialize, Deserialize)]
pub struct EntityData<M, D> {
/// The marker the entity was mapped to.
pub marker: M,
/// The components associated with an entity.
pub components: D,
}
/// Converts a data type (usually a [`Component`]) into its serializable form
/// and back to actual data from it's deserialized form.
///
/// This is automatically implemented for any type that is
/// [`Clone`], [`Serialize`] and [`DeserializeOwned`].
///
/// Implementing this yourself is usually only needed if you
/// have a component that points to another [`Entity`], or has a field which
/// does, and you wish to [`Serialize`] it.
///
/// *Note*: if you're using `specs_derive`
/// you can use `#[derive(Saveload)]` to automatically derive this.
///
/// You must add the `derive` to any type that your component holds which does
/// not auto-implement this traits, including the component itself (similar to
/// how normal [`Serialize`] and [`Deserialize`] work).
///
/// [`Component`]: ../trait.Component.html
/// [`Entity`]: ../struct.Entity.html
/// [`Serialize`]: https://docs.serde.rs/serde/trait.Serialize.html
/// [`Deserialize`]: https://docs.serde.rs/serde/trait.Deserialize.html
/// [`DeserializeOwned`]: https://docs.serde.rs/serde/de/trait.DeserializeOwned.html
///
/// # Example
///
/// ```rust
/// # extern crate specs;
/// # #[macro_use] extern crate serde;
/// use serde::{Deserialize, Serialize};
/// use specs::{
/// prelude::*,
/// saveload::{ConvertSaveload, Marker},
/// };
/// use std::convert::Infallible;
///
/// struct Target(Entity);
///
/// impl Component for Target {
/// type Storage = VecStorage<Self>;
/// }
///
/// // We need a matching "data" struct to hold our
/// // marker. In general, you just need a single struct
/// // per component you want to make `Serialize`/`Deserialize` with each
/// // instance of `Entity` replaced with a generic "M".
/// #[derive(Serialize, Deserialize)]
/// struct TargetData<M>(M);
///
/// impl<M: Marker + Serialize> ConvertSaveload<M> for Target
/// where
/// for<'de> M: Deserialize<'de>,
/// {
/// type Data = TargetData<M>;
/// type Error = Infallible;
///
/// fn convert_into<F>(&self, mut ids: F) -> Result<Self::Data, Self::Error>
/// where
/// F: FnMut(Entity) -> Option<M>,
/// {
/// let marker = ids(self.0).unwrap();
/// Ok(TargetData(marker))
/// }
///
/// fn convert_from<F>(data: Self::Data, mut ids: F) -> Result<Self, Self::Error>
/// where
/// F: FnMut(M) -> Option<Entity>,
/// {
/// let entity = ids(data.0).unwrap();
/// Ok(Target(entity))
/// }
/// }
/// ```
pub trait ConvertSaveload<M>: Sized {
/// (De)Serializable data representation for data type
type Data: Serialize + DeserializeOwned;
/// Error may occur during serialization or deserialization of component
type Error;
/// Convert this data from a deserializable form (`Data`) using
/// entity to marker mapping function
fn convert_from<F>(data: Self::Data, ids: F) -> Result<Self, Self::Error>
where
F: FnMut(M) -> Option<Entity>;
/// Convert this data type into serializable form (`Data`) using
/// entity to marker mapping function
fn convert_into<F>(&self, ids: F) -> Result<Self::Data, Self::Error>
where
F: FnMut(Entity) -> Option<M>;
}
impl<C, M> ConvertSaveload<M> for C
where
C: Clone + Serialize + DeserializeOwned,
{
type Data = Self;
type Error = Infallible;
fn convert_into<F>(&self, _: F) -> Result<Self::Data, Self::Error>
where
F: FnMut(Entity) -> Option<M>,
{
Ok(self.clone())
}
fn convert_from<F>(data: Self::Data, _: F) -> Result<Self, Self::Error>
where
F: FnMut(M) -> Option<Entity>,
{
Ok(data)
}
}
impl<M> ConvertSaveload<M> for Entity
where
M: Serialize + DeserializeOwned,
{
type Data = M;
type Error = Infallible;
fn convert_into<F>(&self, mut func: F) -> Result<Self::Data, Self::Error>
where
F: FnMut(Entity) -> Option<M>,
{
Ok(func(*self).unwrap())
}
fn convert_from<F>(data: Self::Data, mut func: F) -> Result<Self, Self::Error>
where
F: FnMut(M) -> Option<Entity>,
{
Ok(func(data).unwrap())
}
}