Ветвящиеся диалоги на JavaScript: дерево реплик в JSON, условия и флаги

Коротко

Ветвящийся диалог проще всего держать в данных: каждый узел — это id, говорящий, реплика и список выборов, а у выбора есть текст, условие показа, действия над флагами и id следующего узла. Код из четырёх функций — проверить условие, применить действия, отфильтровать выборы, перейти — одинаков для всех персонажей, а проверка при загрузке находит битые ссылки, опечатки во флагах, тупики и циклы без выхода до того, как их найдёт игрок. В нашем прогоне на страже у пещеры и торговце каждая ловушка — от if-цепочки, которая не открывала ворота, до подарка, выданного дважды после загрузки, — видна в выводе и исправлена.

Содержание

  1. Почему цепочка if в коде быстро ломается
  2. Схема данных: узел, выбор, условие, действие
  3. Условия: флаг, отрицание, И и ИЛИ
  4. Флаги: при входе в узел или при выборе
  5. Обход дерева: текущий узел, фильтр, переход, конец
  6. Проверка при загрузке: ссылки, опечатки, тупики, циклы
  7. Код на JavaScript и проверка в Node.js
  8. Что показал прогон: ловушки и исправления
  9. Практический сценарий: страж у пещеры и торговец
  10. Когда вам это не подойдёт

Почему цепочка if в коде быстро ломается

Цепочка if (flags.metGuard) ломается потому, что в ней порядок проверок решает, какую ветку увидит игрок, а каждая новая реплика требует правки кода. Пока у стража три фразы, это незаметно. Когда появляются факел, пропуск, взятка и разговор после открытия пещеры, ошибки становятся типовыми:

  • Недостижимая ветка. В нашем прогоне проверка if (s.hasTorch) стояла раньше, чем else if (s.hasTorch && s.hasPass). Общее условие перехватывает частное, и при факеле и пропуске страж всё равно отправлял игрока в узел «а пропуск?» — ветка «Проходи» не открывалась ни разу.
  • Повтор первой встречи. Флаг «уже знакомы» ставится в одной из веток, а игрок вышел через другую — и в следующий раз страж представляется снова.
  • Ответ, который уже не должен быть виден. После того как пещера открыта, страж в нашем первом варианте по-прежнему спрашивал «Ну что, нашёл огонь?» и предлагал «Вот факел» — на этот случай ветки просто не было.

Если реплики, выборы и условия лежат в данных, все ответы, чьи условия выполнены, показываются одновременно и выбирает игрок, а не порядок if. Связи объектов уровня в данных, а не в коде, разобраны в статье о рычагах и дверях; здесь тот же принцип применён к разговору. Это не дерево поведения врага из статьи о деревьях поведения: узлы диалога не тикают каждый кадр и не возвращают успех или неудачу, они ждут выбора игрока.

Схема данных: узел, выбор, условие, действие

Узел диалога в нашей схеме — объект с id (ключ в nodes), полем speaker, текстом text, необязательными действиями enter и списком choices; выбор — объект с id, text, необязательными if, do, once и обязательным next. Это наш пример схемы, а не отраслевой стандарт; у готовых языков вроде Ink своя структура.

ПолеГдеЧто значитПример
startдеревоid первого узла разговора"greet"
speaker, textузелкто говорит и что"Страж", "Стой…"
enterузелдействия при входе в узел[{"set": "metGuard"}]
idвыборстабильное имя ответа внутри узла"pass"
ifвыборусловие показа; нет поля — виден всегда{"all": ["hasTorch", "hasPass"]}
doвыбордействия при выборе[{"add": ["coins", -5]}]
onceвыборпосле выбора больше не показыватьtrue
nextвыборid следующего узла или "END""open"
varsфайлвсе флаги и счётчики, которые можно читать и менять["metGuard", "coins"]

Идентификаторы узлов и выборов стабильны: на них ссылаются next, сохранение и сценарии проверки. Текст реплики можно переписать, перевести или вынести в отдельную таблицу строк, не трогая ни одной ссылки. Ссылаться на выбор по номеру в списке нельзя — номер меняется, когда соседний ответ скрыт условием (это видно в прогоне, раздел 5).

Весь диалог нашего примера — два персонажа, девять узлов — помещается в один файл dialogs.json. Строки JSON — только в двойных кавычках, запятая после последнего элемента списка запрещена: MDN прямо пишет, что JSON.parse на такой строке бросает SyntaxError.

