@66rpg/cgmaker 0.1.16 → 0.1.18

package/README.md

@@ -22,4 +22,4 @@ Agent 调用请加 `--agent --json`（缺参退出 11、新版本退出 10、未
 
 试玩是独立游戏。模板引用只要字符串 `template_id`。`publish-template` 的 `--version`（缺省 `package.json.version`）须 1–16 位，仅小写字母、数字、`.`、`-`；须以字母或数字开头和结尾，不能有连续符号。`publish-template` 默认不带数据包；该 `data_ver` 尚无包且本地有 `assets/` 则自动上传。再带包用 `--with-assets`。`--assets` 指定绝对路径（zip 内仍为 `assets/`），在 `publish-template` 上出现即视为要上传。只改资源、不发新代码版本用 `publish-template-data`（须已有 origin；未传 `--data-ver` 则读 `package.json`，不写回）。config 不随包：放到 `~/.cgmaker/config.json`。
 
-流程给人看：仓库 `docs/users.md`。给 Agent：本包 `skill/cgmaker/SKILL.md`（怎么发）、`skill/cgmaker-identity/SKILL.md`（参数与配置指南）。
+流程给人看：仓库 `docs/users.md`、`docs/play-sdk.md`。给 Agent：本包 `skill/cgmaker/SKILL.md`（怎么发）、`skill/cgmaker-identity/SKILL.md`（参数与配置指南）、`skill/cgmaker-play-sdk/SKILL.md`（宿主 SDK）。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@66rpg/cgmaker",
-  "version": "0.1.16",
+  "version": "0.1.18",
   "description": "橙光 cgmaker 平台工具：validate-template（TS）；login / publish 等转发 cgmaker",
   "type": "module",
   "bin": {
@@ -33,7 +33,7 @@
     "picocolors": "^1.1.1"
   },
   "optionalDependencies": {
-    "@66rpg/cgmaker-win32-x64": "0.1.16"
+    "@66rpg/cgmaker-win32-x64": "0.1.18"
   },
   "devDependencies": {
     "@types/node": "^22.15.0",

package/skill/cgmaker/SKILL.md

@@ -29,7 +29,7 @@ description: 登录橙光托管平台，发布静态游戏、模板或开源工
 
 ## 何时启用
 
-登录、发游戏 `dist/`、发模板、发开源工程、货架改名。改目录 / 指纹用 `cgmaker-template-spec`，不要用本 skill 改规范。查阅模板短名、版本号、素材版本号及发布参数搭配，看 `cgmaker-identity`。
+登录、发游戏 `dist/`、发模板、发开源工程、货架改名。改目录 / 指纹用 `cgmaker-template-spec`，不要用本 skill 改规范。查阅模板短名、版本号、素材版本号及发布参数搭配，看 `cgmaker-identity`。游戏里调宿主登录 / 查用户 / 跳转 / 全屏，看 `cgmaker-play-sdk`（SDK 由发布时注入，不要把文件打进工程）。
 
 ## 不要做
 
@@ -39,6 +39,11 @@ description: 登录橙光托管平台，发布静态游戏、模板或开源工
 - `--from-dir` 的 origin 为 `local`，不能 `publish-template`。
 - 不要把试玩当成同一 `game_id` 的第二个通道。首发可以只发试玩；后补正式版会自动挂接。
 
+## 发布前请确认
+
+- **发模板或开源工程**：上传的是源码，**不含** `node_modules`。别人从平台拿到工程后，必须能按 `package.json` 把依赖装上。依赖须是公开可装的包、版本号真实存在（不要写只有你电脑上才有的包、未发布的私有包、或装不到的版本）。装不上就先改依赖再发。
+- **发模板、游戏或开源工程**：运行时**不能用在线资源**（CDN 图片、远程字体、外链脚本/样式、热链网上的音视频等）。图、音、字体、文案、数据都用工程里的本地文件：模板和开源工程放在 `assets/` 或源码内；游戏须打进 `dist/`。发现外链，先改成本地再发。
+
 ## 按业务选命令
 
 从模板开工程（用户还没有目录）：

package/skill/cgmaker-identity/SKILL.md

@@ -7,7 +7,7 @@ description: 模板与游戏的参数与标识配置指南。帮助用户理解
 
 本文档面向真实用户（模板作者与游戏创作者），详细说明在开发、发布模板与游戏时涉及的各类**配置字段**与**命令行参数**。
 
-具体操作命令的使用方式请参考 `cgmaker` 说明（须 `--agent --json`）。工程目录结构是否合规请参考 `cgmaker-template-spec`。见到退出码 10 / 11 / 12 先问用户，不要猜、不要擅自 `--skip-update`。
+具体操作命令的使用方式请参考 `cgmaker` 说明。工程目录结构是否合规请参考 `cgmaker-template-spec`。游戏内调宿主登录 / 查用户 / 跳转 / 全屏，请参考 `cgmaker-play-sdk`（SDK 由发布时注入，你不用管文件）。
 
 ## 核心原则
 
@@ -41,3 +41,5 @@ description: 模板与游戏的参数与标识配置指南。帮助用户理解
 - 模板工程一旦发布并在实际项目中使用，请勿更改 `package.json` 中的 `slug`。
 - 模板 `--version` / `package.json.version`（接口 `version_name`）须 1–16 位，仅小写字母、数字、`.`、`-`；须以字母或数字开头和结尾，不能有连续符号。不合法则拒绝发布。游戏 / 开源工程 / `--data-ver` 不套此规则。细则见 [references/fields.md](references/fields.md)。
 - 素材版本号（`--data-ver`）不会由平台自动加 1，每次更新素材时请根据规划显式指定。
+- **发模板或开源工程前**：上传的是源码、不含 `node_modules`。请确认 `package.json` 里的依赖都能在常规 npm 源装到，版本号真实可用；不要写只有本机才有的包或装不到的版本。
+- **发模板、游戏或开源工程前**：运行时请只用本地资源（图、音、字体、文案、数据放在工程内；游戏打进 `dist/`），不要用 CDN 或其它在线地址。

package/skill/cgmaker-identity/references/branches.md

@@ -2,6 +2,11 @@
 
 本文档面向真实用户，详细介绍不同业务场景下命令行功能参数的选择与搭配规则，以及各参数值如何影响发布和构建流程。
 
+发布前请先确认两件事：
+
+- **模板、开源工程**：上传不含 `node_modules`，`package.json` 里的依赖须能公开安装、版本真实可用。
+- **模板、游戏、开源工程**：运行时只用本地资源，不要用 CDN 或其它在线地址。
+
 ---
 
 ## 1. 模板发布业务场景

package/skill/cgmaker-play-sdk/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: cgmaker-play-sdk
+description: 社区播放页（宿主 H5）给游戏提供的 CgMakerSdk。在用户写游戏内登录、查当前用户/游戏、安全跳转、全屏，或问要不要把 SDK 文件打进工程时使用。
+---
+
+# 游戏宿主 SDK（给作者）
+
+游戏发布后跑在社区**播放页**里的 iframe。播放页是宿主 H5，通过 `window.CgMakerSdk` 给你登录、查用户/游戏、回社区、全屏等能力。SDK **不管玩法渲染**，画面和关卡逻辑仍由你自己的代码来画。
+
+**不要管 SDK 文件本身。** 发布游戏时，平台会自动把脚本注入到玩法 HTML。不要下载、不要拷进 `dist/`、不要自己写 `<script src="…cgmaker-game.js">`。本地 `npm run dev` 没有宿主，`ready()` 失败是正常的。
+
+登录、发版命令用 `cgmaker`。目录规范用 `cgmaker-template-spec`。接口明细见 [references/api.md](references/api.md)。
+
+## 这些情况会用到
+
+- 游戏里要登录、显示昵称头像、按是否已购做章节锁
+- 要回社区首页 / 作者页 / 上一页，或进全屏播放
+- 要弄清 SDK 文件放哪、要不要 npm 安装、要不要打进 zip
+
+## 怎么用
+
+只调 `window.CgMakerSdk`。不要自己 `postMessage`，不要读 token，不要自己请求社区登录或下单接口。
+
+```js
+const sdk = window.CgMakerSdk
+if (!sdk) {
+  // 本地预览、或尚未发布到播放页
+  return
+}
+
+const { ready, context, error } = await sdk.ready()
+if (!ready) {
+  // 约 5 秒内没等到宿主。本地开发常见，不要当成崩溃
+  console.debug(error)
+  return
+}
+
+// context.gameId / lang / user / variant（1 正式 · 2 试玩 · 3 衍生）
+if (!sdk.isLoggedIn()) {
+  try {
+    await sdk.requireLogin() // 已登录会立刻成功；用户取消会失败
+  } catch (e) {
+    if (e && e.code === 'LOGIN_CANCELLED') return
+    throw e
+  }
+}
+
+const game = await sdk.queryGame()
+// game.can_play / game.purchased：用来画你自己的关卡锁等。不要在游戏里复刻社区购买墙。
+// 不要用 game.play_url 做跳转。
+
+const stop = sdk.onChange((ctx) => {
+  // 语言或登录变化时，自己刷新 UI
+})
+// 离开页面时 stop()
+
+sdk.navigateHome()
+sdk.navigateAuthorPage()
+sdk.navigateBack()
+sdk.requestFullscreen()
+```
+
+TypeScript 可自行声明：
+
+```ts
+interface Window {
+  CgMakerSdk?: {
+    ready(): Promise<{ ready: boolean; context: unknown; error?: string }>
+    isLoggedIn(): boolean
+    requireLogin(): Promise<void>
+    queryGame(): Promise<{ can_play: boolean; purchased: boolean; play_url: string }>
+    navigateHome(): void
+    requestFullscreen(): Promise<void>
+  }
+}
+```
+
+完整字段与错误码见 [references/api.md](references/api.md)。
+
+## 请确认
+
+- 发布后才有宿主。本地预览不要造假登录、不要 mock 用户。
+- 未登录时试玩仍可玩离线内容；`queryGame` / `queryUser` 在未登录时会失败（`NOT_LOGGED_IN`）。
+- 正式版未获权时，播放页自己盖购买遮罩、**不会加载**游戏 iframe。游戏内只需处理「已经能玩」之后的自制 UI。
+- 图、音、字体仍用工程本地资源，不要靠 SDK 去拉 CDN 素材。
+
+## 不要做
+
+- 不要把 `cgmaker-game.js` 放进工程或 `dist/`
+- 不要自己写 SDK 的 `<script>`（发布时平台会注入）
+- 不要 `postMessage`、不要读或打印 token
+- 不要 `window.top.location`，也不要往 `navigateHome` / `navigateAuthorPage` / `navigateBack` 里塞 URL
+- 不要让游戏去调登录、签发 token、下单、支付
+- 不要用 `queryGame()` 返回的 `play_url` 跳转

package/skill/cgmaker-play-sdk/references/api.md

@@ -0,0 +1,81 @@
+# CgMakerSdk 接口
+
+全局对象：`window.CgMakerSdk`。发布游戏时由平台注入到玩法 HTML，页面加载后即可使用。当前版本见 `version`（如 `0.1.0`）。
+
+## 生命周期
+
+| 方法 / 属性 | 说明 |
+| --- | --- |
+| `version` | SDK 版本字符串 |
+| `ready()` | 与宿主握手。返回 `{ ready, context, error? }`。超时**不抛错**（约 5 秒，`error` 为「等待主站数据超时」） |
+| `isReady()` | 是否已拿到 context |
+| `getError()` | 最近一次握手失败文案 |
+| `getContext()` | 见下方。没有 token |
+| `onChange(fn)` | context / 登录变化时回调，用来自己刷新 UI。必须用返回值取消监听 |
+| `isLoggedIn()` | 是否已有用户 |
+| `getGameId()` / `getUser()` | 便捷读取 |
+
+`getContext()`：
+
+| 字段 | 含义 |
+| --- | --- |
+| `gameId` | 对外游戏 id |
+| `lang` | 握手时播放页语言 |
+| `user` | `{ username, nickname, avatar }` 或 `null`。`username` 来自社区用户 id |
+| `variant` | `1` 正式 / `2` 试玩 / `3` 衍生 |
+| `parentOrigin` | 仅 SDK 内部校验消息来源，不要当业务字段 |
+
+## 登录
+
+| 方法 | 说明 |
+| --- | --- |
+| `requireLogin()` | 已登录立刻成功。否则请宿主弹出社区登录。用户取消 → 错误码 `LOGIN_CANCELLED` |
+
+未登录时试玩 iframe 仍可玩离线内容。`queryGame` / `queryUser` 无登录态时得到 `NOT_LOGGED_IN`。
+
+## 查游戏 / 用户
+
+需已登录。未登录时 `queryGame` / `queryUser` 会失败（`NOT_LOGGED_IN`）。不要自己带 Cookie 去调社区接口。
+
+| 方法 | 说明 |
+| --- | --- |
+| `queryGame()` | 当前游戏货架信息 |
+| `queryUser()` | 当前用户：`username`、`nickname`、`avatar` |
+
+`queryGame()` 常用字段：
+
+- `game_id`、`owner`、`name`、`summary`、`cover_url`
+- `variant`、`parent_game_id`
+- `price_flower` / `price_cny` / `price_usd`
+- `status`：货架 `1` 启用 / `2` 禁用
+- `purchased`：对该可售主体是否已支付（作者未下单为 `false`）
+- `can_play`：当前能否玩
+- **不要用 `play_url` 做跳转**
+
+章节锁、试玩结束等自制 UI 读 `can_play` / `purchased`。不要在 iframe 里复刻社区购买墙。
+
+## 跳转与全屏
+
+只用下面这些无参方法。不要 `window.top.location`，不要往方法里塞 URL；路径由宿主自己改。
+
+| 方法 | 说明 |
+| --- | --- |
+| `navigateHome()` | 回社区首页 |
+| `navigateAuthorPage()` | 打开作者页 |
+| `navigateBack()` | 上一页（没有历史则回帖） |
+| `requestFullscreen()` | 全屏**播放器壳**，不是游戏自己改 `top` |
+| `exitFullscreen()` | 退出全屏壳 |
+
+没有公开的 `toggleFullscreen()`。
+
+## 错误码
+
+失败时抛出的错误带 `code`（`CgMakerError`）：
+
+| 码 | 何时 |
+| --- | --- |
+| `NOT_LOGGED_IN` | 未登录，或查询接口鉴权失败 |
+| `LOGIN_CANCELLED` | 用户关掉登录 |
+| `TIMEOUT` | 握手或桥接超时（`ready()` 超时不抛错，只给 `ready: false`） |
+| `FULLSCREEN_DENIED` | 浏览器拒绝全屏 |
+| `FAILED` | 其它失败 |

package/skill/cgmaker-template-spec/SKILL.md

@@ -5,7 +5,7 @@ description: 橙光 cgmaker 模板工程规范。在用户改目录或脚本名
 
 # cgmaker 模板工程规范
 
-这是**模板工程规范**，不是平台全部规范，也不是某个玩法模板自己的 skill。玩法说明在工程根 `skill/SKILL.md`（若有）。登录、怎么敲命令用 `cgmaker`。模板短名、版本号、素材版本号及发布参数搭配，用 `cgmaker-identity`。不要在本 skill 里做发布决策。
+这是**模板工程规范**，不是平台全部规范，也不是某个玩法模板自己的 skill。玩法说明在工程根 `skill/SKILL.md`（若有）。登录、怎么敲命令用 `cgmaker`。模板短名、版本号、素材版本号及发布参数搭配，用 `cgmaker-identity`。游戏内调宿主 SDK 用 `cgmaker-play-sdk`（文件由发布时注入，不要打进工程）。不要在本 skill 里做发布决策。
 
 ## 何时启用
 
@@ -52,3 +52,5 @@ npx cgmaker publish-template-data --data-ver 2 --assets C:\path\to\assets
 ```
 
 过不过关只认 `cgmaker validate-template`。发布游戏用 `npx cgmaker publish`（只认 `dist/`）；试玩用 `npx cgmaker publish --demo`（先 `build:demo`，可无正式版首发）。命令怎么敲见 `cgmaker`；功能参数与场景搭配见 `cgmaker-identity`。上传素材时没写 `--data-ver` 会问你（可沿用 `package.json` 里的号，不会自动 +1）；没法提问时必须自己写上或保证 `package.json` 已有 `data_ver`。`--data-summary` 可选，空则不写接口。`publish-template` 与 `publish-template-data` 都可用 `--assets` 指定素材目录的完整路径（传上去以后包里仍然叫 `assets/`）。
+
+发布模板或开源工程前：zip 不含 `node_modules`，`package.json` 里的依赖必须能装、版本必须真实可用。发布模板、游戏或开源工程前：运行时只用本地资源，不要热链 CDN 或其它在线地址。

package/skill/cgmaker-template-spec/references/dist.md

@@ -4,9 +4,9 @@
 
 正式版与试玩都打进**同一个** `dist/`（试玩会覆盖正式产物，发完再 `build` 另一份）。不要 `dist-demo/`。试玩由 `scripts.build:demo` 从 `assets/` 切片产出。见 [layout.md](layout.md)。
 
-`npx cgmaker publish` 上传正式版；`npx cgmaker publish --demo` 上传试玩。两次都只认当前 `dist/`。
+`npx cgmaker publish` 上传正式版；`npx cgmaker publish --demo` 上传试玩。两次都只认当前 `dist/`。发布时平台会向玩法 HTML **自动注入**宿主 SDK，不要把 `cgmaker-game.js` 拷进 `dist/`，也不要自己写 SDK 的 `<script>`。游戏里只调 `window.CgMakerSdk`，见 `cgmaker-play-sdk`。
 
-入口按 **通用首页 → 启动页 / 方向首页 → 游戏页** 拆 HTML。所有 HTML 的脚本/样式必须是相对路径（Vite `base: './'`），禁止 `src="/assets/..."`（那是站点根路径，不是源码里的内容目录 `assets/`）。打包器必须 `base: './'`。目录只能叫 `dist/`，不要 `build/` / `out/` / `www/`。Vite 可用 `publicDir: "assets"`，避免和 hashed 文件抢 `dist/assets/`。
+入口按 **通用首页 → 启动页 / 方向首页 → 游戏页** 拆 HTML。所有 HTML 的脚本/样式必须是相对路径（Vite `base: './'`），禁止 `src="/assets/..."`（那是站点根路径，不是源码里的内容目录 `assets/`）。打包器必须 `base: './'`。脚本、样式、字体、图片一律打进 `dist/` 的本地文件，禁止运行时再去拉 CDN 或其它在线地址。目录只能叫 `dist/`，不要 `build/` / `out/` / `www/`。Vite 可用 `publicDir: "assets"`，避免和 hashed 文件抢 `dist/assets/`。
 
 ✅ 必有 · ⭕ 可选。
 

package/skill/cgmaker-template-spec/references/layout.md

@@ -51,12 +51,12 @@
 - 根目录 `data/`、`theme/`（进 `assets/`）
 - `template.yaml` / `template.yml`（身份在 `package.json` 的 `slug`）
 - 产物目录叫 `build/`、`out/`、`www/`（要发静态站只能是 `dist/`）
-- 运行时热链远程素材（除非 skill 写明 CDN 例外）
+- 运行时热链远程素材（CDN 图、远程字体、外链脚本/样式、网上音视频等）；图、音、字体、文案、数据一律用本地 `assets/` 或打进 `dist/` 的文件
 - 模板根目录 `scripts/` 文件夹（和 npm scripts、`skill/scripts/` 撞车）
 - `package.json` 设置 `bin`、写 `"packageManager"`
 - 作者工程依赖 `@66rpg/cgmaker-template-*`（create 只拷源码）
 
-`devDependencies` 必须有 `@66rpg/cgmaker`（脚手架写入；模板 zip 也应带上）。本仓库 `templates/` 下的样板永久 `private`，不是 npm 商品。
+`devDependencies` 必须有 `@66rpg/cgmaker`（脚手架写入；模板 zip 也应带上）。本仓库 `templates/` 下的样板永久 `private`，不是 npm 商品。模板 zip **不含** `node_modules`：`dependencies` / `devDependencies` 必须是别人按 `package.json` 能装到的公开包，版本号须真实存在。
 
 ## package.json
 
@@ -120,7 +120,7 @@ npx cgmaker publish-template-data --data-ver 2 --assets C:\path\to\assets
 
 **不要打进代码 zip：** `assets/`、`node_modules/`、`dist/`、`.git/`、`.cgmaker/`（包内一律丢弃，防伪造 origin / game.json）、`.agents/` `.cursor/` `.claude/` 等 `skill-targets`、`preview/`、`tests/`、根目录 `scripts/`、`build/` `out/` `www/`。资源 zip 只含 `assets/`（`publish-template` / `publish-template-data` 的 `--assets` 可指定其它绝对路径，zip 内仍为 `assets/`）。
 
-平台 skill（`cgmaker`、`cgmaker-template-spec`、`cgmaker-identity`）来自 `@66rpg/cgmaker` 包，不来自模板 zip。zip 里的 `skill/` 只可能是玩法 skill。
+平台 skill（`cgmaker`、`cgmaker-template-spec`、`cgmaker-identity`、`cgmaker-play-sdk`）来自 `@66rpg/cgmaker` 包，不来自模板 zip。zip 里的 `skill/` 只可能是玩法 skill。
 
 ## 改哪里