---
title: "成就系统"
description: "玩家达到里程碑时弹出一张卡片，每个成就只记一次，再用一页显示已拿到和还锁着的成就，不用写代码。"
---

<div v-pre>

# 成就系统

> 玩家达到某个里程碑的时候（金币超过 100、打赢 5 场以上、找到隐藏区域），弹出一张小卡片，写着成就名和一句话。每个成就只会得到一次，得到后收进一个列表，玩家界面里有一页列出哪些已经拿到、哪些还锁着。整套都不用写代码。

---

## 你要做的东西

- **达成的那一刻弹出来**：一张小卡片，有标题、一句话，图片可加可不加
- **自动检测**：行为盯着数值和对话，玩家什么都不用做
- **每个成就只会得到一次**：已经在列表里的时刻不会再弹第二次
- **成就页**：所有成就列在一起，解锁的显示说明，没解锁的显示提示
- **可选**：重开一局也还在的成就

### 怎么运作

```
The player's gold goes from 95 to 101
  → The behavior "Big Spender" is watching Gold (Variable crosses threshold, Rises above 100)
  → Its effect "Unlock a moment" pops up the card "Big Spender"
  → The title "Big Spender" is added to the list variable Achievements
  → The achievements page shows Big Spender as unlocked
```

数值是 AI 跟着剧情在改，但成就有没有得到是引擎说了算，所以不会漏掉，也不会发两次。

---

## 一步一步来

### 第 1 步：建变量

点卡底下 **还可以加** 里的 **＋ 变量**，下面每个变量建一次。

#### Gold

| 字段 | 值 |
|-------|-------|
| 名称 | Gold |
| 类型 | 数值 |
| 初始值 | `0` |
| 范围 | `0` 到（不填） |
| 行为规则 | `The player's gold. Goes up when they're paid, loot something or sell something; goes down when they spend.` |

#### Battles won

| 字段 | 值 |
|-------|-------|
| 名称 | Battles won |
| 类型 | 数值 |
| 初始值 | `0` |
| 行为规则 | `How many fights the player has won. Add 1 each time the player clearly wins a fight.` |

#### Achievements

| 字段 | 值 |
|-------|-------|
| 名称 | Achievements |
| 类型 | 列表/表格 |
| 初始值 | `[]` |

展开 **AI 怎么用它**，把 **AI 权限** 设成 **仅引擎（对 AI 隐藏）**。这个列表只由行为来写，AI 读了也没用。

::: tip 重开一局也还在的成就
在同一栏里勾上 **跨存档保留（每个玩家自己的）**。这样玩家重开一局时，列表从他已经解锁的成就开始，这些成就也不会再弹一次。CG 图鉴、「已达成结局」收集都是这么做的。
:::

---

### 第 2 步：每个成就建一条行为

点 **还可以加** 里的 **＋ 行为**。

#### 行为 1：Big Spender

| 部分 | 设置 |
|------|---------|
| 什么时候触发 | **变量越过阈值**：Gold，**上升到以上**，`100` |
| 效果 | **解锁一个时刻** |

把时刻填好：

| 字段 | 值 |
|-------|-------|
| 标题 | `Big Spender` |
| 消息 | `You've saved more than 100 gold.` |
| 图片（链接） | 可选：一个 `https://` 链接，或者 **面板 → 素材** 里的素材 |
| 收进哪个列表 | Achievements |

「变量越过阈值」只在数值从 100 或以下变成 100 以上的那一下触发。金币从 101 继续涨到 150，不会再触发。金币掉回 100 以下再涨上来，会再触发一次，但这个时刻已经在 Achievements 里了，所以什么都不会弹。

#### 行为 2：Seasoned Fighter

| 部分 | 设置 |
|------|---------|
| 什么时候触发 | **变量越过阈值**：Battles won，**上升到以上**，`5` |
| 效果 | **解锁一个时刻**：标题 `Seasoned Fighter`，消息 `You've won more than 5 battles.`，收进 Achievements |

#### 行为 3：Trailblazer（关键词）

这个盯的是对话，不是数值。一条行为只有一个触发，所以想同时抓玩家说的和 AI 说的，就建两条行为。

**3a**

| 部分 | 设置 |
|------|---------|
| 什么时候触发 | **玩家说出关键词**：`explore, search the cave` |
| 效果 | **解锁一个时刻**：标题 `Trailblazer`，消息 `You went looking for what's hidden.`，收进 Achievements |

**3b**

| 部分 | 设置 |
|------|---------|
| 什么时候触发 | **AI 说出关键词**：`hidden passage, secret room` |
| 效果 | 和 3a 一样的 **解锁一个时刻**，标题也一样 |

关键词用逗号隔开，出现任意一个就算。两条行为收进同一个列表、用同一个标题，所以谁先触发谁发出成就，另一条发现列表里已经有了，就不出声。不用另外加条件。

::: info 用时刻还是用通知？
**显示通知**（样式选 **成功**）也能弹一句「成就解锁」，但它什么都不记：你得每个成就配一个开关变量，加一个条件防止触发两次，再把 **最大触发次数** 设成 1。**解锁一个时刻** 把这些记账的事都替你做了。
:::

