---
title: "用界面做场景跳转与设定切换"
description: "让玩家用一个按钮在写好的开场白之间跳转，再在输入框里打一条规则，改掉设定对 AI 说的话。"
---

<div v-pre>

# 用界面做场景跳转与设定切换

> 点一个按钮 → 跳到另一段写好的开场白。在输入框里打字 → 改掉一条设定对 AI 说的话。两种做法这里都会讲，先讲不写代码的，再讲界面代码的。

---

## 第一部分：用按钮切换开场白

### 你要做的东西

一张有好几段写好的开场白的卡。玩家先看到「主开场」，下面有几个能点的按钮。点其中一个，聊天里的第一条消息马上换成另一段写好的开场白。不用 AI 生成，就是你写好的那段字。

### 怎么运作

一张卡可以有好几个开场白。玩家开新的一局时，所有开场白都会打包成第一条消息上的 **滑动切换**（左右切换）。每个开场白还带着自己的一套变量初始值。

`api.switchGreeting(index)` 直接跳到对应编号的开场白；玩家界面里按钮的 **切换开场白** 这一步做的是同一件事，不用写代码。

```
Player clicks "Enter the Dark Cave"
  → the button switches to opening #2 (index starts at 0, so 1 = the second one)
  → variables reset to that opening's starting values
  → Player sees your pre-written dark cave opening
```

### 不写代码的做法

1. 写好开场白（下面第 1 步）
2. 在[玩家界面](/zh/creator/player-view)里点 **模板**，加上 **选开局**：每个开场白一张卡片，玩家点哪张，故事就从哪张开始。也可以自己在页面上放按钮，每个按钮加一步 **切换开场白**
3. 想让每条路线有自己的设定，照下面第 2、3 步做，这两步也不用写代码

选完路线还想做点别的（放音乐、弹提示），就在 **切换开场白** 这一步 **后面** 加一步 **让一条行为生效**。切换会把变量重置成那个开场白的初始值，所以放在切换前面的改动都会丢。

### 一步一步来

#### 第 1 步：写开场白

在画布上点开场白那一行，写第一段。要再加一段，点开场白块右上角的 **＋**。

**第一个开场白（主开场，让玩家选路线）：**

这是玩家打开这一局最先看到的。描述场景，引导玩家做选择：

```
*You wake up in a mysterious forest. Morning mist swirls between ancient trees.*

Two paths diverge before you:

**To the left** — a narrow trail into darkness. Cold air and distant echoes.

**To the right** — a sun-dappled path with wildflowers and birdsong.

Which way will you go?
```

> 开场白是 **你写好的固定文字**，不是 AI 生成的，玩家看到的每个字都由你决定。

**第二个开场白（黑暗洞穴）：**

```
*You step onto the left path. The canopy thickens overhead, swallowing the light. Within minutes, the trail narrows to a crack in a rock face — the entrance to a cave.*

*Cold air rushes out, carrying the smell of damp stone and something metallic. Faint blue-green light flickers deep inside — bioluminescent fungi clinging to the walls.*

*You take a breath and step in. Behind you, the last sliver of daylight shrinks to a pale line, then vanishes.*

You are alone in the dark.
```

> 这段只有在玩家点了「Enter the Dark Cave」之后才会出现。在那之前，玩家看到的是第一个开场白。

**第三个开场白（阳光草原）：**

```
*You choose the right path. The trees thin out, and warm sunlight floods through the canopy. Within minutes, the forest opens into a vast meadow stretching to the horizon.*

*Wildflowers in every color sway gently in the breeze. A stream glitters in the distance. Somewhere nearby, a bird sings a melody you've never heard before.*

*You feel the tension in your shoulders melt away. Whatever this place is, it feels safe.*

Welcome to the Everbloom Meadow.
```

::: info 开场白的顺序就是 index
开场白的顺序就是 `switchGreeting()` 的 `index`，从 0 开始数：第一个开场白是 index 0（默认显示），第二个是 index 1，第三个是 index 2。玩家界面里 **切换开场白** 这一步把它们列成开场白 1、2、3。
:::

---

#### 第 2 步：建一个路线变量，每个开场白给它一个值

用一个变量记下玩家走的是哪条路线。它有两个用处：
- **选好路线后把按钮藏起来**（代码检查它还是不是 `"none"`）
- **给每条路线发它自己的设定**（第 3 步让设定按它来发）