{
  "vars": ["metGuard", "hasTorch", "hasPass", "coins", "bribed", "caveOpen", "dealUsed", "giftTaken"],
  "guard": { "start": "greet", "nodes": {
    "greet": { "speaker": "Страж", "text": "Стой. В пещеру без огня не ходят.",
      "choices": [
        {"id": "first", "text": "Кто ты?", "if": {"not": "metGuard"}, "next": "intro"},
        {"id": "again", "text": "Это снова я.", "if": {"all": ["metGuard", {"not": "caveOpen"}]}, "next": "again"},
        {"id": "inside", "text": "Как там мыши?", "if": "caveOpen", "next": "done"},
        {"id": "leave", "text": "Уйти.", "next": "END"}
      ] },
    "intro": { "speaker": "Страж", "text": "Я стерегу пещеру. Принеси факел, и поговорим.",
      "enter": [{"set": "metGuard"}],
      "choices": [
        {"id": "ok", "text": "Понял.", "next": "END"}
      ] },
    "again": { "speaker": "Страж", "text": "Ну что, нашёл огонь?",
      "choices": [
        {"id": "torch", "text": "Вот факел.", "if": "hasTorch", "next": "gate"},
        {"id": "pass", "text": "У меня факел и пропуск.", "if": {"all": ["hasTorch", "hasPass"]}, "next": "open"},
        {"id": "bribe", "text": "Дать 5 монет.", "if": {"gte": ["coins", 5]}, "once": true, "do": [{"add": ["coins", -5]}, {"set": "bribed"}], "next": "gate"},
        {"id": "bye", "text": "Пока нет.", "next": "END"}
      ] },
    "gate": { "speaker": "Страж", "text": "Огонь есть, а пропуск?",
      "choices": [
        {"id": "show", "text": "Показать пропуск.", "if": "hasPass", "next": "open"},
        {"id": "back", "text": "Схожу за ним.", "next": "END"}
      ] },
    "open": { "speaker": "Страж", "text": "Проходи. И не буди летучих мышей.",
      "choices": [
        {"id": "go", "text": "Войти.", "do": [{"set": "caveOpen"}], "next": "END"}
      ] },
    "done": { "speaker": "Страж", "text": "Спят. Пока.",
      "choices": [
        {"id": "bye", "text": "Пока.", "next": "END"}
      ] }
  } },
  "merchant": { "start": "hello", "nodes": {
    "hello": { "speaker": "Торговец", "text": "Факелы, верёвки, пропуска.",
      "choices": [
        {"id": "buy", "text": "Факел за 5 монет.", "if": {"all": [{"not": "hasTorch"}, {"gte": ["coins", 5]}]}, "do": [{"add": ["coins", -5]}, {"set": "hasTorch"}], "next": "END"},
        {"id": "deal", "text": "А подешевле?", "if": {"all": [{"not": "hasTorch"}, {"not": "dealUsed"}]}, "next": "deal"},
        {"id": "gift", "text": "Говорят, ты даёшь пропуск.", "if": {"not": "giftTaken"}, "next": "gift"},
        {"id": "bye", "text": "Пока.", "next": "END"}
      ] },
    "deal": { "speaker": "Торговец", "text": "Для тебя — за 3. Только один раз.",
      "choices": [
        {"id": "take", "text": "Беру.", "if": {"gte": ["coins", 3]}, "do": [{"add": ["coins", -3]}, {"set": "hasTorch"}, {"set": "dealUsed"}], "next": "END"},
        {"id": "think", "text": "Подумаю.", "next": "END"}
      ] },
    "gift": { "speaker": "Торговец", "text": "Держи пропуск и 2 монеты на дорогу.",
      "choices": [
        {"id": "thanks", "text": "Спасибо.", "do": [{"set": "hasPass"}, {"add": ["coins", 2]}, {"set": "giftTaken"}], "next": "END"}
      ] }
  } }
}

Флаги и счётчики лежат в одном плоском объекте состояния, например {"metGuard": true, "coins": 4}. Отсутствующий флаг читается как «нет», отсутствующий счётчик — как 0. Сохранить такой объект можно одной строкой JSON.stringify; где его хранить и как менять формат между версиями, разобрано в статье о сохранениях в браузерной игре.

Условия: флаг, отрицание, И и ИЛИ

Условие выбора в нашей схеме — это строка с именем флага или объект с одним из ключей not, all, any, gte, и их можно вкладывать друг в друга. Выбор без поля if виден всегда.

ЗаписьСмыслПример в диалоге
"hasTorch"флаг поднят«Вот факел.»
{"not": "metGuard"}флага нет«Кто ты?» только при первой встрече
{"all": ["hasTorch", "hasPass"]}И: все условия«У меня факел и пропуск.»
{"any": ["a", "b"]}ИЛИ: хотя бы однов нашем дереве не нужно
{"gte": ["coins", 5]}счётчик не меньше числа«Дать 5 монет.»

Путаница И и ИЛИ ломает сцену тихо. Если у ответа «У меня факел и пропуск» написать any вместо all, при одном факеле он становится виден, и в нашем прогоне игрок проходил весь путь again → open → go и открывал пещеру без пропуска. Ошибку не видно ни при полном наборе предметов (оба варианта показывают ответ), ни при пустом (оба прячут) — только на промежуточном состоянии. Поэтому сценарии проверки должны включать состояния «есть одно, нет другого».

