create-pixifact 0.17.0 → 0.19.0

package/README.md

@@ -11,6 +11,17 @@ bun install
 bun run dev
 ```
 
+创建包含基础游戏流程和可替换 UI 库的项目：
+
+```bash
+bun create pixifact my-game --template game
+cd my-game
+bun install
+bun run dev
+```
+
+`game` 模板默认打开 Button / Panel / Dialog / ProgressBar 的交互展台，演示按钮禁用、点击反馈、进度边界和弹窗。底部入口提供竖屏 Web 游戏／暂停／结算流程，包含纯 TypeScript 游戏状态、页面销毁与订阅清理、最高分保存。模板只提供一套基础 UI，用户直接覆盖 `assets/ui/button.png` 和 `assets/ui/panel.png` 即可更换对应背景，保持 96 × 96 尺寸与四边各 24 像素的九宫格边距。详细模块和自定义方式见 [模板说明](./templates/game/README.md)。默认不指定 `--template` 时仍创建最小项目。
+
 生成的项目包含：
 
 - `pixifact.project.json`
@@ -27,7 +38,7 @@ bun run dev
 
 | 命令 | 用途 |
 | --- | --- |
-| `bun run dev` | 启动 Web 开发服务 |
+| `bun run dev` | 启动 Web 开发服务和 Bun Inspector，均支持局域网访问 |
 | `bun run build` | 构建 Web 生产版本 |
 | `bun run compile` | 独立编译 `.scene` 到 `.pixifact/generated` |
 | `bun run editor` | 启动 Pixifact 编辑器 |
@@ -35,6 +46,10 @@ bun run dev
 
 模板的 `.env` 默认设置 `VITE_PLATFORM=web`。`dev` 和 `build` 会自动处理 Scene 编译，也可以使用 `compile` 单独编译 Scene。
 
+`dev` 脚本直接执行 `pixifact dev`，CLI 会自动启用 Bun Inspector 并在终端输出调试地址。用户和 Agent 直接运行 `bun run dev` 即可同时启动开发服务和调试入口。
+
+同一局域网设备可打开启动结果 `urls.network` 中的游戏地址。远程连接 Inspector 时，将 Bun 输出的调试链接中的 `0.0.0.0` 替换为开发电脑的局域网 IP，保留端口和路径。
+
 ## 观察运行中的游戏
 
 ```bash

package/dist/createPixifactProject.d.ts

@@ -1,11 +1,12 @@
+export type PixifactProjectTemplate = 'minimal' | 'game';
 export interface CreatePixifactProjectOptions {
     cwd?: string;
     name: string;
-    template?: 'minimal';
+    template?: PixifactProjectTemplate;
 }
 export interface CreatePixifactProjectResult {
     name: string;
     root: string;
-    template: 'minimal';
+    template: PixifactProjectTemplate;
 }
 export declare function createPixifactProject(options: CreatePixifactProjectOptions): Promise<CreatePixifactProjectResult>;

package/dist/index.js

@@ -1,20 +1,36 @@
 #!/usr/bin/env bun
 import { createPixifactProject } from './createPixifactProject';
+import { parseArgs } from 'node:util';
 function usage() {
     return [
         '用法：',
-        '  bun create pixifact <project-name>',
+        '  bun create pixifact <project-name> [--template minimal|game]',
+        '  minimal：最小 Scene 项目；game：基础游戏框架和一套基础 UI。',
         '',
     ].join('\n');
 }
