ItemsSystem

Назначение

Модель предмета с набором свойств, формируемым при настройке, а не фиксированным в коде.

• Предмет — многоэкземплярная запись БД с полиморфным составом свойств.
• Классы свойств объявляются вне пакета; пакет о конкретных свойствах не знает.
• Доступ к свойству идёт по интерфейсу назначения за O(1).
• Настроечные данные и игровое состояние разделены: правки баланса доходят до уже существующих у игрока предметов.
• Одно событие OnChanged даёт потребителям реактивность без полинга.
• Состав меняется в рантайме и переживает сохранение.

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

Зависимости

Пакет собирается при включённом тумблере itemsSdk в SdkSettings (define-символ USING_VORTEX_ITEMS).

Сборка: ru.vortex.sdk.itemssystem. Требуется Odin Inspector.

Архитектура

Два контейнера свойств

Свойства предмета лежат в двух непубличных словарях.

Из такого хранения следует главный инвариант: не более одного свойства на интерфейс назначения. Он структурен — два свойства на одном интерфейсе физически не помещаются в индекс, конфликт вылезает при вставке.

Цена — память. На 10 000 предметов подсистема занимает порядка 16–20 МБ. Размен сознательный: на фоне сборки, где текстуры измеряются гигабайтами, это доли процента бюджета.

Реактивность

У предмета одно событие — OnChanged, поднимается при изменении значения свойства или состава свойств. Кто меняет значение (контроллер количества, прочности, тающего веса), после мутации зовёт через свойство защищённый ItemProperty.NotifyChanged(owner) — тот дёргает ItemModel.NotifyChanged() (internal). Так изменение доходит до потребителя без полинга и без глобального счётчика: инвентарь подписывается на OnChanged своих предметов и переизлучает его как собственное событие.

Производные величины пересчитываются по требованию — потребитель, читающий суммарную массу, всегда видит текущее значение, включая распад веса. Кеш вводится только там, где профиль покажет проблему.

Контракт

Вход. Идентификатор пресета, опционально — сохранённое состояние.

Гарантии.

Ограничения.

• Сигнал OnChanged при изменении значения свойства — ответственность владеющего контроллера (зовёт NotifyChanged(owner) после мутации). Пакет этого не гарантирует и проверить не может.
• Событие OnItemCreated срабатывает на каждое построение. При загрузке крупной коллекции это тысячи срабатываний подряд — обработчики обязаны быть дешёвыми.
• Исключение в обработчике события не изолируется и обрывает загрузку. Это предпочтительнее тихо полусобранного предмета.
• Идентичность класса свойства в сохранении определяется полным именем типа со сборкой. Переименование или перенос класса свойства — ломающее изменение сохранений.

Разделение настроечных и сохраняемых данных

Умолчание сериализации — «сохраняется». Забытая пометка исключения на настроечном поле приведёт к тому, что значение уедет в сохранение, перекроет настройку при загрузке и патч баланса молча перестанет доходить до старых предметов. Ошибка невидима и всплывает поздно.

Поля свойства делятся на две категории:

Приватный сеттер поле из сохранения не исключает: отбор смотрит на публичность геттера и наличие сеттера любого уровня. Это два независимых механизма.

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

Использование

1. Объявить интерфейс назначения

public interface IMassProperty : IItemProperty
{
    float Mass { get; }
}

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

2. Объявить свойство

[Serializable]
public class FixedMass : ItemProperty, IMassProperty
{
    [SerializeField] private float baseMass;
    [SerializeField] private float bonus;

    [NotPOCO] public float BaseMass { get => baseMass; private set => baseMass = value; }

    public float Bonus { get => bonus; set => bonus = value; }

    public float Mass => BaseMass + Bonus;
}

[Serializable] нужен Unity для [SerializeReference].

Инспектор работает с полями, сохранение — со свойствами. Поэтому пара «сериализуемое поле + свойство над ним»: поле даёт настройку в пресете, свойство определяет судьбу значения в сохранении. BaseMass приходит из настройки и помечен исключением; Bonus — игровое состояние и сохраняется. Mass сеттера не имеет и в сохранение не попадает.

[NotPOCO] допустим только на свойстве — на поле он не скомпилируется.

3. Объявить категории

public partial class ItemCategory
{
    public static readonly ItemCategory Weapon     = new(nameof(Weapon), 100);
    public static readonly ItemCategory Consumable = new(nameof(Consumable), 110);
}

4. Настроить пресет

Create → Database → Item. В инспекторе задаются состав свойств и категория. Тип записи закрепляется как многоэкземплярный автоматически.

5. Построить предмет

var item = ItemsBus.Create(presetGuid);                 // новый
var restored = ItemsBus.Create(presetGuid, saveData);   // из сохранения

Порядок обязателен и собран внутри шины: форма из пресета → наложение состояния → индекс → событие. Владелец берёт экземпляр по идентификатору пресета и только потом передаёт сохранённое состояние.

6. Читать свойство

var mass = item.GetProperty<IMassProperty>();
if (mass != null)
    total += mass.Mass;

7. Реагировать на изменение предмета

item.OnChanged += it => Refresh(it);   // значение свойства или состав изменились

Производную величину считают по требованию — она всегда актуальна:

public float Total(IReadOnlyList<ItemModel> items)
{
    var total = 0f;
    foreach (var item in items)
        if (item.GetProperty<IMassProperty>() is { } mass)
            total += mass.Mass;
    return total;
}

Контроллер, изменивший значение свойства, поднимает сигнал через защищённый ItemProperty.NotifyChanged(owner) — так изменение доходит до подписчиков OnChanged без полинга.

8. Менять состав

ItemsBus.AddProperty(item, new Enchantment());
ItemsBus.RemoveProperty<IEnchantment>(item);

9. Досборка после построения

ItemsBus.OnItemCreated += item =>
{
    if (item.Category == ItemCategory.Weapon && !item.HasProperty<IDurability>())
        ItemsBus.AddProperty(item, new Durability());
};

Событие срабатывает и при создании из пресета, и при восстановлении из сохранения, поэтому доменная досборка пишется один раз.

API

ItemsBus

ItemModel

ItemProperty

Редакторные инструменты

Валидация состава в инспекторе пресета — сообщение об ошибке над списком свойств. Ловятся:

• пустой слот в списке;
• повтор класса свойства;
• занятое назначение с указанием обоих претендентов;
• свойство без единого интерфейса назначения — найти его невозможно, оно инертно.

Результат кешируется на секунду, чтобы проверка не деградировала отрисовку инспектора.

Граничные случаи