код входа

Свой код на появление сущности на карте: ставит ей события по виду, а может и отменить появление
Код игры — он выполняется в этот момент поверх готового фреймворка
Что платформа подаёт в код
Код исполняется телом функции, и платформа подаёт в него эти переменные:
  • $kind — вид создаваемой сущности
  • $data — поля будущей сущности, по ссылке: правки кода доедут до создания

Возврат: ничего либо true — сущность создаётся штатно из $data; готовая сущность — берётся она; false — создание отменяется, но отменить создание копии сущности соседней карты нельзя, это ошибка. В коде входа нельзя создавать сущности и задавать свойства самой сущности — ставить события и править компоненты можно.

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

<?php

// Правила слотового хранилища и торговли живут библиотекой inventory-trade (классы Inventory и Trade):
// их спрашивают и триггеры компонентов, и команды обмена, а на карте без лавки либо без существ с
// инвентарём вызов всё равно обязан быть разрешим. Здесь остаётся лишь разовая проверка объявленности
// цены — она смотрит на состав ИГРЫ, потому и запускается её кодом; повторы отсекает сам метод.
Trade::assertPriceDeclared();

$object = null;
// Предмет, оказавшийся на земле ПО ХОДУ ИГРЫ, кладётся так, чтобы его было ВИДНО: точка занята другой
// вещью, телом либо контейнером — ищем свободное место сперва в своей клетке, затем в соседних. Лежащее
// в одной точке на экране не различить ни глазом, ни кликом, а клиент предметы не разносит. Правило стоит
// ЗДЕСЬ, а не в роняющих механиках: рождаются такие предметы одним каналом — созданием сущности (тем же
// гейтом ниже вешается срок лежания), и копия правила в каждой механике разошлась бы молча.
if(empty($data['slug']) && ($kind == 'item' || World::isKindEquipable($kind)) && isset($data['x'], $data['y']))
{
	// Разброс держится ВНУТРИ клетки — на треть клетки: спрайты не сливаются, а клетка вещи остаётся
	// той, над которой она нарисована: смещение меньше половины клетки, а клетка считается округлением.
	// Места в клетке не осталось — уходим в соседнюю ЦЕЛИКОМ, не на дробную долю: отодвинутая на
	// долю клетки вещь рисуется у границы и глазами читается лежащей сразу на двух клетках, а поднимается
	// только с одной — игрок ходит вокруг неё и не понимает, куда встать.
	$step  = 0.35;   // разброс внутри клетки
	$rings = 1;      // сколько колец СОСЕДНИХ клеток обходим, когда своя занята
	$z     = (float)($data['z'] ?? 0);

	// Считаем от ЦЕНТРА клетки, а не от присланной точки: роняющая механика даёт позицию тела,
	// а тело само разбросано внутри своей клетки — сложение двух смещений вынесло бы вещь за её границу.
	$tile = explode(Position::DELIMETR, (new Position((float)$data['x'], (float)$data['y'], $z))->tile());
	$x    = (float)$tile[0];
	$y    = (float)$tile[1];

	// Закрыть собой вещь могут лежащие предметы, тело убитого и контейнер — живые существа не в счёт:
	// они уходят сами, а выброшенное игроком должно падать ему под ноги. Радиус покрывает все клетки,
	// которые мы перебираем.
	$blockers = World::filter($x, $y, $z, static function(EntityAbstract $near): bool
	{
		if($near->kind == 'item' || World::isKindEquipable($near->kind))
			return true;

		return $near->components->isset('loot')
			&& (!$near->components->isset('hp') || $near->components->get('hp') <= 0);
	}, distance: $rings + 1, count: null);

	$vacant = static function(float $px, float $py) use ($blockers, $z, $step): bool
	{
		if(!Map2D::isPassable(new Position($px, $py, $z)))
			return false;

		foreach($blockers as $near)
			if(abs($near->position->x - $px) < $step && abs($near->position->y - $py) < $step)
				return false;

		return true;
	};

	// Места внутри одной клетки: центр, затем восемь точек вокруг него.
	$offsets = [[0.0, 0.0]];
	foreach([-$step, 0.0, $step] as $ox)
		foreach([-$step, 0.0, $step] as $oy)
			if($ox || $oy)
				$offsets[] = [$ox, $oy];

	$foundX = $x;
	$foundY = $y;
	$placed = false;

	for($ring = 0; $ring <= $rings && !$placed; $ring++)
		for($cx = -$ring; $cx <= $ring && !$placed; $cx++)
			for($cy = -$ring; $cy <= $ring && !$placed; $cy++)
			{
				// Кольцо — только его рамка: клетки внутри перебраны предыдущим кольцом.
				if($ring && abs($cx) != $ring && abs($cy) != $ring)
					continue;

				foreach($offsets as $offset)
				{
					$px = $x + $cx + $offset[0];
					$py = $y + $cy + $offset[1];

					if(!$vacant($px, $py))
						continue;

					$foundX = $px;
					$foundY = $py;
					$placed = true;
					break;
				}
			}

	$data['x'] = $foundX;
	$data['y'] = $foundY;
}

