equip

словарь видно другим игрокам со своим кодом
Экипировка сущности — что на ней надето. Значение — словарь «слот экипировки → {idx, prefab} либо null (слот пуст)»: ключ — слот из справочника слотов экипировки игры, idx — номер ячейки инвентаря с надетой вещью, prefab — префаб надетой вещи. Компонент рассылается всем, кто видит сущность: по prefab клиент рисует надетое на чужом игроке и на прочей сущности, по idx владелец подсвечивает ячейку своего инвентаря. prefab при каждом изменении компонента берётся из ячейки инвентаря, присланный prefab не принимается. Надетой остаётся лишь вещь, которая лежит в своей ячейке и в этот слот надевается: слот, чья ячейка пуста либо держит вещь не для этого слота, при каждом изменении компонента снимается. Ссылку слота на ячейку правит инвентарь, когда надетая вещь переезжает в другую ячейку либо уходит из своей: он ставит экипировке свою правку. Что при этом становится со слотом, сказано в описании компонента inventory. Присланное значение отличается от хранимого: ключ со значением-числом надевает в этот слот вещь из ячейки инвентаря с таким номером, ключ со значением null снимает слот. Объект {idx: …} тоже принимается — в таком виде приходит сохранённая экипировка при появлении сущности; prefab в нём не берётся. Изменение частичное: слоты, которых в присланном нет, остаются как были; пустой словарь снимает всё. Все проверки надевания и снятия делает компонент, и исход зависит от того, откуда пришло значение. В значении из команды игрока любое негодное — слот вне справочника слотов экипировки (и при надевании, и при снятии), ячейка, которой в инвентаре нет, пустая ячейка либо вещь, которая в этот слот не надевается, — нарушение: игрок отключается от игры. Клиент игры шлёт лишь слот из справочника и ячейку, которую игрок видит, поэтому нарушение приходит лишь от программы, которая шлёт команды игрока мимо клиента игры. Вещь из уже освобождённой ячейки не надевает и человек: следующее действие он делает, уже увидев ответ игры на прежнее. Правка от инвентаря и сохранённая экипировка при появлении сущности законно расходятся с нынешним инвентарём, нарушения у них нет. Так же разбирается экипировка, которую игрок прислал в том же кадре: правка от инвентаря вбирает её в себя. Слот вне справочника убирается из значения вместе с ключом — так уходит сохранённая экипировка, чей слот убрали из игры. Надевание из ячейки, которой нет, из пустой ячейки либо вещи не для слота не проходит: значение этот слот не меняет, а прежняя вещь остаётся в слоте, лишь пока лежит в своей ячейке и надевается в этот слот. Поэтому сохранённая экипировка с вещью, которая в свой слот больше не надевается, при появлении сущности приходит пустым слотом. Каждый такой отказ оставляет в журнале предупреждений карты запись с причиной, остальные слоты того же значения применяются. Снятый слот из справочника остаётся в значении ключом со значением null, а не пропадает: так снятие доходит до клиентов, которые видят сущность. Рассылка идёт по слотам — уходят только изменившиеся. Уровень вложенности значения (maxCompareLevel) у компонента не меняют: при другом значении код компонента отбивает каждое значение ошибкой — с тем же исходом, что неверная скорость (описание компонента speed).
Стартовое значение
пусто
Сущность получает компонент пустым: ноль у числа, пустая строка у текста, пустой набор у списка.
Кому выдаётся
bot enemy player
Каждая сущность этих видов получает компонент при создании.
Код компонента — срабатывает, когда значение меняется, и когда сущность появляется на карте
Что платформа подаёт в код
Код исполняется телом функции, и платформа подаёт в него эти переменные:
  • $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;
К игре