Agent Skills › ProwlEngine/Prowl › prowl-serialization

prowl-serialization

GitHub

说明 Prowl 引擎中 Echo 序列化机制,涵盖数据保存、字段规则、类型支持及引用处理。用于解决组件或资产在保存、加载、进入播放模式时的数据丢失、重置问题,以及自定义序列化和字段重命名。

Prowl.Editor/Resources/Agent/Skills/prowl-serialization/SKILL.md ProwlEngine/Prowl

Trigger Scenarios

决定哪些字段被保存或显示 调试保存后值丢失或重置的问题 编写自定义序列化逻辑 处理对象间引用存储

Install

npx skills add ProwlEngine/Prowl --skill prowl-serialization -g -y
More Options

Non-standard path

npx skills add https://github.com/ProwlEngine/Prowl/tree/main/Prowl.Editor/Resources/Agent/Skills/prowl-serialization -g -y

Use without installing

npx skills use ProwlEngine/Prowl@prowl-serialization

指定 Agent (Claude Code)

npx skills add ProwlEngine/Prowl --skill prowl-serialization -a claude-code -g -y

安装 repo 全部 skill

npx skills add ProwlEngine/Prowl --all -g -y

预览 repo 内 skill

npx skills add ProwlEngine/Prowl --list

SKILL.md

Frontmatter
{
    "name": "prowl-serialization",
    "description": "How Prowl saves data with the Echo serializer. Use when deciding which fields of a component or custom asset get saved and shown in the inspector, renaming saved fields or classes, writing custom serialization, storing references between objects, or debugging values that reset or go missing after saving, loading, entering play mode, or copying."
}

Prowl serialization (Echo)

Scenes, prefabs, assets, play mode, copy and paste, undo and duplicate all go through the Echo serializer. If a value is not serialized, it does not survive any of those.

What is saved

On any class or struct, including components and custom assets:

  • Saved: public instance fields, private or protected fields marked [SerializeField], and fields marked [DataMember]. Fields of base classes count too.
  • Not saved: static fields, fields marked [SerializeIgnore] or [NonSerialized], and properties, unless a property has a getter and a setter and is marked [DataMember]. Auto properties are not saved. Prefer a [SerializeField] private field behind a property.
  • The inspector shows the same fields (except [DataMember] ones), minus [HideInInspector].
  • Objects are created with their parameterless constructor (it may be private), field initializers run, then saved values are applied. A field missing from the saved data keeps its initializer value. A field saved as null loads as null.
  • A field that fails to load is logged and skipped. The rest of the object still loads. A component whose class no longer exists is kept as a missing component, so its data is not lost.
using System;
using System.Collections.Generic;
using Prowl.Echo;
using Prowl.Runtime;
using Prowl.Vector;

public enum WeaponKind { Pistol, Rifle }

[Serializable]
public class AmmoSettings
{
    public int Magazine = 30;
    public float ReloadSeconds = 1.5f;
}

public class Weapon : Component
{
    public WeaponKind Kind = WeaponKind.Rifle;               // enums are saved
    public AmmoSettings Ammo = new();                        // nested classes are saved field by field
    public List<Float3> Muzzles = new();                     // lists, arrays, dictionaries, hash sets
    public GameObject? Owner;                                // a reference to another object in the scene
    [SerializeField] private int _shotsFired;                // private, but saved
    [SerializeIgnore] public float Heat;                     // public, but not saved
    [FormerlySerializedAs("Damage")] public float BaseDamage = 10f;   // renamed without losing data

    public int ShotsFired => _shotsFired;                   // properties are not saved

    public void Fire() => _shotsFired++;
}

Supported types

Primitives, string, decimal, enums (saved as numbers, so renaming a member is safe but changing its number is not), Guid, DateTime, TimeSpan, nullable types, tuples, arrays, List, Dictionary with any key type, HashSet, Queue, Stack, nested classes and structs, and the math types Float2, Float3, Quaternion, Color.

  • Polymorphism works. When the value's real type differs from the field type, the type is saved with it, so a List<BaseThing> keeps its subclasses. An interface or abstract field only loads if that type information is there.
  • Shared references and cycles work. An object referenced twice in one save is written once and both fields point at the same object after loading.
  • Delegates, events, lambdas and Action fields are not saved.

