$object — сущность, которой присваивают значение компонента$value — присваиваемое значение; в самом компоненте на этот момент ещё лежит прежнееЗаписано будет то, что лежит в $value после кода: платформа возвращает его сама, свой return тоже годится — так значение правят перед записью либо отказывают в смене. Пустое значение выражается пустой строкой либо пустым набором, null запрещён. Код срабатывает на смену значения и на появление сущности на карте; повторная запись прежнего значения его не запускает. В коде компонента менять компоненты нельзя, ставить события можно.
Кроме них коду доступны классы фреймворка игры и подключённых к ней библиотек — их зовут по имени класса; что именно они умеют, сказано на их страницах.
<?php
# Этот код и при создании существ проверит значение компонента и далее из события что будет меняться.
# ВХОД: {slot_slug => inventory_idx | null} (null = unequip слота); объект {idx => …} на входе тоже
# принимается — в таком виде приезжает уже сохранённое состояние существа при его создании.
# ХРАНЕНИЕ и РАССЫЛКА: {slot_slug => {idx, prefab} | null}. prefab со входа не берётся НИКОГДА —
# он вычисляется тут из inventory[idx]: компонент публичный, и внешний вид с клиента не подделать.
$component = ComponentCollection::list()['equip'];
if($component->maxCompareLevel != 2)
throw new Error('Компонент equip не должен иметь maxCompareLevel отличный от 2');
$current = $object->components->get('equip') ?: [];
// Инвентарь виду не обязателен: снятый с вида, он не держит ничего надетого — каждый слот снимается ниже,
// как у пустой ячейки. Без проверки чтение снятого компонента роняло бы триггер и вход сущности на карту.
$inventory = $object->components->isset('inventory') ? $object->components->get('inventory') : [];
$result = $current;
// Пустой словарь = full-clear (снять всё) — отдельный сигнал от no-op (компонента нет в пакете).
// null на этом уровне запрещён, потому полная очистка кодируется именно пустым значением.
if(!$value)
$result = array_fill_keys(array_keys($current), null);
foreach($value as $slot => $entry)
{
$idx = is_array($entry) ? ($entry['idx'] ?? null) : $entry;
// явный null — снимаем slot с тела. Кладём null (не unset), чтобы delta через
// Data::compare_recursive затёрла старое значение в кеше рассылки WebSocket-сервера.
// unset убирает ключ только из памяти sandbox: при max_compare_level=2 отсутствующий
// в setChanges ключ читается как no-op и старое значение остаётся в кеше до следующей
// перезаписи именно этого слота.
// Проверки ниже — единственные у надевания: команда ui/equip/index их не повторяет. Значение, присланное
// клиентом прямо (Block::$from_client), неверным быть не может — верный клиент шлёт слот из справочника и
// ячейку, которую видит, а между своими действиями человек дожидается ответа сервера. Неверное от него —
// нарушение: игрока снимают с карты. Сохранённая экипировка и каскад инвентаря, переставивший ждущую команду
// игрока от имени сервера, законно расходятся с нынешним составом — их отклонение уходит в журнал.
// Слот вне справочника игры (World::equipmentSlotList — game.equipment_slot) — и при надевании, и при снятии.
// У сохранённой экипировки слот могли убрать из игры: он снимается, вход игрока не держит и клиентам не уходит.
if(!World::equipmentSlotExists($slot))
{
if(Block::$from_client)
throw new Error('Слот экипировки "'.$slot.'" не разрешён в этой игре (доступные: '.implode(', ', array_keys(World::equipmentSlotList())).')');
$object->warning('Слот экипировки '.$slot.' снят: его нет в справочнике игры');
unset($result[$slot]);
continue;
}
if($idx === null)
{
$result[$slot] = null;
continue;
}
if(!array_key_exists($idx, $inventory))
{
if(Block::$from_client)
throw new Error('Надевание в слот '.$slot.': ячейки '.$idx.' в инвентаре нет');
$object->warning('Надевание в слот '.$slot.' отклонено: ячейки '.$idx.' в инвентаре нет');
continue;
}
// Пустая ячейка либо вещь, которая в этот слот не надевается.
$cell = $inventory[$idx];
if(empty($cell) || empty(World::prefabGet($cell['prefab'])['equipableSlot'][$slot]))
{
if(Block::$from_client)
throw new Error('Надевание в слот '.$slot.' из ячейки инвентаря '.$idx.': '.(empty($cell) ? 'ячейка пуста' : 'вещь '.$cell['prefab'].' в этот слот не надевается'));
$object->warning('Надевание в слот '.$slot.' из ячейки инвентаря '.$idx.' отклонено: '.(empty($cell) ? 'ячейка пуста' : 'вещь '.$cell['prefab'].' в этот слот не надевается'));
continue;
}
// TODO: вернуть дедуп (один item в одном slot). Сейчас отключён, чтобы каскад из inventory.php
// корректно переносил все equip-ссылки на один inventory_idx (иначе все, кроме последней,
// затирались тут же и оставались висеть на старом idx — phantom-equip при возврате item).
$result[$slot] = $idx;
}
// Единственная точка сборки хранимого вида: надетое — проекция инвентаря, потому prefab каждого
// слота берётся из него ЗАНОВО. Слот инвентаря мог сдвинуться (каскад inventory.php даёт новый idx)
// или опустеть; застрявший prefab показал бы окружающим не ту вещь, а пустой idx — вещь,
// которого у существа уже нет.
foreach($result as $slot => $entry)
{
$idx = is_array($entry) ? ($entry['idx'] ?? null) : $entry;
// Вещь, которая в этот слот не надевается, держит лишь отклонённое надевание поверх сохранённой экипировки
// (у префаба сменили слоты): надетым он не остаётся, как и пустая ячейка.
if($idx === null || empty($inventory[$idx]) || empty(World::prefabGet($inventory[$idx]['prefab'])['equipableSlot'][$slot]))
$result[$slot] = null;
else
$result[$slot] = ['idx' => $idx, 'prefab' => $inventory[$idx]['prefab']];
}
$value = $result;