📋 概述

Level Design Toolkit（关卡设计工作台）是一个 AI 辅助的关卡设计文档生成与管理工具。它通过多阶段 AI 流水线，将你的关卡构想自动展开为一份完整的 LDD（Level Design Document），并提供 3D 可视化预览、情绪曲线分析、参考图生成和多部门模拟审查。

🚀 快速开始

⚙ 设置配置

点击左下角 ⚙ 按钮打开设置面板。设置分为三个页签：

🤖 模型提供商

配置 AI 大模型的 API 连接信息。工具支持以下提供商：

🖼 参考图生成

配置 AI 图像生成端点，用于在「参考图库」中自动生成关卡视觉参考图。支持两种模式：

• OpenAI 兼容端点（推荐）— 兼容 DALL-E / Stable Diffusion / 公司内部图像 API
• Google Imagen（原生 REST）— Google 的 Imagen 图像生成 API

🔗 引擎桥接

配置与游戏引擎（UE5 / Unity）的双向同步连接。可一键安装引擎插件，支持实时推送和拉取关卡数据。详见「引擎桥接」章节。

📁 项目管理

左侧任务栏管理所有关卡项目。每个项目是一个独立的 LDD 设计方案。

新建项目

点击 ＋ 按钮，输入项目名称即可创建。创建后自动进入「关卡导入」表单。

🏷️ 关卡编号

每个项目拥有一个 4 位数字编号（如 0042），显示为项目名称旁的金色徽章。关卡编号是该项目在引擎场景中的唯一标识，用于区分不同关卡的数据。

切换项目

直接点击左侧项目列表中的项目名称即可切换。切换时会自动加载该项目的 LDD 数据和所有视图。

数据存储

所有项目数据保存在工具目录下的 projects/ 文件夹中。每个项目一个子目录，包含：

• meta.json — 项目元数据和完整 LDD JSON
• review_data.json — 审查讨论结果
• images/ — 生成的参考图片

🎮 关卡导入

这是关卡设计的起点。在此表单中填写关卡的基础框架信息，AI 将基于这些信息展开完整设计。

字段说明

快捷功能

• 📋 一键复制 — 将表单所有字段复制为可读文本（方便分享给同事评审）
• 📥 一键粘贴 — 从剪贴板粘贴之前复制的文本，自动填入对应字段
• 💾 仅保存 — 只保存表单数据不触发 AI 生成（适合分次填写）
• 🚀 保存并开始生成 — 保存并立即启动 AI 分阶段生成流水线

📝 LDD 文档

这是工具的核心输出——完整的关卡设计文档。LDD 通过 5 个阶段逐步生成：

五个生成阶段

LDD 文档视图功能

• 快速导航 — 点击右下角的导航按钮展开目录面板，可快速跳转到文档任意章节
• 折叠展开 — 每个章节标题可点击折叠/展开
• 内容编辑 — 文档内容会随每次 AI 迭代自动更新

💬 对话 & 迭代修改

左侧聊天面板是你与 AI 交互的主要渠道。通过自然语言描述修改意见，AI 会针对性地更新 LDD 的对应部分。

工作模式

生成完 LDD 后，左侧面板会切换到「修改模式」，此时可以：

• 提出具体修改意见：「把R3区域的面积缩小一半」
• 补充设计细节：「R2区域增加一个隐藏密室，需要解谜才能进入」
• 调整整体方向：「整体降低战斗密度，增加探索内容占比」
• 切换关注阶段：点击左侧进度条上的阶段按钮，可切换当前修改的焦点阶段

快捷操作

• 🔄 重新生成图表 — 重新生成所有可视化图表（不调用 AI，基于当前 LDD 数据）
• 📤 导出 — 将当前 LDD 导出为 Markdown 或 Word 文件

🏗 平面图 / 拓扑

基于 LDD 中的区域数据自动生成的 3D 交互式关卡布局图。使用 Three.js 渲染，支持实时操作。

基本操作

AI 辅助功能

• 🤖 AI 诊断优化 — AI 分析当前布局，自动识别动线瓶颈、区域重叠、尺度不合理等问题，并给出优化建议
• 🔄 反向更新 LDD — 手动调整平面图布局后，AI 会将修改反向同步更新到 LDD 文档的文字描述中

侧边栏

点击右侧 ☰ 按钮展开侧边栏，查看：拓扑关系图、区域列表、动线路径、统计信息。

🎨 材质语义对照

平面图左面板底部显示「材质语义」色块对照表，与引擎桥接插件中的白盒材质颜色完全对应。当区域数据包含 role 字段时，平面图会自动使用对应语义颜色渲染。详见 引擎桥接 → 白盒材质语义对照表。

📊 事件时间线

将 LDD 中的事件序列可视化为时间轴和情绪曲线图表。

图表说明

• 情绪曲线（折线）— 玩家在流程中的情绪强度变化，帮助识别节奏问题
• 事件节拍点（圆点）— 每个关键事件在时间轴上的位置，按类型着色
• 悬停查看详情 — 鼠标悬停在事件点上可查看事件描述
• 点击展开 — 点击事件点可在下方展开完整事件详情面板

事件序列表

