GSP/language/README.md

GSP

GSP = Game Specification Protocol。

GSP 是 AI 游戏制作引擎的底层游戏规格协议模块，用于在人类、AI、工具、运行时、实现模块、测试与验收之间传递游戏设计信息。

README 面向准备使用 GSP 语言的人类和 AI。它说明 GSP 的用途、边界和基本写法。严格字段规范以 gsp.schema.json 为准。

文件

文件	作用
README.md	GSP 语言使用前说明。给人类和 AI 阅读。
gsp.schema.json	GSP 第一版核心字段规范。使用 JSON Schema 表达，便于 AI、工具、编译器和实现模块识别。

GSP 是什么

GSP 是一种游戏规格协议，不是具体游戏引擎、代码框架或资源格式。

它用于描述游戏制作中的设计对象和设计语境。一个 GSP 可以是：

• 一句设计方向
• 一个设计风格
• 一个按钮
• 一个页面
• 一个功能
• 一个玩法机制
• 一个反馈设计
• 一个音效表现
• 一个震动表现
• 一个集合或范围
• 一个逐步细化中的设计对象

GSP 不预设抽象和实体的硬边界。所有对象都先被视为 GSP，再由 context、resolution、with、refines 和当前任务共同解释。

GSP 用来做什么

GSP 的核心作用是高效传递设计信息。

它用于支持：

• 人类和 AI 对齐游戏设计意图
• AI 与 AI 之间传递上下文
• 将模糊设计逐步细化为可实现规格
• 让编译器检查缺失、引用和阶段门槛
• 为运行时、目标平台、测试、验收等后续模块提供统一输入

GSP 不负责承载复杂的模块置信度、自我纠错、模块信誉、历史归因等机制。这些能力属于外部模块。

最小 GSP

最小合法 GSP 只有 id。

id: feedback.positive

只有 id 的 GSP 是占位声明。它表示该设计对象存在，但尚未被细化。

基础 GSP

context 用于写入核心设计内容。

id: feedback.positive
context: 积极反馈。用于让玩家在操作后获得明确、正向、值得继续的感受。

字段速览

字段	必需	作用
id	是	唯一身份。
context	否	核心设计内容。
resolution	否	清晰度 / 细化程度。
with	否	通用设计语境关系。
refines	否	单一细化来源。
type	否	辅助分类。

核心边界

• GSP 是单文件、单格式的设计协议。
• id 是唯一强制字段。
• context 可选。
• resolution 是清晰度软指标。
• with 是通用设计语境关系。
• refines 是单一细化来源。
• type 是辅助分类字段。
• GSP 不预设抽象和实体的硬边界。
• 置信度、自我纠错、模块信誉和历史归因属于外部模块，不进入 GSP 核心协议。

resolution

resolution 表示 GSP 当前的清晰度。它是软指标，由人类或 AI 执行者声明。

等级	含义
L0	占位。只有 id，或几乎没有可用设计信息。
L1	有基础语义。能说明大概是什么。
L2	有结构化设计。能说明用途、边界和关联对象。
L3	可实现规格。足够交给目标平台或生成模块执行初版实现。
L4	平台绑定规格。已经明确组件、资源、事件、配置或实现约束。
L5	已实现并通过验证。

编译器可以按阶段检查 resolution，但 resolution 不证明设计质量。

with

with 表示当前 GSP 需要与哪些 GSP 一起进入设计语境。

with 不区分使用、包含、依赖、分组、实体或抽象。

id: page.lottery.main
context: 抽奖页面，需要表达奖励期待、抽取行为和结果反馈。
with:
  - ui.button.primary
  - feedback.positive
  - style.reward.light

with 也可以带局部说明：

with:
  - id: ui.button.primary
    context: 用作主要抽奖操作入口。

refines

refines 表示当前 GSP 是对另一个 GSP 的进一步细化。

refines 只支持单一来源。

id: ui.button.reward_primary
refines: ui.button.primary
context: 奖励场景下的主按钮，比普通主按钮更强调正向点击反馈。

多个相关 GSP 写入 with。

注释

GSP 可以使用 YAML 注释。

id: style.reward.light
context: 奖励表现要轻快、积极，但不要过度刺激。
# ai: 生成时控制节奏，不堆叠过多闪光和震动。

注释是辅助信息，可被编译器或上下文裁剪流程丢弃。核心内容写入正式字段。

使用顺序

使用 GSP 时按以下顺序理解：

1. 先读 id，确认身份。
2. 再读 context，理解核心设计语义。
3. 查看 resolution，判断当前细化程度。
4. 展开 with，补齐相关设计语境。
5. 查看 refines，确认是否来自某个更早或更粗的 GSP。
6. 需要严格校验时使用 gsp.schema.json。