@playcraft/skills 0.0.2

package/skills/phaser.aicomponent/SKILL.md

@@ -0,0 +1,315 @@
+---
+name: phaser.aicomponent
+description: Phaser 3 游戏引擎运行时 + 完整可运行空项目。提供 13 个文件：三场景生命周期（Boot→Preloader→Game）、自适应布局系统（750×1334 设计基准）、移动端适配（安全区/触摸/HiDPI）、音效工具。安装依赖后 `pnpm dev` 即可看到 Hello Phaser 画面。
+triggers: 需要初始化一个新的 Phaser 试玩广告项目、添加游戏引擎基础层，或配置 Phaser 渲染器和 Scene 时触发。
+---
+
+# Phaser 3 游戏引擎（Phaser Engine + Complete Project Skeleton）
+
+## 说明
+
+本 skill 是所有其他 Phaser skill 的基础。它贡献的 **13 个文件**构成了一个**完整可运行的 Phaser 空项目**，开箱即用：
+
+```bash
+pnpm install
+pnpm dev      # 开发模式 → 浏览器显示 "Hello Phaser!" + 布局参考信息
+pnpm build    # 构建产物
+```
+
+**已内置的基础能力：**
+
+- **三场景生命周期**：Boot（全局初始化）→ Preloader（进度条 + 资源加载）→ Game（主场景）
+- **自适应布局系统**：`computeUiLayout()` 基于 750×1334 设计稿，计算 `uiScale` / `vScale` / `centerX` / `centerY`
+- **移动端适配**：viewport meta（禁缩放）、安全区 padding、禁止选中/回弹/长按菜单、2× HiDPI 画布
+- **音效工具**：`safePlaySound()` 封装安全音效播放
+- **TypeScript 完整支持**：资源模块声明（`*.webp` / `*.mp3` 等）+ `__DEV__` 全局变量
+
+**UI 布局数学**以 `responsive_2d_layout.aicomponent` 的 **SKILL.md 第一节 Layout Canon** 为规范原文；本 skill 的 `UiLayout.ts` 为该规范的 Phaser 绑定实现。
+
+---
+
+## Scaffold
+
+| 目标路径 | 来源 | 说明 |
+|---------|-----|-----|
+| `src/index.ts` | `ref/main.ts` | **webpack 入口**：import CSS → DOMContentLoaded → StartGame + resize reload |
+| `src/index.html` | `ref/index.html` | **HTML 容器**：viewport meta + 安全区 + `#game-container` |
+| `src/index.css` | `ref/index.css` | **全屏样式**：移动端适配、安全区 padding、禁止选中/回弹 |
+| `globals.d.ts` | `ref/globals.d.ts` | **类型声明**：资源模块（图片/音频）+ `__DEV__` 全局 |
+| `tsconfig.json` | `ref/tsconfig.json` | **TypeScript 配置**：target es5, moduleResolution bundler, paths assets/* |
+| `src/game/index.ts` | `ref/index.ts` | **`StartGame(parent)`**：2× 设计分辨率 + Scale.FIT + 三场景注册 |
+| `src/game/GameConfig.ts` | `ref/GameConfig.ts` | **游戏配置**：设计稿基准、UI 缩放范围、安全区、调试开关 |
+| `src/game/SceneKeys.ts` | `ref/SceneKeys.ts` | **场景名枚举**：Boot / Preloader / Game |
+| `src/game/scenes/BootScene.ts` | `ref/BootScene.ts` | **Boot 场景**：禁右键菜单 → 路由到 Preloader |
+| `src/game/scenes/PreloaderScene.ts` | `ref/PreloaderScene.ts` | **Preloader 场景**：进度条 + Loading 文字 → 切到 Game |
+| `src/game/scenes/GameScene.ts` | `ref/GameScene.ts` | **Game 场景**：Hello Phaser + 布局参考（十字线/安全区框/坐标信息） |
+| `src/game/utils/UiLayout.ts` | `ref/UiLayout.ts` | **自适应布局**：`computeUiLayout()` — uiScale/vScale/centerX/centerY |
+| `src/game/utils/SoundUtils.ts` | `ref/SoundUtils.ts` | **音效工具**：`safePlaySound()` — 缺失键静默返回 |
+
+`package.json` 新增：`"phaser": "^3.90.0"`
+
+---
+
+## 空项目文件结构
+
+安装本 skill 后 Remix 项目的完整文件树：
+
+```
+<remix-project>/
+├── src/
+│   ├── index.ts              ← webpack 入口
+│   ├── index.html            ← HTML 容器（含 viewport meta）
+│   ├── index.css             ← 全屏 + 移动端适配样式
+│   └── game/
+│       ├── index.ts          ← StartGame()
+│       ├── GameConfig.ts     ← 通用游戏配置
+│       ├── SceneKeys.ts      ← 场景名枚举
+│       ├── scenes/
+│       │   ├── BootScene.ts      ← 全局初始化 → 路由
+│       │   ├── PreloaderScene.ts ← 资源加载 + 进度条
+│       │   └── GameScene.ts      ← Hello Phaser（主场景骨架）
+│       └── utils/
+│           ├── UiLayout.ts       ← 自适应布局系统
+│           └── SoundUtils.ts     ← 安全音效播放
+├── assets/                   ← 资产目录（游戏图片/音频放这里）
+├── globals.d.ts              ← 完整类型声明
+├── tsconfig.json             ← TypeScript 配置
+├── package.json              ← phaser 依赖
+└── webpack.config.js         ← 构建配置（由 webpack_build.aicomponent 提供）
+```
+
+---
+
+## 文件详解
+
+### src/index.ts（webpack 入口）
+
+```typescript
+import "./index.css";
+import { StartGame } from "./game";
+
+document.addEventListener("DOMContentLoaded", () => {
+  StartGame("game-container");
+
+  window.addEventListener("resize", () => {
+    window.location.reload();
+  });
+});
+```
+
+### src/game/index.ts（StartGame 函数）
+
+```typescript
+import { BootScene } from "./scenes/BootScene";
+import { PreloaderScene } from "./scenes/PreloaderScene";
+import { GameScene } from "./scenes/GameScene";
+
+export const StartGame = (parent: string): Phaser.Game => {
+  const DESIGN_SCALE = 2;
+  const designWidth  = Math.round((window.innerWidth  || 375) * DESIGN_SCALE);
+  const designHeight = Math.round((window.innerHeight || 667) * DESIGN_SCALE);
+
+  const config: Phaser.Types.Core.GameConfig = {
+    type: Phaser.WEBGL,
+    parent,
+    width: designWidth,
+    height: designHeight,
+    backgroundColor: 0xffffff,
+    scene: [BootScene, PreloaderScene, GameScene],
+    scale: {
+      mode: Phaser.Scale.FIT,
+      autoCenter: Phaser.Scale.CENTER_BOTH,
+    },
+    input: { activePointers: 2 },
+  };
+
+  return new Phaser.Game(config);
+};
+```
+
+### src/game/GameConfig.ts（通用配置）
+
+```typescript
+export const GameConfig = {
+  baseWidth: 750,        // 设计稿宽度
+  baseHeight: 1334,      // 设计稿高度
+  minScale: 0.7,         // UI 最小缩放
+  maxScale: 1.4,         // UI 最大缩放
+  safeAreaTop: 0,        // 安全区顶部偏移 (dp)
+  safeAreaBottom: 0,     // 安全区底部偏移 (dp)
+  debugScene: "game",    // 启动场景路由
+  showFps: false,        // FPS 显示开关
+  settings: {
+    musicOn: true,
+    soundOn: true,
+  },
+};
+```
+
+### src/game/utils/UiLayout.ts（自适应布局）
+
+```typescript
+export function computeUiLayout(sceneOrCamera, config = GameConfig): UiLayoutResult {
+  // uiScale = clamp(min(Wr/Wd, Hr/Hd), minScale, maxScale)
+  // vScale  = Hr/Hd
+  // centerX = Wr/2, centerY = Hr/2
+  // isLandscape = width > height
+}
+```
+
+**使用示例**：
+
+```typescript
+import { computeUiLayout } from '../utils/UiLayout';
+
+// 在任意 Scene.create() 中
+const { width, height, uiScale, vScale, centerX, centerY, isLandscape } = computeUiLayout(this);
+
+// UI 元素定位
+const buttonY = height - 80 * vScale;    // 距底 80dp
+const iconSize = 48 * uiScale;           // 48dp 图标
+const title = this.add.text(centerX, 100 * vScale, 'Title', {
+  fontSize: `${32 * uiScale}px`,
+}).setOrigin(0.5);
+```
+
+### src/game/scenes/BootScene.ts（全局初始化）
+
+```typescript
+export class BootScene extends Scene {
+  create(): void {
+    this.input.mouse?.disableContextMenu();
+    this.scene.start(SceneKeys.Preloader);  // 或根据 GameConfig.debugScene 路由
+  }
+}
+```
+
+### src/game/scenes/PreloaderScene.ts（通用加载）
+
+```typescript
+export class PreloaderScene extends Scene {
+  preload(): void {
+    // 自动显示进度条
+    // 在此处添加 this.load.image / this.load.audio 调用
+  }
+  create(): void {
+    this.scene.start(SceneKeys.Game);
+  }
+}
+```
+
+### src/game/scenes/GameScene.ts（空白主场景）
+
+显示 "Hello Phaser!" + 十字参考线 + 安全区框 + 布局参数信息。
+作为开发起点，替换 `create()` 内容即可开始编写游戏逻辑。
+
+---
+
+## 坐标系与布局规范
+
+### 坐标系
+
+- **原点**：画布左上角 (0, 0)
+- **x 向右，y 向下**（标准 2D 画布/Phaser 约定）
+- **设计空间**：750 × 1334 dp（竖屏基准）
+
+### 缩放系数（Layout Canon）
+
+| 系数 | 公式 | 用途 |
+|------|------|------|
+| `scaleX` | `Wr / Wd` | 水平缩放比 |
+| `scaleY` | `Hr / Hd` | 垂直缩放比 |
+| `uiScale` | `clamp(min(scaleX, scaleY), minScale, maxScale)` | **UI 元素尺寸**（字号、间距、图标边长） |
+| `vScale` | `scaleY` | **垂向距离**（距底/距顶的 dp 换算） |
+| `centerX/Y` | `Wr/2, Hr/2` | 居中锚点 |
+
+### 使用规则
+
+1. **同一画面只算一次** `computeUiLayout()`，全 UI 共用
+2. 宽高/圆角/字号 → 乘 `uiScale`
+3. 距底/距顶距离 → 乘 `vScale`
+4. 居中偏移 → `centerX/Y` + `偏移 × uiScale`
+5. 安全区先扣减 `safeAreaTop/Bottom`，再代入公式
+
+---
+
+## 移动端适配清单
+
+| 特性 | 实现位置 | 说明 |
+|------|---------|------|
+| **HiDPI 清晰度** | `StartGame()` | viewport × 2 设计分辨率 + Scale.FIT 缩小 |
+| **禁止页面缩放** | `index.html` | `viewport` meta：`user-scalable=no, maximum-scale=1` |
+| **iOS 全屏** | `index.html` | `apple-mobile-web-app-capable` + `black-translucent` 状态栏 |
+| **安全区（刘海屏）** | `index.css` | `env(safe-area-inset-*)` padding |
+| **禁止文字选中** | `index.css` | `user-select: none` |
+| **禁止长按菜单** | `index.css` | `-webkit-touch-callout: none` |
+| **禁止 iOS 回弹** | `index.css` | `overscroll-behavior: none; touch-action: none` |
+| **禁止点击高亮** | `index.css` | `-webkit-tap-highlight-color: transparent` |
+| **禁止右键菜单** | `BootScene.ts` | `this.input.mouse?.disableContextMenu()` |
+| **双指支持** | `StartGame()` | `activePointers: 2`（pinch zoom 预留） |
+| **横竖屏感知** | `UiLayout.ts` | `isLandscape` 字段 |
+| **resize 响应** | `index.ts` | reload 重新计算设计分辨率 |
+
+---
+
+## Imports
+
+本 skill 是所有 Phaser 组件的基础，无 skill 层依赖。
+
+**配套 skill（推荐一起使用）：**
+- `webpack_build.aicomponent` — 提供 webpack.config.js + devDependencies（pnpm dev / pnpm build）
+- `playable_scripts_build.aicomponent` — 腾讯 playable-scripts 构建管线（替代 webpack_build）
+
+**不再需要单独安装**（已内置）：
+- ~~`typescript_module_patterns.aicomponent`~~ — 资源模块声明已合入 `globals.d.ts`
+- ~~`responsive_2d_layout.aicomponent`~~ 的 scaffold 部分 — `UiLayout.ts` 已内置（SKILL.md 规范文档仍然有效）
+- ~~`sound_utils.aicomponent`~~ 的基础版 — `SoundUtils.ts` 已内置（增强版如 BGM 管理仍可独立使用）
+- ~~`phaser_scene_lifecycle.aicomponent`~~ 的场景骨架 — Boot/Preloader/Game 三场景已内置
+
+## Skill Definition
+
+```yaml
+tools:
+  - read_file
+  - write_file
+inputs:
+  - source: ref/main.ts          (webpack entry)
+  - source: ref/index.html       (HTML container with viewport meta)
+  - source: ref/index.css        (fullscreen + mobile styles)
+  - source: ref/globals.d.ts     (asset module declarations + __DEV__)
+  - source: ref/tsconfig.json    (TypeScript config)
+  - source: ref/index.ts         (StartGame function)
+  - source: ref/GameConfig.ts    (generic game config)
+  - source: ref/SceneKeys.ts     (scene key enum)
+  - source: ref/BootScene.ts     (boot scene)
+  - source: ref/PreloaderScene.ts (preloader scene)
+  - source: ref/GameScene.ts     (game scene skeleton)
+  - source: ref/UiLayout.ts      (responsive layout system)
+  - source: ref/SoundUtils.ts    (safe sound playback)
+outputs:
+  - projectSkeleton: 13 files forming a complete runnable Phaser project
+  - phaserDep: phaser ^3.90.0 npm dependency
+  - sceneLifecycle: Boot → Preloader → Game three-scene architecture
+  - responsiveLayout: computeUiLayout() with uiScale/vScale/center
+  - mobileAdaptation: viewport meta, safe areas, touch handling, HiDPI
+```
+
+## Recipe
+
+| 决策 | 原因 |
+|-----|-----|
+| **2× 设计分辨率** | 在 HiDPI 屏上用更高物理像素渲染，再通过 Scale.FIT 缩小，避免模糊 |
+| **resize 时 reload** | 最简单可靠的方式重新计算设计分辨率；试玩广告不需要复杂的响应式 |
+| **activePointers: 2** | 允许双指缩放手势（InputHandler 实现 pinch zoom） |
+| **三场景架构** | Boot 负责全局初始化（只跑一次），Preloader 负责资源加载，Game 为主场景 |
+| **Layout Canon 内置** | computeUiLayout 是所有 UI 定位的基础，不应是可选依赖 |
+| **GameConfig 纯通用** | 去掉所有 arrow-puzzle 专属常量（棋盘/箭头/路径），具体游戏 skill 自行声明 |
+| **globals.d.ts 合并模块声明** | 减少 skill 依赖数量，一个 skill 出完整项目 |
+
+## Adapter
+
+- **Role**: `phaserEngine` — Phaser 3 游戏引擎基座，所有 Phaser 系 skill 的运行时依赖
+- **Provides**: `StartGame()` 启动入口、`SceneKeys` 枚举、`GameConfig` 通用配置、`computeUiLayout()` 自适应布局、`safePlaySound()` 安全音效
+- **Requires**: 无 skill 层硬依赖（`webpack_build.aicomponent` 为配套工具，非运行时依赖）
+- **Consumed by**: 所有以 `phaser.aicomponent` 为 Imports 硬依赖的 skill，包括 `grid_board_layout`、`path_renderer`、`path_input_handler`、`tray_container`、`level_lifecycle`、`game_scene` 等
+- **Integration point**: `src/game/index.ts` 导出 `StartGame()`，由 `src/index.ts` 在 `DOMContentLoaded` 中调用

package/skills/phaser.aicomponent/manifest.json

@@ -0,0 +1,156 @@
+{
+  "schemaVersion": 1,
+  "atomId": "phaser.aicomponent",
+  "bundleType": "aicomponent",
+  "category": "engine",
+  "mode": "fixed",
+  "label": { "zh": "Phaser 3 游戏引擎", "en": "Phaser 3 game engine" },
+  "tags": ["phaser", "game-engine", "webgl", "2d", "canvas", "scene", "runtime", "skeleton", "responsive", "mobile"],
+  "bindingRoles": ["gameEngine"],
+  "scaffold": {
+    "files": {
+      "src/index.ts": {
+        "source": "ref/main.ts",
+        "mode": "full",
+        "weight": 10,
+        "_comment": "webpack 入口：import CSS + 调用 StartGame + 监听 resize"
+      },
+      "src/index.html": {
+        "source": "ref/index.html",
+        "mode": "full",
+        "weight": 10,
+        "_comment": "HTML 容器，包含 viewport meta + #game-container"
+      },
+      "src/index.css": {
+        "source": "ref/index.css",
+        "mode": "full",
+        "weight": 10,
+        "_comment": "全屏样式：移动端适配、安全区、禁止选中/回弹"
+      },
+      "globals.d.ts": {
+        "source": "ref/globals.d.ts",
+        "mode": "full",
+        "weight": 10,
+        "_comment": "资源模块声明（*.webp, *.mp3 等）+ __DEV__ 全局变量"
+      },
+      "tsconfig.json": {
+        "source": "ref/tsconfig.json",
+        "mode": "merge-json",
+        "weight": 10,
+        "_comment": "TypeScript 配置：target es5, moduleResolution bundler, paths assets/*"
+      },
+      "src/game/index.ts": {
+        "source": "ref/index.ts",
+        "mode": "full",
+        "weight": 10,
+        "_comment": "StartGame(parent) 游戏入口，2× 设计分辨率 + Scale.FIT"
+      },
+      "src/game/GameConfig.ts": {
+        "source": "ref/GameConfig.ts",
+        "mode": "full",
+        "weight": 10,
+        "_comment": "通用游戏配置：设计稿基准、UI 缩放范围、安全区、调试开关"
+      },
+      "src/game/SceneKeys.ts": {
+        "source": "ref/SceneKeys.ts",
+        "mode": "full",
+        "weight": 10,
+        "_comment": "场景名枚举，避免字符串硬编码"
+      },
+      "src/game/scenes/BootScene.ts": {
+        "source": "ref/BootScene.ts",
+        "mode": "full",
+        "weight": 10,
+        "_comment": "Boot 场景：全局初始化 + 场景路由"
+      },
+      "src/game/scenes/PreloaderScene.ts": {
+        "source": "ref/PreloaderScene.ts",
+        "mode": "full",
+        "weight": 10,
+        "_comment": "预加载场景：进度条 + Loading 文字"
+      },
+      "src/game/scenes/GameScene.ts": {
+        "source": "ref/GameScene.ts",
+        "mode": "full",
+        "weight": 10,
+        "_comment": "空白主场景：Hello Phaser + 布局参考信息"
+      },
+      "src/game/utils/UiLayout.ts": {
+        "source": "ref/UiLayout.ts",
+        "mode": "full",
+        "weight": 10,
+        "_comment": "自适应布局：computeUiLayout() — uiScale/vScale/centerX/centerY"
+      },
+      "src/game/utils/SoundUtils.ts": {
+        "source": "ref/SoundUtils.ts",
+        "mode": "full",
+        "weight": 10,
+        "_comment": "安全音效播放封装：缺失音效键时静默返回"
+      },
+      "package.json": {
+        "source": "ref/package.json",
+        "mode": "merge-json",
+        "weight": 10,
+        "_comment": "项目依赖：phaser + webpack + ts-loader + html-webpack-plugin 等"
+      },
+      "webpack.config.js": {
+        "source": "ref/webpack.config.js",
+        "mode": "full",
+        "weight": 10,
+        "_comment": "Webpack 5 配置：ts-loader + asset/resource + HtmlWebpackPlugin + __DEV__"
+      }
+    },
+    "packageJson": {
+      "dependencies": {
+        "phaser": { "version": "^3.90.0", "weight": 10 }
+      }
+    }
+  },
+  "exports": [
+    { "name": "StartGame",       "kind": "function",  "location": "src/game/index.ts" },
+    { "name": "GameConfig",      "kind": "object",    "location": "src/game/GameConfig.ts" },
+    { "name": "SceneKeys",       "kind": "object",    "location": "src/game/SceneKeys.ts" },
+    { "name": "BootScene",       "kind": "class",     "location": "src/game/scenes/BootScene.ts" },
+    { "name": "PreloaderScene",  "kind": "class",     "location": "src/game/scenes/PreloaderScene.ts" },
+    { "name": "GameScene",       "kind": "class",     "location": "src/game/scenes/GameScene.ts" },
+    { "name": "computeUiLayout", "kind": "function",  "location": "src/game/utils/UiLayout.ts" },
+    { "name": "UiLayoutConfig",  "kind": "interface", "location": "src/game/utils/UiLayout.ts" },
+    { "name": "UiLayoutResult",  "kind": "interface", "location": "src/game/utils/UiLayout.ts" },
+    { "name": "safePlaySound",   "kind": "function",  "location": "src/game/utils/SoundUtils.ts" }
+  ],
+  "neutralDescriptor": {
+    "geometry": "2D WebGL game engine runtime with complete project skeleton: 3-scene lifecycle (Boot→Preloader→Game), responsive layout system (750×1334 design base), mobile adaptation (safe areas, touch, HiDPI), sound utilities",
+    "layers": ["rendering", "scene-management", "input-system", "responsive-layout", "sound-utils", "project-scaffold"],
+    "replaceable": ["renderer type (WEBGL/CANVAS)", "scene list", "design resolution", "HTML title", "background color"]
+  },
+  "usageHints": [
+    "本 skill 提供完整 Phaser 空项目骨架（15 个文件），包含 package.json + webpack.config.js，scaffold 后 pnpm install && pnpm dev 即可运行",
+    "项目结构：package.json / webpack.config.js / tsconfig.json / globals.d.ts + src/ (13个源文件) + assets/images/ + assets/sounds/",
+    "三场景生命周期：Boot（全局初始化）→ Preloader（资源加载 + 进度条）→ Game（主游戏场景）",
+    "computeUiLayout(scene) 统一计算 uiScale/vScale/centerX/centerY，所有 UI 元素必须使用此函数的输出定位",
+    "设计稿基准 750×1334，运行时 2× viewport 作为设计分辨率（HiDPI 适配）+ Scale.FIT",
+    "移动端已处理：viewport meta（禁缩放）、安全区 padding、禁止选中/回弹/长按菜单、双指输入",
+    "globals.d.ts 已包含所有常见资源类型的模块声明（图片/音频/JSON），无需额外 skill",
+    "webpack.config.js 内置 __DEV__ 全局变量注入，开发模式自动为 true",
+    "safePlaySound(scene, key, config?) 封装安全音效播放，缺失音效键不抛异常",
+    "assets/ 目录约定：assets/images/（图片）+ assets/sounds/（音频），webpack alias 已配置为 'assets' 短路径"
+  ],
+  "files": {
+    "skill":          "SKILL.md",
+    "mainEntry":      "ref/main.ts",
+    "html":           "ref/index.html",
+    "css":            "ref/index.css",
+    "globals":        "ref/globals.d.ts",
+    "tsconfig":       "ref/tsconfig.json",
+    "packageJson":    "ref/package.json",
+    "webpackConfig":  "ref/webpack.config.js",
+    "gameEntry":      "ref/index.ts",
+    "gameConfig":     "ref/GameConfig.ts",
+    "sceneKeys":      "ref/SceneKeys.ts",
+    "bootScene":      "ref/BootScene.ts",
+    "preloaderScene": "ref/PreloaderScene.ts",
+    "gameScene":      "ref/GameScene.ts",
+    "uiLayout":       "ref/UiLayout.ts",
+    "soundUtils":     "ref/SoundUtils.ts"
+  }
+}

package/skills/phaser.aicomponent/ref/BootScene.ts

@@ -0,0 +1,29 @@
+import { Scene } from "phaser";
+import { SceneKeys } from "../SceneKeys";
+import { GameConfig } from "../GameConfig";
+
+/**
+ * Boot 场景 — 引擎初始化后第一个运行的场景。
+ *
+ * 职责：
+ * 1. 设置全局输入配置（禁用右键菜单等）
+ * 2. 根据 GameConfig.debugScene 路由到目标场景
+ */
+export class BootScene extends Scene {
+  constructor() {
+    super(SceneKeys.Boot);
+  }
+
+  create(): void {
+    this.input.mouse?.disableContextMenu();
+
+    const target =
+      GameConfig.debugScene === "preloader"
+        ? SceneKeys.Preloader
+        : GameConfig.debugScene === "game"
+          ? SceneKeys.Game
+          : SceneKeys.Preloader;
+
+    this.scene.start(target);
+  }
+}

