@lingfan-engine/editor 0.0.0-stage → 0.1.2

package/src/script/words/flow.ts

@@ -0,0 +1,391 @@
+/**
+ * Script 词汇层 · **流程域**（wait / pause / random / 跳转导航 / func·call / 控制流 /
+ * assert / guard）。
+ *
+ * **控制流是结构化构造，不是 TS 原生语句**：`when(...).then([...])` 产出 if-op
+ * **节点**（数据）；TS 原生 `if` 在构建期求值（分支展开成静态数据）——两者语义不同，
+ * 按「这一分支是运行期还是构建期」选择。运行期分支的运行期循环同理（whileDo/forIn）。
+ *
+ * `Stmt` 刻意保持 StoryCommand envelope（**不**收窄为 ScriptCommand）：
+ * 块体内建 op 与扩展 op（extOp）混排是合法创作形态，闭合联合会把扩展挡在块体外。
+ */
+import type { StoryCommand } from "@lingfan-engine/core";
+import type { CommandOf, ScriptValue } from "../../schema/index.ts";
+import type { CellHandle, KnownColumnName, KnownGuardName } from "./cells.ts";
+
+export type Stmt = StoryCommand;
+
+// —— 等待与随机 ——
+
+/**
+ * 等待 `seconds` 秒后继续。等待建立时就是回溯检查点；开启 autoSave 时
+ * 此处自动存档。
+ * @param seconds 等待秒数。
+ * @param opts 可选项：skipable 为 true 时玩家可点击/按键提前跳过。
+ * @returns `wait` 故事命令。
+ * @example
+ * wait(2, { skipable: true });
+ */
+export function wait(
+  seconds: number,
+  opts?: { skipable?: boolean },
+): CommandOf<"wait"> {
+  return { op: "wait", seconds, ...opts };
+}
+
+/**
+ * 定长暂停（不可跳过——可跳过的等待用 {@link wait} 传
+ * `{ skipable: true }`）。等待建立时建立回溯检查点。
+ * @param seconds 暂停秒数。
+ * @returns `pause` 故事命令。
+ */
+export function pause(seconds: number): CommandOf<"pause"> {
+  return { op: "pause", seconds };
+}
+
+/**
+ * 用显式种子掷一次随机数：把 `[min, max]` **闭区间**内的一个整数写进
+ * 变量 `into`。种子同时进入随机状态——回溯重放时序列完全一致。
+ * `seed` 必须是整数；`min > max` 报错停机。
+ * @param seed 随机种子（整数，决定具体取值）。
+ * @param min 下界（含）。
+ * @param max 上界（含）。
+ * @param into 收纳结果的变量名。
+ * @returns `random` 故事命令。
+ * @example
+ * random(20260101, 1, 6, "dice");
+ * say("掷出了 {dice} 点！");
+ */
+export function random(
+  seed: number,
+  min: number,
+  max: number,
+  into: string,
+): CommandOf<"random"> {
+  return { op: "random", seed, range: [min, max], var: into };
+}
+
+// —— 跳转与导航 ——
+
+/**
+ * 立即跳进 `target` 列继续（列名即标签，同一故事文件内跳转）。
+ * @param target 目标列名（`stories.gen.d.ts` 存在时收窄为工程内列名字面量联合）。
+ * @returns `jump` 故事命令。
+ * @example
+ * when(cond`gold >= 10`, [jump("shop")]);
+ */
+export function jump(target: KnownColumnName): CommandOf<"jump"> {
+  return { op: "jump", target };
+}
+
+/**
+ * 导航到目标列继续：`scene` 给出时优先（跨章节/场景跳转），缺省用
+ * `path`。跳转前会清掉旧列的对话残留画面；不建立检查点。
+ * @param path 目标列名（缺省目标）。
+ * @param scene 目标列名（显式给出时优先于 path）。
+ * @returns `navigate` 故事命令。
+ * @example
+ * navigate("ep2_gate", "ep2");
+ */
+export function navigate(
+  path: KnownColumnName,
+  scene?: KnownColumnName,
+): CommandOf<"navigate"> {
+  return { op: "navigate", path, ...(scene === undefined ? {} : { scene }) };
+}
+
+// —— 子过程（func / call / ret）——
+
+/**
+ * 注册一个具名子过程：执行到这里时把 `body` 挂进函数表，之后用
+ * {@link call} 调用。对同名重复注册报错（除非两次定义完全相同）。
+ * @param name 子过程名（call 时引用）。
+ * @param params 形参名列表（call 的实参按位绑定进来）。
+ * @param 子过程体（一组故事命令）。
+ * @returns `func` 故事命令。
+ * @example
+ * func("greet", ["who"], [say("你好，{who}！")]);
+ * call("greet", ["阿岚"]);
+ */
+export function func(
+  name: string,
+  params: readonly string[],
+  body: readonly Stmt[],
+): CommandOf<"func"> {
+  return { op: "func", name, params: [...params], body: [...body] };
+}
+
+/**
+ * 调用 {@link func} 注册的子过程（或跳到普通流程列）：实参逐项求值后
+ * 按位绑定给形参，过程体跑完（或 {@link ret}）后回到调用点继续。
+ * 参数个数对不上报错停机。
+ * @param target 子过程名或目标列名。
+ * @param args 实参列表（字面量或 `"{expr}"` 表达式串，按位绑定）。
+ * @param into 结果绑定名：被调过程 {@link ret} 带值返回时，把返回值
+ *   声明为调用方作用域里的这个局部变量；过程正常跑完没有 ret 带值时绑定为
+ *   `null`（与表达式内建的缺失语义同族）。不带 `into` 时返回值被静默丢弃。
+ * @returns `call` 故事命令。
+ * @example
+ * call("greet", ["阿岚"]);
+ * call("greet", ["阿岚"], "greeting");
+ */
+export function call(
+  target: string,
+  args?: readonly ScriptValue[],
+  into?: string,
+): CommandOf<"call"> {
+  return {
+    op: "call",
+    target,
+    ...(args === undefined ? {} : { args: [...args] }),
+    ...(into === undefined ? {} : { into }),
+  };
+}
+
+/**
+ * 从子过程返回到调用点。在子过程（func 体）之外使用报错停机。
+ * @param value 可选返回值（字面量或 `"{expr}"` 表达式串）：带 `into`
+ *   的调用点会把它绑定成局部变量，其余调用点丢弃。
+ * @returns `return` 故事命令。
+ * @example
+ * func("early", [], [when(cond`hp <= 0`, [ret()]), say("继续")]);
+ * func("level", ["exp"], [ret(`Math.floor(exp / 100)`)]);
+ */
+export function ret(value?: ScriptValue): CommandOf<"return"> {
+  return { op: "return", ...(value === undefined ? {} : { value }) };
+}
+
+// —— 条件分支（双入口）——
+// 为什么不做一个可链式的 when：链式方法名（elif/else）与 if-op 的**数据字段同名**
+//    ——方法挂上命令对象后，读字段读到的是方法（elifs.push is not a function），
+//    未收尾的链放进命令数组还会把函数属性带进 Story ⇒ build 期响亮报错。
+//    拆两个入口：`when` 覆盖最常用（then-only，干净数据直出）；`whenChain` 才有链式。
+
+export interface IfChain {
+  elif(cond: string, body: readonly Stmt[]): IfChain;
+  else(body: readonly Stmt[]): Stmt;
+  /** elif 链收尾（无 else 分支时）——产物 = 最终 if 数据 */
+  end(): Stmt;
+}
+
+/**
+ * 运行期条件分支（then-only 最常用形态）：执行到这里时求值 `cond`，
+ * 为真才执行 `thenBody`（分支体在新块作用域里执行）。
+ *
+ * `cond` 是条件表达式：用 {@link cond} 标签串接变量（如
+ * `cond\`gold >= 10\``），或直接写 `"{gold >= 10}"`；表达式必须产出
+ * 布尔值，否则报错停机。
+ *
+ * @param cond 条件表达式（运行期求值，须为布尔）。
+ * @param thenBody 条件成立时执行的一组命令。
+ * @returns `if` 故事命令。
+ * @example
+ * when(cond`gold >= 10`, [
+ *   say("买下了药水。"),
+ *   set("gold", "-= 10"),
+ * ]);
+ */
+export function when(cond: string, thenBody: readonly Stmt[]): CommandOf<"if"> {
+  return { op: "if", cond, then: [...thenBody] };
+}
+
+/**
+ * 需要 elif / else 的条件分支：先给条件与 then 体，再链上
+ * `.elif(cond, body)`、以 `.else(body)` 或 `.end()` 收尾取产物。
+ * 各分支条件都在运行期依次求值，命中第一个为真的分支。
+ * @param cond 首个条件表达式（运行期求值，须为布尔）。
+ * @param thenBody 首个条件成立时执行的一组命令。
+ * @returns 分支链（以 `.else(...)` 或 `.end()` 收尾产出 `if` 故事命令）。
+ * @example
+ * whenChain(cond`mood > 5`, [say("今天心情不错。")])
+ *   .elif(cond`mood > 0`, [say("还过得去。")])
+ *   .else([say("唉……")]);
+ */
+export function whenChain(cond: string, thenBody: readonly Stmt[]): IfChain {
+  const then = [...thenBody];
+  const elifs: Array<{ cond: string; then: Stmt[] }> = [];
+  let elseBody: Stmt[] | undefined;
+  const build = (): Stmt => {
+    const out: Record<string, unknown> = { op: "if", cond, then };
+    if (elifs.length > 0) out.elif = elifs;
+    if (elseBody !== undefined) out.else = elseBody;
+    return out as unknown as Stmt;
+  };
+  const chain: IfChain = {
+    elif(c, body) {
+      elifs.push({ cond: c, then: [...body] });
+      return chain;
+    },
+    else(body) {
+      elseBody = [...body];
+      return build();
+    },
+    end() {
+      return build();
+    },
+  };
+  return chain;
+}
+
+// —— 循环（while / for / foreach）——
+
+/**
+ * 运行期 while 循环：每轮重新求值 `cond`，为真就执行一轮 `body`
+ * （体在新块作用域里执行）。条件必须产出布尔值；永真条件会让循环无法退出。
+ * @param cond 每轮重判的条件表达式（须为布尔）。
+ * @param body 每轮执行的一组命令。
+ * @returns `while` 故事命令。
+ * @example
+ * whileDo(cond`hunger < 100`, [eat()]);
+ */
+export function whileDo(
+  cond: string,
+  body: readonly Stmt[],
+): CommandOf<"while"> {
+  return { op: "while", cond, body: [...body] };
+}
+
+/**
+ * 运行期 for 循环：把 `iterable` 求值（必须得到数组），逐元素赋给
+ * `varName`（块级临时变量，出循环即销毁）并执行一轮 `body`。
+ * @param varName 循环变量名（每轮接收当前元素）。
+ * @param iterable 数组表达式（求值结果必须是数组）。
+ * @param body 每个元素执行的一组命令。
+ * @returns `for` 故事命令。
+ * @example
+ * forIn("item", "backpack", [say("背包里有：{item}")]);
+ */
+export function forIn(
+  varName: string,
+  iterable: string,
+  body: readonly Stmt[],
+): CommandOf<"for"> {
+  return { op: "for", var: varName, in: iterable, body: [...body] };
+}
+
+/**
+ * foreach：`collection` = 集合**变量名**（运行期按名 resolve，须为数组）。
+ * 形状 = 规范四事实（`data/format/` 校验 / foreachSchema / parseTextStory 产物 /
+ * generateText 投影）：`{var, key, body}`——`in` 是 DSL 行文法（`foreach "v" in "k"`）
+ * 的分隔符，**不属于 op 数据**（`in` 字段属于 `for` op）；多产 `in` 会被编辑器
+ * 判 unknown-field。漏 `key` parseStory 即拒（执行层以 key resolve，互锁测试锚定）。
+ *
+ * 逐元素迭代：每轮把当前元素赋给 `varName`（块级临时变量）再执行 `body`。
+ *
+ * @param varName 循环变量名（每轮接收当前元素）。
+ * @param collection 集合**变量名**（运行期按名取数组）。
+ * @param body 每个元素执行的一组命令。
+ * @returns `foreach` 故事命令。
+ * @example
+ * forEach("item", "party", [say("{item} 入队了。")]);
+ */
+export function forEach(
+  varName: string,
+  collection: string,
+  body: readonly Stmt[],
+): CommandOf<"foreach"> {
+  return {
+    op: "foreach",
+    var: varName,
+    key: collection,
+    body: [...body],
+  };
+}
+
+// —— 多路分支与循环控制 ——
+
+/**
+ * 运行期多路分支：把 `on` 求值后与各 `cases` 的取值做相等比较，命中
+ * 哪个就执行哪个分支体（不穿透、不fall-through）；都不命中走
+ * `defaultBody`（未给则直接继续）。
+ * @param on 被比较的表达式（运行期求值）。
+ * @param cases 分支表：`[取值, 分支体]` 对。
+ * @param defaultBody 都不命中时执行的命令（可省略）。
+ * @returns `switch` 故事命令。
+ * @example
+ * switchOn("{choice}", [
+ *   ["inn", [navigate("to_inn")]],
+ *   ["shop", [navigate("to_shop")]],
+ * ], [say("原地待命。")]);
+ */
+export function switchOn(
+  on: string,
+  cases: ReadonlyArray<readonly [ScriptValue, readonly Stmt[]]>,
+  defaultBody?: readonly Stmt[],
+): CommandOf<"switch"> {
+  return {
+    op: "switch",
+    on,
+    cases: cases.map(([value, body]) => ({ value, body: [...body] })),
+    ...(defaultBody === undefined ? {} : { default: [...defaultBody] }),
+  };
+}
+
+/**
+ * 跳出当前所在循环（while / for / foreach）。在循环体之外使用报错停机。
+ * @returns `break` 故事命令。
+ * @example
+ * whileDo(cond`true`, [when(cond`found`, [breakLoop()]), search()]);
+ */
+export function breakLoop(): CommandOf<"break"> {
+  return { op: "break" };
+}
+
+/**
+ * 结束当前这一轮循环，直接进入下一轮条件判断。在循环体之外使用报错停机。
+ * @returns `continue` 故事命令。
+ * @example
+ * forIn("x", "list", [when(cond`x == 0`, [continueLoop()]), use(x)]);
+ */
+export function continueLoop(): CommandOf<"continue"> {
+  return { op: "continue" };
+}
+
+// —— 运行期守卫与断言 ——
+
+/**
+ * 运行期断言：`cond` 求值为假时故事报错停机（状态原样、停在当前命令），
+ * 为真则直接继续。用于给作者捕获「不该发生」的状态。
+ * @param cond 断言条件表达式（须为布尔）。
+ * @param message 报错附带的说明（可省略）。
+ * @returns `assert` 故事命令。
+ * @example
+ * assert(cond`gold >= 0`, "金币不应为负");
+ */
+export function assert(cond: string, message?: string): CommandOf<"assert"> {
+  return { op: "assert", cond, ...(message === undefined ? {} : { message }) };
+}
+
+export interface GuardOptions {
+  /** 纯数据参数（JSON 安全——嵌套对象/数组合法，运行期 findJsonValueError 兜底） */
+  args?: Record<string, unknown>;
+}
+
+/**
+ * 运行期守卫：调用组合根注册的 `(ctx, args)` 纯函数（未注册名 ⇒ fail-closed）。
+ * 名字参数接受**字面量**（注册表有声明 ⇒ 字面量联合，补全 + 写错即红；空表 = 普通
+ * string）或 **cell 句柄**（名字只写一次——声明点即引用点）。
+ *
+ * 值口径原则：**被求值的走 `Value`**（call args / reward /
+ * set——运行期表达式求值，标量语义）；**被运输的走 JSON**（guard args /
+ * minigame config——原样透传宿主，JSON 安全校验兜底）。guardSchema.args 已对齐。
+ *
+ * 运行期行为：守卫通过 = 故事直接继续（不改任何状态）；守卫返回失败、
+ * 抛错、或名字未在组合根注册时，故事报错停机（fail-closed）。
+ *
+ * @param fn 守卫名（字面量联合，补全友好）或 {@link cell} 声明的句柄。
+ * @param opts 可选项：args 传给守卫的纯数据参数（JSON 安全）。
+ * @returns `guard` 故事命令。
+ * @example
+ * guard("checkMoney", { args: { cost: 50 } });
+ */
+export function guard(
+  fn: KnownGuardName | CellHandle,
+  opts?: GuardOptions,
+): CommandOf<"guard"> {
+  return {
+    op: "guard",
+    fn: typeof fn === "string" ? fn : fn.name,
+    ...(opts?.args === undefined ? {} : { args: { ...opts.args } }),
+  };
+}