-const name = process.argv[2];
-if (!name || name === '--help' || name === '-h') {
-    process.stdout.write(usage());
-    process.exitCode = name ? 0 : 1;
-}
-else {
-    try {
-        const result = await createPixifactProject({ name });
+try {
+    const { values, positionals } = parseArgs({
+        args: process.argv.slice(2),
+        allowPositionals: true,
+        options: {
+            template: { type: 'string', default: 'minimal' },
+            help: { type: 'boolean', short: 'h' },
+        },
+    });
+    const name = positionals[0];
+    if (!name || values.help) {
+        process.stdout.write(usage());
+        process.exitCode = values.help ? 0 : 1;
+    }
+    else {
+        if (positionals.length !== 1)
+            throw new Error('请指定一个项目名称。');
+        const template = values.template;
+        if (template !== 'minimal' && template !== 'game') {
+            throw new Error('模板必须为 minimal 或 game。');
+        }
+        const result = await createPixifactProject({ name, template });
         process.stdout.write(`已创建 ${result.name}：${result.root}\n`);
         process.stdout.write('已初始化 Git 仓库，并安装 Pixifact skill 到 .agents/skills/pixifact/。\n');
         process.stdout.write([
@@ -23,17 +39,21 @@ else {
             '  bun install',
             '',
             '项目命令：',
-            '  bun run dev      启动 Web 开发服务',
+            '  bun run dev      启动 Web 开发服务（预览和 --inspect 调试均支持局域网）',
             '  bun run build    构建 Web 生产版本',
             '  bun run compile  编译 Scene',
             '  bun run editor   启动 Pixifact 编辑器',
             '  bun run validate 校验项目',
             '',
         ].join('\n'));
+        if (template === 'game') {
+            process.stdout.write('  bun run typecheck     检查游戏 TypeScript\n');
+            process.stdout.write('更换 UI 素材：直接替换 assets/ui/ 中的同名 PNG，保持图片尺寸和九宫格边距；然后重启开发服务。详见 README。\n');
+        }
     }
-    catch (error) {
-        process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
-        process.exitCode = 1;
-    }
+}
+catch (error) {
+    process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+    process.exitCode = 1;
 }
 export { createPixifactProject };

package/dist/skills/pixifact/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: pixifact
-description: 用于下游 Pixifact 游戏项目：编辑项目相对 .scene 文件、维护同名 Scene 脚本契约、运行 validate / compile 并截取任意 Scene 的静态预览；以及在 Vite Web 开发模式下通过 pixifact runtime 读取运行中游戏的 PixiJS 节点、业务状态和日志，发送标准输入并验证行为。适用于 UI、HUD、menu、轻量 Scene、交互逻辑、视觉检查、运行时验证和诊断任务。
+description: 用于下游 Pixifact 游戏项目：编辑项目相对 .scene 文件、维护同名 Scene 脚本契约、运行 validate / compile 并截取任意 Scene 的静态预览；读取 Editor 当前 Scene 和 selection、确认修改同步并截图；以及在 Vite Web 开发模式下通过 pixifact runtime 读取运行中游戏的 PixiJS 节点、业务状态和日志，发送标准输入并验证行为。适用于 UI、HUD、menu、轻量 Scene、Editor 协作、交互逻辑、视觉检查、运行时验证和诊断任务。
 ---
 
 # Pixifact
@@ -9,7 +9,7 @@ description: 用于下游 Pixifact 游戏项目：编辑项目相对 .scene 文
 
 ## Scene 工作流
 
-处理 Scene、UI、HUD、menu、layout 或视觉资产任务时，优先编辑项目相对 `.scene` 源文件。
+处理 Scene、UI、HUD、menu、layout 或视觉资产任务时，优先编辑项目相对 `.scene` 源文件。用户指向 Editor 当前 Scene 或选中节点时，先按下面的「Editor 协作工作流」确定目标。
 
 1. 读取 `package.json`、`pixifact.project.json` 和目标 `.scene` / `.ts` 文件。
 2. 开始任何非纯查阅的 Scene 改动前，按 `references/scene-authoring-decisions.md` 做短决策；新建或大改 Scene 时先读全文。
@@ -37,11 +37,11 @@ description: 用于下游 Pixifact 游戏项目：编辑项目相对 .scene 文
    ```bash
    pixifact scene validate --all
    ```
-10. 视觉任务在校验通过后截取目标 Scene，不需要启动 Editor：
+10. 视觉任务默认在校验通过后直接截取指定 Scene，Editor 未启动时也可使用：
    ```bash
    pixifact scene screenshot --scene src/scenes/MainMenu.scene --output /tmp/main-menu.png
    ```
-   查看 PNG 后继续调整 `.scene`，直到静态画面符合目标；此命令需要本机 Google Chrome，不执行游戏脚本。游戏运行状态用 `runtime screenshot` 验证。
+   命令从磁盘读取目标 `.scene`、配对脚本接口和项目资源，不需要启动 Editor 或游戏，也不切换已打开的 Editor Scene。查看 PNG 后继续调整 `.scene`，直到静态画面符合目标；此命令需要本机 Google Chrome，不执行游戏脚本。游戏运行状态用 `runtime screenshot` 验证。
 11. 校验通过后编译：
    ```bash
    pixifact compile-scenes
@@ -58,6 +58,29 @@ description: 用于下游 Pixifact 游戏项目：编辑项目相对 .scene 文
 
 默认项目根是当前工作目录；不在项目根运行时再加 `--project-root <path>`。项目自己的 `bun run build`、`bun run dev` 等命令只作为后续检查或预览入口。
 
+## UI 最佳实践
+
+- 九宫格 UI 素材推荐每张 PNG 对应一个 `.scene` / `.ts` 文件对，在 Scene 内集中设置 `NineImage` 的图片路径和四边切片参数；按钮、面板等调用方直接引用该 Scene，只设置位置和盒子尺寸。封装、引用和换图示例见 [NineImage](references/scene-objects.md#nineimage)。
+- `HBoxContainer`、`VBoxContainer`、`GridContainer` 会接管直接子节点的 `x/y`；横排的 `y`、竖排的 `x` 也会被对齐结果覆盖。需要单独微调时，让一个明确尺寸的 `Group` 参与排列，再调整其内部节点。示例和占位尺寸规则见 [排列容器中的单独偏移](references/scene-hierarchy-patterns.md#排列容器中的单独偏移)。
+
+## Editor 协作工作流
+
+静态视觉检查沿用上面的 `scene screenshot` 流程。用户需要打开 Editor 浏览、选择或人工微调时，在项目根目录运行 `pixifact editor`；已运行时复用。用户指向已打开 Editor 的当前 Scene、选中节点或当前画面时：
+
+1. 修改前读取只读上下文：
+   ```bash
+   pixifact editor context
+   ```
+   核对 `projectRoot`，用 `scene.path` 确定活动 Scene，读取 `scene.revision`、`scene.syncState`、`selection` 和 `openScenes`。`selection.kind="scene"` 表示 Scene 根；`kind="node"` 时用返回的 `locator` 和节点 `id` 定位源码，不凭名称猜目标。需要节点详情时使用 `pixifact node inspect --scene <scene.path> --node <locator>`；层级变化后重新获取 locator。
+2. 检查目标文件的同步状态。活动 Scene 未同步时 `editor context` 会拒绝返回上下文；成功返回也不代表其他标签已同步，编辑其他已打开 Scene 前检查 `openScenes` 中对应路径的 `syncState`。`saving` 或 context 正在更新时等待后重读；`unsaved` 或 `conflict` 时先让用户保存草稿或解决冲突，再重新读取 context 和磁盘源文件；`error` 时结合 CLI 错误和 Editor 提示排查。保留用户未保存内容，不擅自覆盖或放弃草稿。没有活动 Editor 或 Scene 时，已知目标路径就直接走 Scene 工作流；任务依赖当前选择且目标不明确时，先请用户明确目标。
+3. 按 Scene 工作流直接编辑目标 `.scene` 和必要的同名 `.ts`，运行 validate、compile 和项目最小相关检查。`editor context` 不提供修改入口。
+4. 外部改动会自动刷新已同步的标签；有未保存修改的标签会保留草稿，保存时可能出现版本冲突。改完后再次运行 `pixifact editor context`，确认活动 `scene.path` 仍是目标且 `scene.syncState="synced"`；成功返回表示该 context 的 revision 与当前磁盘文件一致。若仍在更新，等待后重读；若用户已切换 Scene，不能据此宣称目标 Scene 的预览已确认。
+5. 需要检查当前 Editor 画面时，确认目标 Scene 已同步且 `scene.previewState="ready"`，再截图并查看 PNG：
+   ```bash
+   pixifact editor screenshot --output /tmp/editor-scene.png
+   ```
+   核对截图返回的 Scene 路径和 revision，避免把切换后的其他 Scene 当成目标。截图使用 Scene 设计尺寸，不包含 Editor UI 或选择框，不受画布 zoom / pan 影响，也不执行项目脚本。检查指定 Scene 的磁盘版本时用 `scene screenshot --scene <path>`；检查游戏运行后的状态时用 `runtime screenshot`。
+
 ## 运行时验证工作流
 
 任务影响 Vite Web 游戏行为、交互或运行时状态，或者需要诊断运行中游戏时，先完整阅读 `references/runtime-observation.md`，再按以下顺序操作：

package/dist/skills/pixifact/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "Pixifact"
-  short_description: "在 Pixifact 项目中编辑 Scene、维护脚本契约并验证运行中游戏"
-  default_prompt: "使用 $pixifact 编辑下游游戏的 Scene 或逻辑，并通过 CLI 校验和 Runtime 验证运行结果。"
+  short_description: "在 Pixifact 项目中编辑 Scene、与 Editor 协作并验证运行中游戏"
+  default_prompt: "使用 $pixifact 编辑下游游戏的 Scene 或逻辑，需要时读取 Editor 当前 Scene 和选择，并通过 CLI 校验、预览与 Runtime 验证结果。"

package/dist/skills/pixifact/references/scene-authoring-decisions.md

@@ -41,6 +41,7 @@ Decision:
 优先不拆。只有满足下面至少一条时才新建子 Scene：
 
 - 会在多个父 Scene 中复用。
+- 九宫格 UI 素材需要集中维护图片路径和切片参数，采用每张 PNG 一个素材 Scene 的推荐写法，见 [NineImage](scene-objects.md#nineimage)。
 - 有独立 public props、events 或 slots。
 - 自身有明确交互行为，例如按钮、列表项、弹窗。
 - 层级足够复杂，拆出后能减少父 Scene 噪音。
@@ -88,6 +89,7 @@ Decision:
 | 横向资源条、工具栏 | `HBoxContainer` |
 | 纵向菜单、任务列表 | `VBoxContainer` |
 | 背包、关卡卡片、固定列 | `GridContainer` |
+| 排列中的单个元素需要位置微调 | 明确尺寸的 `Group` 参与排列，偏移写在内部节点；见 [排列容器中的单独偏移](scene-hierarchy-patterns.md#排列容器中的单独偏移) |
 | 长列表、背包滚动区 | `ScrollContainer` + 内部 `VBoxContainer` / `GridContainer` |
 | 纯分组、统一移动或显隐 | `Container` |
 

package/dist/skills/pixifact/references/scene-hierarchy-patterns.md

@@ -129,6 +129,44 @@ Graphics
 
 不要手写大量 `x/y` 去模拟横排、竖排或网格，除非每个元素确实需要独立位置。
 
+## 排列容器中的单独偏移
+
+排列容器管理的是直接子节点的两个坐标：
+
+| 父容器 | 子节点 `x` | 子节点 `y` |
+| --- | --- | --- |
+| `HBoxContainer` | 顺序排列与 `gap` / `justify` | `alignY` 对齐 |
+| `VBoxContainer` | `alignX` 对齐 | 顺序排列与 `gap` / `justify` |
+| `GridContainer` | 列位置与 `alignX` | 行位置与 `alignY` |
+
+所以横排子节点的 `y`、竖排子节点的 `x` 也不能作为自由偏移使用；直接写 `x/y` 会在重新布局时被覆盖。不要用直接子节点的 frame layout 约束或脚本反复改位置来绕过排列。
+
+整组对齐用父容器的 `alignY` / `alignX`，间距和分布用 `gap` / `justify`。只需微调一个元素时，用明确宽高的 `Group` 作为排列占位，内部节点保留自由位置。
+
+横排中把第一个元素单独下移 `8`：
+
+```xml
+<HBoxContainer id="buttonRow" width="280" height="80" gap="16" alignY="center">
+  <Group id="firstSlot" width="120" height="64">
+    <Label id="firstLabel" y="8" width="120" height="48" text="下移 8" fontSize="24" />
+  </Group>
+  <Label id="secondLabel" width="120" height="64" text="保持对齐" fontSize="24" />
+</HBoxContainer>
+```
+
+竖排中把第一个元素单独右移 `8`：
+
+```xml
+<VBoxContainer id="buttonColumn" width="180" height="160" gap="16" alignX="center">
+  <Group id="firstSlot" width="120" height="64">
+    <Label id="firstLabel" x="8" width="104" height="64" text="右移 8" fontSize="24" />
+  </Group>
+  <Label id="secondLabel" width="120" height="64" text="保持对齐" fontSize="24" />
+</VBoxContainer>
+```
+
+排列按外层 `Group.width` / `height` 计算，不会因为内部节点偏移自动扩大占位。需要为内容留出空间时，显式调整占位尺寸；同时检查是否与邻项重叠或被滚动区域裁剪。内部节点若也设置了同轴 frame layout 约束，其 `x/y` 仍会被该约束覆盖。
+
 ## ScrollContainer 标准结构
 
 滚动容器通常只直接承载一个内容 layout container：

package/dist/skills/pixifact/references/scene-objects.md

@@ -166,6 +166,8 @@
 
 横向排列直接子节点。
 
+直接子节点的 `x/y` 都由容器管理，`y` 由 `alignY` 决定。单独上下微调时，使用明确尺寸的 `Group` 占位并调整内部节点，见 [排列容器中的单独偏移](scene-hierarchy-patterns.md#排列容器中的单独偏移)。
+
 | 属性 | 类型 | 可选值 / 说明 |
 | --- | --- | --- |
 | `gap` | number | 子节点之间的基础横向间距。 |
@@ -183,6 +185,8 @@
 
 纵向排列直接子节点。
 
+直接子节点的 `x/y` 都由容器管理，`x` 由 `alignX` 决定。单独左右微调时，使用明确尺寸的 `Group` 占位并调整内部节点，见 [排列容器中的单独偏移](scene-hierarchy-patterns.md#排列容器中的单独偏移)。
+
 | 属性 | 类型 | 可选值 / 说明 |
 | --- | --- | --- |
 | `gap` | number | 子节点之间的基础纵向间距。 |
@@ -323,10 +327,42 @@ Pixifact runtime 九宫格图片，推荐用于按钮底图、弹窗面板、提
 | `anchorY` | number | 纵向 anchor。 |
 | `tint` | color | 图片 tint。 |
 
+推荐每张九宫格 PNG 对应一个素材 Scene，集中维护 `texture` 和四边切片参数；使用相同图片的按钮、面板、弹窗直接引用该 Scene，避免在各处重复配置。
+
+例如 `assets/ui/panel.png` 为 `96 × 96`、四边切片各 `24` 的素材，在 `src/ui/nine/PanelBackground.scene` 中设置：
+
+```xml
+<Scene name="PanelBackground" width="96" height="96" eventMode="none">
+  <NineImage id="image" texture="assets/ui/panel.png"
+    left="0" right="0" top="0" bottom="0"
+    leftWidth="24" rightWidth="24" topHeight="24" bottomHeight="24"
+    eventMode="none" />
+</Scene>
+```
+
+配对的 `src/ui/nine/PanelBackground.ts` 只需要声明 Scene：
+
+```ts
+import { Group } from 'pixifact/runtime';
+import { scene } from 'pixifact/scene';
+
+@scene()
+export class PanelBackground extends Group {}
+```
+
+调用方 `src/ui/Panel.scene` 只负责位置与尺寸，内部 `NineImage` 随 Scene 盒子铺满：
+
 ```xml
-<NineImage id="dialogPanel" texture="assets/ui/panel.png" horizontal="0" vertical="0" width="620" height="420" leftWidth="32" rightWidth="32" topHeight="32" bottomHeight="32" />
+<Scene name="Panel" width="620" height="420">
+  <PanelBackground id="background" scene="./nine/PanelBackground.scene"
+    left="0" right="0" top="0" bottom="0" />
+</Scene>
 ```
 
+调用方仍需同名 `Panel.ts`。纯背景的 `eventMode="none"` 让输入由外层组件处理。
+
+图片尺寸和切片值按素材实际像素设置，`96` / `24` 是示例，不是固定规格。替换同名、同尺寸、同切片边距的 PNG 即可换外观；素材规格变化时，集中修改对应素材 Scene 的图片路径、切片参数和必要的默认盒子尺寸，再校验所有引用并检查不同尺寸下的效果。布局中改变背景尺寸时，使用 Scene 的 `width/height` 或 frame layout；`scaleX/scaleY` 会把边角一起缩放。
+
 ### TileImage
 
 Pixifact runtime 平铺图片，推荐用于重复背景或可滚动纹理。
@@ -509,7 +545,7 @@ declare disabled: boolean;
 
 ```xml
 <Scene name="PrimaryButton" width="420" height="88">
-  <NineImage id="background" texture="assets/ui/button.png" left="0" right="0" top="0" bottom="0" leftWidth="24" rightWidth="24" topHeight="24" bottomHeight="24" />
+  <ButtonBackground id="background" scene="./nine/ButtonBackground.scene" left="0" right="0" top="0" bottom="0" />
   <HBoxContainer id="content" horizontal="0" vertical="0" gap="12" alignY="center">
     <slot name="icon" />
     <Text id="label" text="Button" fontSize="28" fill="#ffffff" />
@@ -519,6 +555,8 @@ declare disabled: boolean;
 
 `<slot />` 省略 `name` 时表示 `default` slot。
 
+`ButtonBackground` 按上面的 `NineImage` 推荐方式封装 `assets/ui/button.png`，并配对同名 `.ts`。
+
 ## Events
 
 事件属性写在子 Scene instance 上，绑定值是 action name：

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-pixifact",
-  "version": "0.17.0",
+  "version": "0.19.0",
   "description": "创建 Pixifact 游戏项目。",
   "packageManager": "bun@1.3.13",
   "type": "module",
@@ -9,7 +9,10 @@
   },
   "files": [
     "dist/",
-    "templates/"
+    "templates/",
+    "!templates/**/.pixifact/**",
+    "!templates/**/dist/**",
+    "!templates/**/node_modules/**"
   ],
   "repository": {
     "type": "git",

package/templates/game/.env

@@ -0,0 +1 @@
+VITE_PLATFORM=web

package/templates/game/README.md

@@ -0,0 +1,119 @@
+# Pixifact 基础游戏模板
+
+这是可以直接复制开发新游戏的 Web 项目。默认设计尺寸为竖屏 `1080 × 1920`，适配模式为 `fixedWidth`。启动首页集中展示可替换外观的基础 UI 组件，并附带游戏、暂停、结算和最高分保存的代码示例。
+
+本模板使用 Bun `1.3.13` 验证；需要本机安装 Bun 和 Git。
+
+## 运行
+
+```bash
+bun install
+bun run dev
+```
+
+打开终端输出的地址，先在组件展台试用：
+
+- **Button**：大、中、小三种尺寸、轻微按压回弹、图标、禁用状态、启用／禁用切换与点击计数。
+- **ProgressBar**：每次增减 25%，到达 0% 或 100% 后禁用对应方向的按钮。
+- **Panel**：标题和内容区组合；展台各区块也复用同一个 Panel。
+- **Dialog**：确认／取消、结果反馈与模态遮罩；弹窗期间不能操作底层组件，关闭后保留展台状态。
+
+点击底部「体验游戏流程」，收集 8 份星光即可结算；可以暂停、继续、返回组件展台和重玩。暂停期间不能得分。最高记录保存在当前浏览器，同一地址刷新后仍可读取；页面切到后台时自动暂停。返回展台会创建新的展示页，组件演示状态恢复初始值。
+
+```bash
+bun run validate
+bun run compile
+bun run typecheck
+bun run build
+bun run editor
+```
+
+`dev` / `build` 自动编译 Scene；独立执行 `compile` 便于检查生成结果。生成目录 `.pixifact/` 和构建目录 `dist/` 不作为源码维护。
+
+`fixedWidth` 使用屏幕宽度除以 1080 作为缩放比例，再由屏幕高度反推 Scene 的可用高度。页面背景和弹窗遮罩随视口铺满；组件展台和游戏示例的内容在短窗口中可以纵向滚动。
+
+## 基础代码
+
+| 位置 | 职责 |
+| --- | --- |
+| `src/main.ts` | Application、Assets、Scene 准备、视口适配、后台暂停、开发期 Runtime |
+| `src/GameApp.ts` | 连接组件预览弹窗、游戏状态、页面事件、暂停和存档 |
+| `src/core/GameSession.ts` | 纯 TypeScript 规则和状态，可替换为自己的玩法 |
+| `src/core/ScreenManager.ts` | 页面替换、断开外部订阅、销毁旧节点；共享纹理继续复用 |
+| `src/core/WebRecordStore.ts` | 显式读写最高分；使用 Web 原生 localStorage |
+| `src/screens/` | 页面 `.scene` 外观和同名 `.ts` 行为契约 |
+| `src/screens/MainMenu.scene/.ts` | 默认组件展台、演示状态和次要游戏入口 |
+| `src/ui/` | 当前生效的基础 UI Scene 与脚本 |
+| `src/ui/nine/` | 每张九宫格素材对应的 Scene，集中设置图片路径和切片参数 |
+| `assets/ui/` | 当前生效的按钮和面板九宫格 PNG 图片（96 × 96，透明 RGBA） |
+
+开始开发自己的游戏时，先修改 `GameSession` 中的规则，再修改 `PlayScreen` 的视觉和公开事件，最后在 `GameApp` 中连接数据流。游戏规则不读取 UI 内部节点。给新页面增加同目录同 basename 的 `.scene/.ts`，启动前用 `prepareSceneClass()` 准备，再交给 `ScreenManager.replace()`。
+
+`ScreenManager.track(event.connect(handler))` 注册当前页面的外部连接，必须在 `replace()` 之后调用。移除页面和关闭弹窗时会统一取消这些连接。GameApp 的初始尺寸读取项目设计分辨率；页面、模态管理器和当前 Scene 通过 frame layout 跟随可用视口。切换设计分辨率时同步修改页面与 Dialog 的根尺寸及页面内容坐标。
+
+## UI 库契约
+
+| 组件 | 公开契约 | 组合方式 |
+| --- | --- | --- |
+| Button | `text`、`disabled`、`size`，`clicked` 事件 | `icon` slot；禁用状态禁止触发事件和按压动画 |
+| Panel | `title` | `content` slot |
+| Dialog | `title`、`message`、`confirmText`、`cancelText`；`confirmed` / `cancelled` 事件 | 全屏遮罩和居中面板，用于模态操作 |
+| ProgressBar | `setProgress(value, max)`，`max > 0` | 可改变宽高；填充比例保持不变 |
+
+例如，在自己的页面 `.scene` 中使用：
+
+```xml
+<Button id="startButton" scene="../ui/Button.scene"
+  horizontal="0" top="400" width="360" height="96" size="large"
+  text="开始游戏" @clicked="start" />
+```
+
+`size` 默认为 `medium`，可在 Scene 中指定或在脚本中赋值。三种尺寸同步调整按钮默认宽高、字号和图标区域：
+
+| size | 默认宽 × 高 | 字号 | 图标区域 |
+| --- | --- | --- | --- |
+| `large` | 360 × 96 | 42 | 36 × 36 |
+| `medium` | 280 × 80 | 36 | 32 × 32 |
+| `small` | 200 × 64 | 32 | 28 × 28 |
+
+Scene 的 `width` / `height` 或 frame layout 可覆盖默认宽高。按下时视觉缩小到 97%，松开后约 140ms 平滑回到原位；移出按钮、在按钮外松开或取消触摸也会复位。动画仅缩放内部 `visual` 节点，按钮布局和命中区域保持稳定；节点移除后不再执行渲染回调。
+
+页面的 `start()` action 负责发出业务事件。文字通过 Prop Binding 更新，父页面依赖公开事件和 slot，不依赖 Button 背景、Panel 内部节点等实现细节。
+
+## 直接替换图片素材
+
+模板只提供一套基础 UI。开发自己的游戏时，直接替换同名 PNG 即可更换对应背景，无需修改 Scene、组件脚本或游戏逻辑。
+
+| 图片 | 素材 Scene | 用途 | 默认尺寸／切片边距 |
+| --- | --- | --- | --- |
+| `assets/ui/button.png` | `src/ui/nine/ButtonBackground.scene` | 所有尺寸按钮的背景 | 96 × 96／四边各 24 像素 |
+| `assets/ui/panel.png` | `src/ui/nine/PanelBackground.scene` | 面板和弹窗的背景 | 96 × 96／四边各 24 像素 |
+
+新素材保持文件名、路径、尺寸与透明 PNG 格式。四个角保持原形，边缘沿单轴拉伸，中间区域随组件尺寸拉伸；将需要保留的边框和圆角放在 24 像素的切片区域内。大、中、小按钮共用同一张图片，文字和点击动画由组件负责。
+
+每张九宫格 PNG 只在对应素材 Scene 中配置一个 `NineImage`。图片路径和 `leftWidth`、`rightWidth`、`topHeight`、`bottomHeight` 集中维护；Button、Panel、Dialog 引用素材 Scene，自身只设置背景的位置和尺寸。例如，在 `src/ui/` 的组件中铺满面板背景：
+
+```xml
+<PanelBackground id="background" scene="./nine/PanelBackground.scene"
+  left="0" right="0" top="0" bottom="0" />
+```
+
+需要调整切片边距或换成不同规格图片时，只修改对应素材 Scene 的 `NineImage` 参数；所有引用位置会使用同一份配置。新增九宫格素材也按一张 PNG 一个 `.scene/.ts` 配对文件组织，素材 Scene 的根和内部图像均设为 `eventMode="none"`，内部图像通过四边为 0 铺满实例。
+
+覆盖图片后，重新启动开发服务并刷新预览；发布构建使用 `bun run build`。PNG 负责上述背景，文字、禁用蒙层和进度条由 Scene 节点渲染；需要调整这些部分的颜色或布局时，再编辑对应 `.scene`。
+
+每个 `.scene` 与同目录同名 `.ts` 配对；`@scene()` 类继承 `Group`，不声明自定义构造参数。非 Prop 依赖用显式方法传入。新增视觉节点或修改事件后运行 `pixifact scene validate --all`，避免外观替换破坏组件契约。
+
+## Agent 观察
+
+开发服务运行且浏览器打开后，在项目根目录执行：
+
+```bash
+pixifact runtime state
+pixifact runtime tree
+pixifact runtime screenshot
+```
+
+业务快照包含 `phase`、`score`、`goal`、`bestScore`、`modalOpen`；首页额外提供 `showcase`，包含 `buttonClicks`、`previewDisabled`、`progress`、`dialogResult`，进入游戏后为 `null`。可以结合真实节点树检查组件状态、弹窗隔离、页面切换、暂停和最高分保存。
+
+首版入口和存档使用 Web API。接入微信／抖音时，按 Pixifact 的平台文档接入现有平台包，并将 DOM 入口、visibility 事件和 WebRecordStore 替换为对应平台实现。

package/templates/game/bunfig.toml

@@ -0,0 +1 @@
+env = false

package/templates/game/index.html

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="zh-CN">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Pixifact UI 组件展示</title>
+  </head>
+  <body>
+    <div id="game"></div>
+    <script type="module" src="/src/main.ts"></script>
+  </body>
+</html>

package/templates/game/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "pixifact-game-starter",
+  "version": "0.1.0",
+  "private": true,
+  "packageManager": "bun@1.3.13",
+  "type": "module",
+  "scripts": {
+    "dev": "pixifact dev --mode development --project-root .",
+    "build": "pixifact build --mode production --project-root .",
+    "compile": "pixifact compile-scenes --project-root .",
+    "editor": "pixifact editor --project-root .",
+    "validate": "pixifact validate --mode production --project-root .",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "pixi.js": "8.18.1",
+    "pixifact": "^0.19.0"
+  },
+  "devDependencies": {
+    "pixifact-cli": "^0.19.0",
+    "typescript": "^5.3.3",
+    "vite": "^8.0.10"
+  }
+}

package/templates/game/pixifact.project.json

@@ -0,0 +1,11 @@
+{
+  "version": 2,
+  "name": "Pixifact Game Starter",
+  "resolution": { "width": 1080, "height": 1920 },
+  "viewport": { "mode": "fixedWidth" },
+  "scenes": {
+    "mainMenu": "src/screens/MainMenu.scene",
+    "play": "src/screens/PlayScreen.scene",
+    "result": "src/screens/ResultScreen.scene"
+  }
+}