switch ($kind)
{
	case 'player':
		$player_key = NewPlayer::getKey(EntityTypeEnum::Player->value, $data['slug']);

		// игрок уже на сцене — не создавать дубль (false = отмена создания в World::add)
		if(World::isset($player_key))
			return false;

		// Только что зарегистрированный игрок приходит без карты: вход пустил его на карту появления игры
		// (Tulimshar Port), и карту ему ставит эта карта. Встаёт он на причал — туда же сходят с корабля.
		// Сменят карту появления в настройках игры — точку здесь менять вместе с ней.
		if(empty($data['map']))
		{
			$data['map'] = MAP_ID;
			$data['x']   = 54;
			$data['y']   = -35;
		}

		$object = new NewPlayer(...$data);

		$object->log('добавим игроку текущей карты отсчёт простоя соединения');

		$object->events->add(SystemActionEnum::Disconnect->value, 'index', from_client: true);
		$object->events->get(SystemActionEnum::Disconnect->value)->resetTimeout();
		break;

	case 'enemy':
		$object = new NewEntity(...$data);

		$object->log('добавим enemys текущей карты движение по его дому (зона либо точка появления)');

		// Зона из нескольких областей — обход их по кругу вместо праздного блуждания. Одна область
		// обходить нечего (обход выродится в стояние у её центра), потому там остаётся блуждание от точки спавна.
		$zone = $object->components->isset('zone') ? $object->components->get('zone') : null;

		if($zone && Map2D::hasZone($zone) && count(Map2D::zonePoints($zone, $object->z)) > 1)
			$object->events->add('move/randommove', 'patrol');
		else
		{
			$spawnData = ['spawn_x'=>$object->x, 'spawn_y'=>$object->y, 'spawn_z'=>$object->z];
			if($object->lifeRadius > 0)
				$spawnData['leash'] = $object->lifeRadius;

			$object->events->add('move/randommove', 'index', $spawnData);
		}
		break;

	// Виды без общих для вида стартовых событий: что нужно конкретному префабу (напр. портал —
	// object/portal, торговец — object/container), объявлено стартовыми событиями САМОГО префаба,
	// не перечислением по prefab здесь.
	case 'object':
	case 'npc':
	case 'npc_silent':
	case 'trader':
	case 'trader_silent':
	case 'portal':
	case 'animal':
	case 'item':
		$object = new NewEntity(...$data);
		break;

	default:
		// Экипируемые виды (оружие, броня) на земле — те же предметы: их кладут в инвентарь и бросают
		// из него, потому создаём их здесь, а не дефолтом, — иначе срок лежания ниже вешать было бы не на что.
		// Прочие виды (снаряд spell и т.п.) — дефолтное создание (true = new $class в World::add);
		// стартовые события такой сущности вешает механика-источник (напр. fight/bolt снаряду)
		if(!World::isKindEquipable($kind))
			return true;

		$object = new NewEntity(...$data);
		break;
}

// Труп: сущность, заведённая мёртвой (hp<=0), — лутабельный труп (ui/loot) до воскрешения
// (status/resurrect вешает триггер hp игрокам; трупом может быть и enemy, и игрок). AI-события enemy
// холостят по hp-гейтам и оживают с воскрешением. Триггер hp событие смерти тут не вешает
// (World::isset=false при спавне), потому вешаем его сами; действие «dead» ставит само событие — коду
// входа свойства сущности менять нельзя. Сброс таймаута нужен, чтобы событие отработало ближайшим
// кадром: иначе труп остаётся с действием появления столько, сколько ждёт своей очереди группа.
// Без hp — гейт пропускает.
if($object->components->isset('hp') && $object->components->get('hp') <= 0)
{
	$object->events->add('status/dead', 'index');
	$object->events->get('status/dead')->resetTimeout();
}

// Предмет, оказавшийся на земле ПО ХОДУ ИГРЫ (выброшен из инвентаря, не вместился в выдачу,
// не влез в добычу контейнера), лежит не вечно — ему заводится срок снятия с карты. Все такие предметы
// рождаются одним каналом — созданием сущности, потому срок вешается здесь, а не в каждой роняющей
// механике. Признак рождения рантаймом — отсутствие идентичности в заказе: у предмета,
// разложенного по карте записями самой игры, она есть, и срока ему не полагается — он содержимое
// карты, а не оставленный хлам.
if(empty($data['slug']) && ($kind == 'item' || World::isKindEquipable($kind)))
{
	$object->events->add('status/despawn', 'index');
	$object->events->get('status/despawn')->resetTimeout();
}

return $object;
К игре