package/src/script/words/index.ts

@@ -0,0 +1,23 @@
+/**
+ * Script 词汇层 · 词条实现（作者可用的 builder 与选项类型）。
+ * 每个文件对应一族词条：叙事 / 流程 / 变量 / 存档 / 音频 / 视频 / 小游戏 /
+ * 元素 / 复合词 / 扩展 / 具名实现槽位 / 交互。
+ * 各文件导出名互不重复，故此处整体转发；对外仍由 `script` 出口按族列出名单。
+ *
+ * 每个词条函数都是**纯数据构造**：只返回一条 `StoryCommand`（与 JSON 同族），
+ * 不执行任何副作用——真正的画面/状态效果发生在引擎运行这条命令时。
+ * 条目级 JSDoc 以「作者视角」描述调用后玩家看到什么、状态怎么变。
+ */
+export * from "./audio.ts";
+export * from "./cells.ts";
+export * from "./compile-time.ts";
+export * from "./composite.ts";
+export * from "./elements.ts";
+export * from "./extension.ts";
+export * from "./flow.ts";
+export * from "./interaction.ts";
+export * from "./minigame.ts";
+export * from "./narrative.ts";
+export * from "./save.ts";
+export * from "./vars.ts";
+export * from "./video.ts";

package/src/script/words/interaction.ts

