---
title: "角色创建表单"
description: "做一张玩家在故事开始前填的角色表，让 AI 从第一条回复起就知道他的名字、职业和背景故事。"
---
<div v-pre>

# 角色创建表单

> 故事开始之前，玩家先填一张角色表：名字、职业、一小段背景故事。然后点「开始冒险」，故事开始，AI 已经知道他是谁了。玩家界面里有专门做这个的模板，所以表单不用写代码。

---

## 你要做的东西

玩家在第一条消息之前要走过的几页：

- **一个名字输入框**
- **一个职业选择**：Warrior、Mage 或 Rogue，每个配一句说明
- **一个背景故事输入框**，可以不填
- **一个确认页**，把选的东西汇总一遍，再用一个按钮开始故事

玩家填的所有东西都存进普通的变量里。AI 从第一条回复起就看得到。

### 怎么运作

```
1. The player starts a new game → the first opening page appears instead of the chat
2. They type a name and a backstory → saved into the variables Player name and Backstory
3. They pick a class → saved into the variable Class
4. They confirm → the chat starts with your opening
5. The player sends their first message
   → The AI's prompt includes the variables, their Behavior Rules,
     and any lore that only goes in for the chosen class
   → The AI calls them by name and writes to their class
```

---

## 一步一步来

### 第 1 步：从模板加开局页

点顶栏中间的 **玩家界面**，再点 **模板**。在 **开局 · 玩家进故事之前** 下面，加上：

| 模板 | 它给你什么 |
|----------|-------------------|
| **建档** | 名字、性别、年龄、外貌和一个秘密，边填边出人物卡。只有名字必填 |
| **选出身** | 一个有三个选项的卡片选择。你会把它改成职业选择 |
| **开局确认页** | 把前面选的汇总一遍。总是排在最后 |

故事开始前，玩家会按顺序走过这几页。每个模板都写着它会给卡加哪些变量（「会给这张卡加这些变量」）。这些都是普通变量，已经配好了告诉 AI 它们是什么意思的行为规则，比如「玩家的名字。故事里的人都用这个名字称呼玩家，不要另起名字。」

::: tip 只要一个名字？
**填名字进故事** 模板只问名字和玩家希望被怎么称呼，别的都不问。
:::

### 第 2 步：把选出身改成选职业

在左边的页面栏里选中 **选出身** 这一页，改一改：

1. 点标题，改成「选择你的职业」
2. 选中卡片选择，把三个选项改名为 **Warrior**（「近战专精，血量高」）、**Mage**（「远程魔法，法力高」）和 **Rogue**（「灵活隐秘，暴击高」）
3. 在页面栏里双击这一页，改名为「职业」

这个选择会把选中的选项存进变量 **出身**。回到画布，在变量块里找到出身，改名为 **职业**，再重写它的 **行为规则**：

```
The class the player chose at the start: Warrior, Mage or Rogue. It decides what they can do in a fight and how others see them. Don't change it.
```

然后展开 **AI 怎么用它**，把 **AI 权限** 设成 **AI 只读**，这样 AI 改不了玩家的职业。

### 第 3 步：精简建档页

在 **建档** 这一页上，留下名字，再把一个输入框改成背景故事：

- 删掉不想要的部件（选中它们，或者在 **图层** 里找到，按 Delete）。之后可以在画布上把它们的变量也删掉
- 把「一个秘密」这个输入框的标签改成「背景故事（可选）」，提示文字改成「用几句话写写你的过去」。然后在画布上把它的变量从 **玩家的秘密** 改名为 **背景故事**，行为规则改成 `The player's backstory, written by the player. Use it; don't contradict it.`（模板自带的规则把它当成故事里没人知道的秘密，这不是背景故事该有的用法）

**玩家名字** 保留模板的规则就行。如果想防止玩家不填名字就跳过去，选中开始按钮，在 **这些填好了才能按** 里勾上玩家名字。这样不填名字，按钮就一直是灰的。

### 第 4 步（可选）：每个职业配一条自己的设定

变量告诉 AI 玩家选了什么。想让每个职业有更多可以发挥的内容，就每个职业加一条设定，只在选了这个职业时才发给 AI：

1. 加一条设定「Mage 设定」，写 Mage 在这个世界里懂什么、能做什么
2. 把 **职业** 变量拖到这条设定上，点那根线。把条件设成 职业 **等于** `Mage`
3. Warrior 和 Rogue 也照做

