@lingfan-engine/editor 0.0.0-stage → 0.1.2

package/src/script/words/audio.ts

@@ -0,0 +1,114 @@
+/**
+ * Script 词汇层 · **音频域**（bgm / se / ambient / voice 四通道 + 对称 stop）。
+ * 生命周期由作者手动控制（状态走 `__audio_*` 系统键 ⇒ 快照/存档/回溯随行）。
+ * Options 派生自 schema（零漂移）；voice 例外——autoStop 是作者侧驼峰词，
+ * builder 负责映射到 op 的 auto_stop 字段。
+ */
+import type { CommandOf } from "../../schema/index.ts";
+
+/** bgm / ambient 共用的可选项：volume 音量、loop 循环、fade 渐入毫秒、restart 重播 */
+export type BgmOptions = Omit<CommandOf<"bgm">, "op" | "resource">;
+
+/** 一次性播放（se）的可选项：只有音量 */
+export type PlayOptions = Pick<BgmOptions, "volume">;
+
+/** stop_* 共用的可选项：fade 渐出毫秒 */
+export type StopOptions = Omit<CommandOf<"stop_bgm">, "op">;
+
+/**
+ * 播放背景音乐：立即开始（故事继续，不等待），一直循环播放到
+ * {@link stopBgm} 或下一次换曲。
+ *
+ * - `loop` 缺省循环；`volume` 缺省 1（范围 0–1）；`fade` 渐入毫秒（缺省 0）。
+ * - 同一曲重复调用保留播放位置；换曲或 `restart: true` 时从 0 重播。
+ * - 通道状态随快照/存档/回溯走：回溯到检查点时 BGM 自动恢复到当时的曲子。
+ *
+ * @param resource 音频资源路径。
+ * @param opts 可选项，见 {@link BgmOptions}。
+ * @returns `bgm` 故事命令。
+ * @example
+ * bgm("audio/town.mp3", { fade: 1000 });
+ * stopBgm();
+ */
+export function bgm(resource: string, opts?: BgmOptions): CommandOf<"bgm"> {
+  return { op: "bgm", resource, ...opts };
+}
+
+/**
+ * 停止背景音乐：立即停止（`fade` 渐出毫秒，缺省立即），故事继续。
+ * @param opts 可选项：fade 渐出毫秒。
+ * @returns `stop_bgm` 故事命令。
+ */
+export function stopBgm(opts?: StopOptions): CommandOf<"stop_bgm"> {
+  return { op: "stop_bgm", ...opts };
+}
+
+/**
+ * 播放一次性音效（不循环）：立即开始（故事继续，不等待），播完自然结束。
+ * @param resource 音频资源路径。
+ * @param opts 可选项：volume 音量（缺省 1，范围 0–1）。
+ * @returns `se` 故事命令。
+ * @example
+ * se("audio/door_open.ogg");
+ */
+export function se(resource: string, opts?: PlayOptions): CommandOf<"se"> {
+  return { op: "se", resource, ...opts };
+}
+
+/**
+ * 播放环境音：语义同 {@link bgm}（独立通道、缺省循环、状态随存档/回溯走），
+ * 常用于雨声、市场喧闹等持续底噪。
+ * @param resource 音频资源路径。
+ * @param opts 可选项，见 {@link BgmOptions}。
+ * @returns `ambient` 故事命令。
+ * @example
+ * ambient("audio/rain_loop.ogg");
+ */
+export function ambient(
+  resource: string,
+  opts?: BgmOptions,
+): CommandOf<"ambient"> {
+  return { op: "ambient", resource, ...opts };
+}
+
+/** 停止环境音（`fade` 渐出毫秒，缺省立即），故事继续。 */
+export function stopAmbient(opts?: StopOptions): CommandOf<"stop_ambient"> {
+  return { op: "stop_ambient", ...opts };
+}
+
+/** voice 的可选项：autoStop 自动停止、restart 同曲重播、volume 音量 */
+export interface VoiceOptions extends PlayOptions {
+  autoStop?: boolean;
+  restart?: boolean;
+}
+
+/**
+ * 播放语音（独立通道、不循环）：立即开始（故事继续，不等待）。
+ *
+ * - `autoStop` 缺省 true：语音不再需要时自动停止；需要手动管理时设为
+ *   false 并用 {@link stopVoice}。
+ * - `restart: true` 强制从头重播同一条语音；`volume` 缺省 1。
+ *
+ * @param resource 语音资源路径。
+ * @param opts 可选项，见 {@link VoiceOptions}。
+ * @returns `voice` 故事命令。
+ * @example
+ * voice("audio/line_01.ogg", { volume: 0.9 });
+ */
+export function voice(
+  resource: string,
+  opts?: VoiceOptions,
+): CommandOf<"voice"> {
+  return {
+    op: "voice",
+    resource,
+    ...(opts?.autoStop === undefined ? {} : { auto_stop: opts.autoStop }),
+    ...(opts?.restart === undefined ? {} : { restart: opts.restart }),
+    ...(opts?.volume === undefined ? {} : { volume: opts.volume }),
+  };
+}
+
+/** 停止语音（`fade` 渐出毫秒，缺省立即），故事继续。 */
+export function stopVoice(opts?: StopOptions): CommandOf<"stop_voice"> {
+  return { op: "stop_voice", ...opts };
+}

