---
title: "世界结构"
description: "Yumina 世界文件 WorldDefinition 的完整 JSON 结构，逐字段说明：身份信息、条目、变量、行为、界面、音频和设置。"
---

# 世界 Schema

Yumina 世界以一个名为 `WorldDefinition` 的 JSON 对象存储。以下是完整的 Schema。

## 顶层结构

```json
{
  "id": "uuid",
  "version": "20.0.0",
  "name": "World Name",
  "description": "Short description",
  "author": "Creator Name",
  "language": "en",

  "entries": [],
  "variables": [],
  "rules": [],
  "reactions": [],

  "rootComponent": null,
  "components": [],
  "audioTracks": [],
  "bgmPlaylist": null,
  "conditionalBGM": [],
  "customUI": [],

  "entryFolders": [],
  "customTags": [],
  "customTagColors": {},
  "editorMode": "advanced",

  "settings": {
    "maxTokens": 12000,
    "maxContext": 200000,
    "temperature": 1.0,
    "topP": 1,
    "frequencyPenalty": 0,
    "presencePenalty": 0,
    "playerName": "Player",
    "lorebookScanDepth": 2,
    "lorebookRecursionDepth": 0
  }
}
```

## 字段参考

### 身份信息

| 字段 | 类型 | 描述 |
|------|------|------|
| `id` | string | UUID，自动生成 |
| `version` | string | Schema 版本，当前为 `"20.0.0"` |
| `name` | string | 世界名称（1-200 字符） |
| `description` | string | 简短描述（0-10,000 字符） |
| `author` | string | 创作者显示名 |
| `language` | string（可选） | BCP 47 语言代码（`"en"`、`"zh"`、`"ja"` 等）。存在于 TypeScript 接口中，但在 Zod Schema 中为可选。 |

### 内容

| 字段 | 类型 | 描述 |
|------|------|------|
| `entries` | WorldEntry[] | AI 在生成时读取的所有内容——角色、设定、规则、开场白 |
| `variables` | Variable[] | 带有行为规则的游戏状态定义 |
| `rules` | Rule[] | WHEN/IF/THEN 自动化触发器 |
| `reactions` | Reaction[]（可选） | 基于事件模式的规则（较新的系统）。可以为 undefined。 |

### 展示层

| 字段 | 类型 | 描述 |
|------|------|------|
| `rootComponent` | RootComponent \| null | 自定义 UI 虚拟文件系统（React/TSX） |
| `components` | GameComponent[] | 内置 UI 组件（状态栏等） |
| `audioTracks` | AudioTrack[] | BGM、音效和环境音轨 |
| `bgmPlaylist` | BGMPlaylist \| null | 自动播放音乐配置 |
| `conditionalBGM` | ConditionalBGM[] | 基于状态触发的音乐 |
| `customUI` | CustomUIComponent[] | 旧版 UI 系统（请改用 rootComponent） |

### 组织结构

| 字段 | 类型 | 描述 |
|------|------|------|
| `entryFolders` | EntryFolder[] | 用于组织条目的文件夹结构 |
| `customTags` | string[] | 创作者自定义的条目标签 |
| `customTagColors` | Record\<string, string\> | 自定义标签的 Tailwind 颜色类 |
| `editorMode` | `"simple"` \| `"advanced"` | 编辑器复杂度级别 |

### 设置

| 字段 | 类型 | 默认值 | 描述 |
|------|------|--------|------|
| `maxTokens` | number | 12000 | 每次 AI 回复的最大 token 数 |
| `maxContext` | number | 200000 | 最大上下文窗口大小 |
| `temperature` | number | 1.0 | AI 创造力（0.0-2.0） |
| `topP` | number | 1 | 核采样阈值 |
| `frequencyPenalty` | number | 0 | 重复 token 惩罚 |
| `presencePenalty` | number | 0 | 已使用 token 惩罚 |
| `playerName` | string | "Player" | 默认的 <code v-pre>{{user}}</code> 替换值 |
| `lorebookScanDepth` | number | 2 | 扫描最近多少轮消息以匹配关键词 |
| `lorebookRecursionDepth` | number | 0 | 被触发的条目再次触发其他条目的递归层数 |
| `topK` | integer（可选） | — | 限制候选 token 数量（最小值：0） |
| `minP` | float（可选） | — | 最小概率阈值（0-1） |
| `structuredOutput` | boolean（可选） | false | 强制 JSON 输出格式 |
| ~~`lorebookBudgetPercent`~~ | ~~number~~ | — | **已废弃** —— token 预算已移除，所有触发的条目都会被包含 |
| ~~`lorebookBudgetCap`~~ | ~~integer~~ | — | **已废弃** —— 同上 |
| ~~`layoutMode`~~ | ~~string~~ | — | **已废弃** —— 布局自动决定，字段被忽略 |
| ~~`uiMode`~~ | ~~string~~ | — | **已废弃** —— 布局自动决定，字段被忽略 |