Вторая тихая ошибка — опечатка в ключе или имени. Ключ "al" вместо "all" наша функция check отклоняет исключением «неизвестное условие», а вот флаг "hasTorh" вместо "hasTorch" синтаксически правилен и просто всегда ложен: ответ «Вот факел» исчезает навсегда. Такие опечатки ловит только сверка со списком vars при загрузке. В Ink для сравнения несколько условий у одного выбора тоже работают как И — все проверки должны пройти, чтобы выбор появился; and и or там пишутся словами или как && и ||.

Флаги: при входе в узел или при выборе

Флаг «уже видел» ставят при входе в узел, а флаг, который закрывает предложение или защищает награду от повтора, ставят в том же списке действий, где выдают награду. Сюжетные флаги диалога — это память о том, что произошло в мире; их не стоит путать с булевыми флагами состояния героя вроде isJumping, которые разобраны в статье о конечном автомате персонажа.

ФлагЧто охраняетГде ставитьЧто ломается в другом месте
metGuard«уже знакомы»enter узла introпри выборе: вышел из игры на реплике — знакомство повторится
dealUsedодноразовая скидкаdo выбора «Беру» вместе с оплатойпри входе: ответил «Подумаю» — скидки больше нет
giftTakenподарокdo выбора «Спасибо» вместе с монетамимонеты при входе: вышел и загрузился — подарок второй раз
used:again.bribeодноразовый ответставит движок по once: true—

Обе ловушки в таблице связаны с сохранением. Мы сохраняем только флаги, а не позицию внутри разговора: после загрузки окно диалога закрыто, и разговор начинается с start. Если флаг поставлен раньше эффекта, игрок теряет то, чего не получил; если эффект выдан раньше флага, игрок получает его повторно. Правило «флаг и эффект в одном списке действий» снимает обе. Если ваша игра сохраняет и позицию в разговоре, проверьте ту же пару отдельно: выход из игры между входом в узел и выбором — обычное поведение игрока.

Одноразовые ответы — частный случай. В нашей схеме ответы по умолчанию повторяемые, а once: true делает ответ одноразовым: движок записывает в состояние ключ used:узел.выбор, и он попадает в сохранение вместе с остальными флагами. В Ink умолчание обратное: каждый выбор по умолчанию можно сделать один раз, а повторяемые («sticky») выборы отмечаются отдельным маркером +. Какое умолчание взять, решает автор; главное — одно на всю игру.

Обход дерева: текущий узел, фильтр, переход, конец

Обход — это цикл из четырёх шагов: войти в текущий узел и применить его enter, отфильтровать выборы по условиям и once, дождаться выбора игрока и применить его do, перейти по next, пока next не равен "END". На END окно диалога закрывается, и игра продолжается с новыми флагами.

id = tree.start
повторять:
  node = tree.nodes[id]          нет узла → ошибка данных
  apply(node.enter)
  options = выборы, у которых if выполнено и once не использован
  options пуст → тупик
  ждать выбор игрока (по id, не по номеру)
  apply(choice.do)
  choice.next == "END" → разговор окончен
  id = choice.next

Окно диалога в браузерной игре удобно держать слоем поверх уровня, а не отдельной сценой: уровень на паузе, но остаётся на месте, и после END игра продолжается без перезагрузки — переходы между настоящими сценами разобраны в статье о сценах и переходах. Если другим системам надо знать, что разговор закончился (квест, музыка, камера), диалог может отправить событие, а не вызывать их напрямую — так, как описано в статье об издателе и подписчике. Как показать саму строку на экране — подложка, длина строки, время показа — разобрано в статье о доступности 2D-игры; здесь — только какая строка и какие ответы. Голос к реплике подключается так же, как любой другой звук, — через шины громкости из статьи о Web Audio API.

В функции talk из кода ниже вместо ожидания игрока передаётся список id выборов, а ограничитель maxSteps останавливает обход, если разговор ходит по кругу. Список кончился раньше END — значит, игрок вышел из игры посреди разговора; так мы проверяем сохранение.

Проверка при загрузке: ссылки, опечатки, тупики, циклы

Проверка при загрузке — это функция, которая до первого разговора обходит дерево как граф и возвращает список проблем; пустой список — данные можно пускать в игру. В нашем примере validate ищет пять видов ошибок:

ОшибкаКак ищемСообщение в прогоне
next на несуществующий узелкаждый next есть в nodes или равен ENDagain.pass → opne: нет такого узла
опечатка во флагеимена в if, do, enter есть в varsagain.torch: неизвестная переменная hasTorh
недостижимый узелобход в ширину от start по всем nextузел: недостижим от старта
тупикиз узла есть путь до END по выборам без if и oncegate: выход только через условие
цикл без выходато же правило: петля без безусловного выходаagain: выход только через условие

Правило «выход без условий» строже, чем нужно: оно не знает, что флаг hasPass к этому моменту, может быть, уже гарантированно поднят. Зато оно простое и находит тупики, которые иначе всплывают только у игрока с редким набором флагов. У Ink для того же случая есть запасной выбор (fallback choice): выбор без текста, который никогда не показывается, но выбирается автоматически, когда других вариантов нет. В нашей схеме роль запасного выхода играет обычный безусловный ответ — «Пока нет», «Схожу за ним».