在画布上点 **还可以加** 里的 **＋ 变量**：

| 字段 | 填什么 | 为什么 |
|-------|-----------------|-----|
| 变量名称 | `current_route` | 代码和条件都是按这个名字找变量 |
| 类型 | 文字 | 值是文字（`"none"`、`"dark"`、`"light"`） |
| 初始值 | `none` | 意思是「还没选」 |
| AI 权限（在 **AI 怎么用它** 里） | AI 只读 | 只由开场白来设；AI 看得到，但改不了 |

再给每条路线一个自己的初始值：把第二个开场白拖到 `current_route` 上，值设成 `dark`，再把第三个开场白拖上去，值设成 `light`。玩家切换到哪个开场白，`current_route` 就变成那个开场白给的值。

---

#### 第 3 步：（可选）给每条路线自己的设定

想让选完路线以后 AI 的回复用不同的世界设定，就做这一步。只想换开场文字的话，跳过就行。

加两条设定，都做成 **条件设定**：把 `current_route` 拖到设定上，再点那根线设条件（洞穴那条是 `current_route` 等于 `dark`，草原那条是 `light`）。条件设定只在条件成立的时候发给 AI。

**黑暗洞穴的设定**（条件：`current_route` 等于 `dark`）：

```
[World Setting: Shadowmaw Cave]
The player is exploring Shadowmaw Cave. Key details:
- Ancient dwarven ruins, abandoned for centuries
- Bioluminescent fungi provide faint blue-green light
- Strange creatures lurk in the deeper tunnels
- Temperature drops the further in you go

Maintain a tense horror-survival atmosphere. Describe echoing sounds, flickering shadows, water dripping, and the oppressive weight of stone overhead.
```

**阳光草原的设定**（条件：`current_route` 等于 `light`）：写草原的环境和氛围。

玩家选之前，`current_route` 是 `none`，两条设定都不会发。

如果一条路线有很多自己的设定、变量和 AI，就把它放进一个[情境](/zh/creator/modules)，再把开场白拖到这个情境上：这样只有从那个开场白开始的那一局才有这个情境。

---

#### 第 4 步：用界面代码加路线按钮

想把按钮放进第一条聊天气泡里，就用界面代码写。打开 **面板 → 界面代码** → `index.tsx`，把里面的内容换成：

```tsx
export default function MyWorld() {
  const api = useYumina();
  const hasChosen = api.variables.current_route !== "none";

  return (
    <Chat renderBubble={(msg) => (
      <div>
        {/* Render the message text normally */}
        <div
          style={{ color: "#e2e8f0", lineHeight: 1.7 }}
          dangerouslySetInnerHTML={{ __html: msg.contentHtml }}
        />

        {/* Route selection buttons */}
        {/* msg.messageIndex === 0 means only show on the first message */}
        {/* !hasChosen means hide once a choice has been made */}
        {msg.messageIndex === 0 && !hasChosen && (
          <div style={{
            display: "flex",
            gap: "12px",
            marginTop: "16px",
          }}>
            <button
              onClick={() => api.switchGreeting(1)}   // Switch to the 2nd opening
              style={{
                flex: 1,
                padding: "16px",
                background: "linear-gradient(135deg, #1e1b4b, #312e81)",
                border: "1px solid #4338ca",
                borderRadius: "12px",
                color: "#c7d2fe",
                fontSize: "15px",
                fontWeight: "bold",
                cursor: "pointer",
              }}
            >
              Enter the Dark Cave
            </button>

            <button
              onClick={() => api.switchGreeting(2)}   // Switch to the 3rd opening
              style={{
                flex: 1,
                padding: "16px",
                background: "linear-gradient(135deg, #365314, #4d7c0f)",
                border: "1px solid #65a30d",
                borderRadius: "12px",
                color: "#ecfccb",
                fontSize: "15px",
                fontWeight: "bold",
                cursor: "pointer",
              }}
            >
              Walk to the Sunlit Meadow
            </button>
          </div>
        )}
      </div>
    )} />
  );
}
```

**逐行说明：**

