# GameMaker Windows Boundary

## 目标

把 GameMaker Studio 2 Windows 首期该由哪一层负责说清楚。

这份说明只覆盖首期范围：

- 授权验证
- 成就能力

不覆盖：

- room
- realtime
- 对战相关能力

## 分工

### 1. GameMaker 脚本层

这一层只负责对游戏侧暴露稳定入口。

常规接入口径也在这一层收口：

- 游戏侧默认只需要提供 `app_id`
- `desktop_pipe_endpoint` 不要求常规接入手填
- `desktop_launch_command` 不要求常规接入手填
- 这两个字段只作为调试、特殊发行形态或非标准 desktop 部署时的覆盖项保留

首期应放在这里的东西：

- `igp_init(...)`
- `igp_update()`
- `igp_is_initialized()`
- `igp_get_authorization_state()`
- `igp_is_authorization_required()`
- `igp_unlock_achievement(...)`
- `igp_report_achievement_progress(...)`
- `igp_poll_event()`

这一层还可以放：

- 初始化后的本地状态缓存
- 结果队列读取
- 对游戏更顺手的返回值整理
- 基础输入检查

这一层不应该放：

- desktop pipe 连接细节
- desktop 拉起和重试逻辑
- Windows 安装路径发现
- 命令编解码
- 真实的授权和成就请求执行

### 2. Windows 扩展层

这一层负责和本机 desktop 对话。

首期应放在这里的东西：

- desktop session attach
- desktop 自动拉起
- attach 失败后的重试窗口
- pipe 连接
- 默认 pipe endpoint
- desktop 启动命令自动发现
- 请求和响应编解码
- 错误码转换
- 授权查询
- 成就解锁
- 成就进度上报

这一层是首期真正的能力执行面。

### 3. desktop session 复用层

GameMaker 首期不重新发明一套授权和成就语义，直接复用现有 desktop session 路径。

要直接复用的内容：

- `appId`
- 授权状态
- 登录用户上下文
- 成就结果
- 统一错误码

也就是说：

- GameMaker 只管把请求送出去、把结果带回来
- 真正的能力判断仍然由 desktop session 决定
- desktop 自动拉起、启动命令发现和 attach 重试都应与 Unity 保持同口径

## 结果回到游戏的方式

首期只保留两种回传方式：

### 1. 调用返回值

适合这种情况：

- 初始化是否发起成功
- 请求是否已经送出

### 2. 事件队列

适合这种情况：

- 连接状态变化
- 授权状态变化
- 成就结果
- 错误
- 断开

队列是首期最稳的回传方式。

## 连接状态口径

首期 GameMaker 侧把连接状态收成这几种：

- `disconnected`
- `connecting`
- `connected`
- `failed`

其中：

- 开启自动附着时，`igp_init(...)` 后可以先看到 `connecting`
- 附着成功后再切到 `connected`
- 附着失败或主动断开后回到 `failed` 或 `disconnected`
- `connection_state_changed` 事件会带 `state`，方便游戏侧直接显示当前状态

## 首期边界判断

如果一段逻辑回答的是“怎么连上 desktop、怎么发请求、怎么收结果”，它属于 Windows 扩展层。

如果一段逻辑回答的是“游戏怎么更方便地拿到结果”，它属于 GameMaker 脚本层。

如果一段逻辑回答的是“授权和成就本身是什么状态”，它应该继续沿用现有 desktop session 路径，不在 GameMaker 里重写一套。

## 首期文件落点

当前先放这些最小文件：

- `../../adapters/gamemaker/runtime/README.md`
- `../../adapters/gamemaker/runtime/igp_gms2_windows_runtime.gml`
- `../../adapters/gamemaker/README.md`

后续如果补实际工程，再在这条边界上往下展开。
