Валидация ассетов в Unity3D

Начнём с того, что я обожаю сериализацию в Unity. Она надёжна и очень проста в использовании. Я просто расширяю MonoBehaviour, ScriptableObject и подобные классы и настраиваю сериализуемые поля экземпляров в инспекторе.

Но у неё есть и слабости. Одна из них ― человеческий фактор. Представьте себе огромный проект, который живёт несколько лет и над которым работает около сотни человек. И любой из них может совершить ошибку: оставить пустую ссылку на объект, указать число вне диапазона, ввести строку в неверном формате, заполнить массив слишком маленьким или, наоборот, слишком большим количеством объектов. Уверен, у каждого из вас найдутся такие примеры из своего опыта. Причин и оправданий тоже множество: невнимательность, неожиданные последствия слияния веток, сбои редактора… И никто от этого не застрахован.

Такие ошибки до поры до времени остаются незаметными: компилятору до них нет дела, в отличие от опечаток в коде. Особенно неприятны они тем, что проявляются часто уже во время выполнения кода. Только тогда вы начинаете читать журнал сообщений и идёте проверять данные: тыкать их в редакторе или листать YAML. Но объектов может быть достаточно много, есть риск что-то пропустить или попросту залениться.

Конечно, можно добавить проверок в коде, но от этого он загрязнится. Иногда эти проверки негативно влияют на производительность. А ещё не всегда однозначно понятно, как именно обработать каждую конкретную ошибку.

Универсального или даже штатного метода бороться с подобным в Unity нет. Поэтому мы в Pixonic реализовали свою систему валидации ассетов. И это очень помогает нам жить.

Сейчас я опишу, как там всё устроено.

Работает система на основе атрибутов на сериализуемых полях. Сначала тот, кто пишет скрипт, с помощью атрибута явно указывает свои ожидания от значения поля. Самый частый пример ― ExpectNotNull.

public class LookAtTarget : MonoBehaviour {   [SerializeField, ExpectNotNull] private Transform target;    // ... }

При постобработке ассетов значения в таких полях будут проверены на соответствие ожиданиям. В обычном режиме при сохранении ассета в логе можно увидеть нарушения с подробной локализацией, а при клике на такой лог объект подсвечивается в редакторе:

[Error] Reference is null  Property: target  Attribute: ExpectNotNullAttribute  Script: Game.Core.LookAtTarget  Object: Turret  Asset: Assets/Scripts/Game/Test.unity

В режиме batch mode у нас собирается отдельный отчёт обо всех нарушениях. Опционально существует возможность завершить сборку в CI (Continuous Integration) неудачно, если хотя бы одно ожидание с Severity.Error не сработало.

Именно эта деталь даёт нам хорошие (но не стопроцентные!) гарантии того, что данным можно доверять, и проверять их дополнительно, скорее всего, не следует.

Вроде бы этого должно быть достаточно. Но бывает такое, что в редакторе закрыта панель лога, или в ней стоит фильтр, из-за чего человек лог не видит. Поэтому для того, чтобы разработчик сразу при настройке понимал, что нарушает ожидание, была сделана система уведомлений прямо в инспекторе:

Система расширяема, и любой может добавить свой тип ожидания, написав атрибут и валидатор к нему. У нас реализовано несколько таких типов и иногда добавляются новые: как общие, так и проектно-специфичные.

Пример атрибута для валидации длины строки:

public class ExpectStringLengthAttribute : ExpectationWithSeverityAttribute {   public readonly int Min;   public readonly int Max;    public ExpectStringLengthAttribute(int min, int max) => (Min, Max) = (min, max); }

И сам валидатор длины строки:

[Validator(typeof(ExpectStringLengthAttribute))] public class ExpectStringLengthValidator : IValidator {   void IValidator.Validate(SerializedProperty property, ExpectationAttribute attribute, IList<Issue> output)   {  	if (property.propertyType != SerializedPropertyType.String)  	{     	output.AddTypeNotSupported(attribute, property.type);     	return;  	}   	var length = property.stringValue.Length;  	var rangeAttribute = (ExpectStringLengthAttribute) attribute;  	if (length < rangeAttribute.Min || length > rangeAttribute.Max)  	{     	output.Add(        	rangeAttribute.Severity,        	attribute,        	"Length out of range [{0}, {1}]", rangeAttribute.Min, rangeAttribute.Max     	);  	}   } }

Для чего нужны эти два класса? Класс атрибута должен находиться в сборке с основным кодом игры: это просто метка с параметрами. Код класса валидатора запускается только в контексте редактора и поэтому должен находиться в соответствующей сборке (в поддиректории Editor). После загрузки скриптов в контексте редактора мы обходим сборки и составляем статический словарь с ключами в виде типов атрибутов и значениями в виде экземпляров валидатора.

[DidReloadScripts] public static void ReloadScripts() {   var validatorType = typeof(IValidator);   _validators.Clear();    foreach (var assembly in AppDomain.CurrentDomain.GetAssemblies())   {  	foreach (var type in assembly.GetTypes())  	{     	if (type == validatorType || !validatorType.IsAssignableFrom(type))     	{        	continue;     	}      	foreach (var attribute in type.GetCustomAttributes(typeof(ValidatorAttribute), true))     	{        	_validators.Add(           	((ValidatorAttribute) attribute).AttributeType,           	(IValidator) Activator.CreateInstance(type)        	);     	}  	}   } }

Этот словарь далее используется как в постобработке, так и при отрисовке инспектора.

public static void Validate(SerializedProperty property, FieldInfo fieldInfo, IList<Issue> output) {   var attributes = fieldInfo.GetCustomAttributes(typeof(ExpectationAttribute), true);   for (int i = 0, count = attributes.Length; i != count; ++i)   {  	var propertyAttribute = (ExpectationAttribute) attributes[i];   	if (_validators.TryGetValue(propertyAttribute.GetType(), out var validator))  	{     	validator.Validate(property, propertyAttribute, output);  	}   } }

Во время отрисовки инспектора вызвать валидацию легче, так как в PropertyDrawer сразу доступны и property, и fieldInfo. Во время постобработки дело обстоит сложнее, так как обходить всё сериализуемое дерево приходится вручную, параллельно через рефлексию собирая FieldInfo для каждого SerializedProperty. Это достаточно объёмный код, поэтому я не буду добавлять его в статью, но здесь можно посмотреть, как это делается.

В иных сферах подобная валидация будет слишком слабой защитой от непредвиденных ошибок, но для наших целей такой способ вынести некоторые проверки из этапа времени выполнения на этапы редактирования и сборки вполне себя оправдывает. Это ускоряет разработку уже хотя бы тем, что мы можем точно увидеть, где и кто что-то сломал, снижая влияние человеческого фактора на качество сборки.