- `<Chat renderBubble={...} />`：用平台默认的聊天界面（输入框、滑动切换、存档点都是自带的），你只接管气泡怎么画
- `const api = useYumina()`：拿到 Yumina 的 API，可以读变量、写变量、让行为生效、切换开场白
- `api.variables.current_route`：读当前路线变量的值
- `hasChosen`：不是 `"none"` 就说明玩家已经选过了
- `msg.contentHtml`：renderBubble 传进来的、已经渲染好的 HTML（Markdown 已经处理过）
- `msg.messageIndex === 0`：只在第一条消息上显示按钮，不是每条都显示
- `api.switchGreeting(1)`：把第一条消息切换到 index 1（第二个开场白）。变量会重置成那个开场白的初始值，所以 `current_route` 变成 `"dark"`，按钮消失，洞穴设定开始发给 AI

**点一下想多做几件事。** 如果按钮还要跑一条行为（放音乐、弹提示、改别的数值），就先切换，等切换完成再跑行为：

```tsx
onClick={async () => {
  await api.switchGreeting(1);                 // resets variables to opening 2's values
  await api.executeActionAndWait("choose-dark"); // a behavior triggered by The player presses a button → Button "choose-dark"
}}
```

在切换 **之前** 调 `setVariable` 或者跑行为是留不住的：切换会把那个开场白的初始值放回去。

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

---

#### 第 5 步：保存并测试

1. 点顶栏的 **保存**
2. 点 **试玩** 开始试玩
3. 你会看到主开场，下面有两个按钮
4. 点「Enter the Dark Cave」。第一条消息变成你写的洞穴开场，按钮消失
5. 给 AI 发几条消息。如果做了第 3 步，AI 的回复会照着洞穴的设定来
6. 想试另一条路线，重新开一次试玩，点另一个按钮

**出问题时：**

| 现象 | 可能的原因 | 怎么改 |
|---------|--------------|-----|
| 看不到按钮 | 界面代码没保存，或者有语法错误 | **面板 → 界面代码** 应该显示 **正常**，不是 **错误** |
| 按钮点了，开场白没换 | 开场白不够 | 确认这张卡有 3 个开场白 |
| 开场白换了，按钮还在 | 这个开场白没给 `current_route` 设初始值 | 把这个开场白拖到 `current_route` 上，设好它的值 |
| 设定没切换 | 设定的条件对不上 | 点 `current_route` 和设定之间的那根线，检查值（`dark` / `light`） |
| 点按钮时设的值不见了 | 它是在切换之前设的 | 先 await `switchGreeting`，再改值 |

---

## 第二部分：玩家输入改写设定内容

### 你要做的东西

一个输入框，玩家在里面打字（一条自定义规则、一个角色名、一句剧情指示）。打的字存进一个变量，一条设定里引用了这个变量，于是 AI 下一次读到的内容就变了。

### 怎么运作

设定支持 **宏**。在设定内容里写 `{{variable_name}}`，引擎每次给 AI 拼提示词时，都会把它换成这个变量当前的值。

比如：

- 你在设定里写：`Special rule: {{custom_rule}}`
- 变量 `custom_rule` 的值是 `"All magic is allowed"`
- AI 收到的提示词里，这一行就变成：`Special rule: All magic is allowed`

替换发生在每次拼提示词的时候，也就是玩家发下一条消息、AI 准备回复的时候。

完整的顺序：

```
1. Entry content says: "Special rule: {{custom_rule}}"
2. Variable custom_rule's current value = "All magic is allowed"
3. Player sends message → engine builds prompt → replaces {{custom_rule}} with variable value
   → AI receives "Special rule: All magic is allowed" → AI replies accordingly

4. Player types "Magic is forbidden" in the input box, clicks "Apply"
5. The variable custom_rule is set to "Magic is forbidden"
   → variable value updates immediately
6. The AI doesn't see it yet: the prompt hasn't been rebuilt.

7. Player sends another message → engine rebuilds prompt → this time uses the new value
   → AI receives "Special rule: Magic is forbidden" → AI starts obeying the new rule
```

变量是马上变的，AI 要到下一条消息才看到变化。

### 不写代码的做法

在[玩家界面](/zh/creator/player-view)里加一个 **填写项** 部件（**一行字** 或 **一段话**），**写进哪个变量** 选 `custom_rule`。玩家一边打字，变量一边更新。再放一个 **文字** 部件，用 **插入变量的值…** 显示当前的规则。然后做下面的第 1、2 步；第 3 步只在想把输入框放进聊天里时才需要。

### 一步一步来

#### 第 1 步：建一个文字变量

这个变量存玩家打的字。在画布上点 **还可以加** 里的 **＋ 变量**：

