Add World serialization example

Cargo.toml

@@ -41,6 +41,7 @@ rand = "0.8.3"
 trybuild = "1.0.23"
 serde = { version = "1.0.117", features = ["derive"] }
 serde_test = "1.0.117"
+bincode = "1.3.3"
 
 [[bench]]
 name = "bench"
@@ -52,3 +53,8 @@ debug = true
 
 [workspace]
 members = ["macros", "tests/no-std-test-crates/macros"]
+
+
+[[example]]
+name = "serialize_to_disk"
+required-features = ["column-serialize"]

examples/serialize_to_disk.rs

@@ -0,0 +1,180 @@
+//! This example demonstrates how to save [hecs::World] instance
+//! to disk and load it back to memory using serialization. It can be useful for implementing
+//! a save mechanism for a game.
+//!
+//! The example creates a sample `World`, serializes it, saves it to disk as `saved_world.world` file,
+//! loads it back from the disk, deserializes the loaded world data and validates that component
+//! data of the worlds match.
+//!
+//! Run this example from crate root with:
+//! `cargo run --example serialize_to_disk --features "column-serialize"`
+
+use hecs::serialize::column::{
+    deserialize_column, try_serialize, try_serialize_id, DeserializeContext, SerializeContext,
+};
+use hecs::{Archetype, ColumnBatchBuilder, ColumnBatchType, World};
+use serde::{Deserialize, Serialize};
+use std::any::TypeId;
+use std::fs::File;
+use std::io::{BufReader, Write};
+use std::path::Path;
+
+// Identifiers for the components we want to include in the serialization process:
+#[derive(Serialize, Deserialize)]
+enum ComponentId {
+    ComponentA,
+    ComponentB,
+}
+
+// We need to implement context types for the hecs serialization process:
+#[derive(Default)]
+struct SaveContextSerialize {}
+#[derive(Default)]
+struct SaveContextDeserialize {
+    components: Vec<ComponentId>,
+}
+
+// Components of our world.
+// Only Serialize and Deserialize derives are necessary.
+#[derive(Serialize, Deserialize, Eq, PartialEq, Debug, Clone)]
+struct ComponentA {
+    data: usize,
+}
+
+#[derive(Serialize, Deserialize, Eq, PartialEq, Debug, Clone)]
+struct ComponentB {
+    some_other_data: String,
+}
+
+impl DeserializeContext for SaveContextDeserialize {
+    fn deserialize_component_ids<'de, A>(&mut self, mut seq: A) -> Result<ColumnBatchType, A::Error>
+    where
+        A: serde::de::SeqAccess<'de>,
+    {
+        self.components.clear(); // Discard data from the previous archetype
+        let mut batch = ColumnBatchType::new();
+        while let Some(id) = seq.next_element()? {
+            match id {
+                ComponentId::ComponentA => {
+                    batch.add::<ComponentA>();
+                }
+                ComponentId::ComponentB => {
+                    batch.add::<ComponentB>();
+                }
+            }
+            self.components.push(id);
+        }
+        Ok(batch)
+    }
+
+    fn deserialize_components<'de, A>(
+        &mut self,
+        entity_count: u32,
+        mut seq: A,
+        batch: &mut ColumnBatchBuilder,
+    ) -> Result<(), A::Error>
+    where
+        A: serde::de::SeqAccess<'de>,
+    {
+        // Decode component data in the order that the component IDs appeared
+        for component in &self.components {
+            match *component {
+                ComponentId::ComponentA => {
+                    deserialize_column::<ComponentA, _>(entity_count, &mut seq, batch)?;
+                }
+                ComponentId::ComponentB => {
+                    deserialize_column::<ComponentB, _>(entity_count, &mut seq, batch)?;
+                }
+            }
+        }
+        Ok(())
+    }
+}
+
+impl SerializeContext for SaveContextSerialize {
+    fn component_count(&self, archetype: &Archetype) -> usize {
+        archetype
+            .component_types()
+            .filter(|&t| t == TypeId::of::<ComponentA>() || t == TypeId::of::<ComponentB>())
+            .count()
+    }
+
+    fn serialize_component_ids<S: serde::ser::SerializeTuple>(
+        &mut self,
+        archetype: &Archetype,
+        mut out: S,
+    ) -> Result<S::Ok, S::Error> {
+        try_serialize_id::<ComponentA, _, _>(archetype, &ComponentId::ComponentA, &mut out)?;
+        try_serialize_id::<ComponentB, _, _>(archetype, &ComponentId::ComponentB, &mut out)?;
+        out.end()
+    }
+
+    fn serialize_components<S: serde::ser::SerializeTuple>(
+        &mut self,
+        archetype: &Archetype,
+        mut out: S,
+    ) -> Result<S::Ok, S::Error> {
+        try_serialize::<ComponentA, _>(archetype, &mut out)?;
+        try_serialize::<ComponentB, _>(archetype, &mut out)?;
+        out.end()
+    }
+}
+
+fn main() {
+    // initialize world:
+    let mut world = World::new();
+    let input_data1 = ComponentA { data: 42 };
+    let input_data2 = ComponentB {
+        some_other_data: "Hello".to_string(),
+    };
+    world.spawn((input_data1.clone(),));
+    world.spawn((input_data2.clone(),));
+
+    let save_file_name = "saved_world.world";
+
+    // serialize and save our world to disk:
+    let mut buffer: Vec<u8> = Vec::new();
+    let options = bincode::options();
+    let mut serializer = bincode::Serializer::new(&mut buffer, options);
+    hecs::serialize::column::serialize(
+        &world,
+        &mut SaveContextSerialize::default(),
+        &mut serializer,
+    )
+    .expect("Failed to serialize");
+    let path = Path::new(save_file_name);
+    let mut file = match File::create(&path) {
+        Err(why) => panic!("couldn't create {}: {}", path.display(), why),
+        Ok(file) => file,
+    };
+    file.write(&buffer)
+        .expect(&format!("Failed to write file: {}", save_file_name));
+    println!("Saved world \'{}\' to disk.", path.display());
+
+    // load our world from disk and deserialize it back as world:
+    let open = File::open(path).expect("not found!");
+    let reader = BufReader::new(open);
+    let mut deserializer = bincode::Deserializer::with_reader(reader, options);
+    match hecs::serialize::column::deserialize(
+        &mut SaveContextDeserialize::default(),
+        &mut deserializer,
+    ) {
+        Ok(world) => {
+            // we loaded world from disk successfully, let us confirm that its data is still
+            // the same:
+            println!("Loaded world \'{}\' from disk.", path.display());
+
+            print!("Validating world data... ");
+            for (_, t) in &mut world.query::<&ComponentA>() {
+                assert_eq!(t, &input_data1);
+            }
+            for (_, t) in &mut world.query::<&ComponentB>() {
+                assert_eq!(t, &input_data2);
+            }
+            println!("Ok!");
+        }
+        Err(err) => {
+            println!("Failed to deserialize world: {}", err);
+        }
+    }
+}