index

из группы item/give
Выдача названных вещей (параметр items) получателю-игроку из добычи контейнера (компонент loot), на котором команда исполняется. Списание у контейнера — перенос: разница на землю не падает; зачисление уходит одним изменением состояния получателя. Место у получателя выдача не ищет: его находит зачисление в момент применения, а вещь, которой места нет, падает получателю под ноги. Выдаётся всё в одном кадре. Пока стоит отсчёт допуска к добыче (status/lootfree), выдаёт только допущенным — тем, кто в его списке. Заявки нескольких получателей одного кадра исполняются по очереди, каждая в своём кадре. У торгующего контейнера (есть компонент trade) выдача — это продажа за монеты, которые покупатель заплатил заранее своей командой забора (параметр paid): здесь считается цена выданного, а выручка ложится в ту же добычу, откуда ушёл товар. Точка решения о сделке одна — та, где товар списывается. Вещь, которую торговец не продаёт (у неё нет базовой цены — компонент price — либо множитель продажи (buy) у торговца нулевой), остаётся у него, остальные продаются и оплачиваются только они. Цена выданного не совпала с уплаченным либо выручку некуда положить (монет в добыче торговца нет, а разных вещей в ней и после выдачи предел — столько, сколько ячеек в умолчании компонента inventory, подпись поля — «По умолчанию») — не уходит ничего. Любой отказ — ТИХИЙ, без списания. Получатель отошёл дальше соседней клетки — гонка: заявку обошёл его же шаг, отказ пишется в журнал предупреждений. Прочие отказы (получатель ушёл с карты либо вышел из игры, получатель мёртв, названных вещей в добыче нет, ни одну из них торговец не продаёт, получатель не допущен к добыче отсчётом status/lootfree, цена не совпала с уплаченным, выручку некуда положить) — исход механики, в журнал не пишется; пропажу предоплаты ушедшего покупателя называет параметр paid. Отказы команда даёт без ошибки: она исполняется не на игроке, а ошибка в команде, исполняемой не на игроке, роняет карту; на игроке ошибка лишь отключает игрока от игры.
Цена в кадре
Одно срабатывание: 0.2 мс процессорного времени
Срабатываний в минуту у одной сущности: 1
Формулами, потому что обе величины зависят от обстановки на карте — сколько вокруг сущностей и сколько из них живых.
Параметры 4
Параметр По умолчанию Что задаёт
items пусто
Вещи к выдаче с количеством каждой, каждая в виде {prefab, count, components}, как вещь хранит компонент inventory: префаб, количество и, у вещи со своими значениями компонентов, они. Каждую выдача ищет в добыче по ней самой в момент выдачи, а не по месту, где получатель её видел: вещи, которой к этому моменту в добыче нет, в выдаче нет; у одной вещи в добыче одна запись, поэтому вещь, названная повторно, к выдаче ничего не добавляет; названо больше, чем лежит, — запись уходит целиком, названо меньше — остаток остаётся в добыче.
key пусто Ключ получателя на запущенной карте (вида players_1). Получатель — живой игрок на клетке контейнера либо на соседней того же этажа, иначе выдачи нет.
to пусто
Желаемая ячейка инвентаря получателя: её номер, счёт с единицы; пусто либо ноль — место подбирается само. Учитывается, только когда к выдаче нашлась одна вещь; как зачисление выбирает ячейку, сказано в описании компонента inventory (служебный ключ __add).
paid пусто
Сколько монет покупатель уже заплатил: их сняла его команда забора до заявки. Торговец монеты покупателя не трогает, а выдаёт товар с ценой, лишь когда цена выданного равна уплаченному: пусто либо ноль у торговца — товара с ценой не будет. При другой цене и при любом другом отказе уплаченное возвращается покупателю зачислением; покупателя уже не видно (ушёл с карты, вышел из игры) — вернуть некому, и уплаченное пропадает с записью в журнал предупреждений.
Кому доступна
bot item armor enemy animal object player trader weapon trader_silent
Что делает команда — код, который выполняется при её срабатывании
Что платформа подаёт в код
Код исполняется телом функции, и платформа подаёт в него эти переменные:
  • $object — сущность, выполняющая команду
  • $data — параметры команды: ключ — slug параметра; непереданные приходят со своим значением по умолчанию
  • $from_client — команду прислал игрок пакетом, а не поставил код механик
  • $client_origin — цепочку начал игрок: признак наследуют и события, которые код поставит по ходу неё

Код команды ничего не возвращает. Менять компоненты и свойства можно только у своей сущности.

Кроме них коду доступны классы фреймворка игры и подключённых к ней библиотек — их зовут по имени класса; что именно они умеют, сказано на их страницах.

<?php
/** @var EntityAbstract $object @var array $data @var bool $from_client */

