Используйте класс JsonUtility для преобразования объектов Unity в JSON формат. Например, сериализацию JSON можно использовать для взаимодействия с веб-службами или для простой упаковки и распаковки данных в текстовый формат.
Сериализация JSON использует понятие «структурированного» JSON: вы создаете класс или структуру для описания того, какие переменные вы хотите хранить в своих данных JSON. Например:
[Serializable]
public class MyClass
{
public int level;
public float timeElapsed;
public string playerName;
}
Это определяет простой класс C#, содержащий три переменные (level, timeElapsed и playerName), и помечает его Serializable для работы с сериализатором JSON. Чтобы создать экземпляр вашего класса, вы можете использовать что-то вроде этого:
MyClass myObject = new MyClass();
myObject.level = 1;
myObject.timeElapsed = 47.5f;
myObject.playerName = "Dr Charles Francis";
Затем используйте метод JsonUtility.ToJson, чтобы сериализовать его (преобразовать) в формат JSON:
string json = JsonUtility.ToJson(myObject);
// json now contains: '{"level":1,"timeElapsed":47.5,"playerName":"Dr Charles Francis"}'
Чтобы преобразовать JSON обратно в объект, используйте JsonUtility.FromJson:
myObject = JsonUtility.FromJson(json);
Это создает новый экземпляр MyClass и задает для него значения с использованием данных JSON. Если данные JSON содержат значения, не соответствующие полям в MyClass, сериализатор игнорирует эти значения. Если в данных JSON отсутствуют значения для полей в MyClass, сериализатор оставляет созданные значения для этих полей в возвращаемом объекте.
Перезапись объектов с помощью JSON
Вы также можете десериализовать данные JSON поверх существующего объекта, что перезапишет любые существующие данные:
JsonUtility.FromJsonOverwrite(json, myObject);
Если данные JSON не содержат значения для поля, сериализатор не изменяет значение этого поля. Этот метод позволяет свести выделение к минимуму за счет повторного использования ранее созданных объектов. Он также позволяет вам «исправлять» объекты, преднамеренно перезаписывая их с помощью JSON, который содержит только небольшое подмножество полей.
Предупреждение. JSON Serializer API поддерживает MonoBehaviour и ScriptableObject. подклассы, а также простые структуры и классы. Однако при десериализации JSON в подклассы MonoBehaviour или ScriptableObject необходимо использовать FromJsonOverwrite. Если вы попытаетесь использовать FromJson, Unity выдаст исключение, поскольку такое поведение не поддерживается.
Поддерживаемые типы
JSON Serializer API поддерживает любой подкласс MonoBehaviour, подкласс ScriptableObject, а также простой класс или структуру с [Serializable]. Когда вы передаете объект стандартному сериализатору Unity для обработки, применяются те же правила и ограничения, что и в Инспекторе: Unity сериализует только поля; и такие типы, как Dictionary<>, не поддерживаются.
Unity не поддерживает передачу других типов напрямую в API, таких как примитивные типы или массивы. Если вам нужно преобразовать их, оберните их в какой-нибудь класс или struct.
Только в редакторе есть параллельный API, EditorJsonUtility, который позволяет сериализовать любой объект, производный от UnityEngine.Object как в JSON, так и из него. Это создает JSON, который содержит те же данные, что и YAML-представление объекта.
JsonUtility и EditorJsonUtility — это служебные классы для сериализации объектов в JSON и обратно. строковый формат с использованием правил сериализации Unity. В тех случаях, когда необходимо манипулировать данными JSON с помощью кода или сериализовать структуры данных, которые не поддерживает сериализация Unity, вы можете использовать библиотеку .NET JSON общего назначения в качестве дополнения к JsonUtility API.
Производительность
Эталонные тесты показывают, что JsonUtility работает значительно быстрее, чем популярные решения .NET JSON, хотя в некоторых случаях этот класс предоставляет меньше функций.
Использование памяти для сборки мусора (GC) минимально:
- ToJson выделяет память GC только для возвращаемой строки.
- FromJson выделяет память GC только для возвращаемого объекта, а также для любых необходимых подобъектов (например, если вы десериализуете объект, содержащий массив, то Unity выделяет память GC для массива).
- FromJsonOverwrite выделяет память GC только по мере необходимости для записанных полей (например, строк и массивов). Это означает, что Unity вообще не выделяет память GC, если все поля, перезаписываемые JSON, имеют тип значения.
Вы можете использовать JsonUtility API из фонового потока. Однако, как и в случае с любым многопоточным кодом, будьте осторожны, чтобы не получить доступ к объекту или не изменить его в одном потоке, пока другой поток сериализует или десериализует его.
Управление выводом ToJson()
Метод ToJson поддерживает красивую печать вывода JSON. По умолчанию он отключен, но вы можете включить его, передав true в качестве второго параметра.
Вы можете исключить поля из вывода, используя атрибут [NonSerialized].
Использование FromJson() с неизвестными типами
Если вы заранее не знаете тип объекта, десериализуйте JSON в класс или структуру, содержащую «общие» поля, а затем используйте значения этих полей, чтобы определить, какой фактический тип вам нужен. Затем выполните десериализацию во второй раз в этот тип.
