item/give0.2 мс процессорного времени1| Параметр | По умолчанию | Что задаёт |
|---|---|---|
items |
пусто | Вещи к выдаче с количеством каждой, каждая в виде {prefab, count, components}, как вещь хранит компонент inventory: префаб, количество и, у вещи со своими значениями компонентов, они. Каждую выдача ищет в добыче по ней самой в момент выдачи, а не по месту, где получатель её видел: вещи, которой к этому моменту в добыче нет, в выдаче нет; у одной вещи в добыче одна запись, поэтому вещь, названная повторно, к выдаче ничего не добавляет; названо больше, чем лежит, — запись уходит целиком, названо меньше — остаток остаётся в добыче. |
key |
пусто | Ключ получателя на запущенной карте (вида players_1). Получатель — живой игрок на клетке контейнера либо на соседней того же этажа, иначе выдачи нет. |
to |
пусто | Желаемая ячейка инвентаря получателя: её номер, счёт с единицы; пусто либо ноль — место подбирается само. Учитывается, только когда к выдаче нашлась одна вещь; как зачисление выбирает ячейку, сказано в описании компонента inventory (служебный ключ __add). |
paid |
пусто | Сколько монет покупатель уже заплатил: их сняла его команда забора до заявки. Торговец монеты покупателя не трогает, а выдаёт товар с ценой, лишь когда цена выданного равна уплаченному: пусто либо ноль у торговца — товара с ценой не будет. При другой цене и при любом другом отказе уплаченное возвращается покупателю зачислением; покупателя уже не видно (ушёл с карты, вышел из игры) — вернуть некому, и уплаченное пропадает с записью в журнал предупреждений. |
$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]]]);