package/src/script/words/cells.ts

@@ -0,0 +1,78 @@
+/**
+ * Script 词汇层 · **具名实现槽位**（cell —— build-time 声明词）。
+ *
+ * cell 声明的实现由构建期扫描收集进生成注册物（`Stories.src/gen/fun_register.g.ts`）：
+ * 故事 JSON 只留名字引用（guard 的 `fn` 字段），实现住生成模块——
+ * 「名字在数据、实现在代码、build 做名字闭合」。
+ *
+ * cell 是 **build-time 声明词**：运行期（模块被导入时，如测试/类型检查）必须纯——
+ * 只返回句柄、零副作用；实现文本由构建期 AST 提取，不经过本函数。
+ */
+import type { GuardFn } from "@lingfan-engine/core";
+
+/** 具名实现句柄：消费方（guard 等）按 face 取名字；face v1 恒 `guards` */
+export interface CellHandle<N extends string = string> {
+  readonly face: "guards";
+  readonly name: N;
+}
+
+/**
+ * 守卫名注册表（类型扩充点）：生成物尾部 `declare module "@lingfan-engine/editor"`
+ * 往本接口塞进每个已声明守卫名的字面量键 ⇒ `guard("…")` 的名字参数获得
+ * 补全与写错即红（vue-router typed-routes 同机制）。
+ * 空表 = `KnownGuardName` 退化为普通 string——不空注册表吓跑作者。
+ */
+// eslint-disable-next-line @typescript-eslint/no-empty-object-type -- 类型扩充点：只有接口可被生成物 declare module 合并（type 别名不能），空体是有意形态
+export interface GuardNameRegistry {}
+
+/** 已声明守卫名（有声明 = 字面量联合；空 = string） */
+export type KnownGuardName = keyof GuardNameRegistry extends never
+  ? string
+  : keyof GuardNameRegistry & string;
+
+/**
+ * 列名注册表（类型扩充点）：构建期生成的 `Stories.src/gen/stories.gen.d.ts`
+ * 往本接口塞进工程内每个列 id 的字面量键 ⇒ `jump("…")` 与 `option("…", "…")`
+ * 的目标列名获得补全、写错即红。空表退化为普通 string。
+ */
+// eslint-disable-next-line @typescript-eslint/no-empty-object-type -- 类型扩充点：只有接口可被生成物 declare module 合并（type 别名不能），空体是有意形态
+export interface ColumnNameRegistry {}
+
+/** 已声明列名（有声明 = 字面量联合；空 = string） */
+export type KnownColumnName = keyof ColumnNameRegistry extends never
+  ? string
+  : keyof ColumnNameRegistry & string;
+
+/**
+ * 插值键注册表（类型扩充点）：生成物塞进工程内所有能当 `{…}` 键的名字——
+ * state schema 展平键、defineVars 登记变量、产物 op 流里的声明名，
+ * 以及扩展命名空间前缀（生成物写成 `ext.<id>.${string}` 的字面量类型）。
+ * 空表退化为普通 string；富文本行内标记由词汇层的模板串类型单独豁免。
+ */
+// eslint-disable-next-line @typescript-eslint/no-empty-object-type -- 类型扩充点：只有接口可被生成物 declare module 合并（type 别名不能），空体是有意形态
+export interface InterpolationKeyRegistry {}
+
+/** 已声明插值键（有声明 = 字面量联合；空 = string） */
+export type KnownInterpolationKey = keyof InterpolationKeyRegistry extends never
+  ? string
+  : keyof InterpolationKeyRegistry & string;
+
+/**
+ * 声明一个守卫实现槽位：构建期扫描收集 `impl` 生成注册物，故事数据里
+ * 只留名字（{@link guard} 的 fn 字段）。运行期是纯声明——不执行 impl。
+ * 返回的句柄可直接传给 {@link guard}，名字只写一次。
+ *
+ * @param name 守卫名（进故事 JSON 与生成注册物）。
+ * @param impl 守卫实现纯函数（构建期 AST 提取，不在运行期调用）。
+ * @returns 实现句柄（传给 {@link guard} 引用）。
+ * @example
+ * export const checkMoney = cell("checkMoney", (ctx, args) => true);
+ * guard(checkMoney, { args: { cost: 50 } });
+ */
+export function cell<const N extends string>(
+  name: N,
+  impl: GuardFn,
+): CellHandle<N> {
+  void impl;
+  return { face: "guards", name };
+}

