宏替换

当世界书条目里出现 {{ macro }} 结构时，服务端会先展开宏，再把结果发送给模型。

换句话说，模型看到的不是宏本身，而是宏展开后的文本结果。

先记住这三条规则

1. 宏是在发送前展开的

宏替换发生在服务端，先展开，后发送。

这意味着：

• 模型不会理解“宏语法”
• 模型只能看到最终展开后的文本
• 宏写错时，进模型的可能就是一段无效原文

2. 世界书宏和本地预设宏不互通

世界书里的宏、变量和本地预设中的同类能力，不会自动共享。

不要假设你在其他位置 setvar 过，世界书里就能直接 getvar 到。

3. 不支持的宏会原样保留

如果平台不支持某个宏，或无法识别它，它通常会作为原文保留下来，再一起发给模型。

WARNING

这类无效原文会直接干扰模型理解。

如果你是从第三方预设或 JSON 导入的内容，务必手动清理不兼容宏。

支持哪些宏？

类型	用途
user / char	读取当前用户昵称与角色名称
time / date / datetime	注入当前时间信息
roll	掷骰，生成随机数或总和
random	从候选项中随机选择一项
setvar / getvar	在同一本世界书内记录并引用变量

静态变量：user / char

作用：快速引用当前会话中的用户昵称与角色名称。

亲爱的 {{user}}，我是 {{char}}；你今天想体验怎样的冒险？

这类宏最适合做称呼替换、上下文指代和轻量个性化。

时间宏：time / date / datetime

作用：适合在条目里描述当前时间线，或生成“今日状态”“当前日期”一类提示。

当前日期：{{date}}
当前时间：{{time}}
最近一次情报更新时间：{{datetime}}

什么时候适合用？

• 日志类条目
• 每日任务类条目
• 实时对话类条目
• 需要当前时间感的广播、记录、公告

掷骰宏：roll

生成随机数或返回掷骰总和，适合跑团判定、攻击掉血、概率事件、资源分配等场景。

语法

{{roll NdM}}
{{ roll::NdM }}

示例

{{roll d10}} 生成 1-10 的随机数
{{roll 2d6}} 若结果 ≥ 9，请提示玩家谨慎前进

提示

• roll 适合做“判定”，不适合用来替代完整的剧情设计
• 单段文本最多 20 个 roll 宏
• 单宏掷骰不超过 30 次
• 单骰面数不超过 100000
• 累积掷骰总数不超过 150
• 超限时，该宏会被忽略

随机宏：random

从候选项里等概率选择一条，适合制造微变体、支线分支、环境反馈和随机事件。

语法

逗号分隔: {{random:选项1,选项2}}
双冒号分隔: {{random::选项1::选项2}}

示例

获得物品：{{random:破旧的航海图,断裂的徽章}}
通关奖励：{{random::屠龙刀::倚天剑::九阴真经}}
录音机传来 {{random::断断续续的军方广播::被干扰的求救信号::无法分辨内容的短波噪音}}。

变量宏：setvar / getvar

利用 setvar 作为全局“开关”或“状态机”，通过在世界书列表顶部放置不同的变量定义条目，来一键控制下方所有条目的逻辑走向。

适用场景：快速切换剧情分支、动态调整 AI 语气风格、或根据环境（如白天/黑夜）批量改变 NPC 的行为准则。

语法

{{ setvar::key::value }}
{{ getvar::key }}

示例

{{setvar::target::北境要塞}}
侦察目标：{{getvar::target}}
若 {{getvar::target}} 处于戒严状态，请提示玩家走密道

• setvar：写入变量并移除自身文本
• getvar：读取已存值；若不存在则移除文本

提示

1. 顶部定义状态：在列表最上方创建专门存放 setvar 的条目。
   • 例如：{{setvar::剧情阶段::避难所初期}}
2. 下游引用逻辑：下方所有条目均通过 getvar 获取该值。条目内容：
   • 如果 {{getvar::剧情阶段}} 是‘避难所初期’，请表现得绝望；如果是‘物资充沛’，则表现得贪婪。
3. 一键切换：当你想推进剧情时，无需修改每一个条目，只需关闭旧的变量条目、开启新的变量条目，整套逻辑便会瞬时同步。

使用顺序

getvar 只能读取已经写入的值，所以涉及变量时，一定要确保 setvar 写在前面。

完整示例：围城广播条目

下面这个例子演示了日期、随机文本和变量引用如何写在同一条里：

{{setvar::site::中央医院废墟}}
日期：{{date}}
侦查地点：{{getvar::site}}

今日广播摘要：
{{random::军方封锁了通往中央医院废墟的主路。::有人声称中央医院废墟的地下仓库还留有未清点药品。::昨夜有幸存者在中央医院废墟附近失踪。}}

模型最终看到的会是一段已经展开完成的普通文本，而不是这些宏本身。

最实用的原则

先把条目正文写成“就算不用宏也成立”的内容，再考虑宏是不是能让它更灵活。