Код на JavaScript и проверка в Node.js

Модуль ниже ничего не рисует: в нём проверка условий, применение действий, фильтр видимых выборов, обход одного разговора и проверка дерева при загрузке. Запуск — Node.js 24.22.1, модуль ES (.mjs); персонажи, реплики, флаги и числа — наш пример.

/** dialog.mjs — обход дерева реплик из JSON: условия, действия, одноразовые выборы, проверка */

// Условие: строка "flag" | {"not": c} | {"all": [..]} | {"any": [..]} | {"gte": ["var", n]}.
export function check(cond, state) {
  if (cond === undefined) return true;
  if (typeof cond === "string") return Boolean(state[cond]);
  if ("not" in cond) return !check(cond.not, state);
  if ("all" in cond) return cond.all.every((c) => check(c, state));
  if ("any" in cond) return cond.any.some((c) => check(c, state));
  if ("gte" in cond) return (state[cond.gte[0]] ?? 0) >= cond.gte[1];
  throw new Error("неизвестное условие: " + JSON.stringify(cond));
}

// Действие: {"set": "flag"} | {"clear": "flag"} | {"add": ["var", n]}.
export function apply(actions, state) {
  for (const a of actions ?? []) {
    if ("set" in a) state[a.set] = true;
    else if ("clear" in a) delete state[a.clear];
    else if ("add" in a) state[a.add[0]] = (state[a.add[0]] ?? 0) + a.add[1];
    else throw new Error("неизвестное действие: " + JSON.stringify(a));
  }
}

const usedKey = (nodeId, choiceId) => "used:" + nodeId + "." + choiceId;

// Видимые выборы узла: условие выполнено и одноразовый выбор ещё не сделан.
export function visible(tree, nodeId, state) {
  return tree.nodes[nodeId].choices.filter((c) =>
    check(c.if, state) && !(c.once && state[usedKey(nodeId, c.id)]));
}

// Один разговор. picks — id выборов по порядку; кончились раньше END — игрок вышел из игры.
export function talk(tree, state, picks, maxSteps = 20) {
  const path = [];
  let id = tree.start, i = 0;
  for (let step = 0; step < maxSteps; step++) {
    const node = tree.nodes[id];
    if (!node) return { path, end: "нет узла " + id };
    apply(node.enter, state);
    path.push(id);
    const options = visible(tree, id, state);
    if (options.length === 0) return { path, end: "тупик: нет видимых выборов" };
    if (i >= picks.length) return { path, end: "вышел посреди разговора" };
    const choice = options.find((c) => c.id === picks[i]);
    if (!choice) return { path, end: "выбор " + picks[i] + " не виден" };
    i++;
    path.push(">" + choice.id);
    if (choice.once) state[usedKey(id, choice.id)] = true;
    apply(choice.do, state);
    if (choice.next === "END") return { path, end: "END" };
    id = choice.next;
  }
  return { path, end: maxSteps + " шагов без выхода" };
}

// Переменные, которые читает условие, — чтобы найти опечатки в именах флагов.
function condVars(cond, out) {
  if (cond === undefined) return out;
  if (typeof cond === "string") out.push(cond);
  else if ("not" in cond) condVars(cond.not, out);
  else if ("all" in cond || "any" in cond) for (const c of cond.all ?? cond.any) condVars(c, out);
  else if ("gte" in cond) out.push(cond.gte[0]);
  return out;
}

// Проверка при загрузке: ссылки, объявленные переменные, достижимость, выход из каждого узла.
export function validate(tree, vars) {
  const problems = [], ids = Object.keys(tree.nodes), known = new Set(vars);
  if (!tree.nodes[tree.start]) problems.push("нет стартового узла " + tree.start);
  for (const id of ids) {
    for (const a of tree.nodes[id].enter ?? []) {
      const n = a.set ?? a.clear ?? a.add[0];
      if (!known.has(n)) problems.push(id + ".enter: неизвестная переменная " + n);
    }
    for (const c of tree.nodes[id].choices) {
      if (c.next !== "END" && !tree.nodes[c.next]) problems.push(id + "." + c.id + " → " + c.next + ": нет такого узла");
      const names = condVars(c.if, []);
      for (const a of c.do ?? []) names.push(a.set ?? a.clear ?? a.add[0]);
      for (const n of names) if (!known.has(n)) problems.push(id + "." + c.id + ": неизвестная переменная " + n);
    }
  }
  // Достижимость от старта по всем выборам, без учёта условий.
  const seen = new Set(), queue = [tree.start];
  while (queue.length) {
    const id = queue.shift();
    if (seen.has(id) || !tree.nodes[id]) continue;
    seen.add(id);
    for (const c of tree.nodes[id].choices) if (c.next !== "END") queue.push(c.next);
  }
  for (const id of ids) if (!seen.has(id)) problems.push(id + ": недостижим от старта");
  // Выход без условий: из узла можно дойти до END по выборам без "if" и без "once".
  const free = (c) => c.if === undefined && !c.once;
  const exits = new Set();
  let grew = true;
  while (grew) {
    grew = false;
    for (const id of ids) {
      if (exits.has(id)) continue;
      if (tree.nodes[id].choices.some((c) => free(c) && (c.next === "END" || exits.has(c.next)))) {
        exits.add(id); grew = true;
      }
    }
  }
  for (const id of ids) if (!exits.has(id)) problems.push(id + ": выход только через условие");
  return problems;
}