package/src/script/words/compile-time.ts

@@ -0,0 +1,27 @@
+/**
+ * Script 词汇层 · **编译期构造**：只在 Stories.src 源内有意义，由 stories 构建管线静态展开，
+ * 运行期不提供实现（误调用即抛错）。这里只放纯编译期声明与类型，不产 op、不进 op schema。
+ */
+import type { StoryCommand } from "@lingfan-engine/core";
+
+/** 故事文件的 default 导出引用（jump 跨故事引用等编译期引用形态的目标类型）。 */
+export type StoryFn = () => void;
+
+/**
+ * 编译期定数循环：`staticFor(n, (i) => [命令…])` 在构建期展开为 n 份按序内联的静态命令，
+ * i 以数字字面量代换（含模板串插值）。运行期不可调用。
+ *
+ * @param count 展开份数（构建期常量）。
+ * @param generator 以序号产出命令数组的生成函数（构建期求值）。
+ * @returns 展开后的静态命令（只在 Stories.src 源内有意义；误调用即抛错）。
+ * @example
+ * staticFor(3, (i) => [say(`第 ${i} 次操练`)]);
+ */
+export function staticFor(
+  _count: number,
+  _generator: (i: number) => readonly StoryCommand[],
+): StoryCommand[] {
+  throw new Error(
+    "staticFor 是编译期构造：由 stories 构建管线静态展开，运行期不可调用",
+  );
+}

package/src/script/words/composite.ts