@@ -0,0 +1,44 @@
+/**
+ * Script 词汇层 · **玩法系统域**（interaction op）。
+ *
+ * 外部玩法系统（行走 / 战斗 / QTE…）由宿主注册制挂载（未知 system 运行期 fail-closed）——
+ * builder 只产数据。onSuccess/onFail 是作者侧驼峰词，builder 负责映射到 op 的 snake_case 字段。
+ */
+import type { CommandOf } from "../../schema/index.ts";
+
+export interface InteractionOptions {
+  config?: Record<string, unknown>;
+  /** 成功/失败分流目标列 */
+  onSuccess?: string;
+  onFail?: string;
+  z?: number;
+}
+
+/**
+ * 让外部玩法系统接管整屏（行走 / 战斗 / QTE…）：系统名由宿主注册制提供
+ * （未注册的 system 报错停机）。接管期间建立回溯检查点；开启 autoSave 时
+ * 此处自动存档。
+ *
+ * 系统回报结果后：成功走 `onSuccess` 列、失败走 `onFail` 列；
+ * 两者都省略则在原列继续。系统附带的状态由引擎归档，回溯/存档一致。
+ *
+ * @param system 外部玩法系统标识（宿主已注册的）。
+ * @param opts 可选项：config 透传给系统的配置（任意 JSON）、
+ *   onSuccess/onFail 分流目标列、z 实例层级。
+ * @returns `interaction` 故事命令。
+ * @example
+ * interaction("walk", { onSuccess: "arrived", onFail: "cancelled" });
+ */
+export function interaction(
+  system: string,
+  opts?: InteractionOptions,
+): CommandOf<"interaction"> {
+  return {
+    op: "interaction",
+    system,
+    ...(opts?.config === undefined ? {} : { config: { ...opts.config } }),
+    ...(opts?.onSuccess === undefined ? {} : { on_success: opts.onSuccess }),
+    ...(opts?.onFail === undefined ? {} : { on_fail: opts.onFail }),
+    ...(opts?.z === undefined ? {} : { z: opts.z }),
+  };
+}

