187 lines
5.5 KiB
Markdown
187 lines
5.5 KiB
Markdown
# GSP
|
||
|
||
GSP = Game Specification Protocol。
|
||
|
||
GSP 是通用游戏规格协议，用于在人类、AI、工具、运行时、实现模块、测试与验收之间传递游戏设计信息。
|
||
|
||
README 面向准备使用 GSP 语言的人类和 AI。它说明 GSP 的用途、边界和基本写法。严格字段规范以 `gsp.schema.json` 为准。
|
||
|
||
## 文件
|
||
|
||
| 文件 | 作用 |
|
||
|---|---|
|
||
| `README.md` | GSP 语言使用前说明。给人类和 AI 阅读。 |
|
||
| `gsp.schema.json` | GSP 第一版核心字段规范。使用 JSON Schema 表达，便于 AI、工具、编译器和实现模块识别。 |
|
||
| `gsp.manifest.schema.json` | GSP 工程 manifest 字段规范。 |
|
||
| `gsp.message.schema.json` | GSP agent 通信消息字段规范。 |
|
||
| `commands.md` | GSP Toolkit 命令规范。 |
|
||
| `ai-usage.md` | GSP 项目 AI 使用规则。 |
|
||
| `message.md` | GSP Message 说明。 |
|
||
|
||
## GSP 是什么
|
||
|
||
GSP 是一种游戏规格协议，不是具体游戏引擎、代码框架或资源格式。
|
||
|
||
它用于描述游戏制作中的设计对象和设计语境。一个 GSP 可以是：
|
||
|
||
- 一句设计方向
|
||
- 一个设计风格
|
||
- 一个按钮
|
||
- 一个页面
|
||
- 一个功能
|
||
- 一个玩法机制
|
||
- 一个反馈设计
|
||
- 一个音效表现
|
||
- 一个震动表现
|
||
- 一个集合或范围
|
||
- 一个逐步细化中的设计对象
|
||
|
||
GSP 不预设抽象和实体的硬边界。所有对象都先被视为 GSP，再由 `title`、`context`、`resolution`、`with`、`refines` 和当前任务共同解释。
|
||
|
||
## GSP 用来做什么
|
||
|
||
GSP 的核心作用是高效传递设计信息。
|
||
|
||
它用于支持：
|
||
|
||
- 人类和 AI 对齐游戏设计意图
|
||
- AI 与 AI 之间传递上下文
|
||
- 将模糊设计逐步细化为可实现规格
|
||
- 让编译器检查缺失、引用和阶段门槛
|
||
- 为运行时、目标平台、测试、验收等后续模块提供统一输入
|
||
|
||
GSP 不负责承载复杂的模块置信度、自我纠错、模块信誉、历史归因等机制。这些能力属于外部模块。
|
||
|
||
## 最小 GSP
|
||
|
||
最小合法 GSP 只有 `id`。
|
||
|
||
```yaml
|
||
id: feedback.positive
|
||
```
|
||
|
||
只有 `id` 的 GSP 是占位声明。它表示该设计对象存在，但尚未被细化。
|
||
|
||
默认情况下，`.gsp` 文件放在 GSP 工程根目录的 `design/` 目录下。
|
||
|
||
## 基础 GSP
|
||
|
||
`context` 用于写入核心设计内容。
|
||
|
||
```yaml
|
||
id: feedback.positive
|
||
context: 积极反馈。用于让玩家在操作后获得明确、正向、值得继续的感受。
|
||
```
|
||
|
||
## 字段速览
|
||
|
||
| 字段 | 必需 | 作用 |
|
||
|---|---|---|
|
||
| `id` | 是 | 唯一身份。 |
|
||
| `title` | 否 | 展示标题。 |
|
||
| `context` | 否 | 核心设计内容。 |
|
||
| `resolution` | 否 | 清晰度 / 细化程度。 |
|
||
| `with` | 否 | 通用设计语境关系。 |
|
||
| `refines` | 否 | 单一细化来源。 |
|
||
| `type` | 否 | 辅助分类。 |
|
||
|
||
## 核心边界
|
||
|
||
- GSP 是单文件、单格式的设计协议。
|
||
- `id` 是唯一强制字段。
|
||
- `title` 是展示标题。
|
||
- `context` 可选。
|
||
- `resolution` 是清晰度软指标。
|
||
- `with` 是通用设计语境关系。
|
||
- `refines` 是单一细化来源。
|
||
- `type` 是辅助分类字段。
|
||
- GSP 不预设抽象和实体的硬边界。
|
||
- 置信度、自我纠错、模块信誉和历史归因属于外部模块，不进入 GSP 核心协议。
|
||
|
||
## resolution
|
||
|
||
`resolution` 表示 GSP 当前的清晰度。它是软指标，由人类或 AI 执行者声明。
|
||
|
||
| 等级 | 含义 |
|
||
|---|---|
|
||
| `L0` | 占位。只有 `id`，或几乎没有可用设计信息。 |
|
||
| `L1` | 有基础语义。能说明大概是什么。 |
|
||
| `L2` | 有结构化设计。能说明用途、边界和关联对象。 |
|
||
| `L3` | 可实现规格。足够交给目标平台或生成模块执行初版实现。 |
|
||
| `L4` | 平台绑定规格。已经明确组件、资源、事件、配置或实现约束。 |
|
||
| `L5` | 已实现并通过验证。 |
|
||
|
||
编译器可以按阶段检查 `resolution`，但 `resolution` 不证明设计质量。
|
||
|
||
## title
|
||
|
||
`title` 表示 GSP 的展示标题。
|
||
|
||
```yaml
|
||
id: page.lottery.main
|
||
title: 抽奖页面
|
||
```
|
||
|
||
工具在图形、索引和 AI 入口中优先使用 `title` 展示。没有 `title` 时使用 `id`。
|
||
|
||
## with
|
||
|
||
`with` 表示当前 GSP 需要与哪些 GSP 一起进入设计语境。
|
||
|
||
`with` 不区分使用、包含、依赖、分组、实体或抽象。
|
||
|
||
```yaml
|
||
id: page.lottery.main
|
||
context: 抽奖页面，需要表达奖励期待、抽取行为和结果反馈。
|
||
with:
|
||
- ui.button.primary
|
||
- feedback.positive
|
||
- style.reward.light
|
||
```
|
||
|
||
`with` 也可以带局部说明：
|
||
|
||
```yaml
|
||
with:
|
||
- id: ui.button.primary
|
||
context: 用作主要抽奖操作入口。
|
||
```
|
||
|
||
## refines
|
||
|
||
`refines` 表示当前 GSP 是对另一个 GSP 的进一步细化。
|
||
|
||
`refines` 只支持单一来源。
|
||
|
||
```yaml
|
||
id: ui.button.reward_primary
|
||
refines: ui.button.primary
|
||
context: 奖励场景下的主按钮，比普通主按钮更强调正向点击反馈。
|
||
```
|
||
|
||
多个相关 GSP 写入 `with`。
|
||
|
||
## 注释
|
||
|
||
GSP 可以使用 YAML 注释。
|
||
|
||
```yaml
|
||
id: style.reward.light
|
||
context: 奖励表现要轻快、积极，但不要过度刺激。
|
||
# ai: 生成时控制节奏，不堆叠过多闪光和震动。
|
||
```
|
||
|
||
注释是辅助信息，可被编译器或上下文裁剪流程丢弃。核心内容写入正式字段。
|
||
|
||
## 使用顺序
|
||
|
||
使用 GSP 时按以下顺序理解：
|
||
|
||
1. 先读 `id`，确认身份。
|
||
2. 再读 `title`，确认展示名称。
|
||
3. 再读 `context`，理解核心设计语义。
|
||
4. 查看 `resolution`，判断当前细化程度。
|
||
5. 展开 `with`，补齐相关设计语境。
|
||
6. 查看 `refines`，确认是否来自某个更早或更粗的 GSP。
|
||
7. 需要严格校验时使用 `gsp.schema.json`。
|