From f40a301aa9b8ff974aa3748cd1a96b466e180202 Mon Sep 17 00:00:00 2001 From: xxSeys1 Date: Fri, 24 Jan 2025 17:54:54 +0100 Subject: [PATCH 1/3] serialization docs pass --- manual/scripting/serialization/index.md | 40 ++++++++++++++----------- 1 file changed, 23 insertions(+), 17 deletions(-) diff --git a/manual/scripting/serialization/index.md b/manual/scripting/serialization/index.md index d294f8c2..6612ae8b 100644 --- a/manual/scripting/serialization/index.md +++ b/manual/scripting/serialization/index.md @@ -1,33 +1,39 @@ # Scripts serialization -**Scripts serialization** is a feature that allows to save the object into a portable data format. Later this data can be used to restore the state of the object. It's used when loading scenes, performing hot-reload or recording undo actions. +**Scripts serialization** is a feature that allows to save an object into a portable data format. Later, this data can be used to restore the state of the object. It is used when loading scenes, performing hot-reload or recording undo actions. -Flax uses **Json** format to store scripts and objects state. It's a lightweight and very standardized format. Flax C# API contains a build-in methods to serialize and deserialize objects, even at runtime. See [JsonSerializer](https://docs.flaxengine.com/api/FlaxEngine.Json.JsonSerializer.html) class. Under the hood Flax uses custom [Json.NET](https://github.com/JamesNK/Newtonsoft.Json) which is a popular high-performance JSON framework for .NET. +Flax uses the **Json** format to store scripts and objects state. It's a lightweight and very standardized format. + +Flax's C# API contains a build-in methods to serialize and deserialize objects, even at runtime. See [JsonSerializer](https://docs.flaxengine.com/api/FlaxEngine.Json.JsonSerializer.html) class. Under the hood, Flax uses custom [Json.NET](https://github.com/JamesNK/Newtonsoft.Json) which is a popular high-performance JSON framework for .NET. ## Serialization rules -Flax serializes object field or properties if: +Flax serializes an object field or a property if: -* It's `public` or has [Serialize](https://docs.flaxengine.com/api/FlaxEngine.SerializeAttribute.html) attribute (inherited `private` members are not saved - but `protected` are) -* It has no [NoSerialize](https://docs.flaxengine.com/api/FlaxEngine.NoSerializeAttribute.html) attribute -* It's not `static` -* It's not `readonly` -* It's not `const` * Its type can be serialized +* It is `public` +* It is `private` **and** has a [Serialize](https://docs.flaxengine.com/api/FlaxEngine.SerializeAttribute.html) attribute (inherited `private` members are not saved - but `protected` are) + +Flax does not serialize an object field or a property if: +* It is `private` +* It is `static` +* It is `readonly` +* It is a `const` +* It has a [NoSerialize](https://docs.flaxengine.com/api/FlaxEngine.NoSerializeAttribute.html) attribute -[Here](https://github.com/FlaxEngine/FlaxEngine/blob/master/Source/Engine/Serialization/JsonCustomSerializers/ExtendedDefaultContractResolver.cs) you can find a open source file that implements serialization rules used by the Flax. +You can find an open source file that implements serialization rules used by Flax [here](https://github.com/FlaxEngine/FlaxEngine/blob/master/Source/Engine/Serialization/JsonCustomSerializers/ExtendedDefaultContractResolver.cs) . -Flax deserialization works more like `populate` existing object with data rather than `full load`. This reduces amount of data required to save and helps with changing the default values for the fields and properties. +Flax deserialization works more like `populate` existing object with data rather than `full load`. This reduces the amount of data required to save, and it helps with changing the default values for the fields and properties. ## Serialization tips -Here are listed various hints about Flax serialization: +Here are some tips and hints about serialization in Flax: -* References to the scene objects (actors, scripts) are serialized as `Guid` (hex format, inlined). See [Object.ID](https://docs.flaxengine.com/api/FlaxEngine.Object.html#FlaxEngine_Object_ID). -* Editor uses default serialization rules for Undo -* Flax deserializes all child scene object before calling `OnAwake`/`OnStart` methods on loaded objects (parent object may not be deserialized yet). -* Avoid recursive references for custom objects types. It's better to use loop-references for scene objects. -* When performing code refactoring see [this tutorial](../advanced/refactoring-renaming.md) about supporting old data format loading +* References to scene objects (actors, scripts) are serialized as `Guid` (hex format, inlined). See [Object.ID](https://docs.flaxengine.com/api/FlaxEngine.Object.html#FlaxEngine_Object_ID). +* The editor uses default serialization rules for the Undo & Redo system. +* Flax deserializes all child scene object before calling the `OnAwake`/`OnStart` methods on loaded objects (parent object may not be deserialized yet). +* It is best to avoid recursive references for custom objects types. It's better to use loop-references for scene objects. +* When performing code refactoring, take a look at [this tutorial](../advanced/refactoring-renaming.md) about supporting old data format loading ## Serialization Callbacks @@ -73,4 +79,4 @@ public class MyScript : Script ## Native C\+\+ serialization -To learn about C++ objects serialization see related documentation [here](../cpp/serialization.md). +To learn more about C++ objects serialization, see the related documentation [here](../cpp/serialization.md). From b1d93ca12e16c887af47061ade89d2a4bd0cd4a3 Mon Sep 17 00:00:00 2001 From: xxSeys1 Date: Fri, 24 Jan 2025 17:57:39 +0100 Subject: [PATCH 2/3] add info about custom newtonsoft json fork --- manual/scripting/serialization/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/manual/scripting/serialization/index.md b/manual/scripting/serialization/index.md index 6612ae8b..2318dd32 100644 --- a/manual/scripting/serialization/index.md +++ b/manual/scripting/serialization/index.md @@ -4,7 +4,7 @@ Flax uses the **Json** format to store scripts and objects state. It's a lightweight and very standardized format. -Flax's C# API contains a build-in methods to serialize and deserialize objects, even at runtime. See [JsonSerializer](https://docs.flaxengine.com/api/FlaxEngine.Json.JsonSerializer.html) class. Under the hood, Flax uses custom [Json.NET](https://github.com/JamesNK/Newtonsoft.Json) which is a popular high-performance JSON framework for .NET. +Flax's C# API contains a build-in methods to serialize and deserialize objects, even at runtime. See [JsonSerializer](https://docs.flaxengine.com/api/FlaxEngine.Json.JsonSerializer.html) class. Under the hood, Flax uses a custom fork of [Json.NET](https://github.com/JamesNK/Newtonsoft.Json), which is a popular high-performance JSON framework for .NET. ## Serialization rules From 38a9a285fe9b64ee4a66354d74f787e4a676d5e9 Mon Sep 17 00:00:00 2001 From: xxSeys1 Date: Fri, 24 Jan 2025 22:56:42 +0100 Subject: [PATCH 3/3] put a greater emphasis on the not --- manual/scripting/serialization/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/manual/scripting/serialization/index.md b/manual/scripting/serialization/index.md index 2318dd32..a2caa055 100644 --- a/manual/scripting/serialization/index.md +++ b/manual/scripting/serialization/index.md @@ -14,7 +14,7 @@ Flax serializes an object field or a property if: * It is `public` * It is `private` **and** has a [Serialize](https://docs.flaxengine.com/api/FlaxEngine.SerializeAttribute.html) attribute (inherited `private` members are not saved - but `protected` are) -Flax does not serialize an object field or a property if: +Flax does *not* serialize an object field or a property if: * It is `private` * It is `static` * It is `readonly`