---

### 第 3 步：做成就页

点顶栏中间的 **玩家界面**。用 **新建一页** 加一页（选 **空白页** 就行），起个标题，再从 **加一个部件** 里加一个 **列表** 部件：

1. **内容从哪来** 选 **自己写几行**，每个成就加一行：`Big Spender`、`Seasoned Fighter`、`Trailblazer`，每行配一句话
2. 打开 **每一行画成一张卡**
3. 在 **锁住直到** 里打开 **没解锁的行显示成锁住**。**看哪个变量** 选 Achievements，**对照这一行的哪个字段** 保持 `title` 不动。列表里有这一行的标题，这一行就算解锁，**解锁一个时刻** 放进去的正好就是标题
4. 在 **锁住时显示** 里写解锁之前玩家看到的提示，比如「先攒点钱」
5. 加一个 **按钮**，步骤选 **跳到页面**，跳回对话页，免得这一页走不出去（不然页面栏会提醒 **没出口**）
6. 在对话页上加一个写着「成就」的 **按钮**，步骤是 **跳到页面** → 你刚建的那一页

如果你的收集品是 AI 在剧情里发的，而不是行为发的，就改从 **收集图鉴** 模板开始：「能找的东西先是灰的，故事里找到一样亮一样。」它自带列表变量、弹窗，还有告诉 AI 什么时候往里加的行为规则。

把顶上的 **编辑** 关掉，就能像玩家一样点着试试这一页。

::: tip 数一数
加一个数值变量叫「Achievements unlocked」，**公式（自动算）** 填 `len(Achievements)`。在页面上放一个文字部件写 `{Achievements unlocked} / 3`，数字会自己更新。
:::

---

### 第 4 步：试玩

点顶栏的 **试玩**。

1. 点 **成就**：三个都锁着，显示各自的提示
2. 一直玩到金币超过 100。「Big Spender」卡片弹出来，成就页上显示已解锁
3. 打赢六场。Battles won 从 5 变成 6 的时候，「Seasoned Fighter」弹出来
4. 发一句「I want to explore this cave」。「Trailblazer」弹出来。之后 AI 提到「hidden passage」，不会再弹

试玩右边的 **这回合** 能看到哪些行为触发了，没触发的是为什么。

**如果出了问题：**

| 现象 | 可能的原因 | 怎么改 |
|---------|-------------|-----|
| 金币过了 100 但什么都没弹 | 金币根本没越过这条线：一开始就在 100 以上 | 阈值只在越过的那一下触发。检查 **初始值** 是不是等于或低于阈值 |
| 时刻弹了，但成就页没变 | **收进哪个列表** 没填，或者页面看的是另一个变量 | 两边都选 Achievements |
| 已经弹过了，成就页还显示锁着 | 这一行的标题和时刻的标题不完全一样 | 改成一模一样，大小写也要一样 |
| 一个成就弹了两次 | 两条行为用了不同的标题或不同的列表 | 同一个标题、同一个列表 |

---

## 写代码的做法：聊天下方的成就面板

如果想自己画这个面板，比如放在最后一条消息下面，而不是单独一页，就在界面代码里写。上面的行为一点都不用改，代码只是读 Achievements 这个列表。

**面板 → 界面代码** → 打开 `index.tsx`，把默认的 `return <Chat />` 换掉：

```tsx
export default function MyWorld() {
  const api = useYumina();
  const msgs = api.messages || [];

  // Titles must match the moment titles in your behaviors
  const achievements = [
    { title: "Big Spender", desc: "Save more than 100 gold", icon: "💰" },
    { title: "Seasoned Fighter", desc: "Win more than 5 battles", icon: "⚔️" },
    { title: "Trailblazer", desc: "Find a hidden area or secret", icon: "🗺️" },
  ];

  // The list the moments are collected into, read by its name
  const unlockedList = Array.isArray(api.variables["Achievements"])
    ? api.variables["Achievements"].map(String)
    : [];
  const isUnlocked = (a) => unlockedList.includes(a.title);
  const unlockedCount = achievements.filter(isUnlocked).length;

  return (
    <Chat renderBubble={(msg) => {
      const isLastMsg = msg.messageIndex === msgs.length - 1;
      return (
        <div>
          <div
            style={{ color: "#e2e8f0", lineHeight: 1.7 }}
            dangerouslySetInnerHTML={{ __html: msg.contentHtml }}
          />

          {isLastMsg && (
            <div style={{
              marginTop: "16px",
              padding: "12px 16px",
              background: "linear-gradient(135deg, #1c1917, #292524)",
              border: "1px solid #44403c",
              borderRadius: "10px",
            }}>
              <div style={{
                display: "flex",
                justifyContent: "space-between",
                alignItems: "center",
                marginBottom: "10px",
              }}>
                <span style={{ fontSize: "13px", fontWeight: "bold", color: "#fbbf24" }}>
                  🏆 Achievements
                </span>
                <span style={{ fontSize: "12px", color: "#a8a29e" }}>
                  {unlockedCount} / {achievements.length}
                </span>
              </div>

              <div style={{ display: "flex", flexDirection: "column", gap: "6px" }}>
                {achievements.map((a) => {
                  const unlocked = isUnlocked(a);
                  return (
                    <div
                      key={a.title}
                      style={{
                        display: "flex",
                        alignItems: "center",
                        gap: "10px",
                        padding: "6px 8px",
                        borderRadius: "6px",
                        background: unlocked
                          ? "rgba(251, 191, 36, 0.08)"
                          : "rgba(120, 113, 108, 0.08)",
                      }}
                    >
                      <span style={{ fontSize: "18px", opacity: unlocked ? 1 : 0.3 }}>
                        {unlocked ? a.icon : "🔒"}
                      </span>
                      <div style={{ flex: 1, minWidth: 0 }}>
                        <div style={{
                          fontSize: "13px",
                          fontWeight: "600",
                          color: unlocked ? "#fbbf24" : "#78716c",
                        }}>
                          {a.title}
                        </div>
                        <div style={{
                          fontSize: "11px",
                          color: unlocked ? "#a8a29e" : "#57534e",
                          marginTop: "1px",
                        }}>
                          {a.desc}
                        </div>
                      </div>
                      {unlocked && (
                        <span style={{ fontSize: "11px", color: "#fbbf24" }}>✓ Unlocked</span>
                      )}
                    </div>
                  );
                })}
              </div>
            </div>
          )}
        </div>
      );
    }} />
  );
}
```