图表下方的表格以列表形式展示所有事件的：时间、类型、描述、位置、强度。

🖼 参考图库

管理 AI 生成的关卡视觉参考图。每个区域和关键场景可以生成对应的概念参考图。

生成 LDD 的美术阶段完成后，图库页面会自动显示可生成的参考图列表。点击图片卡片触发生成。

📋 资产需求表

基于 LDD 文档内容，按部门/职能自动拆解出可执行的资产需求清单。

六大分类

使用方式

1. 切换到「📋 资产需求表」Tab
2. 选择需求分类标签页（如「概设原画需求」）
3. 点击 🤖 AI 生成需求 — AI 根据 LDD 自动拆解生成该分类的需求清单
4. 点击 ➕ 手动添加 可手动创建需求条目
5. 每条需求可点击 🎨 生成参考图 为其生成 AI 参考图
6. 生成的参考图会同步到「参考图库」中统一管理

需求卡片说明

• 优先级标签 — P0（必须）/ P1（重要）/ P2（可选）
• 模块 — 对应 LDD 中的区域（如 R1）、机制（如 M01）或全局
• 资产名称 — 简洁清晰的资产标识
• 详细描述 — 可直接执行的需求细节（含规格参数、风格要求等）
• Prompt — 用于 AI 生成参考图的英文提示词

⚔ 审查讨论

模拟真实的项目评审环境，5 个部门的 AI Agent 从各自专业视角对 LDD 进行严格审查。

五个审查部门

使用方式

1. 切换到「⚔ 审查讨论」Tab
2. 点击顶部的部门卡片选择要查看的审查方向
3. 点击 ▶ 触发审查 或 🔄 下一轮审查 启动该部门的 AI 审查
4. 审查完成后，下方显示驳斥意见（按 CRITICAL / MAJOR / MINOR 分级）和解决辩论方案
5. 每个部门的轮次独立计算——你可以单独对某个部门多次审查而不影响其他部门

🎨 美术管线

美术管线将 LDD 设计无缝延伸至视觉生产。从风格锚定到 3D 模型，全流程 AI 驱动。

视觉风格锚点

在关卡导入表单底部展开「🎨 视觉风格锚点」区域，设定：

设定后，系统会自动将风格约束注入所有后续图像生成 Prompt，确保一致性。

场景原画

在「🎨 美术管线」Tab 的「🏞 场景原画」子面板中操作：

1. 方式 A — AI 生成：添加条目 → 配置视角/参考图 → 点击生成，Prompt 自动从 LDD 空间结构提取
2. 方式 B — 上传导入：点击「📤 上传原画」直接导入外部工具（Photoshop/MidJourney 等）制作的原画，支持多张批量上传
3. 上传或生成后的原画均可直接用于物件拆分，两种方式可混合使用

物件拆分 & 多视图

在「🔧 物件拆分 & 多视图」子面板中，从场景原画拆分出可用的 3D 资产参考：

完成后可一键导出为 Tripo Multiview 格式，直接送入 3D 生成。

3D 模型生成（后端已完成）

后端已直连 Tripo REST API：上传四视角图 → 创建任务 → 轮询进度 → 自动下载 GLB。支持面数预设（2K/5K/10K/20K）和批量生成。前端 UI 待后续版本。

📤 导出

将当前项目的 LDD 文档导出为文件，支持多种格式：

• Markdown (.md) — 纯文本格式，适合放入 Git 仓库或在线协作工具
• Word (.docx) — 带格式的 Word 文档，适合正式评审和存档
• Excel (.xlsx) — 表格形式，便于比对和筛选
• GLB 3D 模型 — 白盒关卡的 3D 模型文件，Blender/Unity/UE5 通用
• 引擎交接包 (.zip) — 包含 ldd.json、平面图、动线、节拍等 7 个文件，引擎 Agent 可直接消费

导出方式：点击顶部 Tab 栏右侧的 📤 按钮，或点击左侧聊天面板的「📤 导出」按钮。

🔌 MCP 接入（供外部 AI Agent 调用）

本工具内置 MCP (Model Context Protocol) Server，可以让 Claude Code、Cursor、Echo Agent 等任何兼容 MCP 的 AI 客户端直接调用关卡设计工具的全部功能，实现纯对话式 LDD 生成。

前提条件

• Python 3.10+ 已安装且在系统 PATH 中可用
• 安装 MCP 专用依赖（只需一次）：

pip install httpx pydantic "mcp[cli]"

工作原理

AI Agent ↔ stdio (MCP) ↔ mcp_server/server.py ↔ HTTP :8800 ↔ Flask 后端

MCP Server 启动时会自动启动 Flask 后端（端口 8800），无需手动管理。

配置步骤

在你的 MCP 客户端的配置文件中添加以下内容（将路径替换为实际安装路径）：

▸ Claude Code / Claude Desktop

配置文件位置：~/.claude/claude_desktop_config.json（macOS/Linux）或 %APPDATA%\Claude\claude_desktop_config.json（Windows）

{
  "mcpServers": {
    "level-design-toolkit": {
      "command": "python",
      "args": ["你的安装路径/mcp_server/server.py"],
      "env": {
        "PYTHONPATH": "你的安装路径"
      }
    }
  }
}

