legion/internals/serialize/
mod.rs

1//! Contains types required to serialize and deserialize a world via the serde library.
2
3use std::{collections::HashMap, hash::Hash, marker::PhantomData};
4
5use de::{WorldDeserializer, WorldVisitor};
6use id::EntitySerializer;
7use ser::WorldSerializer;
8use serde::{de::DeserializeSeed, Serializer};
9
10use crate::{
11    internals::{
12        storage::{
13            archetype::{ArchetypeIndex, EntityLayout},
14            component::{Component, ComponentTypeId},
15            UnknownComponentStorage,
16        },
17        world::World,
18    },
19    storage::UnknownComponentWriter,
20};
21
22pub mod archetypes;
23pub mod de;
24mod entities;
25pub mod id;
26pub mod ser;
27
28/// A (de)serializable type which can represent a component type in a serialized world.
29///
30/// This trait has a blanket impl for all applicable types.
31pub trait TypeKey:
32    serde::Serialize + for<'de> serde::Deserialize<'de> + Ord + Clone + Hash
33{
34}
35
36impl<T> TypeKey for T where
37    T: serde::Serialize + for<'de> serde::Deserialize<'de> + Ord + Clone + Hash
38{
39}
40/// A [`TypeKey`] which can construct itself for a given type T.
41pub trait AutoTypeKey<T: Component>: TypeKey {
42    /// Constructs the type key for component type `T`.
43    fn new() -> Self;
44}
45
46type SerializeFn = fn(*const u8, &mut dyn FnMut(&dyn erased_serde::Serialize));
47type SerializeSliceFn =
48    fn(&dyn UnknownComponentStorage, ArchetypeIndex, &mut dyn FnMut(&dyn erased_serde::Serialize));
49type DeserializeSliceFn = fn(
50    UnknownComponentWriter,
51    &mut dyn erased_serde::Deserializer,
52) -> Result<(), erased_serde::Error>;
53type DeserializeSingleBoxedFn =
54    fn(&mut dyn erased_serde::Deserializer) -> Result<Box<[u8]>, erased_serde::Error>;
55
56#[derive(Copy, Clone)]
57/// An error type describing what to do when a component type is unrecognized.
58pub enum UnknownType {
59    /// Ignore the component.
60    Ignore,
61    /// Abort (de)serialization wwith an error.
62    Error,
63}
64
65/// A world (de)serializer which describes how to (de)serialize the component types in a world.
66///
67/// The type parameter `T` represents the key used in the serialized output to identify each
68/// component type. The type keys used must uniquely identify each component type, and be stable
69/// between recompiles.
70///
71/// See the [legion_typeuuid crate](https://github.com/TomGillen/legion_typeuuid) for an example
72/// of a type key which is stable between compiles.
73pub struct Registry<T>
74where
75    T: TypeKey,
76{
77    _phantom_t: PhantomData<T>,
78    missing: UnknownType,
79    serialize_fns: HashMap<
80        ComponentTypeId,
81        (
82            T,
83            SerializeSliceFn,
84            SerializeFn,
85            DeserializeSliceFn,
86            DeserializeSingleBoxedFn,
87        ),
88    >,
89    constructors: HashMap<T, (ComponentTypeId, fn(&mut EntityLayout))>,
90}
91
92impl<T> Registry<T>
93where
94    T: TypeKey,
95{
96    /// Constructs a new registry.
97    pub fn new() -> Self {
98        Self {
99            missing: UnknownType::Error,
100            serialize_fns: HashMap::new(),
101            constructors: HashMap::new(),
102            _phantom_t: PhantomData,
103        }
104    }
105
106    /// Sets the behavior to use when a component type is unknown.
107    pub fn on_unknown(&mut self, unknown: UnknownType) {
108        self.missing = unknown;
109    }
110
111    /// Registers a component type and its key with the registry.
112    pub fn register<C: Component + serde::Serialize + for<'de> serde::Deserialize<'de>>(
113        &mut self,
114        mapped_type_id: T,
115    ) {
116        let type_id = ComponentTypeId::of::<C>();
117        let serialize_slice_fn =
118            |storage: &dyn UnknownComponentStorage,
119             archetype,
120             serialize: &mut dyn FnMut(&dyn erased_serde::Serialize)| unsafe {
121                let (ptr, len) = storage.get_raw(archetype).unwrap();
122                let slice = std::slice::from_raw_parts(ptr as *const C, len);
123                (serialize)(&slice);
124            };
125        let serialize_fn = |ptr, serialize: &mut dyn FnMut(&dyn erased_serde::Serialize)| {
126            let component = unsafe { &*(ptr as *const C) };
127            (serialize)(component);
128        };
129        let deserialize_slice_fn =
130            |storage: UnknownComponentWriter, deserializer: &mut dyn erased_serde::Deserializer| {
131                // todo avoid temp vec
132                ComponentSeq::<C> {
133                    storage,
134                    _phantom: PhantomData,
135                }
136                .deserialize(deserializer)?;
137                Ok(())
138            };
139        let deserialize_single_boxed_fn = |deserializer: &mut dyn erased_serde::Deserializer| {
140            let component = erased_serde::deserialize::<C>(deserializer)?;
141            unsafe {
142                let vec = std::slice::from_raw_parts(
143                    &component as *const C as *const u8,
144                    std::mem::size_of::<C>(),
145                )
146                .to_vec();
147                std::mem::forget(component);
148                Ok(vec.into_boxed_slice())
149            }
150        };
151        let constructor_fn = |layout: &mut EntityLayout| layout.register_component::<C>();
152        self.serialize_fns.insert(
153            type_id,
154            (
155                mapped_type_id.clone(),
156                serialize_slice_fn,
157                serialize_fn,
158                deserialize_slice_fn,
159                deserialize_single_boxed_fn,
160            ),
161        );
162        self.constructors
163            .insert(mapped_type_id, (type_id, constructor_fn));
164    }
165
166    /// Registers a component type and its key with the registry.
167    pub fn register_auto_mapped<
168        C: Component + serde::Serialize + for<'de> serde::Deserialize<'de>,
169    >(
170        &mut self,
171    ) where
172        T: AutoTypeKey<C>,
173    {
174        self.register::<C>(<T as AutoTypeKey<C>>::new())
175    }
176
177    /// Constructs a serde::DeserializeSeed which will deserialize into an existing world.
178    pub fn as_deserialize_into_world<'a, E: EntitySerializer>(
179        &'a self,
180        world: &'a mut World,
181        entity_serializer: &'a E,
182    ) -> DeserializeIntoWorld<'a, Self, E> {
183        DeserializeIntoWorld {
184            world,
185            world_deserializer: self,
186            entity_serializer,
187        }
188    }
189
190    /// Constructs a serde::DeserializeSeed which will deserialize into a new world.
191    pub fn as_deserialize<'a, E: EntitySerializer>(
192        &'a self,
193        entity_serializer: &'a E,
194    ) -> DeserializeNewWorld<'a, Self, E> {
195        DeserializeNewWorld {
196            world_deserializer: self,
197            entity_serializer,
198        }
199    }
200}
201
202impl<T> Default for Registry<T>
203where
204    T: TypeKey,
205{
206    #[inline]
207    fn default() -> Self {
208        Self::new()
209    }
210}
211
212impl<T> WorldSerializer for Registry<T>
213where
214    T: TypeKey,
215{
216    type TypeId = T;
217
218    unsafe fn serialize_component<Ser: Serializer>(
219        &self,
220        ty: ComponentTypeId,
221        ptr: *const u8,
222        serializer: Ser,
223    ) -> Result<Ser::Ok, Ser::Error> {
224        if let Some((_, _, serialize_fn, _, _)) = self.serialize_fns.get(&ty) {
225            let mut serializer = Some(serializer);
226            let mut result = None;
227            let result_ref = &mut result;
228            (serialize_fn)(ptr, &mut move |serializable| {
229                *result_ref = Some(erased_serde::serialize(
230                    serializable,
231                    serializer
232                        .take()
233                        .expect("serialize can only be called once"),
234                ));
235            });
236            result.unwrap()
237        } else {
238            panic!();
239        }
240    }
241
242    fn map_id(&self, type_id: ComponentTypeId) -> Result<Self::TypeId, UnknownType> {
243        if let Some(type_id) = self
244            .serialize_fns
245            .get(&type_id)
246            .map(|(type_id, _, _, _, _)| type_id.clone())
247        {
248            Ok(type_id)
249        } else {
250            Err(self.missing)
251        }
252    }
253
254    unsafe fn serialize_component_slice<Ser: Serializer>(
255        &self,
256        ty: ComponentTypeId,
257        storage: &dyn UnknownComponentStorage,
258        archetype: ArchetypeIndex,
259        serializer: Ser,
260    ) -> Result<Ser::Ok, Ser::Error> {
261        if let Some((_, serialize_fn, _, _, _)) = self.serialize_fns.get(&ty) {
262            let mut serializer = Some(serializer);
263            let mut result = None;
264            let result_ref = &mut result;
265            (serialize_fn)(storage, archetype, &mut move |serializable| {
266                *result_ref = Some(erased_serde::serialize(
267                    serializable,
268                    serializer
269                        .take()
270                        .expect("serialize can only be called once"),
271                ));
272            });
273            result.unwrap()
274        } else {
275            panic!();
276        }
277    }
278}
279
280impl<T> WorldDeserializer for Registry<T>
281where
282    T: TypeKey,
283{
284    type TypeId = T;
285
286    fn unmap_id(&self, type_id: &Self::TypeId) -> Result<ComponentTypeId, UnknownType> {
287        if let Some(type_id) = self.constructors.get(type_id).map(|(id, _)| *id) {
288            Ok(type_id)
289        } else {
290            Err(self.missing)
291        }
292    }
293
294    fn register_component(&self, type_id: Self::TypeId, layout: &mut EntityLayout) {
295        if let Some((_, constructor)) = self.constructors.get(&type_id) {
296            (constructor)(layout);
297        }
298    }
299
300    fn deserialize_component_slice<'a, 'de, D: serde::Deserializer<'de>>(
301        &self,
302        type_id: ComponentTypeId,
303        storage: UnknownComponentWriter<'a>,
304        deserializer: D,
305    ) -> Result<(), D::Error> {
306        if let Some((_, _, _, deserialize, _)) = self.serialize_fns.get(&type_id) {
307            use serde::de::Error;
308            let mut deserializer = erased_serde::Deserializer::erase(deserializer);
309            (deserialize)(storage, &mut deserializer).map_err(D::Error::custom)
310        } else {
311            //Err(D::Error::custom("unrecognized component type"))
312            panic!()
313        }
314    }
315
316    fn deserialize_component<'de, D: serde::Deserializer<'de>>(
317        &self,
318        type_id: ComponentTypeId,
319        deserializer: D,
320    ) -> Result<Box<[u8]>, D::Error> {
321        if let Some((_, _, _, _, deserialize)) = self.serialize_fns.get(&type_id) {
322            use serde::de::Error;
323            let mut deserializer = erased_serde::Deserializer::erase(deserializer);
324            (deserialize)(&mut deserializer).map_err(D::Error::custom)
325        } else {
326            //Err(D::Error::custom("unrecognized component type"))
327            panic!()
328        }
329    }
330}
331
332struct ComponentSeq<'a, T: Component> {
333    storage: UnknownComponentWriter<'a>,
334    _phantom: PhantomData<T>,
335}
336
337impl<'a, 'de, T: Component + for<'b> serde::de::Deserialize<'b>> serde::de::DeserializeSeed<'de>
338    for ComponentSeq<'a, T>
339{
340    type Value = ();
341
342    fn deserialize<D>(self, deserializer: D) -> Result<Self::Value, D::Error>
343    where
344        D: serde::de::Deserializer<'de>,
345    {
346        struct SeqVisitor<'b, C: Component + for<'c> serde::de::Deserialize<'c>> {
347            storage: UnknownComponentWriter<'b>,
348            _phantom: PhantomData<C>,
349        }
350
351        impl<'b, 'de, C: Component + for<'c> serde::de::Deserialize<'c>> serde::de::Visitor<'de>
352            for SeqVisitor<'b, C>
353        {
354            type Value = ();
355
356            fn expecting(&self, formatter: &mut std::fmt::Formatter) -> std::fmt::Result {
357                formatter.write_str("component seq")
358            }
359
360            fn visit_seq<V>(mut self, mut seq: V) -> Result<Self::Value, V::Error>
361            where
362                V: serde::de::SeqAccess<'de>,
363            {
364                if let Some(len) = seq.size_hint() {
365                    self.storage.ensure_capacity(len);
366                }
367
368                while let Some(component) = seq.next_element::<C>()? {
369                    unsafe {
370                        let ptr = &component as *const C as *const u8;
371                        self.storage.extend_memcopy_raw(ptr, 1);
372                        std::mem::forget(component)
373                    }
374                }
375                Ok(())
376            }
377        }
378
379        deserializer.deserialize_seq(SeqVisitor::<T> {
380            storage: self.storage,
381            _phantom: PhantomData,
382        })
383    }
384}
385
386/// Wraps a [`WorldDeserializer`] and a world and implements `serde::DeserializeSeed`
387/// for deserializing into the world.
388pub struct DeserializeIntoWorld<'a, W: WorldDeserializer, E: EntitySerializer> {
389    /// The [World](../world/struct.World.html) to deserialize into.
390    pub world: &'a mut World,
391    /// The [WorldDeserializer](trait.WorldDeserializer.html) to use.
392    pub world_deserializer: &'a W,
393    /// The [EntitySerializer](trait.EntitySerializer.html) to use.
394    pub entity_serializer: &'a E,
395}
396
397impl<'a, 'de, W: WorldDeserializer, E: EntitySerializer> DeserializeSeed<'de>
398    for DeserializeIntoWorld<'a, W, E>
399{
400    type Value = ();
401
402    fn deserialize<D>(self, deserializer: D) -> Result<Self::Value, D::Error>
403    where
404        D: serde::Deserializer<'de>,
405    {
406        deserializer.deserialize_map(WorldVisitor {
407            world: self.world,
408            world_deserializer: self.world_deserializer,
409            entity_serializer: self.entity_serializer,
410        })
411    }
412}
413
414/// Wraps a [`WorldDeserializer`] and a world and implements `serde::DeserializeSeed`
415/// for deserializing into a new world.
416pub struct DeserializeNewWorld<'a, W: WorldDeserializer, E: EntitySerializer> {
417    /// The [WorldDeserializer](trait.WorldDeserializer.html) to use.
418    pub world_deserializer: &'a W,
419    /// The [EntitySerializer](trait.EntitySerializer.html) to use.
420    pub entity_serializer: &'a E,
421}
422
423impl<'a, 'de, W: WorldDeserializer, E: EntitySerializer> DeserializeSeed<'de>
424    for DeserializeNewWorld<'a, W, E>
425{
426    type Value = World;
427
428    fn deserialize<D>(self, deserializer: D) -> Result<Self::Value, D::Error>
429    where
430        D: serde::Deserializer<'de>,
431    {
432        let mut world = World::default();
433        DeserializeIntoWorld {
434            world: &mut world,
435            world_deserializer: self.world_deserializer,
436            entity_serializer: self.entity_serializer,
437        }
438        .deserialize(deserializer)?;
439        Ok(world)
440    }
441}
442
443#[derive(serde::Serialize, serde::Deserialize)]
444#[serde(rename_all = "lowercase")]
445enum WorldField {
446    Packed,
447    Entities,
448}
449
450#[cfg(test)]
451mod test {
452    use super::Registry;
453    use crate::internals::{
454        entity::Entity,
455        query::filter::filter_fns::any,
456        serialize::id::{set_entity_serializer, Canon},
457        world::{EntityStore, World},
458    };
459
460    #[test]
461    fn serialize_json() {
462        let mut world = World::default();
463
464        let entity = world.extend(vec![
465            (1usize, false, 1isize),
466            (2usize, false, 2isize),
467            (3usize, false, 3isize),
468            (4usize, false, 4isize),
469        ])[0];
470
471        #[derive(serde::Serialize, serde::Deserialize)]
472        struct EntityRef(Entity);
473
474        let with_ref = world.extend(vec![
475            (5usize, 5isize, EntityRef(entity)),
476            (6usize, 6isize, EntityRef(entity)),
477            (7usize, 7isize, EntityRef(entity)),
478            (8usize, 8isize, EntityRef(entity)),
479        ])[0];
480
481        let entity_serializer = Canon::default();
482        let mut registry = Registry::<String>::default();
483        registry.register::<usize>("usize".to_string());
484        registry.register::<bool>("bool".to_string());
485        registry.register::<isize>("isize".to_string());
486        registry.register::<EntityRef>("entity_ref".to_string());
487
488        let json =
489            serde_json::to_value(&world.as_serializable(any(), &registry, &entity_serializer))
490                .unwrap();
491        println!("{:#}", json);
492
493        use serde::de::DeserializeSeed;
494        let world: World = registry
495            .as_deserialize(&entity_serializer)
496            .deserialize(json)
497            .unwrap();
498        let entry = world.entry_ref(entity).unwrap();
499        assert_eq!(entry.get_component::<usize>().unwrap(), &1usize);
500        assert_eq!(entry.get_component::<bool>().unwrap(), &false);
501        assert_eq!(entry.get_component::<isize>().unwrap(), &1isize);
502        assert_eq!(
503            world
504                .entry_ref(with_ref)
505                .unwrap()
506                .get_component::<EntityRef>()
507                .unwrap()
508                .0,
509            entity
510        );
511
512        assert_eq!(8, world.len());
513    }
514
515    #[test]
516    fn serialize_bincode() {
517        let mut world = World::default();
518
519        let entity = world.extend(vec![
520            (1usize, false, 1isize),
521            (2usize, false, 2isize),
522            (3usize, false, 3isize),
523            (4usize, false, 4isize),
524        ])[0];
525
526        world.extend(vec![
527            (5usize, 5isize),
528            (6usize, 6isize),
529            (7usize, 7isize),
530            (8usize, 8isize),
531        ]);
532
533        let entity_serializer = Canon::default();
534        let mut registry = Registry::<i32>::default();
535        registry.register::<usize>(1);
536        registry.register::<bool>(2);
537        registry.register::<isize>(3);
538
539        let encoded =
540            bincode::serialize(&world.as_serializable(any(), &registry, &entity_serializer))
541                .unwrap();
542
543        use bincode::config::Options;
544        use serde::de::DeserializeSeed;
545        let mut deserializer = bincode::de::Deserializer::from_slice(
546            &encoded[..],
547            bincode::config::DefaultOptions::new()
548                .with_fixint_encoding()
549                .allow_trailing_bytes(),
550        );
551        let world: World = registry
552            .as_deserialize(&entity_serializer)
553            .deserialize(&mut deserializer)
554            .unwrap();
555        let entity = world.entry_ref(entity).unwrap();
556        assert_eq!(entity.get_component::<usize>().unwrap(), &1usize);
557        assert_eq!(entity.get_component::<bool>().unwrap(), &false);
558        assert_eq!(entity.get_component::<isize>().unwrap(), &1isize);
559
560        assert_eq!(8, world.len());
561    }
562
563    #[test]
564    fn run_as_context_panic() {
565        std::panic::catch_unwind(|| {
566            let entity_serializer = Canon::default();
567            set_entity_serializer(&entity_serializer, || panic!());
568        })
569        .unwrap_err();
570
571        // run the serialize_bincode test again
572        serialize_bincode();
573    }
574
575    #[test]
576    fn serialize_json_external_canon() {
577        let mut world1 = World::default();
578
579        let entity = world1.extend(vec![
580            (1usize, false, 1isize),
581            (2usize, false, 2isize),
582            (3usize, false, 3isize),
583            (4usize, false, 4isize),
584        ])[0];
585
586        #[derive(serde::Serialize, serde::Deserialize)]
587        struct EntityRef(Entity);
588
589        let with_ref = world1.extend(vec![
590            (5usize, 5isize, EntityRef(entity)),
591            (6usize, 6isize, EntityRef(entity)),
592            (7usize, 7isize, EntityRef(entity)),
593            (8usize, 8isize, EntityRef(entity)),
594        ])[0];
595
596        let entity_serializer = Canon::default();
597        let mut registry = Registry::<String>::new();
598        registry.register::<usize>("usize".to_string());
599        registry.register::<bool>("bool".to_string());
600        registry.register::<isize>("isize".to_string());
601        registry.register::<EntityRef>("entity_ref".to_string());
602
603        let json =
604            serde_json::to_value(&world1.as_serializable(any(), &registry, &entity_serializer))
605                .unwrap();
606        println!("{:#}", json);
607
608        let entityname = entity_serializer.get_name(entity).unwrap();
609        assert_eq!(entity_serializer.get_id(&entityname).unwrap(), entity);
610
611        use serde::de::DeserializeSeed;
612        let world2: World = registry
613            .as_deserialize(&entity_serializer)
614            .deserialize(json)
615            .unwrap();
616        let entry = world2.entry_ref(entity).unwrap();
617        assert_eq!(entry.get_component::<usize>().unwrap(), &1usize);
618        assert_eq!(entry.get_component::<bool>().unwrap(), &false);
619        assert_eq!(entry.get_component::<isize>().unwrap(), &1isize);
620        assert_eq!(
621            world2
622                .entry_ref(with_ref)
623                .unwrap()
624                .get_component::<EntityRef>()
625                .unwrap()
626                .0,
627            entity
628        );
629
630        assert_eq!(8, world2.len());
631    }
632}
legion/internals/serialize/mod.rs

legion/internals/serialize/
mod.rs