@@ -0,0 +1,125 @@
+/**
+ * Script 词汇层 · **复合词**（多 op/元素的高频组合，纯展开）。
+ * 复合词不产出新语义：每个函数 = 既有元素的语法糖。
+ */
+import type { ElementNode } from "@lingfan-engine/core";
+
+export interface ElementOptions {
+  id?: string;
+  x?: number | string;
+  y?: number | string;
+  width?: number | string;
+  height?: number | string;
+  color?: string;
+  size?: number | string;
+  halign?: string;
+  opacity?: number;
+  zindex?: number;
+  [attr: string]: unknown;
+}
+
+/**
+ * 文本元素：在场景里显示一段文字。产物是元素**节点**（数据），
+ * 放进 scene 列的 `elements` 数组才会出现在画面上。
+ * @param text 显示的文字。
+ * @param opts 元素属性（id/x/y/width/height/color/size/halign/opacity/zindex 等）。
+ * @returns text 元素节点。
+ * @example
+ * textElement("第二章 · 广场", { x: "5%", y: "12%", size: 32 });
+ */
+export function textElement(text: string, opts?: ElementOptions): ElementNode {
+  return { type: "text", text, ...opts };
+}
+
+/**
+ * 图片元素：在场景里显示一张图。产物是元素**节点**（数据）。
+ * @param source 图片资源路径。
+ * @param opts 元素属性（id/x/y/width/height/opacity/zindex 等）。
+ * @returns image 元素节点。
+ * @example
+ * imageElement("images/market.png", { x: "10%", y: "30%", width: "40%" });
+ */
+export function imageElement(
+  source: string,
+  opts?: ElementOptions,
+): ElementNode {
+  return { type: "image", source, ...opts };
+}
+
+/**
+ * 按钮元素：可点击的按钮；`nav` 给出点击后跳转的目标列名。
+ * 产物是元素**节点**（数据）。
+ * @param text 按钮上的文字。
+ * @param opts 元素属性 + nav（点击跳转的目标列名）。
+ * @returns button 元素节点。
+ * @example
+ * buttonElement("开始游戏", { nav: "intro", y: "60%" });
+ */
+export function buttonElement(
+  text: string,
+  opts?: ElementOptions & { nav?: string },
+): ElementNode {
+  return { type: "button", text, ...opts };
+}
+
+/**
+ * 场景设置：背景 + 可选标题两个元素。
+ * 产物 = 元素**数组**（作者展开进 scene 列的 elements）。
+ * @param backgroundPath 背景图资源路径（铺满整屏）。
+ * @param title 场景标题文字（可省略，出现在画面上方居中）。
+ * @param opts 可选项：bgOpacity 背景不透明度、titleSize 标题字号、
+ *   titleColor 标题颜色。
+ * @returns 背景与标题元素节点数组（可省略标题）。
+ * @example
+ * export default scene("square", () => ({
+ *   type: "menu",
+ *   elements: [...sceneSetup("images/square.png", "城镇广场")],
+ *   columns: { ... },
+ * }));
+ */
+export function sceneSetup(
+  backgroundPath: string,
+  title?: string,
+  opts?: {
+    bgOpacity?: number;
+    titleSize?: number | string;
+    titleColor?: string;
+  },
+): ElementNode[] {
+  const bg: ElementNode = {
+    type: "background",
+    source: backgroundPath,
+    x: "0",
+    y: "0",
+    width: "100%",
+    height: "100%",
+    ...(opts?.bgOpacity === undefined ? {} : { opacity: opts.bgOpacity }),
+  };
+  const heading =
+    title === undefined
+      ? []
+      : [
+          {
+            type: "text",
+            text: title,
+            x: "5%",
+            y: "12%",
+            width: "90%",
+            halign: "center",
+            ...(opts?.titleSize === undefined ? {} : { size: opts.titleSize }),
+            ...(opts?.titleColor === undefined
+              ? {}
+              : { color: opts.titleColor }),
+          } satisfies ElementNode,
+        ];
+  return [bg, ...heading];
+}
+
+/**
+ * 列的 `type` 字段（game 缺省不写——与序列化口径一致）。
+ * @param type 列类型：menu（菜单列）或 ui（界面列）。
+ * @returns 带类型标记的对象，展开进列定义。
+ */
+export function sceneType(type: "menu" | "ui"): { type: "menu" | "ui" } {
+  return { type };
+}

package/src/script/words/elements.ts