▸ Cursor

配置文件位置：项目根目录 .cursor/mcp.json 或全局 ~/.cursor/mcp.json

{
  "mcpServers": {
    "level-design-toolkit": {
      "command": "python",
      "args": ["你的安装路径/mcp_server/server.py"],
      "env": {
        "PYTHONPATH": "你的安装路径"
      }
    }
  }
}

▸ Windows 路径示例（假设解压到 D:\Tools\LevelDesignToolkit）：

{
  "mcpServers": {
    "level-design-toolkit": {
      "command": "python",
      "args": ["D:\\Tools\\LevelDesignToolkit\\mcp_server\\server.py"],
      "env": {
        "PYTHONPATH": "D:\\Tools\\LevelDesignToolkit"
      }
    }
  }
}

LLM 配置

MCP Server 复用本工具的 config.json 配置。首次使用前需要先配置好 API Key：

• 方式一：运行本工具 GUI → 设置 → 填入 API Key → 保存
• 方式二：直接编辑安装目录下 config.json，在 providers 中填入 api_key 和 base_url

可用工具（23 个）

分为三组：核心工具（11 个）、Handoff 工具（7 个，支持外部 LLM 独立生成后提交结果）、Bridge 工具（5 个，引擎桥接操作）。

核心工具（11 个）

Handoff 工具（7 个）— 外部 LLM 独立生成模式

Bridge 工具（5 个）— 引擎桥接操作

标准工作流示例

在 Claude Code 中，你可以直接告诉 Agent：

故障排除

🔗 引擎桥接

引擎桥接功能让 LDT 与游戏引擎（UE5 / Unity）实现不依赖离线导出的双向实时同步。LDD 中的区域、连接、机制等设计数据可以直接推送到引擎关卡中，引擎中的修改也可以同步回 LDT。

第一步：安装引擎插件

进入 设置 → 「引擎桥接」页签，在「一键安装引擎插件」区域：

1. 选择引擎类型（Unreal Engine 5 或 Unity）
2. 输入你的游戏项目根目录路径
   • UE5 项目：该目录下应有 .uproject 文件
   • Unity 项目：该目录下应有 Assets/ 文件夹
3. 点击 「📦 安装插件」 按钮

LDT 会自动将内置的 Bridge 插件文件拷贝到引擎识别的位置：

第二步：在引擎中启用插件并启动服务

▸ UE5

1. 一键安装后重新生成项目文件（右键 .uproject → Generate Visual Studio project files），然后编译项目
2. 打开 UE5 编辑器，菜单栏 Edit → Plugins，搜索 「LDT Bridge」，勾选启用并重启编辑器
3. 启用后通过 Window → LDT Bridge 或工具栏的 LDT 按钮 打开管理面板
4. 在面板中点击 ▶ Start 启动 HTTP Server（默认端口 24680）

面板会实时显示连接状态、LDT 实体列表和变更历史。

▸ Unity

打开 Unity 编辑器，菜单栏点击 Tools → LDT Bridge，在弹出窗口中点击 Start Server。

第三步：在 LDT 中连接

设置 → 「引擎桥接」→ 在「连接引擎」区域：

1. 主机地址：通常为 127.0.0.1（本机），远程协作时填对方 IP
2. 端口：默认 24680，与引擎插件启动时一致
3. 点击 「🔗 连接」

连接成功后会自动执行首次扫描，并显示引擎中已有的 LDT 实体。

关卡编号隔离

引擎桥接的所有同步操作都基于当前项目的 4 位关卡编号（level_code）进行隔离，确保多个 LDT 项目在同一引擎场景中互不干扰。

• 推送：创建的 Actor 自动携带 LDT:level_code=XXXX 标签
• 扫描：只返回带有当前项目编号的 Actor，忽略其他项目的数据
• 引擎内查看：在 UE5 中选中 LDT Actor，Details 面板的 LDT Info 分类会显示 Level Code、LDT ID 和 Actor Type
• 插件内筛选：引擎插件的 Planar Edit 和 Markers 标签页顶部有 Level Code 下拉框，可按编号筛选列表中显示的 Actor（默认 "All" 显示全部）

项目自动关联

引擎插件无需手动填写 Project ID。点击 Import from LDT 时，插件会连接 LDT 后端并自动获取当前打开项目的 ID 和关卡编号。

• Settings 页面中 Active Project 为只读显示，展示当前自动关联的项目
• 如果显示 "(none)"，请确保 LDT 桌面端已打开且已选择一个项目
• Export to LDT 前需要先执行一次 Import（以建立项目关联）

同步操作

支持的引擎

🎨 白盒材质语义对照表

UE5 桥接插件中的白盒形状使用语义化网格材质（ShapeRole），每种角色对应不同颜色。此配色同时用于 LDT 平面图渲染和场景原画 AI 生成提示。

在 UE5 中选中 LDT Shape Actor，在 Details 面板的 LDT | Shape → ShapeRole 下拉菜单中选择角色即可切换材质。

❓ 常见问题

⌨ 快捷键

全局

3D 平面图