Проверочный файл читает dialogs.json и прогоняет десять сцен: проверку исходного файла, шесть разговоров подряд на одном состоянии и намеренно испорченные копии дерева — if-цепочку, any вместо all, выбор по номеру, флаг при входе в узел, награду при входе, удалённый запасной ответ, опечатки, цикл и синтаксис JSON.

import { readFileSync } from "node:fs";
import { check, visible, talk, validate } from "./dialog.mjs";

const data = JSON.parse(readFileSync(new URL("./dialogs.json", import.meta.url), "utf8"));
const { vars, guard, merchant } = data;
const copy = (x) => structuredClone(x);
const show = (r) => r.path.join(" ") + " | " + r.end;
const flags = (s) => Object.keys(s).map((k) => s[k] === true ? k : k + "=" + s[k]).join(", ");
const save = (s) => JSON.stringify(s);
const load = (text) => JSON.parse(text);

console.log("1. Цепочка if в коде: страж при факеле и пропуске");
function naiveGuard(s) {
  if (!s.metGuard) return "intro";
  if (s.hasTorch) return "gate";
  else if (s.hasTorch && s.hasPass) return "open";
  return "again";
}
const both = { metGuard: true, hasTorch: true, hasPass: true };
console.log("   if-цепочка: " + naiveGuard(both) + " (ветка open недостижима)");
console.log("   данные: видны " + visible(guard, "again", both).map((c) => c.id).join(", "));

console.log("2. Проверка при загрузке");
console.log("   guard: " + (validate(guard, vars).join("; ") || "проблем нет"));
console.log("   merchant: " + (validate(merchant, vars).join("; ") || "проблем нет"));

console.log("3. Повторные разговоры, старт: 4 монеты");
let s = { coins: 4 };
const steps = [
  [guard, ["first", "ok"]],
  [guard, ["again", "bye"]],
  [merchant, ["deal", "take"]],
  [merchant, ["gift", "thanks"]],
  [guard, ["again", "pass", "go"]],
  [guard, ["inside", "bye"]],
];
steps.forEach(([tree, picks], n) => {
  const r = talk(tree, s, picks);
  console.log("   " + (n + 1) + ") " + show(r) + "\n      " + flags(s));
});

const stale = copy(guard);
stale.nodes.greet.choices[1].if = "metGuard";
stale.nodes.greet.choices.splice(2, 1);
delete stale.nodes.done;
console.log("   без ветки caveOpen: " + show(talk(stale, s, ["again"])) + "; видны " +
  visible(stale, "again", s).map((c) => c.id).join(", "));

console.log("4. И вместо ИЛИ: выбор pass при одном факеле");
const orGuard = copy(guard);
orGuard.nodes.again.choices[1].if = { any: ["hasTorch", "hasPass"] };
const torchOnly = { metGuard: true, hasTorch: true };
console.log("   all: " + visible(guard, "again", torchOnly).map((c) => c.id).join(", "));
console.log("   any: " + visible(orGuard, "again", torchOnly).map((c) => c.id).join(", ") +
  " → " + show(talk(orGuard, copy(torchOnly), ["again", "pass", "go"])));

console.log("5. Выбор по номеру вместо id");
for (const coins of [0, 5]) {
  const st = { metGuard: true, hasTorch: true, coins };
  const list = visible(guard, "again", st).map((c) => c.id);
  console.log("   монет " + coins + ": видны " + list.join(", ") + "; кнопка 2 → " + list[1]);
}

console.log("6. Одноразовый выбор: взятка");
s = { metGuard: true, coins: 12 };
console.log("   " + show(talk(guard, s, ["again", "bribe", "back"])) + " | монет " + s.coins);
console.log("   " + show(talk(guard, s, ["again", "bribe"])) + " | монет " + s.coins);
console.log("   в сохранении: " + save(s));

console.log("7. Флаг при входе в узел: скидка торговца");
const early = copy(merchant);
early.nodes.deal.enter = [{ set: "dealUsed" }];
for (const [name, tree] of [["флаг при входе", early], ["флаг при выборе", merchant]]) {
  const st = { coins: 2 };
  talk(tree, st, ["deal", "think"]);
  st.coins = 3;
  const r = talk(tree, st, ["deal", "take"]);
  console.log("   " + name + ": " + show(r) + " | " + flags(st));
}

