diff --git a/apps/ai-game-creator-shell/src-tauri/resources/agc-skills/agc-game-production-workflow/SKILL.md b/apps/ai-game-creator-shell/src-tauri/resources/agc-skills/agc-game-production-workflow/SKILL.md index 77ee538c0..48af3d09f 100644 --- a/apps/ai-game-creator-shell/src-tauri/resources/agc-skills/agc-game-production-workflow/SKILL.md +++ b/apps/ai-game-creator-shell/src-tauri/resources/agc-skills/agc-game-production-workflow/SKILL.md @@ -16,7 +16,7 @@ Use `agc_apply_patch` for targeted source edits with the official Add/Delete/Upd 1. **Brief and scope** — Read the current planning output and project instructions. Record this turn's required game loop, actions, visuals, viewports and completion evidence. Use a bounded first-delivery scope; do not add new features or artwork during final review. For a new Web project, start from the prepared project scaffold. Do not repeat environment preflight unless new evidence requires it; `agc_environment_check` remains available for diagnosis. If blocked, report the toolchain/browser issue; do not download a second toolchain or search the whole machine. Read-only diagnosis and editor projects do not require this Web preflight. 2. **Project and asset inventory** — Inspect the existing project structure and call `agc_list_registered_assets` (and `agc_list_project_files` when needed). Record which requested visuals already have usable registered identities and which are missing. Do not invent asset identities from filenames. 3. **Visual production** — For missing or unsuitable visuals, call the reviewed `agc_tools` workflow: use `taonier_prepare_game_art` for a complete package, or `agc_generate_image` / `agc_edit_image` for focused assets. Read returned paths, identities, and warnings. A warning or partial package requires a narrower retry or independent assets before continuing. -4. **Game implementation** — Implement the complete playable loop and wire the returned project-relative asset paths into the actual runtime. Every required character, object, background, effect, and UI visual must have a real source or an explicit brief-level decision to remain code-native. Generated assets that are unused, documentation-only, or replaced by emoji/CSS placeholders do not satisfy this stage. +4. **Game implementation** — Implement the complete playable loop and wire the returned project-relative asset paths into the actual runtime. Every required character, object, background, effect, and UI visual must have a real source or an explicit brief-level decision to remain code-native. Generated assets that are unused, documentation-only, or replaced by emoji/CSS placeholders do not satisfy this stage. Web games (Phaser 4 / three.js) must also satisfy the 运行画面点选契约 in `agc-web-game-development`: publish the read-only engine handle, load Phaser images with `loader.imageLoadType='HTMLImageElement'`, annotate asset-rendered objects with the manifest identity, and keep media at a stable dist path aligned with `localPath`; without it 点选 only degrades to a region reference without an asset id. 5. **Build and local verification** — After the needed implementation, record the build through `agc_run_validation` with `purpose=build`, `program=npm`, `arguments=["run","build"]` and the package `cwd` (`game` for a new Web project). Confirm the actual playable entry under `dist` and fix build or asset-loading failures before preview. Use `purpose=test` for a declared focused test. A successful raw shell command does not replace the recorded `agc_run_validation` build result. 6. **Validation** — Use the approved browser tool and fixed scenarios. Call `agc_browser_playtest` with `mode=visual` for art/layout checks or `mode=gameplay` for fixed real-input/state/restart checks. Use `agc_run_validation` for existing focused Node/npm tests when needed. Fix blocking findings and rerun only the affected layer after an actual change. Do not rerun a whole playthrough for a color or documentation edit. A visual pass does not establish gameplay or complete-level coverage. 7. **Delivery** — Once required evidence matches the current input, stop and report the observed validation scope. Do not start another side effect, art cycle, or polish cycle. A fixed scenario is not a full long-level playthrough. List new nonblocking ideas as follow-up work. Missing required evidence remains an explicit gap. diff --git a/apps/ai-game-creator-shell/src-tauri/resources/agc-skills/agc-web-game-development/SKILL.md b/apps/ai-game-creator-shell/src-tauri/resources/agc-skills/agc-web-game-development/SKILL.md index 7fef9c8c8..89b0088de 100644 --- a/apps/ai-game-creator-shell/src-tauri/resources/agc-skills/agc-web-game-development/SKILL.md +++ b/apps/ai-game-creator-shell/src-tauri/resources/agc-skills/agc-web-game-development/SKILL.md @@ -27,6 +27,21 @@ Make targeted source changes with `agc_apply_patch` using the official patch syn When implementing a new game loop or a broad gameplay revision, read `references/game-quality-checklist.md`. +## 运行画面点选契约（运行态素材身份） + +客户端「点选素材」把运行画面里点中的对象落成一条 `runtime-region` 引用；命中已登记素材时引用带上该素材的稳定 id，显示名与 `@` 候选、资源卡「引用」一致。Phaser 4 与 three.js 项目都要满足下面四条，新生成的游戏才对点选可用。 + +1. **发布只读引擎句柄**：引擎实例创建后发布一次，只服务点选与调试，不承载业务状态。句柄缺失或 `engine` 不是 `phaser` / `three` 时点选按第 4 条退化。 + - Phaser：`window.__GENARRATIVE_PREVIEW_GAME__ = { engine: 'phaser', game };` + - three.js：`window.__GENARRATIVE_PREVIEW_GAME__ = { engine: 'three', THREE, scene, camera, renderer };`（`THREE` 是 `import * as THREE from 'three'` 的命名空间，点选要靠它做射线与包围盒） +2. **Phaser 图片用 Image 标签装载**：游戏配置固定 `loader: { imageLoadType: 'HTMLImageElement' }`。默认的 XHR 装载把贴图地址换成会话内临时地址，点选读不回原始素材路径；这类项目只能靠第 3 条的显式标注。 +3. **给渲染对象标注素材身份**：用已登记素材渲染的对象要带上 manifest 的稳定身份，值只取 `agc_list_registered_assets` 返回的 `localAssetId` / `localPath`，不自行编造、不改写文件名。 + - Phaser：`sprite.setData('genarrativeResourceId', '')`，或 `sprite.setData('genarrativeResourcePath', '')`；两者都给时 id 优先。 + - three.js：`mesh.userData.genarrativeResourceId` / `mesh.userData.genarrativeResourcePath`；GLB、分组或关卡导入的模型给 `traverse` 到的实际渲染 mesh 标注。 +4. **素材进 dist 走稳定路径**：素材放进游戏包 `public/`（脚手架 Vite 配置的默认 `publicDir`，原样拷贝、不加 hash），并保持与 `localPath` 相同的相对段（项目根 `assets/hero.png` → `game/public/assets/hero.png`，运行时用 `./assets/hero.png` 加载）。不要 `import` 图片或模型：构建产物名会带内容 hash，与 manifest 路径对不上，点选只剩文件名兜底，重名素材直接丢掉。 + +点选只在用户按下时读取上述信息；不满足时**不报错、不伪造 id**，退化为不带素材的区域引用，引用仍能插入、能发送。这四条就是点选能力的验收面。 + # Notes * Do not edit UI Editor JSON directly. If the user exports `ui/generated-.js`, read that file instead; its embedded documentation explains how to use it. diff --git a/apps/ai-game-creator-shell/src-tauri/resources/agc-skills/agc-web-game-development/references/game-quality-checklist.md b/apps/ai-game-creator-shell/src-tauri/resources/agc-skills/agc-web-game-development/references/game-quality-checklist.md index f352481b0..885affe0e 100644 --- a/apps/ai-game-creator-shell/src-tauri/resources/agc-skills/agc-web-game-development/references/game-quality-checklist.md +++ b/apps/ai-game-creator-shell/src-tauri/resources/agc-skills/agc-web-game-development/references/game-quality-checklist.md @@ -11,3 +11,4 @@ - 在构建后的实际页面检查桌面、移动和 resize：比较 canvas 与游戏父容器的中心，预期居中时水平/垂直误差不超过 1 CSS px，并检查画面没有溢出或意外滚动条。偏移先修游戏 CSS/scale 配置，不要靠调整预览位置掩盖布局问题。 - HUD and overlays reserve space and do not cover essential interactive content. - Requested Taonier art is visibly integrated into the core experience when available. +- 运行画面点选契约已满足：发布只读引擎句柄、Phaser 图片用 Image 标签装载、素材渲染对象带 manifest 身份标注，且素材在 dist 里保持与 `localPath` 对齐的稳定路径（见主 Skill「运行画面点选契约」）。 diff --git a/apps/ai-game-creator-shell/src-tauri/resources/agc-skills/manifest.json b/apps/ai-game-creator-shell/src-tauri/resources/agc-skills/manifest.json index 12678da03..028881a46 100644 --- a/apps/ai-game-creator-shell/src-tauri/resources/agc-skills/manifest.json +++ b/apps/ai-game-creator-shell/src-tauri/resources/agc-skills/manifest.json @@ -1,6 +1,6 @@ { "schemaVersion": "agc-skill-pack.v1", - "version": "2026-08-26.37", + "version": "2026-08-26.38", "skills": [ { "name": "agc-unity-editor", @@ -59,7 +59,7 @@ "agents/openai.yaml", "references/workflow-contract.md" ], - "sha256": "6c3dac5d6ad693cd854347dbc2c202eb2c6ebed336468daa4ccfb55c08698e0b" + "sha256": "5672e5f931464a90b26bf82e68e1c80577ce3efb29cc0c3234a93c4c71e5769d" }, { "name": "agc-project-structure", @@ -121,7 +121,7 @@ "agents/openai.yaml", "references/game-quality-checklist.md" ], - "sha256": "855803443e6b76e4271df1b4207c8836a7634438814d61e66da08ed27a44ae8c" + "sha256": "55fb4e14fba3682028b4508ac1721a907d1196cf7527113ebb4977d6025d0cdc" }, { "name": "agc-browser-playtest", diff --git a/docs/project-memory/plans/【实施计划】AGC运行画面点选引擎适配-2026-10-04.md b/docs/project-memory/plans/【实施计划】AGC运行画面点选引擎适配-2026-10-04.md index 5f6680636..49262159d 100644 --- a/docs/project-memory/plans/【实施计划】AGC运行画面点选引擎适配-2026-10-04.md +++ b/docs/project-memory/plans/【实施计划】AGC运行画面点选引擎适配-2026-10-04.md @@ -22,7 +22,7 @@ 明确不修改： - `runtime-region` 引用契约、`genarrative.local-preview-inspect.v1` 消息版本号、`LocalGamePreviewFrame.tsx` 的解析与净化、Rust `direct_codex_user_item` 的校验口径（不新增字段；若实测必须加字段，单独评审）。 -- `packages/shared`、manifest / 版本绑定 / 素材替换链路、AGC 玩法 Skill 与 Runtime Prompt、模板 zip 发布与线上索引。 +- `packages/shared`、manifest / 版本绑定 / 素材替换链路、Runtime Prompt 文案、模板 zip 发布与线上索引（AGC 玩法 Skill 的生成期契约属阶段二，见下 `## 阶段二进展`）。 - DOM 点选语义与 `enabled / disabled / cancelled` 协议。 ## 实现顺序 @@ -62,3 +62,13 @@ - 脚手架与三个起步模板发布只读引擎句柄：`DEFAULT_GAME_SCRIPT_JS`、`phaser-2d-starter`、`threejs-3d-starter`、`blank-3d-scene`。 - 自动化验证通过：五个前端用例文件（`runtimeInspectEngines` / `runtimeInspectResourceMatch` / `localGamePreviewFrame` / `resourceReferenceInput` / `appSurface`）292 passed / 9 skipped（301 项）；`npm run agc:typecheck` 通过；`cargo test --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml --offline -- preview` 通过（43 passed）。 - 分四个提交落盘：6c6850352（桥与引擎档）、6264fed6b（宿主匹配）、ab518ea57（脚手架与模板）、f729203c6（规范与踩坑）；验收证据见里程碑文档。 + +## 阶段二进展 + +阶段一让点选能识别素材，但可用性依赖玩法满足三条约定（发布句柄、Phaser 用 Image 装载、对象标注素材身份）；阶段二把这几条写进**生成期契约**，新生成的 Phaser 4 / three.js 项目不改代码即可点出素材。同一 PR 续推，`template.zip` 与线上索引仍未重新发布。 + +- 主源（唯一写全契约处）：`resources/agc-skills/agc-web-game-development/SKILL.md` 新增「运行画面点选契约（运行态素材身份）」四条——发布只读引擎句柄（`{ engine:'phaser', game }` / `{ engine:'three', THREE, scene, camera, renderer }`）、Phaser 固定 `loader: { imageLoadType: 'HTMLImageElement' }`、给素材渲染对象标注 manifest 身份（Phaser `setData('genarrativeResourceId' | 'genarrativeResourcePath', …)`，three.js `mesh.userData.…`，值只取 `agc_list_registered_assets` 的 `localAssetId` / `localPath`）、素材进 dist 走与 `localPath` 对齐的稳定路径（`public/` 原样拷贝，不用 `import` 的 hash 产物名）；并写明不满足时不报错、不伪造 id、退化为不带素材的区域引用（= 验收面）。 +- 派生副本只补指针，不复制契约：`agc-web-game-development/references/game-quality-checklist.md` 增加一条勾选项；`agc-game-production-workflow/SKILL.md` 第 4 步（Game implementation）指向该契约（新游戏编排必读）。 +- 指纹同步：`npm run agc:skill-pack:sync` 更新 `resources/agc-skills/manifest.json` 的 `version` 与两个 skill 的 `sha256`；`skill_pack.rs` 逐文件 `include_bytes!`，因此**未新增 skill 文件、未改任何 Rust**。 +- 验证：`npm run agc:typecheck`（含 skill-pack 指纹校验）、`node scripts/check-doc-index.mjs`、`npm run check:encoding`、`git diff --check` 全部通过（退出码与结论行见 PR 评论）。 +- 冻结面不变：`preview.rs`、`resources/preview/local-preview-fit.js`（sha256 仍为 `6276ac48…917a`）、宿主匹配、脚手架与模板源均未改；未合并主线。 diff --git a/docs/project-memory/plans/【里程碑】AGC运行画面点选引擎适配-2026-10-04.md b/docs/project-memory/plans/【里程碑】AGC运行画面点选引擎适配-2026-10-04.md index 406796a10..fe565a475 100644 --- a/docs/project-memory/plans/【里程碑】AGC运行画面点选引擎适配-2026-10-04.md +++ b/docs/project-memory/plans/【里程碑】AGC运行画面点选引擎适配-2026-10-04.md @@ -23,7 +23,7 @@ ## 不在范围内 -- 生成期契约落位：把句柄发布与对象素材标注写进 AGC 玩法 Skill / Runtime Prompt，并重新发布模板产物（`template.zip` 与线上索引）——另立里程碑。 +- 生成期契约落位：把句柄发布与对象素材标注写进 AGC 玩法 Skill（**同一 PR 的阶段二**，见实施计划 `## 阶段二进展`）；重新发布模板产物（`template.zip` 与线上索引）仍不在本次范围内。 - 运行期资源使用关系持久化（不记录"某素材在某位置被用过"，不注入代码、不写侧车）。 - Cocos Creator / Godot / Unity 的点选；纯 2D canvas 引擎与 Babylon.js。 - `runtime-region` 引用契约、预览消息版本号、Rust `resourceIds` 校验、资源选中与信息栏判据的任何变化。 diff --git a/docs/【功能说明】AGC聊天素材引用-2026-09-08.md b/docs/【功能说明】AGC聊天素材引用-2026-09-08.md index ab163fb6e..a53cd241e 100644 --- a/docs/【功能说明】AGC聊天素材引用-2026-09-08.md +++ b/docs/【功能说明】AGC聊天素材引用-2026-09-08.md @@ -74,6 +74,7 @@ AGC 聊天输入框支持以结构化引用标记当前项目已登记素材， - 不做像素级或颜色拾取，不为了识别素材去改写玩法源码、资源文件或渲染结果。 - **Phaser 4 默认装载下贴图地址不可得**：Phaser 4 默认用 XHR 装载图片，贴图元素上的地址是会话内的临时地址，读不回原始素材路径。这类项目**必须由玩法显式标注素材身份**才能点出素材；没有标注就按第 4 条退化（退化为不带素材的区域引用），不猜。 - **只认玩法发布的只读引擎句柄**：预览页没有发布该句柄、或句柄声明的引擎类型不在支持范围内时，一律退化为不带素材的区域引用；宿主不通过扫描全局对象去猜引擎。 +- **生成期契约落在 AGC 玩法 Skill**：句柄发布、Phaser 图片的 Image 装载、素材渲染对象的身份标注、素材在 dist 的稳定路径这四条写进 `agc-web-game-development`（「运行画面点选契约」，本里程碑阶段二，同一 PR 落位），生成期即按契约产出；本能力说明不承诺历史项目自动具备，也不改写既有项目。 ### 验收标准与证据