这样玩 Mage 的玩家，AI 拿到的是 Mage 那条，另外两条不会发。挂条件的设定见[开场白和设定](/zh/creator/entries#设定)。

### 第 5 步：写开场白

开场白（画布上的 **开场白**）是表单之后的第一条消息。照平常那样写：

```
*The gate of destiny swings open, and dawn light spills over the Elderlands.*

*The silhouette of a distant city shimmers ahead, and a cobblestone road stretches toward it. The wind smells of grass and far-off hearth-smoke.*

Three paths lie before you: a wide road leading to town, a narrow trail through the woods, and a slope down to the river. Which way do you go?
```

::: warning 别把玩家的选择写进开场白
开场白在一局游戏创建时就写好了，那时玩家还没填表。开场白里的 `{{Player name}}` 宏显示的是变量的初始值，不是玩家填的内容。名字和职业交给 AI 就行：它的第一条回复就已经知道了。
:::

### 第 6 步：试玩

在玩家界面里关掉 **编辑**，就能一页页点过去，不花额度。然后点顶栏的 **试玩**：

1. 出现建档页。填「艾拉」和一句背景故事
2. 选 **Mage**
3. 确认页列出你的选择。点它的开始按钮
4. 开场白出现。发一句「我朝镇子走去」
5. AI 叫你艾拉，把你写成 Mage（法杖、咒语、路人注意到你的法袍）

试玩右边的 **这回合** 能看到 AI 拿到了哪些变量和设定。

**如果出了问题：**

| 现象 | 可能的原因 | 怎么改 |
|---------|-------------|-----|
| 表单没出现 | 这几页不在开局的那一串里 | 它们必须来自 **开局 · 玩家进故事之前** 里的模板，确认页排在最后 |
| 有一页挂着 **没出口** 的提醒 | 这一页上没有能去别处的按钮 | 给它加一个 **跳到页面** 的按钮 |
| AI 不管职业 | 职业变量没写行为规则，或者 AI 看不到变量 | 给它写行为规则，再看看卡的 **对话记忆** 里 **变量给 AI 的方式** 是不是 **不给** |
| 职业设定一直没进来 | 条件里的值和选项不完全一样 | 条件里必须写 `Mage`，和选项的标题一字不差 |
| AI 给玩家改了名字 | 玩家名字是 AI 能改的 | 把它的 **AI 权限** 设成 **AI 只读** |

---

## 写代码的做法：放在第一条消息里的表单

如果想让表单由你自己的界面代码来画，比如就放在第一条消息下面，下面是代码版。它用三个文字变量 `player_name`、`player_class` 和 `player_backstory`（都是 **AI 只读**，`player_name` 初始值是 `Traveler`），还有两条开场白：第一条是一小段「你是谁？」的场景，第二条才是真正的故事开头。

界面代码按变量名读写变量。**面板 → 界面代码** → 打开 `index.tsx`，把默认的 `return <Chat />` 换掉：

```tsx
export default function MyWorld() {
  const api = useYumina();

  const [name, setName] = React.useState("");
  const [selectedClass, setSelectedClass] = React.useState("");
  const [backstory, setBackstory] = React.useState("");

  // Once a class is saved, the form is done
  const hasCreated = String(api.variables.player_class || "") !== "";

  const classes = [
    { id: "Warrior", label: "Warrior", icon: "⚔️", desc: "Melee specialist, high HP" },
    { id: "Mage", label: "Mage", icon: "🔮", desc: "Ranged magic, high MP" },
    { id: "Rogue", label: "Rogue", icon: "🗡️", desc: "Agile and stealthy, high crit" },
  ];

  const handleStart = async () => {
    if (!selectedClass) return;
    // Switch to the second opening FIRST: switching resets variables
    // to that opening's starting values
    await api.switchGreeting(1);
    api.setVariable("player_name", name.trim() || "Traveler");
    api.setVariable("player_class", selectedClass);
    api.setVariable("player_backstory", backstory.trim());
  };

  const label = { fontSize: "13px", color: "#a5b4fc", marginBottom: "6px", fontWeight: "600" };
  const field = {
    width: "100%", padding: "10px 14px", background: "#0f172a",
    border: "1px solid #334155", borderRadius: "8px", color: "#e2e8f0",
    fontSize: "14px", outline: "none", boxSizing: "border-box", fontFamily: "inherit",
  };

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

        {msg.messageIndex === 0 && !hasCreated && (
          <div style={{
            marginTop: "20px",
            padding: "24px",
            background: "linear-gradient(135deg, #1e1b4b 0%, #1a1a2e 100%)",
            borderRadius: "16px",
            border: "1px solid #312e81",
          }}>
            <div style={{ fontSize: "18px", fontWeight: "bold", color: "#c4b5fd", marginBottom: "20px", textAlign: "center" }}>
              Create Your Character
            </div>

            <div style={{ marginBottom: "16px" }}>
              <div style={label}>Character Name</div>
              <input
                type="text"
                value={name}
                onChange={(e) => setName(e.target.value)}
                placeholder="Leave blank for 'Traveler'"
                style={field}
              />
            </div>

            <div style={{ marginBottom: "16px" }}>
              <div style={{ ...label, marginBottom: "8px" }}>Choose a Class</div>
              <div style={{ display: "flex", gap: "10px" }}>
                {classes.map((cls) => {
                  const picked = selectedClass === cls.id;
                  return (
                    <button
                      key={cls.id}
                      onClick={() => setSelectedClass(cls.id)}
                      style={{
                        flex: 1,
                        padding: "14px 10px",
                        background: picked ? "linear-gradient(135deg, #4338ca, #6366f1)" : "#1e293b",
                        border: picked ? "2px solid #818cf8" : "1px solid #334155",
                        borderRadius: "10px",
                        color: picked ? "#e0e7ff" : "#94a3b8",
                        cursor: "pointer",
                        textAlign: "center",
                      }}
                    >
                      <div style={{ fontSize: "24px", marginBottom: "4px" }}>{cls.icon}</div>
                      <div style={{ fontSize: "14px", fontWeight: "bold", marginBottom: "2px" }}>{cls.label}</div>
                      <div style={{ fontSize: "11px", opacity: 0.7 }}>{cls.desc}</div>
                    </button>
                  );
                })}
              </div>
            </div>

            <div style={{ marginBottom: "20px" }}>
              <div style={label}>Backstory (optional)</div>
              <textarea
                value={backstory}
                onChange={(e) => setBackstory(e.target.value)}
                placeholder="A few sentences about your character's past..."
                rows={3}
                style={{ ...field, resize: "vertical" }}
              />
            </div>

            <button
              onClick={handleStart}
              disabled={!selectedClass}
              style={{
                width: "100%",
                padding: "14px",
                background: selectedClass ? "linear-gradient(135deg, #7c3aed, #a855f7)" : "#374151",
                border: "none",
                borderRadius: "10px",
                color: selectedClass ? "#f5f3ff" : "#6b7280",
                fontSize: "16px",
                fontWeight: "bold",
                cursor: selectedClass ? "pointer" : "not-allowed",
              }}
            >
              {selectedClass ? "Start Adventure" : "Pick a class first"}
            </button>
          </div>
        )}
      </div>
    )} />
  );
}
```

**代码做了什么：**

- `msg.messageIndex === 0 && !hasCreated` 让表单只出现在第一条消息上，而且只到职业存好为止
- 三个 `React.useState` 存着玩家正在填的内容，直到他点 **Start Adventure**
- `api.switchGreeting(1)` 把第一条消息换成第二条开场白（开场白从 0 开始数）。**切换会把变量重置成那条开场白的初始值**，所以代码先等切换完成，再写变量。顺序反过来的话，切换会把它们清掉
- `api.setVariable("player_class", ...)` 按变量名写入

AI 在下一次的提示里就会读到这些变量。想让一条设定把人物资料写清楚，也可以在一条每回合都发的设定里写宏：

```
[Player character]
Name: {{player_name}}
Class: {{player_class}}
Backstory: {{player_backstory}}
```

设定里的宏在每次拼 AI 的提示时填进去，所以永远是当前的值。开场白里的宏不是这样：开场白在一局游戏创建时就写好了，所以那里的 `{{player_name}}` 显示的是初始值（「Traveler」）。

**面板 → 界面代码** 里文件旁边的状态应该是绿色的 **正常**。

### 在后面的消息上显示角色

在 `renderBubble` 里，消息正文上面加：

```tsx
{hasCreated && (
  <div style={{ display: "flex", gap: "8px", marginBottom: "8px", fontSize: "12px", color: "#a5b4fc" }}>
    <span>{String(api.variables.player_name)}</span>
    <span style={{ opacity: 0.5 }}>|</span>
    <span>{String(api.variables.player_class)}</span>
  </div>
)}
```

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

---

## 再进一步

### 更多职业

用模板的做法，就在卡片选择里加一个选项，再加一条对应的设定。用代码的做法，就在 `classes` 数组里加一项。

### 属性点

**分配属性点** 模板把六点分到力量、敏捷、魅力、智力上。把它放在职业页和确认页之间。

### 每个职业不同的开局

如果每个职业要从完全不同的地方开始，就每个职业写一条开场白，再加上 **选开局** 模板（至少要两条开场白）。和某条开场白绑定的情境，只在从那条开场白开始的那局里存在。见[情境](/zh/creator/modules)。

---

## 速查

| 你想要 | 怎么做 |
|---------------|-------------|
| 故事之前先填一张表 | **玩家界面** → **模板** → **开局 · 玩家进故事之前** |
| 只要名字 | **填名字进故事** 模板 |
| 好几个输入项 | **建档** 模板 |
| 几个选项里挑一个 | **选出身** 模板（一个卡片选择），改个名字 |
| 开始前汇总一遍 | **开局确认页** 模板，总是排在最后 |
| 某一项必须填 | 开始按钮 → **这些填好了才能按** |
| 不让 AI 改玩家的选择 | **AI 权限**：**AI 只读** |
| 每个选择配不同的设定 | 挂了变量条件的设定 |
| 把选择写进设定正文 | 在设定里写 `{{player_name}}` 这样的宏（别写在开场白里） |
| 代码：先切开场白，再存选择 | `await api.switchGreeting(1)`，然后 `api.setVariable(...)` |

---

::: tip 这是食谱 #4
[场景跳转与设定切换](./scene-jumping.md)里更详细地讲了用按钮切换开场白、在设定里用宏。角色创建常常是别的食谱的第一步：职业可以决定[商店](./shop.md)的初始金币，或者[背包](./inventory.md)里的初始物品。
:::

</div>
