@doodle-engine/cli 0.0.7 → 0.0.9

package/dist/cli.js

@@ -1,57 +1,255 @@
 #!/usr/bin/env node
-import { Command as C } from "commander";
-import { crayon as t } from "crayon.js";
-import { createServer as T, build as N } from "vite";
-import O from "@vitejs/plugin-react";
-import { watch as I } from "chokidar";
-import { readdir as _, readFile as y, mkdir as S, writeFile as a } from "fs/promises";
-import { join as o, extname as g } from "path";
-import { parse as w } from "yaml";
-import { parseDialogue as R } from "@doodle-engine/core";
-import A from "prompts";
-const E = "🐾", G = "✨", q = "✏️", H = "➕";
-async function j() {
-  const e = process.cwd(), s = o(e, "content");
-  console.log(""), console.log(t.bold.magenta(`  ${E} Doodle Engine Dev Server ${E}`)), console.log("");
-  const d = {
+import { Command as G } from "commander";
+import { crayon as c } from "crayon.js";
+import { createServer as j, build as $ } from "vite";
+import A from "@vitejs/plugin-react";
+import { watch as H } from "chokidar";
+import { readdir as y, readFile as p, mkdir as R, writeFile as g } from "fs/promises";
+import { join as s, extname as f, relative as w } from "path";
+import { parse as b } from "yaml";
+import { parseDialogue as v } from "@doodle-engine/core";
+import M from "prompts";
+function I(e, n) {
+  const i = [];
+  for (const a of Object.values(e.dialogues)) {
+    const o = n.get(a.id) || `dialogue:${a.id}`;
+    i.push(...F(a, o));
+  }
+  for (const a of Object.values(e.characters))
+    if (a.dialogue && !e.dialogues[a.dialogue]) {
+      const o = n.get(a.id) || `character:${a.id}`;
+      i.push({
+        file: o,
+        message: `Character "${a.id}" references non-existent dialogue "${a.dialogue}"`,
+        suggestion: `Create dialogue "${a.dialogue}" or fix the reference`
+      });
+    }
+  return i.push(...J(e, n)), i;
+}
+function F(e, n) {
+  const i = [], a = /* @__PURE__ */ new Set();
+  for (const o of e.nodes)
+    a.has(o.id) && i.push({
+      file: n,
+      message: `Duplicate node ID "${o.id}"`,
+      suggestion: "Node IDs must be unique within a dialogue"
+    }), a.add(o.id);
+  a.has(e.startNode) || i.push({
+    file: n,
+    message: `Start node "${e.startNode}" not found`,
+    suggestion: `Add a NODE ${e.startNode} or fix the startNode reference`
+  });
+  for (const o of e.nodes)
+    i.push(...B(o, a, n));
+  return i;
+}
+function B(e, n, i) {
+  const a = [];
+  if (e.next && !n.has(e.next) && a.push({
+    file: i,
+    message: `Node "${e.id}" GOTO "${e.next}" points to non-existent node`,
+    suggestion: `Add NODE ${e.next} or fix the GOTO target`
+  }), e.conditionalNext)
+    for (const o of e.conditionalNext)
+      n.has(o.next) || a.push({
+        file: i,
+        message: `Node "${e.id}" IF block GOTO "${o.next}" points to non-existent node`,
+        suggestion: `Add NODE ${o.next} or fix the GOTO target`
+      }), a.push(...O(o.condition, e.id, i));
+  for (const o of e.choices) {
+    if (!o.effects?.some(
+      (t) => t.type === "endDialogue" || t.type === "goToLocation"
+    ) && !n.has(o.next) && a.push({
+      file: i,
+      message: `Node "${e.id}" choice "${o.id}" GOTO "${o.next}" points to non-existent node`,
+      suggestion: `Add NODE ${o.next} or fix the GOTO target`
+    }), o.conditions)
+      for (const t of o.conditions)
+        a.push(...O(t, e.id, i));
+    if (o.effects)
+      for (const t of o.effects)
+        a.push(...C(t, e.id, i));
+  }
+  if (e.conditions)
+    for (const o of e.conditions)
+      a.push(...O(o, e.id, i));
+  if (e.effects)
+    for (const o of e.effects)
+      a.push(...C(o, e.id, i));
+  return a;
+}
+const L = {
+  hasFlag: ["flag"],
+  notFlag: ["flag"],
+  hasItem: ["itemId"],
+  notItem: ["itemId"],
+  variableEquals: ["variable", "value"],
+  variableGreaterThan: ["variable", "value"],
+  variableLessThan: ["variable", "value"],
+  questAtStage: ["questId", "stageId"],
+  atLocation: ["locationId"],
+  characterAt: ["characterId", "locationId"],
+  characterInParty: ["characterId"],
+  relationshipAbove: ["characterId", "value"],
+  relationshipBelow: ["characterId", "value"],
+  itemAt: ["itemId", "locationId"]
+}, U = {
+  setFlag: ["flag"],
+  clearFlag: ["flag"],
+  setVariable: ["variable", "value"],
+  addVariable: ["variable", "value"],
+  addItem: ["itemId"],
+  removeItem: ["itemId"],
+  moveItem: ["itemId", "locationId"],
+  goToLocation: ["locationId"],
+  advanceTime: ["hours"],
+  setQuestStage: ["questId", "stageId"],
+  addJournalEntry: ["entryId"],
+  startDialogue: ["dialogueId"],
+  endDialogue: [],
+  setCharacterLocation: ["characterId", "locationId"],
+  addToParty: ["characterId"],
+  removeFromParty: ["characterId"],
+  setRelationship: ["characterId", "value"],
+  addRelationship: ["characterId", "value"],
+  setCharacterStat: ["characterId", "stat", "value"],
+  addCharacterStat: ["characterId", "stat", "value"],
+  setMapEnabled: ["enabled"],
+  playMusic: ["track"],
+  playSound: ["sound"],
+  notify: ["message"],
+  playVideo: ["file"]
+};
+function O(e, n, i) {
+  const a = [];
+  if (!e.type)
+    return a.push({
+      file: i,
+      message: `Node "${n}" has condition with missing type`
+    }), a;
+  if (e.type === "timeIs")
+    return e.hour === void 0 && e.day === void 0 && a.push({
+      file: i,
+      message: `Node "${n}" condition "timeIs" must have at least one of "hour" or "day" argument`
+    }), a;
+  const o = L[e.type];
+  if (!o)
+    return a;
+  for (const r of o)
+    (e[r] === void 0 || e[r] === null || e[r] === "") && a.push({
+      file: i,
+      message: `Node "${n}" condition "${e.type}" missing required "${r}" argument`
+    });
+  return a;
+}
+function C(e, n, i) {
+  const a = [];
+  if (!e.type)
+    return a.push({
+      file: i,
+      message: `Node "${n}" has effect with missing type`
+    }), a;
+  const o = U[e.type];
+  if (!o)
+    return a;
+  for (const r of o)
+    (e[r] === void 0 || e[r] === null || e[r] === "") && a.push({
+      file: i,
+      message: `Node "${n}" effect "${e.type}" missing required "${r}" argument`
+    });
+  return a;
+}
+function J(e, n) {
+  const i = [], a = /* @__PURE__ */ new Set();
+  for (const t of Object.values(e.locales))
+    for (const l of Object.keys(t))
+      a.add(l);
+  const o = (t) => t.startsWith("@"), r = (t, l, d) => {
+    const u = t.slice(1);
+    if (!a.has(u)) {
+      const h = n.get(l) || `${d}:${l}`;
+      i.push({
+        file: h,
+        message: `Localization key "${t}" not found in any locale file`,
+        suggestion: `Add "${u}: ..." to your locale files`
+      });
+    }
+  };
+  for (const t of Object.values(e.locations))
+    o(t.name) && r(t.name, t.id, "location"), o(t.description) && r(t.description, t.id, "location");
+  for (const t of Object.values(e.characters))
+    o(t.name) && r(t.name, t.id, "character"), o(t.biography) && r(t.biography, t.id, "character");
+  for (const t of Object.values(e.items))
+    o(t.name) && r(t.name, t.id, "item"), o(t.description) && r(t.description, t.id, "item");
+  for (const t of Object.values(e.quests)) {
+    o(t.name) && r(t.name, t.id, "quest"), o(t.description) && r(t.description, t.id, "quest");
+    for (const l of t.stages)
+      o(l.description) && r(l.description, t.id, "quest");
+  }
+  for (const t of Object.values(e.journalEntries))
+    o(t.title) && r(t.title, t.id, "journal"), o(t.text) && r(t.text, t.id, "journal");
+  for (const t of Object.values(e.dialogues))
+    for (const l of t.nodes) {
+      o(l.text) && r(l.text, t.id, "dialogue");
+      for (const d of l.choices)
+        o(d.text) && r(d.text, t.id, "dialogue");
+    }
+  return i;
+}
+function T(e) {
+  if (e.length === 0) {
+    console.log(c.green("✓ No validation errors"));
+    return;
+  }
+  console.log(c.red(`
+✗ Found ${e.length} validation error${e.length === 1 ? "" : "s"}:
+`));
+  for (const n of e)
+    console.log(c.bold(n.file) + (n.line ? `:${n.line}` : "")), console.log("  " + c.red(n.message)), n.suggestion && console.log("  " + c.dim(n.suggestion)), console.log();
+}
+const N = "🐾", W = "✨", Q = "✏️", V = "➕";
+async function Y() {
+  const e = process.cwd(), n = s(e, "content");
+  console.log(""), console.log(c.bold.magenta(`  ${N} Doodle Engine Dev Server ${N}`)), console.log("");
+  const i = {
     name: "doodle-content-loader",
-    configureServer(r) {
-      r.middlewares.use("/api/content", async (n, l) => {
+    configureServer(o) {
+      o.middlewares.use("/api/content", async (t, l) => {
         try {
-          const i = await x(s);
-          l.setHeader("Content-Type", "application/json"), l.end(JSON.stringify(i));
-        } catch (i) {
-          console.error(t.red("  Error loading content:"), i), l.statusCode = 500, l.end(JSON.stringify({ error: "Failed to load content" }));
+          const d = await P(n);
+          l.setHeader("Content-Type", "application/json"), l.end(JSON.stringify(d));
+        } catch (d) {
+          console.error(c.red("  Error loading content:"), d), l.statusCode = 500, l.end(JSON.stringify({ error: "Failed to load content" }));
         }
       });
-      const c = I(o(s, "**/*"), {
+      const r = H(n, {
         ignored: /(^|[\/\\])\../,
         persistent: !0
       });
-      c.on("change", (n) => {
-        console.log(t.yellow(`  ${q} Content changed: ${n}`)), r.ws.send({
+      r.on("change", async (t) => {
+        console.log(c.yellow(`  ${Q} Content changed: ${t}`)), await S(n), o.ws.send({
           type: "full-reload",
           path: "*"
         });
-      }), c.on("add", (n) => {
-        console.log(t.green(`  ${H} Content added: ${n}`)), r.ws.send({
+      }), r.on("add", async (t) => {
+        console.log(c.green(`  ${V} Content added: ${t}`)), await S(n), o.ws.send({
           type: "full-reload",
           path: "*"
         });
       });
     }
-  }, h = await T({
+  }, a = await j({
     root: e,
-    plugins: [O(), d],
+    plugins: [A(), i],
     server: {
       port: 3e3,
       open: !0
     }
   });
-  await h.listen(), h.printUrls(), console.log(""), console.log(t.dim(`  ${G} Watching content files for changes...`)), console.log("");
+  await a.listen(), a.printUrls(), console.log(""), console.log(c.dim(`  ${W} Watching content files for changes...`)), console.log("");
 }
-async function x(e) {
-  const s = {
+async function P(e) {
+  const n = {
     locations: {},
     characters: {},
     items: {},
@@ -61,8 +259,8 @@ async function x(e) {
     journalEntries: {},
     locales: {}
   };
-  let d = null;
-  const h = [
+  let i = null;
+  const a = [
     { dir: "locations", key: "locations" },
     { dir: "characters", key: "characters" },
     { dir: "items", key: "items" },
@@ -70,41 +268,41 @@ async function x(e) {
     { dir: "quests", key: "quests" },
     { dir: "journal", key: "journalEntries" }
   ];
-  for (const { dir: r, key: c } of h) {
-    const n = o(e, r);
+  for (const { dir: o, key: r } of a) {
+    const t = s(e, o);
     try {
-      const l = await _(n);
-      for (const i of l)
-        if (g(i) === ".yaml" || g(i) === ".yml") {
-          const u = o(n, i), m = await y(u, "utf-8"), b = w(m);
-          b && b.id && (s[c][b.id] = b);
+      const l = await y(t);
+      for (const d of l)
+        if (f(d) === ".yaml" || f(d) === ".yml") {
+          const u = s(t, d), h = await p(u, "utf-8"), m = b(h);
+          m && m.id && (n[r][m.id] = m);
         }
     } catch {
     }
   }
   try {
-    const r = o(e, "locales"), c = await _(r);
-    for (const n of c)
-      if (g(n) === ".yaml" || g(n) === ".yml") {
-        const l = o(r, n), i = await y(l, "utf-8"), u = w(i), m = n.replace(/\.(yaml|yml)$/, "");
-        s.locales[m] = u ?? {};
+    const o = s(e, "locales"), r = await y(o);
+    for (const t of r)
+      if (f(t) === ".yaml" || f(t) === ".yml") {
+        const l = s(o, t), d = await p(l, "utf-8"), u = b(d), h = t.replace(/\.(yaml|yml)$/, "");
+        n.locales[h] = u ?? {};
       }
   } catch {
   }
   try {
-    const r = o(e, "dialogues"), c = await _(r);
-    for (const n of c)
-      if (g(n) === ".dlg") {
-        const l = o(r, n), i = await y(l, "utf-8"), u = n.replace(".dlg", ""), m = R(i, u);
-        s.dialogues[m.id] = m;
+    const o = s(e, "dialogues"), r = await y(o);
+    for (const t of r)
+      if (f(t) === ".dlg") {
+        const l = s(o, t), d = await p(l, "utf-8"), u = t.replace(".dlg", ""), h = v(d, u);
+        n.dialogues[h.id] = h;
       }
   } catch {
   }
   try {
-    const r = o(e, "game.yaml"), c = await y(r, "utf-8");
-    d = w(c);
+    const o = s(e, "game.yaml"), r = await p(o, "utf-8");
+    i = b(r);
   } catch {
-    console.warn(t.yellow("  No game.yaml found, using defaults")), d = {
+    console.warn(c.yellow("  No game.yaml found, using defaults")), i = {
       startLocation: "tavern",
       startTime: { day: 1, hour: 8 },
       startFlags: {},
@@ -112,43 +310,224 @@ async function x(e) {
       startInventory: []
     };
   }
-  return { registry: s, config: d };
+  return { registry: n, config: i };
 }
-async function M() {
-  const e = process.cwd();
-  console.log(`🐕🎮 Building Doodle Engine game...
-`);
+async function S(e) {
   try {
-    await N({
+    const { registry: n, fileMap: i } = await K(e), a = I(n, i);
+    a.length > 0 && (console.log(""), T(a), console.log(""));
+  } catch (n) {
+    console.error(c.red("  Error running validation:"), n);
+  }
+}
+async function K(e) {
+  const n = {
+    locations: {},
+    characters: {},
+    items: {},
+    maps: {},
+    dialogues: {},
+    quests: {},
+    journalEntries: {},
+    locales: {}
+  }, i = /* @__PURE__ */ new Map(), a = [
+    { dir: "locations", key: "locations" },
+    { dir: "characters", key: "characters" },
+    { dir: "items", key: "items" },
+    { dir: "maps", key: "maps" },
+    { dir: "quests", key: "quests" },
+    { dir: "journal", key: "journalEntries" }
+  ];
+  for (const { dir: o, key: r } of a) {
+    const t = s(e, o);
+    try {
+      const l = await y(t);
+      for (const d of l)
+        if (f(d) === ".yaml" || f(d) === ".yml") {
+          const u = s(t, d), h = await p(u, "utf-8"), m = b(h);
+          m && m.id && (n[r][m.id] = m, i.set(m.id, w(process.cwd(), u)));
+        }
+    } catch {
+    }
+  }
+  try {
+    const o = s(e, "locales"), r = await y(o);
+    for (const t of r)
+      if (f(t) === ".yaml" || f(t) === ".yml") {
+        const l = s(o, t), d = await p(l, "utf-8"), u = b(d), h = t.replace(/\.(yaml|yml)$/, "");
+        n.locales[h] = u ?? {};
+      }
+  } catch {
+  }
+  try {
+    const o = s(e, "dialogues"), r = await y(o);
+    for (const t of r)
+      if (f(t) === ".dlg") {
+        const l = s(o, t), d = await p(l, "utf-8"), u = t.replace(".dlg", ""), h = v(d, u);
+        n.dialogues[h.id] = h, i.set(h.id, w(process.cwd(), l));
+      }
+  } catch {
+  }
+  return { registry: n, fileMap: i };
+}
+async function z() {
+  const e = process.cwd(), n = s(e, "content");
+  console.log(""), console.log(c.bold.magenta("🐕 Building Doodle Engine game...")), console.log(""), console.log(c.dim("Validating content..."));
+  let i;
+  try {
+    const { registry: a, fileMap: o, config: r } = await X(n), t = I(a, o);
+    T(t), t.length > 0 && (console.log(c.red("Build failed due to validation errors.")), console.log(""), process.exit(1)), i = { registry: a, config: r };
+  } catch (a) {
+    console.error(c.red("Error loading content:"), a), process.exit(1);
+  }
+  console.log("");
+  try {
+    await $({
       root: e,
-      plugins: [O()],
+      plugins: [A()],
       build: {
         outDir: "dist",
         emptyOutDir: !0
       }
-    }), console.log(`
-✅ Build complete! Output in dist/
-`), console.log("To preview the build:"), console.log(`  yarn preview
-`);
-  } catch (s) {
-    console.error("Build failed:", s), process.exit(1);
+    });
+    const a = s(e, "dist", "api");
+    await R(a, { recursive: !0 }), await g(s(a, "content"), JSON.stringify(i)), console.log(""), console.log(c.green("✅ Build complete! Output in dist/")), console.log(""), console.log("To preview the build:"), console.log(c.dim("  yarn preview")), console.log("");
+  } catch (a) {
+    console.error(c.red("Build failed:"), a), process.exit(1);
   }
 }
-const k = "🐾", $ = "🐕", v = "🦴", B = "✨", D = "📁", f = "✅", F = "🚀";
-async function U(e) {
-  const s = o(process.cwd(), e);
-  console.log(""), console.log(t.bold.magenta(`  ${k} Doodle Engine ${k}`)), console.log(t.dim("  Text-based RPG and Adventure Game Scaffolder")), console.log(""), console.log(`  ${$} Creating new game: ${t.bold.cyan(e)}`), console.log("");
-  const { useDefaultRenderer: d } = await A({
+async function X(e) {
+  const n = {
+    locations: {},
+    characters: {},
+    items: {},
+    maps: {},
+    dialogues: {},
+    quests: {},
+    journalEntries: {},
+    locales: {}
+  }, i = /* @__PURE__ */ new Map(), a = [
+    { dir: "locations", key: "locations" },
+    { dir: "characters", key: "characters" },
+    { dir: "items", key: "items" },
+    { dir: "maps", key: "maps" },
+    { dir: "quests", key: "quests" },
+    { dir: "journal", key: "journalEntries" }
+  ];
+  for (const { dir: r, key: t } of a) {
+    const l = s(e, r);
+    try {
+      const d = await y(l);
+      for (const u of d)
+        if (f(u) === ".yaml" || f(u) === ".yml") {
+          const h = s(l, u), m = await p(h, "utf-8"), k = b(m);
+          k && k.id && (n[t][k.id] = k, i.set(k.id, w(process.cwd(), h)));
+        }
+    } catch {
+    }
+  }
+  try {
+    const r = s(e, "locales"), t = await y(r);
+    for (const l of t)
+      if (f(l) === ".yaml" || f(l) === ".yml") {
+        const d = s(r, l), u = await p(d, "utf-8"), h = b(u), m = l.replace(/\.(yaml|yml)$/, "");
+        n.locales[m] = h ?? {};
+      }
+  } catch {
+  }
+  try {
+    const r = s(e, "dialogues"), t = await y(r);
+    for (const l of t)
+      if (f(l) === ".dlg") {
+        const d = s(r, l), u = await p(d, "utf-8"), h = l.replace(".dlg", ""), m = v(u, h);
+        n.dialogues[m.id] = m, i.set(m.id, w(process.cwd(), d));
+      }
+  } catch {
+  }
+  let o = null;
+  try {
+    const r = s(e, "game.yaml"), t = await p(r, "utf-8");
+    o = b(t);
+  } catch {
+    o = { id: "game", startLocation: "", startTime: { day: 1, hour: 8 }, startFlags: {}, startVariables: {}, startInventory: [] };
+  }
+  return { registry: n, fileMap: i, config: o };
+}
+async function Z() {
+  const e = process.cwd(), n = s(e, "content");
+  console.log(""), console.log(c.bold.magenta("🐾 Validating Doodle Engine content...")), console.log("");
+  try {
+    const { registry: i, fileMap: a } = await ee(n), o = I(i, a);
+    T(o), o.length > 0 && process.exit(1);
+  } catch (i) {
+    console.error(c.red("Error loading content:"), i), process.exit(1);
+  }
+}
+async function ee(e) {
+  const n = {
+    locations: {},
+    characters: {},
+    items: {},
+    maps: {},
+    dialogues: {},
+    quests: {},
+    journalEntries: {},
+    locales: {}
+  }, i = /* @__PURE__ */ new Map(), a = [
+    { dir: "locations", key: "locations" },
+    { dir: "characters", key: "characters" },
+    { dir: "items", key: "items" },
+    { dir: "maps", key: "maps" },
+    { dir: "quests", key: "quests" },
+    { dir: "journal", key: "journalEntries" }
+  ];
+  for (const { dir: o, key: r } of a) {
+    const t = s(e, o);
+    try {
+      const l = await y(t);
+      for (const d of l)
+        if (f(d) === ".yaml" || f(d) === ".yml") {
+          const u = s(t, d), h = await p(u, "utf-8"), m = b(h);
+          m && m.id && (n[r][m.id] = m, i.set(m.id, w(process.cwd(), u)));
+        }
+    } catch {
+    }
+  }
+  try {
+    const o = s(e, "locales"), r = await y(o);
+    for (const t of r)
+      if (f(t) === ".yaml" || f(t) === ".yml") {
+        const l = s(o, t), d = await p(l, "utf-8"), u = b(d), h = t.replace(/\.(yaml|yml)$/, "");
+        n.locales[h] = u ?? {};
+      }
+  } catch {
+  }
+  try {
+    const o = s(e, "dialogues"), r = await y(o);
+    for (const t of r)
+      if (f(t) === ".dlg") {
+        const l = s(o, t), d = await p(l, "utf-8"), u = t.replace(".dlg", ""), h = v(d, u);
+        n.dialogues[h.id] = h, i.set(h.id, w(process.cwd(), l));
+      }
+  } catch {
+  }
+  return { registry: n, fileMap: i };
+}
+const D = "🐾", te = "🐕", q = "🦴", oe = "✨", x = "📁", _ = "✅", ae = "🚀";
+async function ne(e) {
+  const n = s(process.cwd(), e);
+  console.log(""), console.log(c.bold.magenta(`  ${D} Doodle Engine ${D}`)), console.log(c.dim("  Text-based RPG and Adventure Game Scaffolder")), console.log(""), console.log(`  ${te} Creating new game: ${c.bold.cyan(e)}`), console.log("");
+  const { useDefaultRenderer: i } = await M({
     type: "confirm",
     name: "useDefaultRenderer",
     message: "Use default renderer?",
     initial: !0
   });
-  d === void 0 && (console.log(t.yellow(`
-  ${v} No worries, maybe next time! Woof!`)), process.exit(0)), console.log(""), await J(s, e, d), console.log(""), console.log(t.bold.green(`  ${f} Project created successfully!`)), console.log(""), console.log(t.dim(`  ${D} ${s}`)), console.log(""), console.log(t.bold("  Next steps:")), console.log(t.cyan(`    cd ${e}`)), console.log(t.cyan("    npm install       ") + t.dim("# or: yarn install / pnpm install")), console.log(t.cyan("    npm run dev        ") + t.dim("# or: yarn dev / pnpm dev")), console.log(""), console.log(t.dim(`  ${F} Happy game making! ${k}`)), console.log("");
+  i === void 0 && (console.log(c.yellow(`
+  ${q} No worries, maybe next time! Woof!`)), process.exit(0)), console.log(""), await re(n, e, i), console.log(""), console.log(c.bold.green(`  ${_} Project created successfully!`)), console.log(""), console.log(c.dim(`  ${x} ${n}`)), console.log(""), console.log(c.bold("  Next steps:")), console.log(c.cyan(`    cd ${e}`)), console.log(c.cyan("    npm install       ") + c.dim("# or: yarn install / pnpm install")), console.log(c.cyan("    npm run dev        ") + c.dim("# or: yarn dev / pnpm dev")), console.log(""), console.log(c.dim(`  ${ae} Happy game making! ${D}`)), console.log("");
 }
-async function J(e, s, d) {
-  const h = [
+async function re(e, n, i) {
+  const a = [
     "content/locations",
     "content/characters",
     "content/items",
@@ -166,12 +545,12 @@ async function J(e, s, d) {
     "assets/audio/voice",
     "src"
   ];
-  console.log(`  ${D} ${t.bold("Creating directories...")}`);
-  for (const m of h)
-    await S(o(e, m), { recursive: !0 });
-  console.log(t.green(`  ${f} Directories created`)), console.log("");
-  const r = {
-    name: s,
+  console.log(`  ${x} ${c.bold("Creating directories...")}`);
+  for (const h of a)
+    await R(s(e, h), { recursive: !0 });
+  console.log(c.green(`  ${_} Directories created`)), console.log("");
+  const o = {
+    name: n,
     version: "0.1.0",
     type: "module",
     scripts: {
@@ -194,11 +573,11 @@ async function J(e, s, d) {
       vite: "^6.0.0"
     }
   };
-  console.log(`  ${B} ${t.bold("Writing project files...")}`), await a(
-    o(e, "package.json"),
-    JSON.stringify(r, null, 2)
+  console.log(`  ${oe} ${c.bold("Writing project files...")}`), await g(
+    s(e, "package.json"),
+    JSON.stringify(o, null, 2)
   );
-  const c = {
+  const r = {
     compilerOptions: {
       target: "ES2024",
       lib: ["ES2024", "DOM", "DOM.Iterable"],
@@ -215,10 +594,10 @@ async function J(e, s, d) {
     },
     include: ["src"]
   };
-  await a(
-    o(e, "tsconfig.json"),
-    JSON.stringify(c, null, 2)
-  ), await a(o(e, "index.html"), `<!doctype html>
+  await g(
+    s(e, "tsconfig.json"),
+    JSON.stringify(r, null, 2)
+  ), await g(s(e, "index.html"), `<!doctype html>
 <html lang="en">
   <head>
     <meta charset="UTF-8" />
@@ -230,7 +609,7 @@ async function J(e, s, d) {
     <script type="module" src="/src/main.tsx"><\/script>
   </body>
 </html>
-`), await a(o(e, "src/main.tsx"), `import { StrictMode } from 'react'
+`), await g(s(e, "src/main.tsx"), `import { StrictMode } from 'react'
 import { createRoot } from 'react-dom/client'
 import { App } from './App'
 import './index.css'
@@ -241,10 +620,10 @@ createRoot(document.getElementById('root')!).render(
   </StrictMode>,
 )
 `);
-  let i;
-  d ? i = `import { useEffect, useState } from 'react'
+  let d;
+  i ? d = `import { useEffect, useState } from 'react'
 import type { ContentRegistry, GameConfig } from '@doodle-engine/core'
-import { GameShell } from '@doodle-engine/react'
+import { GameShell, LoadingScreen } from '@doodle-engine/react'
 
 export function App() {
   const [content, setContent] = useState<{ registry: ContentRegistry; config: GameConfig } | null>(null)
@@ -256,7 +635,7 @@ export function App() {
   }, [])
 
   if (!content) {
-    return <div style={{ padding: '2rem', fontFamily: 'sans-serif' }}>Loading game...</div>
+    return <LoadingScreen />
   }
 
   return (
@@ -267,13 +646,14 @@ export function App() {
       subtitle="A text-based adventure"
       splashDuration={2000}
       availableLocales={[{ code: 'en', label: 'English' }]}
+      devTools={import.meta.env.DEV}
     />
   )
 }
-` : i = `import { useEffect, useState } from 'react'
+` : d = `import { useEffect, useState } from 'react'
 import { Engine } from '@doodle-engine/core'
 import type { GameState, Snapshot } from '@doodle-engine/core'
-import { GameProvider, useGame } from '@doodle-engine/react'
+import { GameProvider, LoadingScreen, useGame } from '@doodle-engine/react'
 
 export function App() {
   const [game, setGame] = useState<{ engine: Engine; snapshot: Snapshot } | null>(null)
@@ -289,11 +669,11 @@ export function App() {
   }, [])
 
   if (!game) {
-    return <div style={{ padding: '2rem', fontFamily: 'sans-serif' }}>Loading game...</div>
+    return <LoadingScreen />
   }
 
   return (
-    <GameProvider engine={game.engine} initialSnapshot={game.snapshot}>
+    <GameProvider engine={game.engine} initialSnapshot={game.snapshot} devTools={import.meta.env.DEV}>
       <GameUI />
     </GameProvider>
   )
@@ -361,7 +741,7 @@ function createEmptyState(): GameState {
     currentLocale: 'en',
   }
 }
-`, await a(o(e, "src/App.tsx"), i), await a(o(e, "src/index.css"), `body {
+`, await g(s(e, "src/App.tsx"), d), await g(s(e, "src/index.css"), `body {
   margin: 0;
   font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', 'Roboto', 'Oxygen',
     'Ubuntu', 'Cantarell', 'Fira Sans', 'Droid Sans', 'Helvetica Neue',
@@ -369,7 +749,7 @@ function createEmptyState(): GameState {
   -webkit-font-smoothing: antialiased;
   -moz-osx-font-smoothing: grayscale;
 }
-`), console.log(t.green(`  ${f} Source files created`)), console.log(""), console.log(`  ${v} ${t.bold("Writing starter content...")}`), await a(o(e, "content/game.yaml"), `# Game Configuration
+`), console.log(c.green(`  ${_} Source files created`)), console.log(""), console.log(`  ${q} ${c.bold("Writing starter content...")}`), await g(s(e, "content/game.yaml"), `# Game Configuration
 startLocation: tavern
 startTime:
   day: 1
@@ -380,40 +760,40 @@ startVariables:
   reputation: 0
   _drinksBought: 0
 startInventory: []
-`), await a(o(e, "content/locations/tavern.yaml"), `id: tavern
+`), await g(s(e, "content/locations/tavern.yaml"), `id: tavern
 name: "@location.tavern.name"
 description: "@location.tavern.description"
 banner: ""
 music: ""
 ambient: ""
-`), await a(o(e, "content/locations/market.yaml"), `id: market
+`), await g(s(e, "content/locations/market.yaml"), `id: market
 name: "@location.market.name"
 description: "@location.market.description"
 banner: ""
 music: ""
 ambient: ""
-`), await a(o(e, "content/characters/bartender.yaml"), `id: bartender
+`), await g(s(e, "content/characters/bartender.yaml"), `id: bartender
 name: "@character.bartender.name"
 biography: "@character.bartender.bio"
 portrait: ""
 location: tavern
 dialogue: bartender_greeting
 stats: {}
-`), await a(o(e, "content/characters/merchant.yaml"), `id: merchant
+`), await g(s(e, "content/characters/merchant.yaml"), `id: merchant
 name: "@character.merchant.name"
 biography: "@character.merchant.bio"
 portrait: ""
 location: market
 dialogue: merchant_intro
 stats: {}
-`), await a(o(e, "content/items/old_coin.yaml"), `id: old_coin
+`), await g(s(e, "content/items/old_coin.yaml"), `id: old_coin
 name: "@item.old_coin.name"
 description: "@item.old_coin.description"
 icon: ""
 image: ""
 location: tavern
 stats: {}
-`), await a(o(e, "content/maps/town.yaml"), `id: town
+`), await g(s(e, "content/maps/town.yaml"), `id: town
 name: "@map.town.name"
 image: ""
 scale: 1
@@ -424,7 +804,7 @@ locations:
   - id: market
     x: 300
     y: 150
-`), await a(o(e, "content/quests/odd_jobs.yaml"), `id: odd_jobs
+`), await g(s(e, "content/quests/odd_jobs.yaml"), `id: odd_jobs
 name: "@quest.odd_jobs.name"
 description: "@quest.odd_jobs.description"
 stages:
@@ -434,40 +814,60 @@ stages:
     description: "@quest.odd_jobs.stage.talked_to_merchant"
   - id: complete
     description: "@quest.odd_jobs.stage.complete"
-`), await a(o(e, "content/journal/tavern_discovery.yaml"), `id: tavern_discovery
+`), await g(s(e, "content/journal/tavern_discovery.yaml"), `id: tavern_discovery
 title: "@journal.tavern_discovery.title"
 text: "@journal.tavern_discovery.text"
 category: places
-`), await a(o(e, "content/journal/odd_jobs_accepted.yaml"), `id: odd_jobs_accepted
+`), await g(s(e, "content/journal/odd_jobs_accepted.yaml"), `id: odd_jobs_accepted
 title: "@journal.odd_jobs_accepted.title"
 text: "@journal.odd_jobs_accepted.text"
 category: quests
-`), await a(o(e, "content/journal/market_square.yaml"), `id: market_square
+`), await g(s(e, "content/journal/market_square.yaml"), `id: market_square
 title: "@journal.market_square.title"
 text: "@journal.market_square.text"
 category: places
-`), await a(o(e, "content/dialogues/tavern_intro.dlg"), `TRIGGER tavern
+`), await g(s(e, "content/dialogues/tavern_intro.dlg"), `# This dialogue triggers automatically when the player enters the tavern.
+# TRIGGER <locationId> fires on arrival. REQUIRE conditions guard the trigger.
+# Use notFlag to make it a one-time intro.
+
+TRIGGER tavern
 REQUIRE notFlag seenTavernIntro
 
+# Each NODE is a conversation point. The first NODE is always the start.
 NODE start
+  # NARRATOR: has no speaker — used for scene-setting text.
+  # @narrator.tavern_intro is a localization key defined in content/locales/en.yaml.
+  # You can also write text inline: NARRATOR: "The tavern is warm and smells of ale."
   NARRATOR: @narrator.tavern_intro
+
+  # Effects run immediately when this node is reached, before choices are shown.
   SET flag seenTavernIntro
 
+  # CHOICE text can use a @key or "inline text".
+  # A choice with END dialogue is a terminal choice — no GOTO needed.
   CHOICE @narrator.choice.look_around
     END dialogue
   END
-`), await a(o(e, "content/dialogues/market_intro.dlg"), `TRIGGER market
+`), await g(s(e, "content/dialogues/market_intro.dlg"), `# One-time narrator intro for the market. Same pattern as tavern_intro.dlg.
+
+TRIGGER market
 REQUIRE notFlag seenMarketIntro
 
 NODE start
   NARRATOR: @narrator.market_intro
   SET flag seenMarketIntro
+
+  # ADD journalEntry unlocks a journal entry for the player.
   ADD journalEntry market_square
 
   CHOICE @narrator.choice.look_around
     END dialogue
   END
-`), await a(o(e, "content/dialogues/bartender_greeting.dlg"), `NODE start
+`), await g(s(e, "content/dialogues/bartender_greeting.dlg"), `# This dialogue is triggered by clicking the bartender character.
+# SPEAKER: lines set who's talking — matched to character ID (case-insensitive).
+# Nodes can have multiple CHOICE blocks; REQUIRE hides a choice if the condition fails.
+
+NODE start
   BARTENDER: @bartender.greeting
 
   # Always available — ask for rumors (demonstrates: flag, relationship, journalEntry)
@@ -605,7 +1005,10 @@ NODE work_done
 NODE farewell
   BARTENDER: @bartender.farewell
   END dialogue
-`), await a(o(e, "content/dialogues/merchant_intro.dlg"), `NODE start
+`), await g(s(e, "content/dialogues/merchant_intro.dlg"), `# Merchant dialogue. Same speaker-line and CHOICE syntax as bartender_greeting.dlg.
+# The quest choices here demonstrate multi-stage quest gating with questAtStage.
+
+NODE start
   MERCHANT: @merchant.greeting
 
   CHOICE @merchant.choice.browse_wares
@@ -705,7 +1108,7 @@ NODE about_market
 NODE farewell
   MERCHANT: @merchant.farewell
   END dialogue
-`), await a(o(e, "content/locales/en.yaml"), `# ===================
+`), await g(s(e, "content/locales/en.yaml"), `# ===================
 # Narrator Intros
 # ===================
 narrator.tavern_intro: "You push open the heavy oak door and step inside. The warmth hits you first, then the smell — stale ale, wood smoke, and something frying in the kitchen. A few patrons hunch over their mugs. Behind the bar, a broad-shouldered man wipes down glasses, watching you with quiet interest."
@@ -833,21 +1236,24 @@ notification.quest_updated: "Quest Updated: Odd Jobs"
 notification.quest_complete: "Quest Complete: Odd Jobs (+50 gold, +10 reputation)"
 notification.bought_drink: "Bought a drink (-5 gold)"
 notification.bought_map: "Bought a map (-20 gold)"
-`), console.log(t.green(`  ${f} Starter content created`)), console.log(""), console.log(t.dim("  Content includes:")), console.log(t.dim("    2 locations (tavern, market)")), console.log(t.dim("    2 characters (bartender, merchant)")), console.log(t.dim("    1 item (old coin)")), console.log(t.dim("    1 map (town)")), console.log(t.dim("    1 quest with 3 stages")), console.log(t.dim("    3 journal entries")), console.log(t.dim("    4 dialogues (2 narrator intros, 2 NPC conversations)")), console.log(t.dim("    English locale with all strings")), await a(o(e, ".gitignore"), `node_modules
+`), console.log(c.green(`  ${_} Starter content created`)), console.log(""), console.log(c.dim("  Content includes:")), console.log(c.dim("    2 locations (tavern, market)")), console.log(c.dim("    2 characters (bartender, merchant)")), console.log(c.dim("    1 item (old coin)")), console.log(c.dim("    1 map (town)")), console.log(c.dim("    1 quest with 3 stages")), console.log(c.dim("    3 journal entries")), console.log(c.dim("    4 dialogues (2 narrator intros, 2 NPC conversations)")), console.log(c.dim("    English locale with all strings")), await g(s(e, ".gitignore"), `node_modules
 dist
 .DS_Store
 *.log
 `);
 }
-const p = new C();
-p.name("doodle").description(t.magenta("🐾 Doodle Engine") + t.dim(" — Narrative RPG development tools")).version("0.0.1");
-p.command("create <project-name>").description("Scaffold a new Doodle Engine game project").action(async (e) => {
-  await U(e);
+const E = new G();
+E.name("doodle").description(c.magenta("🐾 Doodle Engine") + c.dim(" — Narrative RPG development tools")).version("0.0.1");
+E.command("create <project-name>").description("Scaffold a new Doodle Engine game project").action(async (e) => {
+  await ne(e);
+});
+E.command("dev").description("Start development server with hot reload").action(async () => {
+  await Y();
 });
-p.command("dev").description("Start development server with hot reload").action(async () => {
-  await j();
+E.command("build").description("Build game for production").action(async () => {
+  await z();
 });
-p.command("build").description("Build game for production").action(async () => {
-  await M();
+E.command("validate").description("Validate game content").action(async () => {
+  await Z();
 });
-p.parse();
+E.parse();