console.log("8. Награда при входе в узел, флаг при выборе: подарок и выход из игры");
const late = copy(merchant);
late.nodes.gift.enter = [{ add: ["coins", 2] }];
late.nodes.gift.choices[0].do = [{ set: "hasPass" }, { set: "giftTaken" }];
for (const [name, tree] of [["награда при входе", late], ["всё в выборе", merchant]]) {
  let st = { coins: 0 };
  const r1 = talk(tree, st, ["gift"]);
  st = load(save(st));
  const r2 = talk(tree, st, ["gift", "thanks"]);
  console.log("   " + name + ": " + show(r1) + " → загрузка → " + show(r2) + " | монет " + st.coins);
}

console.log("9. Ошибки в данных");
const noBack = copy(guard);
noBack.nodes.gate.choices.pop();
console.log("   без «Схожу за ним»: " + show(talk(noBack, { metGuard: true, hasTorch: true }, ["again", "torch"])));
console.log("      проверка: " + validate(noBack, vars).join("; "));
const typoNext = copy(guard);
typoNext.nodes.again.choices[1].next = "opne";
console.log("   опечатка в next: " + show(talk(typoNext, copy(both), ["again", "pass"])));
try {
  const next = typoNext.nodes.again.choices[1].next;
  console.log(typoNext.nodes[next].text);
} catch (e) { console.log("      без проверки: " + e.constructor.name + ": " + e.message); }
console.log("      проверка: " + validate(typoNext, vars).join("; "));
const typoFlag = copy(guard);
typoFlag.nodes.again.choices[0].if = "hasTorh";
console.log("   опечатка во флаге: видны " + visible(typoFlag, "again", torchOnly).map((c) => c.id).join(", "));
console.log("      проверка: " + validate(typoFlag, vars).join("; "));
const loop = copy(guard);
loop.nodes.again.choices[3].next = "gate";
loop.nodes.gate.choices[1].next = "again";
console.log("   цикл: " + show(talk(loop, { metGuard: true }, ["again", "bye", "back", "bye", "back", "bye"], 6)));
console.log("      проверка: " + validate(loop, vars).join("; "));

console.log("10. Ошибки синтаксиса");
try { JSON.parse('{"choices": [{"id": "ok", "next": "END"},]}'); }
catch (e) { console.log("   запятая в конце списка: " + e.constructor.name + ": " + e.message); }
try { check({ al: ["hasTorch"] }, {}); } catch (e) { console.log("   опечатка в ключе: " + e.message); }

Вывод прогона (Node.js 24.22.1, node test.mjs):

1. Цепочка if в коде: страж при факеле и пропуске
   if-цепочка: gate (ветка open недостижима)
   данные: видны torch, pass, bye
2. Проверка при загрузке
   guard: проблем нет
   merchant: проблем нет
3. Повторные разговоры, старт: 4 монеты
   1) greet >first intro >ok | END
      coins=4, metGuard
   2) greet >again again >bye | END
      coins=4, metGuard
   3) hello >deal deal >take | END
      coins=1, metGuard, hasTorch, dealUsed
   4) hello >gift gift >thanks | END
      coins=3, metGuard, hasTorch, dealUsed, hasPass, giftTaken
   5) greet >again again >pass open >go | END
      coins=3, metGuard, hasTorch, dealUsed, hasPass, giftTaken, caveOpen
   6) greet >inside done >bye | END
      coins=3, metGuard, hasTorch, dealUsed, hasPass, giftTaken, caveOpen
   без ветки caveOpen: greet >again again | вышел посреди разговора; видны torch, pass, bye
4. И вместо ИЛИ: выбор pass при одном факеле
   all: torch, bye
   any: torch, pass, bye → greet >again again >pass open >go | END
5. Выбор по номеру вместо id
   монет 0: видны torch, bye; кнопка 2 → bye
   монет 5: видны torch, bribe, bye; кнопка 2 → bribe
6. Одноразовый выбор: взятка
   greet >again again >bribe gate >back | END | монет 7
   greet >again again | выбор bribe не виден | монет 7
   в сохранении: {"metGuard":true,"coins":7,"used:again.bribe":true,"bribed":true}
7. Флаг при входе в узел: скидка торговца
   флаг при входе: hello | выбор deal не виден | coins=3, dealUsed
   флаг при выборе: hello >deal deal >take | END | coins=0, hasTorch, dealUsed
8. Награда при входе в узел, флаг при выборе: подарок и выход из игры
   награда при входе: hello >gift gift | вышел посреди разговора → загрузка → hello >gift gift >thanks | END | монет 4
   всё в выборе: hello >gift gift | вышел посреди разговора → загрузка → hello >gift gift >thanks | END | монет 2
9. Ошибки в данных
   без «Схожу за ним»: greet >again again >torch gate | тупик: нет видимых выборов
      проверка: gate: выход только через условие
   опечатка в next: greet >again again >pass | нет узла opne
      без проверки: TypeError: Cannot read properties of undefined (reading 'text')
      проверка: again.pass → opne: нет такого узла
   опечатка во флаге: видны bye
      проверка: again.torch: неизвестная переменная hasTorh
   цикл: greet >again again >bye gate >back again >bye gate >back again >bye | 6 шагов без выхода
      проверка: again: выход только через условие; gate: выход только через условие