**代码做了什么：**

- `<Chat renderBubble={...} />` 保留平台自带的消息列表、输入框和滚动，你只负责画每个气泡
- `msg.messageIndex === msgs.length - 1` 让面板只出现在最后一条消息下面
- `msg.contentHtml` 是已经渲染成 HTML 的消息
- `api.variables["Achievements"]` 按变量名读这个列表。名字里有空格或大写字母，用方括号的写法都能读
- 标题在列表里，这个成就就算解锁，和时刻用的是同一条规则

**面板 → 界面代码** 里文件旁边的状态应该是绿色的 **正常**。如果显示 **错误**，下面的提示会告诉你是哪一行。

::: tip 不想自己写代码？
点画布右上角的 **创作助手**，说说你想要什么样的面板，它会替你写界面代码。
:::

---

## `Variable crosses threshold` 和 `Variable changes`

两个触发都是盯变量的，但触发的时机不一样。

**变量越过阈值** 在数值越过一条线的那一下触发：

```
gold: 80 → 95 → 101   ← fires on 95→101 (crossed above 100)
gold: 101 → 150 → 200  ← doesn't fire (already above)
gold: 200 → 50 → 120   ← fires on 50→120 (crossed above 100 again)
```

适合里程碑、警告（「生命掉到 20 以下」）和死亡判定。

**变量变化** 在你选的那个变量每次变化时都触发，不管值是多少：

```
gold: 80 → 95   ← fires
gold: 95 → 101  ← fires
gold: 101 → 150 ← fires
```

它得配一个 **如果……** 条件才有用（「只在 Gold ≥ 100 时」），而且每变一次都要重新检查一遍。成就关心的是越过的那一下，所以用 **变量越过阈值** 最顺手。

---

## 更多成就

每多一个成就，就是一条行为，加上成就页上的一行：

| 成就 | 什么时候触发 |
|-------------|---------------|
| 话痨 | **每 N 回合**：`50`，**最大触发次数** 填 `1` |
| 囤积狂 | **变量越过阈值**：Gold 上升到 `500` 以上 |
| 社交达人 | **AI 说出关键词**：`trusts you, become friends` |
| 死里逃生 | **变量越过阈值**：Health 下降到 `10` 以下时，把开关「Was nearly dead」打开；第二条行为在 Health 上升到 `50` 以上、**如果……** Was nearly dead 为真时，解锁这个时刻 |

---

## 速查

| 你想要 | 怎么做 |
|---------------|-------------|
| 数值达标时解锁 | **什么时候触发**：**变量越过阈值**，**上升到以上** |
| 说了某句话时解锁 | **玩家说出关键词** 或 **AI 说出关键词** |
| 弹一张卡片并记住它 | 效果：**解锁一个时刻**，填好 **收进哪个列表** |
| 确保只解锁一次 | 同一个标题、同一个列表。列表里已经有的标题，时刻不会再触发 |
| 重开一局成就还在 | 在列表变量上勾 **跨存档保留（每个玩家自己的）** |
| 显示已拿到和还锁着的成就 | **玩家界面** → **收集图鉴** 模板，或者一个打开了 **锁住直到** 的列表部件 |
| 数一数 | 一个数值变量，公式填 `len(Achievements)` |
| 自己画的面板 | 读这个列表的界面代码（见上面写代码的做法） |

---

::: tip 这是食谱 #13
成就可以和别的食谱搭着用：从战斗系统里数胜场，盯着[商店](./shop.md)里的金币，或者[任务](./quest-tracker.md)完成时发一个。行为之间互不干扰，加了成就也不会改变卡里其它部分怎么运作。
:::

</div>