# Выдача получателю — исполняется НА КОНТЕЙНЕРЕ (владельце источника): списание у себя
# атомарно в моём тике, две конкурентные выдачи одной позиции невозможны — вторая увидит пустую
# позицию (анти-дюп; коллизии игроков нет, тайл-эксклюзия не защищает). Вешается сервером из
# ui/inventory/take (isPublic=false).
# Никаких throw: событие на НЕ-игроке — Frame::tick перебрасывает исключение и роняет сервер.
# Несходимость — тихий отказ, предмет остаётся у меня (списания ещё не было).

// получатель исчез (вышел/умер финально) — отказ без списания; его предоплату вернуть некому, и она пропадает
if(!World::isset($data['key']))
{
	if(!empty($data['paid']))
		$object->warning('покупка игроком '.$data['key'].' не состоялась: покупателя больше не видно, предоплата '.(int)$data['paid'].' пропала');

	return;
}

$player = World::get($data['key']);

// Предоплата покупателя: монеты уже сняла его команда забора (ui/inventory/take). Сделка не состоялась — они уходят назад
// зачислением; у неторгующего контейнера предоплаты нет, и отказ тихий.
$paid = (int)($data['paid'] ?: 0);
$refuse = static function() use ($player, $paid): void
{
	if($paid)
		$player->events->push('status/changes', 'index', ['data' => ['components' => ['inventory' => ['__add' => [['item' => ['prefab' => Trade::COIN, 'count' => $paid]]]]]]]);
};

// выдача by-design только игрокам (адресный send стейта)
if(!($player instanceof Player))
{
	$refuse();
	return;
}

// получатель мёртв — исход механики, отказ
if(!$player->components->isset('hp') || $player->components->get('hp') <= 0)
{
	$refuse();
	return;
}

// Получатель отошёл от меня дальше соседней клетки: его же шаг обошёл заявку — гонка, отказ с записью в журнал
// предупреждений с ключом получателя (решение автора 2026-10-21).
if(!$player->position->adjacent($object->position))
{
	$object->warning('выдача игроку '.$player->key.' не исполнена: получатель не рядом с контейнером (item/give/index)');
	$refuse();
	return;
}

// Право на добычу лежит в параметрах команды-таймера status/lootfree: висит она — берут только
// перечисленные в ней; снялась, когда допускать стало некого, — добыча свободна любому.
// Здесь проверка стоит потому, что это единственная точка списания: открытие окна отказывает раньше,
// но истина — тут, у самого переноса.
if(!$object->components->isset('loot') || !Inventory::lootAllowed($object, $player->key))
{
	$refuse();
	return;
}

$inv = $object->components->get('loot');

// У торгующего контейнера выдача — это продажа: товар уходит лишь за предоплату по цене.
$trading = $object->components->isset('trade');

// Место у получателя здесь не ищется: зачисление найдёт его само в момент применения, а некуда — предмет
// упадёт получателю под ноги. Выдача поэтому не зависит от того, сколько места у получателя.
// Выбор — сами вещи с количеством (решение автора 2026-10-21): позиции ищутся по вещи здесь, в момент списания, —
// вещь, легшая в ту же позицию после показа, в выдачу не попадает.
[$taken, $add, $price] = Inventory::give($inv, Inventory::pick($inv, (array)$data['items']), (int)($data['to'] ?: 0), $trading ? $object : null);

// выдавать нечего (названных вещей нет, у торговца ни у одной нет цены) — отказ без списания
if(!$add)
{
	$refuse();
	return;
}

$changes = ['__add' => $add];
$after = Inventory::lootAfter($inv, $taken);

if($price)
{
	// Предоплата пришла за другую цену (состав лавки сменился, пока заявка шла) либо её нет вовсе — сделки нет:
	// брать ли товар не по показанной цене, решает покупатель, а не торговец.
	if($paid != $price)
	{
		$refuse();
		return;
	}

	// Выручка ложится в то же хранилище, откуда ушёл товар: запас монет торговца конечен,
	// и ими же он платит, когда скупает. Место ищется по составу ПОСЛЕ списания — опустевшая запись годится.
	$after = Inventory::lootPut($after, ['prefab' => Trade::COIN, 'count' => $price]);

	// Выручку некуда положить — сделки нет: отдать товар, потеряв плату, хуже отказа.
	if($after === null)
	{
		$refuse();
		return;
	}
}

// списание у себя (владельца) — атомарно
$object->components->add('loot', $after);

// зачисление получателю штатным каналом чужих изменений — ОДНИМ событием со списком: инвентарные операции
// игрока сериализованы по одной за тик; заявку другого писателя того же кадра push ставит в очередь, а не затирает
$player->events->push('status/changes', 'index', ['data' => ['components' => ['inventory' => $changes]]]);
К игре