# 什么时候该用它

它很适合做这些内容：

• 角色状态摘要
• 战斗面板说明
• 对象详情文字
• 表格内容汇总
• AI 提示词片段

# 最重要的规则

• 只能做读取
• 必须返回字符串
• 写了脚本后，这条动态字符串就不再适合作为“允许修改”的写入目标
• 如果返回内容会直接展示给玩家，优先用 tools.tr(...) 包起来，方便项目多语言

# 1. 最简单的写法

return `生命：${player.getPro("生命")}`;

这就是最常见的动态字符串脚本写法。

如果你准备支持多语言，更推荐这样写：

return tools.tr("生命：{value}", {
  value: player.getPro("生命")
});

# 2. 多行文字

const hp = player.getPro("生命");
const maxHp = player.getPro("生命上限");
const stamina = player.getPro("体力");

return `生命：${hp}/${maxHp}<br>体力：${stamina}`;

如果你想显示成多行，可以直接把返回内容拼出来。

# 3. 按条件返回不同文字

let hp = player.getPro("生命");
let maxHp = player.getPro("生命上限");

if (maxHp <= 0) return "状态：未知";
if (hp / maxHp < 0.3) return "状态：濒危";
if (hp / maxHp < 0.7) return "状态：受伤";
return "状态：健康";

这类脚本很适合状态提示。

如果你要做多语言，可以改成：

if (maxHp <= 0) return tools.tr("状态：未知");
if (hp / maxHp < 0.3) return tools.tr("状态：濒危");
if (hp / maxHp < 0.7) return tools.tr("状态：受伤");
return tools.tr("状态：健康");

# 4. 结合表格和对象

# 读表格

const table = player.getTable("剧情日志");
if (!table) return "暂无记录";

return String(table.getData("最近", "摘要") || "暂无记录");

# 统计对象

const npcs = objects.getObjects("NPC");
const lines = npcs.map((npc) => `${npc.getName()}：好感 ${npc.getPro("好感度")}`);

return lines.join("<br>");

# 5. 在对象上下文里显示不同内容

如果这个动态字符串是在对象控件里显示的，通常可以直接拿当前对象：

let obj = tools.kwargs.object;
if (!obj) return "当前没有对象";

return [
  `姓名：${obj.getName()}`,
  `好感：${obj.getPro("好感度")}`,
  `状态：${obj.getString("对象状态")}`
].join("<br>");

这样同一条动态字符串，就可以给不同对象显示不同内容。

# 6. 和“允许修改”的区别

动态字符串常见有两种用法：

用法	适合什么
脚本返回	每次显示时重新计算
允许修改	某一刻写进去，然后保存下来

如果你要做的是：

• 玩家改名
• AI 写回一段内容
• 脚本保存一段留言

更常见的是用 允许修改。

如果你要做的是：

• 根据当前属性实时显示
• 根据对象状态动态展示
• 根据表格内容动态汇总

更常见的是用脚本。

# 7. 这类内容通常不写在这里

下面这些内容更常写在事件、普通脚本或别的联动位置：

• 改属性
• 新建对象
• 删除对象
• 场景跳转
• 弹窗
• 发 AI 请求

例如：

player.addPro("金币", 100);
return "奖励已发放";

动态字符串脚本主要负责“显示什么”。

# 8. 常见错误

# 忘了 return

player.getPro("生命");

# 返回了数字

return 123;

# 返回了布尔值

return true;

更常见的写法是直接返回一段字符串。

# 使用时要注意的几件事

• 必须返回字符串。
• 更适合做说明和展示。
• 对象控件里可以直接用 tools.kwargs.object。
• 如果这条字符串还要让别的流程写入，通常就不会再给它配脚本。

# 下一步

如果你接下来要控制场景是否开放，可以继续看 场景解锁脚本。