10. Ошибки синтаксиса
   запятая в конце списка: SyntaxError: Unexpected token ']', ..."": "END"},]}" is not valid JSON
   опечатка в ключе: неизвестное условие: {"al":["hasTorch"]}

Что показал прогон: ловушки и исправления

Прогон показал, что почти каждая ошибка диалога прячется на промежуточном наборе флагов и не видна в «полном» прохождении с правильными предметами; по пунктам:

  1. If-цепочка. При факеле и пропуске функция naiveGuard вернула gate: общее if (s.hasTorch) перехватило частное hasTorch && hasPass. В данных при том же состоянии видны torch, pass, bye — оба пути, выбирает игрок.
  2. Разговор после финала. Шесть разговоров подряд (сцена 3) прошли путь «знакомство → нет огня → скидка 3 монеты → подарок +2 → вход в пещеру» с 4 монетами на старте и 3 в конце. Первый вариант дерева после caveOpen всё ещё показывал torch, pass, bye и вопрос про огонь. Исправление — условие {"not": "caveOpen"} у ответа «Это снова я» и отдельный ответ inside → узел done; шестой разговор идёт greet >inside done >bye.
  3. ИЛИ вместо И. С any ответ pass виден при одном факеле, и игрок открывает пещеру без пропуска. С all при том же состоянии видны только torch, bye.
  4. Выбор по номеру. У игрока с факелом без монет вторая кнопка — bye, с 5 монетами — bribe: условие взятки сдвинуло список. Скрипт проверки, подсказка или сохранённый выбор «по номеру 2» в одном случае уходит, в другом отдаёт 5 монет. Исправление — везде ссылаться на id выбора.
  5. Одноразовый ответ. Взятка с 12 монет оставила 7, и второй раз bribe не виден, хотя монет хватает; в сохранение попал ключ used:again.bribe. Без него после загрузки взятку можно было бы дать снова.
  6. Флаг при входе в узел. Если dealUsed ставить в enter узла deal, игрок с 2 монетами, у которого и кнопки «Беру» нет (нужно 3), отвечает «Подумаю» — и скидка исчезает навсегда: при 3 монетах выбор deal уже не виден. С флагом в do выбора «Беру» тот же игрок возвращается и покупает факел за 3.
  7. Награда при входе, флаг при выборе. Если 2 монеты выдавать в enter узла gift, а giftTaken ставить по «Спасибо», игрок, который вышел из игры на реплике торговца, после загрузки получает подарок снова: 4 монеты вместо 2. Когда монеты, пропуск и флаг лежат в одном do, выходит 2.
  8. Ошибки в данных. Без ответа «Схожу за ним» игрок с факелом без пропуска попадает в узел gate с нулём видимых выборов — тупик, и проверка ловит его заранее. Опечатка opne в next без проверки даёт TypeError: Cannot read properties of undefined (reading 'text') посреди разговора; с проверкой — понятное сообщение при загрузке. Опечатка hasTorh молча прячет «Вот факел». Цикл again ↔ gate без END обход останавливает только ограничитель — 6 шагов без выхода.
  9. Синтаксис. Запятая после последнего элемента даёт SyntaxError при JSON.parse, как и предупреждает MDN; ключ "al" в условии наша check отклоняет исключением, а не считает ложным.

На исходном dialogs.json проверка возвращает «проблем нет» для обоих персонажей — это и есть критерий, с которым файл идёт в игру.

Практический сценарий: страж у пещеры и торговец

Задача: в браузерной 2D-игре страж не пускает в пещеру без факела и пропуска, факел продаёт торговец за 5 монет (или один раз за 3), пропуск торговец дарит вместе с 2 монетами, у игрока на старте 4 монеты, а с каждым персонажем можно говорить сколько угодно раз. Нужно, чтобы ни один разговор не завёл в тупик, ни одна награда не выдавалась дважды и ни одно предложение не пропадало без выбора игрока.

  1. Список флагов. Выписать в vars всё, что диалог читает и меняет: metGuard, hasTorch, hasPass, coins, bribed, caveOpen, dealUsed, giftTaken. Флаги, которые ставит не диалог, а игра (подобранный факел), — туда же.
  2. Узлы и id. Каждой реплике — узел с коротким id, каждому ответу — id внутри узла. Текст писать последним: от него ничего не зависит.
  3. Условия. Для каждого ответа записать, когда он виден; для составных условий прогнать состояния «есть одно, нет другого».
  4. Флаги и эффекты. «Уже видел» — в enter; всё, что охраняет награду или предложение, — в том же do, что и сама награда.
  5. Запасной выход. В каждом узле — хотя бы один ответ без условий, ведущий к END или к узлу с таким ответом.
  6. Финал. Добавить ветку для состояния «квест выполнен», чтобы персонаж не предлагал то, что уже сделано.
  7. Проверка. validate для каждого дерева при загрузке и сценарии разговоров с выходом из игры посреди разговора — в тестах, как test.mjs.

