Serialization
Turn reflected values into RON or JSON and back with ReflectSerializer and ReflectDeserializer, without deriving serde traits, and choose which fields are saved.
Any type that derives Reflect can be written to and read from any serde format (RON, JSON and others) through the type registry. You don't derive serde's Serialize and Deserialize. World files, the RON asset loader and the editor's tools all serialize this way.
Serialize#
ReflectSerializer writes a map with one entry: the type's path and its data.
use neo::{prelude::*, reflect::serde::ReflectSerializer};
#[derive(Reflect)]
pub struct Player {
name: String,
health: u32,
}
fn save(type_registry: Res<AppTypeRegistry>) {
let registry = type_registry.read();
let player = Player { name: "Ada".into(), health: 80 };
let serializer = ReflectSerializer::new(&player, ®istry);
let ron = ron::ser::to_string_pretty(&serializer, ron::ser::PrettyConfig::default()).unwrap();
info!("{ron}");
}{
"my_game::save::Player": (
name: "Ada",
health: 80,
),
}serde_json::to_string(&serializer) writes the same as JSON. TypedReflectSerializer writes only the data, without the type path, for when the reader already knows the type.
Deserialize#
ReflectDeserializer reads the type path, finds the type in the registry and returns a Box<dyn PartialReflect>:
use neo::reflect::serde::ReflectDeserializer;
use serde::de::DeserializeSeed;
fn load(type_registry: Res<AppTypeRegistry>) {
let registry = type_registry.read();
let text = r#"{ "my_game::save::Player": (name: "Ada", health: 80) }"#;
let mut ron_de = ron::de::Deserializer::from_str(text).unwrap();
let value = ReflectDeserializer::new(®istry).deserialize(&mut ron_de).unwrap();
// the data arrives as a dynamic value; turn it into the real type
let player = Player::from_reflect(&*value).unwrap();
info!("{} has {} health", player.name, player.health);
}The result is usually a dynamic value (DynamicStruct and so on), not a Player. Convert it with FromReflect, or apply it onto an existing value; see Reflection. TypedReflectDeserializer::new(registration, ®istry) reads data written by TypedReflectSerializer.
What gets written#
| Situation | What happens |
|---|---|
A field marked #[reflect(skip_serializing)] | Left out. On load it gets its default value. |
A field marked #[reflect(ignore)] | Left out, and not reflected at all. |
A type with #[reflect(Serialize, Deserialize)] | Written with its own serde implementation instead of field by field. Use this for types with a compact or custom format. |
An opaque type (#[reflect(opaque)]) | Needs Serialize and Deserialize registered, or it can't be written. |
| A type that isn't registered | An error naming the type. |
Handles to assets are written as their asset path when they have one, so a saved component that refers to models/crate.glb#Scene0 loads that asset again.
Which format#
| Format | Use it for |
|---|---|
| RON | World files (.scn.ron) and data assets read by the RON loader. Readable and close to Rust syntax. |
| JSON | Data shared with web services or other tools. |
Add the ron or serde_json crate to your game's dependencies to use them. For player progress and shared game state, NEO has a save system; see Saving data.
Examples#
Run them from the engine core's workspace (the folder of the engine source that holds the neo crate's Cargo.toml):
| Example | What it shows |
|---|---|
serialization | JSON in and out with the reflect serializers. |
reflection | RON in and out, and applying the result. |
world_serialization | Saving and loading whole worlds. |