package/skills/phaser.aicomponent/ref/GameConfig.ts

@@ -0,0 +1,29 @@
+/**
+ * 游戏全局配置（通用基础版）。
+ *
+ * 具体游戏的业务常量（棋盘间距、箭头尺寸等）应在各自 skill 中声明，
+ * 不要污染此文件。
+ */
+export const GameConfig = {
+  // ─── 设计稿基准 ───
+  baseWidth: 750,
+  baseHeight: 1334,
+
+  // ─── UI 缩放范围（供 computeUiLayout 使用） ───
+  minScale: 0.7,
+  maxScale: 1.4,
+
+  // ─── 安全区偏移（刘海屏等，单位 dp；启用后 UiLayout 自动扣减） ───
+  safeAreaTop: 0,
+  safeAreaBottom: 0,
+
+  // ─── 调试 ───
+  debugScene: "game" as "boot" | "preloader" | "game",
+  showFps: false,
+
+  // ─── 音频默认状态 ───
+  settings: {
+    musicOn: true,
+    soundOn: true,
+  },
+};

package/skills/phaser.aicomponent/ref/GameScene.ts

@@ -0,0 +1,88 @@
+import { Scene } from "phaser";
+import { SceneKeys } from "../SceneKeys";
+import { computeUiLayout } from "../utils/UiLayout";
+import { GameConfig } from "../GameConfig";
+
+/**
+ * 主游戏场景（空白骨架）。
+ *
+ * 执行脚手架后，此场景显示 "Hello Phaser!" 文字和布局参考网格，
+ * 作为开发起点。替换 create() 中的内容即可开始编写游戏逻辑。
+ */
+export class GameScene extends Scene {
+  private fpsText?: Phaser.GameObjects.Text;
+
+  constructor() {
+    super(SceneKeys.Game);
+  }
+
+  create(): void {
+    const layout = computeUiLayout(this);
+    const { width, height, centerX, centerY, uiScale, vScale, isLandscape } =
+      layout;
+
+    // ─── 背景 ───
+    this.cameras.main.setBackgroundColor(0xf5f5f5);
+
+    // ─── 参考十字线（设计期辅助，正式项目可删除） ───
+    const crosshair = this.add.graphics();
+    crosshair.lineStyle(1, 0xcccccc, 0.5);
+    crosshair.lineBetween(centerX, 0, centerX, height);
+    crosshair.lineBetween(0, centerY, width, centerY);
+
+    // ─── 安全区可视化边框 ───
+    const safeMargin = 40 * uiScale;
+    const safeRect = this.add.graphics();
+    safeRect.lineStyle(1, 0x4488ff, 0.3);
+    safeRect.strokeRect(safeMargin, safeMargin, width - safeMargin * 2, height - safeMargin * 2);
+
+    // ─── 标题 ───
+    this.add
+      .text(centerX, centerY - 40 * uiScale, "Hello Phaser!", {
+        fontSize: `${48 * uiScale}px`,
+        color: "#333333",
+        fontFamily: "Arial, sans-serif",
+        fontStyle: "bold",
+      })
+      .setOrigin(0.5);
+
+    // ─── 布局信息（帮助开发者理解坐标系） ───
+    const info = [
+      `canvas: ${width} × ${height}`,
+      `design: ${GameConfig.baseWidth} × ${GameConfig.baseHeight}`,
+      `uiScale: ${uiScale.toFixed(3)}  vScale: ${vScale.toFixed(3)}`,
+      `orientation: ${isLandscape ? "landscape" : "portrait"}`,
+      `dpr: ${window.devicePixelRatio}`,
+    ].join("\n");
+
+    this.add
+      .text(centerX, centerY + 30 * uiScale, info, {
+        fontSize: `${14 * uiScale}px`,
+        color: "#888888",
+        fontFamily: "monospace",
+        align: "center",
+        lineSpacing: 6 * uiScale,
+      })
+      .setOrigin(0.5, 0);
+
+    // ─── FPS 显示 ───
+    if (GameConfig.showFps) {
+      this.fpsText = this.add
+        .text(10, 10, "FPS: 0", {
+          fontSize: `${12 * uiScale}px`,
+          color: "#00cc00",
+          fontFamily: "monospace",
+          backgroundColor: "#00000066",
+          padding: { x: 4, y: 2 },
+        })
+        .setScrollFactor(0)
+        .setDepth(9999);
+    }
+  }
+
+  update(): void {
+    if (this.fpsText) {
+      this.fpsText.setText(`FPS: ${this.game.loop.actualFps.toFixed(0)}`);
+    }
+  }
+}