Проверяемый итог: validate возвращает пустой список, шесть разговоров подряд проходят с 4 монет до 3 с флагом caveOpen, подарок после выхода и загрузки даёт ровно 2 монеты, а скидка остаётся доступной до покупки. Если вашей игре нужен повтор прохождения, записывайте выборы игрока по id, а не по номеру кнопки, — подробный разбор повтора к этой статье не относится.

Когда вам это не подойдёт

Свой JSON с четырьмя функциями обхода подходит для нескольких персонажей и десятков узлов; вот где он лишний или его мало:

  • Линейный разговор без выбора. Если персонаж говорит три фразы подряд и ответов нет, хватит массива строк; дерево, условия и проверка ссылок ничего не добавят.
  • Большой сюжет, который пишет сценарист. Когда реплик тысячи, а автор текста не программист, JSON с кавычками и запятыми мешает писать. Для этого есть готовые языки: Ink — язык сценариев inkle, где текст первичен, а логика вставляется внутрь, с редактором Inky и экспортом в JSON; Yarn Spinner — набор инструментов для интерактивных историй со своим языком Yarn и интеграцией в Unity, Godot и Unreal Engine. Выбор между ними — отдельная тема.
  • Сложные выражения в условиях. Если ответы зависят от формул («репутация больше 10 и меньше 30, если не вечер»), список из not, all, any, gte придётся расширять до своего языка выражений — разумнее сразу взять готовый.
  • Сетевой разговор нескольких игроков. Если выбор делает один игрок, а флаги видят все, нужен сервер, который решает, чей выбор принят; локальный объект состояния эту задачу не решает.
  • Проверка не доказывает отсутствие тупиков. Наша validate не знает, какие флаги гарантированно подняты к моменту разговора, поэтому она строже, чем нужно, и при этом не ловит ошибку сюжета вроде «пропуск нигде не выдаётся». Сценарии разговоров в тестах нужны всё равно.

Мы разрабатываем J2DRU — браузерный 2D игровой движок, где логика собирается из событий, условий и действий, а проект можно углублять на TypeScript. Движок в разработке и публично пока не открыт, заявку можно оставить на странице раннего доступа (подача заявки не гарантирует приглашение).

Источники (проверено: ноябрь 2026, 11.11.2026): inkle — ink (язык сценариев для игр; текст первичен, логика вставляется внутрь; редактор Inky с экспортом в JSON; интеграция с Unity; лицензия MIT); inkle — Writing with Ink (knots как основная единица; выборы по умолчанию одноразовые, повторяемые отмечаются +; запасной выбор без текста; несколько условий у выбора — все должны пройти; and/&&, or/||); Yarn Spinner — документация (набор инструментов для интерактивных историй; язык Yarn; Unity, Godot, Unreal Engine); MDN — JSON.parse() (SyntaxError на невалидном JSON; запрет запятой после последнего элемента; строки только в двойных кавычках). Схема dialogs.json, функции check, apply, visible, talk, validate, персонажи, реплики, флаги, монеты и все числа прогона — наш пример и наш расчёт в Node.js 24.22.1.

Читайте также:

Частые вопросы

Почему нельзя писать диалог цепочкой if в коде?

Можно, пока реплик пять. Дальше каждая новая ветка требует правки кода, а порядок проверок начинает решать за игрока: в нашем прогоне if (hasTorch) стоял раньше, чем if (hasTorch && hasPass), и ветка с пропуском не открывалась никогда. В данных оба ответа видны одновременно, а выбирает игрок.

Когда ставить флаг: при показе реплики или при выборе ответа?

Флаг «уже говорили» ставят при входе в узел: игрок реплику видел. Флаг, который закрывает предложение или награду, ставят вместе с самим эффектом, в одном списке действий выбора. Иначе в нашем прогоне скидка пропадала, когда игрок ответил «Подумаю», а подарок после выхода из игры и загрузки выдавался второй раз.

Как не запереть игрока в разговоре, где все ответы скрыты?

Проверять дерево при загрузке: из каждого узла должен быть путь до END по выборам без условий. В нашем прогоне узел, где остался только «Показать пропуск», при факеле без пропуска давал ноль видимых выборов, и проверка нашла его до запуска: «gate: выход только через условие». Исправление — безусловный ответ вроде «Схожу за ним».

Когда брать Ink или Yarn Spinner вместо своего JSON?

Когда сюжет пишет сценарист и реплик тысячи. Ink — язык сценариев inkle, где текст первичен, а логика вставляется в него; Yarn Spinner — набор инструментов для интерактивных историй с интеграцией в Unity, Godot и Unreal Engine. Для нескольких персонажей браузерной игры с десятком узлов свой JSON и четыре функции обхода обычно проще.