| 字段 | 填什么 | 为什么 |
|-------|-----------------|-----|
| 变量名称 | `custom_rule` | 设定里的 `{{custom_rule}}` 宏就是按这个名字找的 |
| 类型 | 文字 | 内容是玩家随便打的字 |
| 初始值 | *（留空，或者填一个默认值，比如 `All magic is allowed`）* | 空 = 新的一局没有规则；不空 = 一开始就有一条规则 |
| AI 权限（在 **AI 怎么用它** 里） | AI 只读 | 由玩家来设；AI 读得到，但改不了 |

---

#### 第 2 步：在设定里用宏

建一条用 `{{custom_rule}}` 占位的设定。在画布上的 **角色和世界** 块里（每回合都发），点块右上角的 **＋**：

| 字段 | 填什么 | 为什么 |
|-------|-----------------|-----|
| 名称 | 世界规则 | 给你自己看的 |
| 什么时候发给 AI | 角色和世界（每回合） | 规则对每一条回复都有效 |

内容：

```
[World Rules]
The following rule is in effect for this world and must be respected at all times:
{{custom_rule}}
```

> 引擎每次拼提示词时，都会在设定里找 `{{...}}`。花括号里的名字和某个变量对得上，就换成这个变量现在的值。
>
> 变量是空的，那一行就是空的。AI 看到「The following rule is in effect...」后面什么都没有。值是「Magic is forbidden」的话，AI 看到的就是「The following rule is in effect... Magic is forbidden」。

---

#### 第 3 步：用界面代码加输入框

这一步在聊天里最后一条消息下面放一个输入框，写在 `renderBubble` 里面（只放在最后一条消息下面，这样只有一个输入框，不会每条消息下面都有一个）。

在你的 `index.tsx` 里加上下面这些。如果已经有第一部分的代码，就加在 `renderBubble` 返回的 JSX 里、消息文字的下面：

```tsx
// Near the top of MyWorld() (outside <Chat>), add these
const api = useYumina();                                    // If you already have it, don't duplicate
const msgs = api.messages || [];
const [ruleInput, setRuleInput] = React.useState("");
const currentRule = String(api.variables.custom_rule || "");

// Inside renderBubble, add a check
const isLastMsg = msg.messageIndex === msgs.length - 1;    // whether this is the last message

// In the JSX renderBubble returns, below the message text
{isLastMsg && (
  <div style={{
    marginTop: "12px",
    padding: "12px",
    background: "rgba(30,41,59,0.5)",
    borderRadius: "8px",
    border: "1px solid #334155",
  }}>
    <div style={{ fontSize: "12px", color: "#94a3b8", marginBottom: "6px" }}>
      World Rule: {currentRule || "(not set)"}
    </div>
    <div style={{ display: "flex", gap: "8px" }}>
      <input
        type="text"
        value={ruleInput}
        onChange={(e) => setRuleInput(e.target.value)}
        placeholder="Type a new rule..."
        style={{
          flex: 1, padding: "6px 10px", background: "#1e293b",
          border: "1px solid #475569", borderRadius: "6px",
          color: "#e2e8f0", fontSize: "13px", outline: "none",
        }}
        onKeyDown={(e) => {
          if (e.key === "Enter" && ruleInput.trim()) {
            api.setVariable("custom_rule", ruleInput.trim());
            setRuleInput("");
          }
        }}
      />
      <button
        onClick={() => {
          if (ruleInput.trim()) {
            api.setVariable("custom_rule", ruleInput.trim());
            setRuleInput("");
          }
        }}
        style={{
          padding: "6px 14px", background: "#4338ca", borderRadius: "6px",
          color: "#e0e7ff", fontSize: "13px", fontWeight: "600",
          cursor: "pointer", border: "none",
        }}
      >
        Apply
      </button>
    </div>
  </div>
)}
```

**逐行说明：**

- `isLastMsg`：只在最后一条消息上显示输入框，不然每条消息都会有一个
- `currentRule`：读变量现在的值，显示在输入框上面，让玩家知道当前规则是什么
- `ruleInput`：React state，记着正在打的字
- `onKeyDown`：按回车也能提交，不只是点按钮
- `api.setVariable("custom_rule", ...)`：把玩家打的字写进变量。AI 下一次回复时，设定里的 `{{custom_rule}}` 就会换成这段字
- `setRuleInput("")`：提交后清空输入框