@@ -0,0 +1,202 @@
+/**
+ * Script 词汇层 · **元素域**（show / hide / background / bg_switch / zindex / style /
+ * window / animate / animate_block / transition / shake / text_typewriter）。
+ * x/y = 数字（px）或 CSS 长度串（`"50%"`）——与元素系统契约一致。
+ * Options 派生自 schema（零漂移）；返回类型 = `CommandOf<op>` 判别联合成员。
+ */
+import type { CommandOf, ScriptValue } from "../../schema/index.ts";
+
+/** show 的可选项：x/y 位置（数字 px 或 CSS 长度串）、id/name 标识、background 背景位 */
+export type ShowOptions = Omit<CommandOf<"show">, "op" | "target">;
+
+/**
+ * 在画面上追加一个元素：`target` 是资源路径（落到元素的 source）。
+ * 故事立即继续，不等待。
+ *
+ * - `x` / `y` 定位（数字 px 或 `"50%"` 长度串）；`id` / `name` 给元素
+ *   起标识（之后 {@link hide} / {@link setZ} / {@link style} / {@link animate}
+ *   按它寻址）。
+ * - `background: true` 表示这是一张背景：先清掉旧背景再追加，固定在最底层。
+ *
+ * @param target 元素资源路径。
+ * @param opts 可选项，见 {@link ShowOptions}。
+ * @returns `show` 故事命令。
+ * @example
+ * show("images/npc_guide.png", { x: "30%", y: "40%", id: "guide" });
+ */
+export function show(target: string, opts?: ShowOptions): CommandOf<"show"> {
+  return { op: "show", target, ...opts };
+}
+
+/**
+ * 从画面移除元素：按 `id` / `name` / 资源路径匹配（含子元素）。
+ * 没找到就什么都不做（幂等，不报错）。立即生效、故事继续。
+ * @param target 要移除的元素（id、name 或资源路径）。
+ * @returns `hide` 故事命令。
+ * @example
+ * hide("guide");
+ */
+export function hide(target: string): CommandOf<"hide"> {
+  return { op: "hide", target };
+}
+
+/**
+ * 换背景：先清掉旧背景，再把新图追加为固定在最底层的背景元素。
+ * 立即生效、故事继续。
+ * @param resource 背景图资源路径。
+ * @returns `background` 故事命令。
+ * @example
+ * background("images/inn_night.png");
+ */
+export function background(resource: string): CommandOf<"background"> {
+  return { op: "background", resource };
+}
+
+/**
+ * 切换背景（与 {@link background} 同语义的另一形式）：先清旧背景再追加新背景。
+ * @param resource 背景图资源路径。
+ * @returns `bg_switch` 故事命令。
+ */
+export function bgSwitch(resource: string): CommandOf<"bg_switch"> {
+  return { op: "bg_switch", resource };
+}
+
+/**
+ * 调整元素层级（z 序）。目标元素未找到时报错停机。
+ * @param target 元素（id、name 或资源路径）。
+ * @param value 新层级值（数字越大越靠上）。
+ * @returns `zindex` 故事命令。
+ */
+export function setZ(target: string, value: number): CommandOf<"zindex"> {
+  return { op: "zindex", target, value };
+}
+
+/**
+ * 批量修改元素的展示属性（键限于元素系统支持的属性集，未知键报错停机）。
+ * @param target 元素（id、name 或资源路径）。
+ * @param props 属性名 → 新值的映射。
+ * @returns `style` 故事命令。
+ * @example
+ * style("guide", { opacity: 0.6 });
+ */
+export function style(
+  target: string,
+  props: Record<string, ScriptValue>,
+): CommandOf<"style"> {
+  return { op: "style", target, props: { ...props } };
+}
+
+/** 对话框显隐模式：auto 跟随对话状态（缺省）、show 显示、hide 隐藏 */
+export type DialogWindowMode = CommandOf<"window">["mode"];
+
+/**
+ * 控制对话框窗口的显隐：`"auto"` 跟随对话状态（默认行为）、
+ * `"show"` 强制显示、`"hide"` 强制隐藏。立即生效、故事继续。
+ * @param mode 显隐模式。
+ * @returns `window` 故事命令。
+ * @example
+ * dialogWindow("hide");   // 无对话演出时收起对话框
+ */
+export function dialogWindow(mode: DialogWindowMode): CommandOf<"window"> {
+  return { op: "window", mode };
+}
+
+/** animate 的可选项：duration 时长（秒，缺省 0.3）、easing 缓动名（缺省 EaseOutQuad） */
+export type AnimateOptions = Omit<
+  CommandOf<"animate">,
+  "op" | "target" | "property" | "value"
+>;
+
+/**
+ * 让元素的某个属性平滑过渡到目标值：起点取元素当前值（无值按 0），
+ * 结束值写回元素。故事**不等待**动画播完，直接继续执行下一句。
+ * @param target 元素（id、name 或资源路径）。
+ * @param property 要动的属性名（如 x / opacity）。
+ * @param value 目标值。
+ * @param opts 可选项：duration 秒数（缺省 0.3）、easing 缓动名。
+ * @returns `animate` 故事命令。
+ * @example
+ * animate("guide", "x", "60%", { duration: 0.5 });
+ */
+export function animate(
+  target: string,
+  property: string,
+  value: number,
+  opts?: AnimateOptions,
+): CommandOf<"animate"> {
+  return { op: "animate", target, property, value, ...opts };
+}
+
+export type AnimateBlockOptions = Omit<
+  CommandOf<"animate_block">,
+  "op" | "target"
+>;
+
+/**
+ * 让元素的多个属性**同时**平滑过渡（共用一个 duration，并行插值）。
+ * 故事不等待；需要先后顺序时改用多条 {@link animate}。
+ * @param target 元素（id、name 或资源路径）。
+ * @param opts 目标属性（x/y/opacity/rotation/scale，数字）+ duration 秒数
+ *   （缺省 0.3）+ easing 缓动名（缺省 EaseOutQuad）。
+ * @returns `animate_block` 故事命令。
+ * @example
+ * animateBlock("guide", { x: 300, opacity: 1, duration: 0.6 });
+ */
+export function animateBlock(
+  target: string,
+  opts?: AnimateBlockOptions,
+): CommandOf<"animate_block"> {
+  return { op: "animate_block", target, ...opts };
+}
+
+/**
+ * 全屏转场效果（如淡入淡出、黑屏）：`type` 给出转场名（必填），
+ * `duration` 控制时长（秒，缺省 0.5）。立即生效、故事继续。
+ * @param type 转场类型名。
+ * @param duration 转场时长（秒）。
+ * @returns `transition` 故事命令。
+ * @example
+ * transition("fade", 0.8);
+ */
+export function transition(
+  type: string,
+  duration?: number,
+): CommandOf<"transition"> {
+  return {
+    op: "transition",
+    type,
+    ...(duration === undefined ? {} : { duration }),
+  };
+}
+
+/** shake 的可选项：intensity 震动强度（缺省 8）、duration 时长（秒） */
+export type ShakeOptions = Omit<CommandOf<"shake">, "op">;
+
+/**
+ * 让画面震动一下（表现强调）。故事立即继续，不等待。
+ * @param opts 可选项：intensity 强度（缺省 8）、duration 时长（秒）。
+ * @returns `shake` 故事命令。
+ * @example
+ * shake({ intensity: 12 });
+ */
+export function shake(opts?: ShakeOptions): CommandOf<"shake"> {
+  return { op: "shake", ...opts };
+}
+
+/** text_typewriter 的可选项：enabled 开关、speed 打字速度（字符/秒，至少其一） */
+export type TypewriterOptions = Omit<CommandOf<"text_typewriter">, "op">;
+
+/**
+ * 设置全局打字机效果：`enabled` 开关、`speed` 打字速度（字符/秒）——
+ * 两者至少给一个。与玩家自己的偏好设置分离：玩家显式设置时以玩家为准。
+ * 立即生效、故事继续。
+ * @param opts 可选项：enabled 开关、speed 速度（字符/秒）。
+ * @returns `text_typewriter` 故事命令。
+ * @example
+ * textTypewriter({ enabled: true, speed: 30 });
+ */
+export function textTypewriter(
+  opts?: TypewriterOptions,
+): CommandOf<"text_typewriter"> {
+  return { op: "text_typewriter", ...opts };
+}

