dialog

словарь со своим кодом
Разговор — дерево реплик и вариантов ответа. Значение — словарь из двух ключей: start — имя первой реплики; nodes — реплики по именам. У реплики text — что говорит собеседник, options — список вариантов ответа игрока; у варианта text — его надпись, next — имя реплики, к которой он ведёт, quest — ключ квеста из квестов этого NPC (компонент quests): такой вариант берёт либо сдаёт квест. У квестового варианта intent — take либо complete: вариант сдачи виден, лишь когда квест можно сдать, вариант взятия в это время скрыт; квестовый вариант без intent служит обоим. next у квестового варианта — реплика после исполненного выбора: у сдачи — благодарность NPC. Вариант без next и quest заканчивает разговор. Переходы между репликами клиент ведёт сам, сервер при этом не участвует. Дерево — черта конкретной сущности: его задают у каждой сущности карты, а у префаба значение остаётся пустым — префаб служит заготовкой для многих сущностей. Говорить можно с каждым, чьему виду положен этот компонент: собеседника клиент узнаёт по наличию компонента у вида префаба, значение для этого не нужно. Пустое значение законно — разговор ещё не написан. Видящим значение не рассылается: что уходит заговорившему и как дерево достраивается под него — вариант «Торговать», квестовые варианты, сигнальная реплика на месте ненаписанного разговора, — сказано в описании команды ui/dialog/open. Торговцу без разговора нужен вид trader_silent: такого клиент открывает лавкой сразу. Неверная форма — start либо next, называющие реплику, которой нет, quest, которого нет в квестах NPC, intent без quest либо не take и не complete, квест, чьи варианты дают лишь взятие либо лишь сдачу, неизвестный ключ — отбивается кодом компонента в момент появления сущности на карте и при каждой смене значения: карта с такой сущностью не запускается, а смена значения по ходу игры роняет работающую карту; запись об ошибке ложится в журнал ошибок песочницы карты.
Стартовое значение
пусто
Сущность получает компонент пустым: ноль у числа, пустая строка у текста, пустой набор у списка.
Кому выдаётся
npc trader
Каждая сущность этих видов получает компонент при создании.
Код компонента — срабатывает, когда значение меняется, и когда сущность появляется на карте
Что платформа подаёт в код
Код исполняется телом функции, и платформа подаёт в него эти переменные:
  • $object — сущность, которой присваивают значение компонента
  • $value — присваиваемое значение; в самом компоненте на этот момент ещё лежит прежнее

Записано будет то, что лежит в $value после кода: платформа возвращает его сама, свой return тоже годится — так значение правят перед записью либо отказывают в смене. Пустое значение выражается пустой строкой либо пустым набором, null запрещён. Код срабатывает на смену значения и на появление сущности на карте; повторная запись прежнего значения его не запускает. В коде компонента менять компоненты нельзя, ставить события можно.

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

<?php
# Дерево разговора: реплики по именам и варианты ответа к каждой. Переходы между репликами клиент ведёт сам,
# поэтому форму проверяем здесь: ссылка на несуществующую реплику ломала бы разговор у игрока молча.
# Неверная форма — ошибка автора контента, поэтому отказ, а не подгонка.
/** @var array $value входящее значение, прокинуто closure-обёрткой ComponentCollection::trigger */

if(!is_array($value))
	throw new Error($object->key.': компонент dialog задаётся словарём {start, nodes}');

// Пустое значение — разговор ещё не написан: законно, начало разговора отдаст сигнальную реплику «Разговор не написан» без вариантов.
if(!$value)
	return $value;

if(array_diff(array_keys($value), ['start', 'nodes']) || !isset($value['start'], $value['nodes']) || !is_string($value['start']) || !is_array($value['nodes']))
	throw new Error($object->key.': компонент dialog — словарь ровно из start (имя первой реплики) и nodes (реплики по именам)');

// Квесты NPC — для сверки ссылок вариантов. При появлении сущности на карте значения всех её компонентов уже
// заданы до запуска их кода, поэтому квесты видны здесь и раньше собственного кода компонента квестов.
$quests = $object->components->isset('quests') ? $object->components->get('quests') : [];

if(!isset($value['nodes'][$value['start']]))
	throw new Error($object->key.': первая реплика разговора «'.$value['start'].'» не найдена среди его реплик');

foreach($value['nodes'] as $name => $node)
{
	if(!is_array($node) || array_diff(array_keys($node), ['text', 'options']) || !isset($node['text']) || !is_string($node['text']))
		throw new Error($object->key.': реплика разговора «'.$name.'» — словарь из text (что говорит NPC) и необязательного options (варианты ответа)');

	$options = $node['options'] ?? [];

	if(!is_array($options) || array_keys($options) !== array_keys(array_values($options)))
		throw new Error($object->key.': варианты ответа реплики «'.$name.'» задаются списком');

	foreach($options as $i => $option)
	{
		if(!is_array($option) || array_diff(array_keys($option), ['text', 'next', 'quest', 'intent']) || !isset($option['text']) || !is_string($option['text']))
			throw new Error($object->key.': вариант '.($i + 1).' реплики «'.$name.'» — словарь из text (надпись) и необязательных next (имя следующей реплики), quest (ключ квеста NPC) и intent (take либо complete, только при quest)');

		if(isset($option['next']) && !isset($value['nodes'][$option['next']]))
			throw new Error($object->key.': вариант '.($i + 1).' реплики «'.$name.'» ведёт в несуществующую реплику «'.$option['next'].'»');

		if(isset($option['intent']) && (!isset($option['quest']) || ($option['intent'] !== 'take' && $option['intent'] !== 'complete')))
			throw new Error($object->key.': вариант '.($i + 1).' реплики «'.$name.'» — intent задаётся только квестовому варианту и равен take либо complete');

		// Ссылка на квест сверяется с квестами самого NPC: вариант без записи квеста нечем было бы ни взять, ни сдать.
		if(isset($option['quest']))
		{
			if(!isset($quests[$option['quest']]))
				throw new Error($object->key.': вариант '.($i + 1).' реплики «'.$name.'» ссылается на квест «'.$option['quest'].'», которого нет в квестах NPC (компонент quests)');

			$covers[$option['quest']][$option['intent'] ?? 'any'] = true;
		}
	}
}

// Квест с вариантами автора обязан быть и взят, и сдан ими: вариант с намерением скрыт в чужом состоянии квеста, а свой
// вариант сервер достраивает лишь квесту без вариантов автора — иначе одно из действий в разговоре не нашлось бы.
foreach($covers ?? [] as $quest => $intents)
	if(!isset($intents['any']) && !isset($intents['take'], $intents['complete']))
		throw new Error($object->key.': у квеста «'.$quest.'» есть вариант лишь на '.(isset($intents['take']) ? 'взятие' : 'сдачу').' — нужен и второй (intent '.(isset($intents['take']) ? 'complete' : 'take').') либо вариант без intent');

return $value;
К игре