::: info 为什么放在 renderBubble 里？
`index.tsx` 返回 `<Chat />` 就是平台自带的聊天。想往聊天里放能点的东西（按钮、输入框），有两种办法：1）像这里一样放进 `<Chat renderBubble={...} />`，跟着消息气泡一起画出来；2）用 flex 布局把 `<Chat />` 和你自己的组件并排放（做侧边栏用）。如果要一个完全不带聊天的全屏界面（比如视觉小说），就不用 `<Chat />`，自己写布局，需要的话用 `<MessageList />` + `<MessageInput />`。
:::

---

#### 第 4 步：保存并测试

1. 保存这张卡，点 **试玩** 开始试玩
2. 最后一条消息下面会出现「World Rule: (not set)」和一个输入框
3. 打「Magic is forbidden」，点「Apply」（或者按回车）
4. 输入框上面的字变成「World Rule: Magic is forbidden」。变量已经更新了
5. **现在发一条消息**（比如「I try to cast a fireball」）。这时引擎拼提示词，把 `{{custom_rule}}` 换成「Magic is forbidden」
6. AI 的回复应该会体现这条规则（比如「你抬手准备施法，却发现魔力像被什么看不见的东西锁住了」）
7. 再改一次规则（比如改成「Only fire magic is allowed」），再发一条消息。AI 会跟着变

---

## 两种做法合起来用

切换开场白和改写设定可以合起来用。举个具体的例子：

**建角色 + 故事开场：**

- **第一个开场白（index 0）** 还不是故事：是一个建角色的页面，有名字、职业、背景故事几个输入框
- 玩家填好 → 输入框写进变量 → 带 `{{player_name}}`、`{{player_class}}`、`{{player_backstory}}` 宏的设定拿到这些值
- 玩家点「开始冒险」→ `switchGreeting(1)` 跳到真正的故事开场。切换会把变量重置成那个开场白的初始值，所以要在切换 **之后** 再存玩家填的内容（先 await `switchGreeting`，再 `setVariable` 或 `patchVariables`）
- 从 AI 的第一条回复开始，它就已经知道玩家角色的名字、职业和背景故事

玩家界面里的开局模板（**填名字进故事**、**建档**、**选出身**、**分配属性点**）不写代码就能在故事开始前做出这种页面。

---

## 速查

| 你想要 | 怎么做 |
|---------------|-------------|
| 跳到一段写好的开场白 | 玩家界面：**切换开场白** 这一步，或者 **选开局** 模板。代码：`await api.switchGreeting(index)`（从 0 开始，按开场白的顺序） |
| 每个开场白不同的数值 | 在画布上把开场白拖到变量上，设好初始值 |
| 让玩家的输入改变 AI 的表现 | 文字变量 + 设定里的 `{{variable_name}}` + 一个 **填写项**（或者代码里调 `setVariable()`） |
| 按钮只在第一条消息上显示 | 在 `<Chat renderBubble>` 里判断 `msg.messageIndex === 0` |
| 选完以后藏起按钮 | 用一个变量记下选择，在 TSX 里判断 `hasChosen` |
| 选完路线切换设定 | 按路线变量设的 **条件设定**，或者绑在开场白上的情境 |
| 切换时放声音或弹提示 | 一条带 **播放音乐** / **播放音效** / **显示通知** 的行为，在切换之后让它生效 |

---

## 自己试试：可导入的演示

下载这个 JSON 文件导入进去：

<a href="/recipe-1-demo-zh.json" download>recipe-1-demo.json</a>

**怎么导入：**
1. 点左边的 **创建**，选 **空白项目**
2. 打开 **面板 → 卡的设置**，点 **导入文件** → **选择文件**
3. 选下载好的 `.json` 文件。导入会替换掉这张卡里的所有内容
4. 点 **保存**，再点 **试玩** 试试

**里面有：**
- 3 个开场白（主开场 + 黑暗洞穴 + 阳光草原）
- 2 个变量（`current_route` 记路线，`custom_rule` 存玩家可以改的规则）
- 2 条由 **玩家点了某个按钮** 触发的行为（`choose-dark` / `choose-light`），负责设路线、开关路线设定
- 一个消息渲染器（画每条消息的界面代码），带路线按钮和规则编辑框
- 一条用了 `{{custom_rule}}` 宏的设定

演示里的按钮一下子做完三件事：设路线、跑行为、再切换开场白。切换会把变量重置成开场白的初始值，所以路线可能留不住；上面第 2 到 4 步的做法不会有这个问题。

</div>