package/src/script/words/minigame.ts

@@ -0,0 +1,66 @@
+/**
+ * Script 词汇层 · **小游戏域**（minigame op + reward 句柄）。
+ * UI 组件由注册制挂载（未知 gameId 运行期 fail-closed）——builder 只产数据。
+ * onSuccess/onFail 是作者侧驼峰词，builder 负责映射到 op 的 snake_case 字段。
+ */
+import type { CommandOf, ScriptValue } from "../../schema/index.ts";
+
+export interface MinigameOptions {
+  config?: Record<string, unknown>;
+  /** 成功/失败分流目标列 */
+  onSuccess?: string;
+  onFail?: string;
+  reward?: ReadonlyArray<{ readonly key: string; readonly value: ScriptValue }>;
+  z?: number;
+}
+
+/**
+ * 进入一个小游戏（UI 组件由注册制挂载，未知 game 报错停机）：
+ * 玩家玩完这局后故事按胜负分流——成功走 `onSuccess` 列并发放奖励，
+ * 失败走 `onFail` 列；两者都省略则在原列继续。
+ *
+ * 建立等待时就是回溯检查点；开启 autoSave 时此处自动存档。
+ * 奖励的 `value` 在运行期求值（支持 `"{expr}"`），回溯重放保持确定。
+ *
+ * @param game 小游戏标识（宿主已注册的）。
+ * @param opts 可选项：config 透传给组件的配置（任意 JSON）、
+ *   onSuccess/onFail 分流目标列、reward 奖励键值表（用 {@link reward} 构造）、
+ *   z 实例层级。
+ * @returns `minigame` 故事命令。
+ * @example
+ * minigame("cook", {
+ *   reward: [reward("coin", "+= 20")],
+ *   onSuccess: "dish_done",
+ * });
+ */
+export function minigame(
+  game: string,
+  opts?: MinigameOptions,
+): CommandOf<"minigame"> {
+  return {
+    op: "minigame",
+    game,
+    ...(opts?.config === undefined ? {} : { config: { ...opts.config } }),
+    ...(opts?.onSuccess === undefined ? {} : { on_success: opts.onSuccess }),
+    ...(opts?.onFail === undefined ? {} : { on_fail: opts.onFail }),
+    ...(opts?.reward === undefined
+      ? {}
+      : { reward: opts.reward.map((r) => ({ key: r.key, value: r.value })) }),
+    ...(opts?.z === undefined ? {} : { z: opts.z }),
+  };
+}
+
+/**
+ * 构造一条奖励条目，配合 {@link minigame} 的 `reward` 使用：
+ * 小游戏成功后把 `value` 写进状态键 `key`（`value` 支持 `"{expr}"`
+ * 运行期求值，如 `"+= 20"` 复合赋值）。
+ * @param key 收纳奖励的状态变量名。
+ * @param value 奖励值（字面量或 `"{expr}"` 表达式串）。
+ * @returns 奖励键值对。
+ */
+export function reward(
+  key: string,
+  value: ScriptValue,
+): { key: string; value: ScriptValue } {
+  return { key, value };
+}