References

  • Another object in the same scene (a GameObject, component or Transform field) is saved as a link and comes back pointing at the same object.
  • An asset in a field is saved as its GUID. Loading resolves it to the shared asset object without loading the content. See the prowl-assets skill for plain fields versus AssetRef<T>.
  • A prefab can not hold scene references. Fields in a prefab that point at objects outside the prefab come back null when it is instantiated. Look such objects up at runtime instead.
  • GameObject.Identifier and component Identifier are restored when a scene loads, but copies and instantiated objects get new ones. Store the object reference, not its Guid.

Renaming

  • Renaming a field drops its saved value unless you add [FormerlySerializedAs("OldName")] (repeat it for several old names). Field names also match case insensitively, so a change of case alone is safe.
  • Renaming a class needs [FormerlySerializedAs("OldName")] on the class (the old short name or the old namespace qualified name both work), or saved components of it become missing.

Attributes (Prowl.Echo)

Attribute Effect
[SerializeField] save a private or protected field
[SerializeIgnore] do not save a field (also [NonSerialized])
[FormerlySerializedAs("old")] read the old name, on fields or types
[IgnoreOnNull] do not write the field when it is null
[SerializeIf("Member")] save only when a bool field, property or method returns true

Custom serialization

  • Hooks, keeping normal fields: implement ISerializationCallbackReceiver with OnBeforeSerialize() and OnAfterDeserialize(). Use it to rebuild caches after loading or to copy live state into saved fields. On a component, override OnBeforeSerialize and OnAfterDeserialize instead.
  • Full control: implement ISerializable with Serialize(ref EchoObject compound, SerializationContext ctx) and Deserialize(EchoObject value, SerializationContext ctx). This replaces field saving completely, so write and read everything yourself.

When state resets

  • Entering play mode saves the edit scene and loads a copy. Anything not serialized, such as values set in a private non [SerializeField] field from the editor, starts at its initializer value.
  • Script hot reload does not go through serialization. Live objects move to the new code with every field kept, private ones included. Mark a field [Prowl.Ember.ReloadIgnore] to reset it on reload instead.
  • Duplicate, copy and paste, undo all serialize, so they keep exactly the saved fields.

Reading and writing Echo data directly

using Prowl.Echo;

public static class SaveExample
{
    public static string Save(object value) => Serializer.Serialize(value).WriteToString();

    public static T? Load<T>(string text) => Serializer.Deserialize<T>(EchoObject.ReadFromString(text));
}

WriteToString uses the Echo text format, which looks like JSON with type suffixes such as 1.5F and 3L. WriteToJson and EchoObject.ReadFromJson give plain JSON. Serializer.DeserializeInto(data, existing) loads into an object you already have. ObjectCopy.Clone(obj) (in Prowl.Runtime) deep copies through serialization. References to objects outside the copy stay pointing at the originals.

Version History

  • f68efb0 Current 2026-11-21 16:09

Same Skill Collection

Prowl.Editor/Resources/Agent/Skills/prowl-animation/SKILL.md
Prowl.Editor/Resources/Agent/Skills/prowl-assets/SKILL.md
Prowl.Editor/Resources/Agent/Skills/prowl-cli/SKILL.md
Prowl.Editor/Resources/Agent/Skills/prowl-paper/SKILL.md
Prowl.Editor/Resources/Agent/Skills/prowl-physics/SKILL.md
Prowl.Editor/Resources/Agent/Skills/prowl-profiler/SKILL.md
Prowl.Editor/Resources/Agent/Skills/prowl-rendering/SKILL.md
Prowl.Editor/Resources/Agent/Skills/prowl-scenes/SKILL.md
Prowl.Editor/Resources/Agent/Skills/prowl-ui/SKILL.md

Metadata

Files
0
Version
f68efb0
Hash
c7fc88d9
Indexed
2026-11-21 16:09

Accueil - Wiki
Copyright © 2011-2026 iteam. Current version is 2.156.0. UTC+08:00, 2026-11-21 16:35
浙ICP备14020137号-1