package/src/script/words/extension.ts

@@ -0,0 +1,25 @@
+/**
+ * Script 词汇层 · **扩展域**（extOp 通用出口）。
+ *
+ * 扩展 op = 宿主经 `EngineOptions.extensions` 注册的自定义 op。本出口只产
+ * 数据、不持白名单——持有就是重复定义真相。放行与否归两端把守：
+ * - **构建期**：清单 `extensions` 声明扩展模块 → `buildStories` 校验故事里的 op 名
+ *   是否被声明扩展提供（未被放行 = 构建期拦截，fail-early）；
+ * - **运行期**：opRegistry 注册制，未注册 = `unknown-op` fail-closed。
+ */
+import type { StoryCommand } from "@lingfan-engine/core";
+
+/**
+ * 扩展 op 通用构造：op 恒由首参决定（负载展开在前、op 在后——负载不得劫持 op 键）。
+ * @param op 扩展 op 名（须由宿主注册的扩展模块提供）。
+ * @param payload 扩展负载（原样透传，形状由扩展自定）。
+ * @returns 扩展故事命令。
+ * @example
+ * extOp("weather:set", { sky: "rain" });
+ */
+export function extOp(
+  op: string,
+  payload?: Record<string, unknown>,
+): StoryCommand {
+  return { ...payload, op };
+}