EJS 编辑器变量定义指南

1. 简介

在 EJS 编辑器中，“变量”是构建动态故事世界的基石。无论是记录角色的好感度、追踪剧情的进度，还是管理世界的状态，都离不开对变量的精确定义。

为了方便不同习惯的用户，编辑器提供了两种功能强大且数据互通的变量编辑模式：

• YAML 文本编辑模式: 对于习惯代码和文本操作的用户，提供了高效、精确的编辑方式。
• 节点树可视化编辑模式: 对于偏爱图形化界面的用户，提供了直观、易于上手的操作体验。

这两种模式操作的是同一份数据，您可以随时根据需要进行切换，取长补短，高效地构建您的故事变量体系。

2. YAML 文本编辑模式

YAML 是一种易于人类阅读的数据序列化语言。在 EJS 编辑器中，您可以通过编写 YAML 文本来快速定义复杂的变量结构。

2.1. 基本语法

• 键值对: 使用 key: value 的格式定义一个变量。

名字: 顾青

• 层级结构: 使用缩进（建议使用两个空格）来表示变量之间的层级关系。这对于组织相关的变量至关重要。

角色:
  顾青:
    好感度: 0
    黑化度: 0

在上面的例子中，好感度 和 黑化度 都是 顾青 的子变量，而 顾青 是 角色 的子变量。在 EJS 模板中，您可以通过路径 角色.顾青.好感度 来访问它。

• 数据类型:
  • 数值: 年份: 799
  • 字符串: 主要武器: 木剑 (注意: 如果字符串中包含特殊字符，建议用引号包裹，例如 "一把生锈的铁剑")

2.2. 核心语法：带描述的变量

这是 EJS 编辑器中最具特色的语法，它允许您为每个变量附加一段描述或规则说明。

• 格式: 变量名: [默认值, "描述与规则"]

• 作用:

  • 默认值: 变量在故事开始时的初始值。
  • "描述与规则": 一段字符串，用于解释该变量的用途、取值范围、更新条件等。这段描述会作为提示信息显示在编辑器的界面中，对于理解和维护变量至关重要。

• 示例解析:

# 一个简单的数值变量，带有更新规则说明
年份: [799, 年份，数值，按照提示词更新]

# 一个带有详细取值范围和编辑限制的变量
好感度: [0, 有效值 -100 ~ 100，默认 0 无感，单次编辑最高 2 点]

2.3. 最佳实践

• 保持层级清晰: 合理地使用层级结构对变量进行分组（例如，按 世界、剧情、角色 等），使您的变量系统一目了然。
• 描述信息力求准确: 在描述中清晰地说明变量的类型（数值、字符串等）、有效范围和更新逻辑，这将极大地帮助您和他人理解剧情逻辑。

3. 节点树可视化编辑模式

节点树编辑器提供了一个图形化界面，让您可以像操作文件目录一样直观地管理变量。

3.1. 界面与操作

• 添加节点:
  • 点击“添加根节点”按钮来创建一个顶层变量。
  • 点击每个节点右侧的“+”号按钮，可以为该节点添加一个子节点。
• 编辑节点:
  • 键 (Key): 节点的名称，对应 YAML 中的 key。
  • 值 (Value): 节点的值，对应 [默认值, ...] 中的 默认值。只有叶子节点（没有子节点的节点）才能设置值。
  • 描述 (Description): 节点的描述，对应 [..., "描述与规则"] 中的 "描述与规则"。
• 删除节点: 点击节点右侧的垃圾桶图标按钮即可删除该节点及其所有子节点。

请注意！！！

不要在创建节点后，不对其添加任何内容，否则节点树模式将无法识别该节点。yml 解析也讲失败

3.2. 注意事项

• 数据同步: 节点树中的任何修改（添加、删除、编辑）都会被实时同步到 YAML 编辑器的文本中。同样，在 YAML 编辑器中点击“解析变量”也会立即更新节点树的结构。
• 操作便捷性: 节点树模式非常适合快速构建和调整变量的层级结构，例如拖动排序（未来可能支持）或快速增删。
• 文本编辑的优势: 对于编写和修改复杂的“描述与规则”文本，直接在 YAML 模式下进行大段文本编辑通常比在节点树的小输入框中更高效。

4. 模式对比与选择建议

特性	YAML 文本模式	节点树可视化模式
优点	批量编辑快、复制/粘贴方便、适合处理长描述、对程序员友好	直观、易于理解层级、操作简单、不易出错
缺点	语法要求严格、层级深时不易阅读	难以进行批量修改、编辑长描述不便
数据同步	点击“解析变量”后更新节点树	实时自动更新 YAML 文本

选择建议:

• 初次构建/快速原型: 可以使用节点树模式快速搭建出变量的整体框架。
• 批量添加/修改: 当您需要从外部文档复制大量变量，或者对多个变量进行统一修改时，YAML 模式的文本编辑能力会更胜一筹。
• 完善描述信息: 在框架搭好后，切换到 YAML 模式来为每个变量精心撰写详细的描述和规则。
• 日常维护: 两种模式可以随时切换，根据当前最方便的方式进行操作。