@playcraft/skills 0.0.2

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

@@ -0,0 +1,78 @@
+import { Scene } from "phaser";
+import { SceneKeys } from "../SceneKeys";
+import { computeUiLayout } from "../utils/UiLayout";
+
+/**
+ * 通用预加载场景。
+ *
+ * 提供居中进度条 + "Loading..." 文字。
+ * 在 preload() 中按需添加 this.load.image / this.load.audio 等调用即可。
+ */
+export class PreloaderScene extends Scene {
+  constructor() {
+    super(SceneKeys.Preloader);
+  }
+
+  preload(): void {
+    const { centerX, centerY, uiScale } = computeUiLayout(this);
+
+    // ─── 进度条 ───
+    const barW = 300 * uiScale;
+    const barH = 16 * uiScale;
+    const barRadius = barH * 0.5;
+
+    // 背景槽
+    const barBg = this.add.graphics();
+    barBg.fillStyle(0x333333, 1);
+    barBg.fillRoundedRect(
+      centerX - barW * 0.5,
+      centerY - barH * 0.5,
+      barW,
+      barH,
+      barRadius,
+    );
+
+    // 填充条
+    const barFill = this.add.graphics();
+
+    // Loading 文字
+    const loadText = this.add
+      .text(centerX, centerY + 30 * uiScale, "Loading...", {
+        fontSize: `${16 * uiScale}px`,
+        color: "#aaaaaa",
+        fontFamily: "Arial, sans-serif",
+      })
+      .setOrigin(0.5);
+
+    // ─── 进度回调 ───
+    this.load.on("progress", (value: number) => {
+      barFill.clear();
+      barFill.fillStyle(0x4488ff, 1);
+      barFill.fillRoundedRect(
+        centerX - barW * 0.5,
+        centerY - barH * 0.5,
+        barW * value,
+        barH,
+        barRadius,
+      );
+    });
+
+    this.load.on("complete", () => {
+      loadText.setText("Ready");
+    });
+
+    // ──────────────────────────────────────────
+    // 在下方添加你的资源加载调用，例如：
+    //
+    //   import logoImage from "assets/images/logo.webp";
+    //   this.load.image("logo", logoImage);
+    //
+    //   import bgmAudio from "assets/sounds/bgm.mp3";
+    //   this.load.audio("bgm", bgmAudio);
+    // ──────────────────────────────────────────
+  }
+
+  create(): void {
+    this.scene.start(SceneKeys.Game);
+  }
+}

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

@@ -0,0 +1,7 @@
+export const SceneKeys = {
+  Boot: "Boot",
+  Preloader: "Preloader",
+  Game: "Game",
+} as const;
+
+export type SceneKey = (typeof SceneKeys)[keyof typeof SceneKeys];

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

@@ -0,0 +1,21 @@
+import * as Phaser from "phaser";
+
+/**
+ * 安全播放音效。
+ * - 音效键不存在时静默返回 null（不抛异常）
+ * - 可通过 config 控制音量、循环等
+ */
+export function safePlaySound(
+  scene: Phaser.Scene,
+  key: string,
+  config?: Phaser.Types.Sound.SoundConfig,
+): Phaser.Sound.BaseSound | null {
+  if (!scene.cache.audio.exists(key)) {
+    return null;
+  }
+  try {
+    return scene.sound.play(key, config) as unknown as Phaser.Sound.BaseSound;
+  } catch {
+    return null;
+  }
+}

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

@@ -0,0 +1,74 @@
+import * as Phaser from "phaser";
+import { GameConfig } from "../GameConfig";
+
+export interface UiLayoutConfig {
+  baseWidth?: number;
+  baseHeight?: number;
+  minScale?: number;
+  maxScale?: number;
+}
+
+export interface UiLayoutResult {
+  camera: Phaser.Cameras.Scene2D.Camera;
+  width: number;
+  height: number;
+  scaleX: number;
+  scaleY: number;
+  uiScale: number;
+  vScale: number;
+  centerX: number;
+  centerY: number;
+  isLandscape: boolean;
+}
+
+/**
+ * Layout Canon（Phaser 绑定）。
+ *
+ * 基于 750×1334 设计稿，统一计算 UI 适配参数：
+ * - uiScale = clamp(min(scaleX, scaleY), minScale, maxScale)
+ * - vScale  = scaleY（仅随高度变化，用于贴底/贴顶垂向距离）
+ *
+ * @see responsive_2d_layout.aicomponent SKILL.md 第一节
+ */
+export function computeUiLayout(
+  sceneOrCamera: Phaser.Scene | Phaser.Cameras.Scene2D.Camera,
+  config: UiLayoutConfig = GameConfig,
+): UiLayoutResult {
+  const camera =
+    sceneOrCamera instanceof Phaser.Scene
+      ? sceneOrCamera.cameras.main
+      : sceneOrCamera;
+
+  const { width, height } = camera;
+
+  const baseWidth = config.baseWidth ?? 750;
+  const baseHeight = config.baseHeight ?? 1334;
+
+  const scaleX = width / baseWidth;
+  const scaleY = height / baseHeight;
+
+  const minScale = config.minScale ?? 0.7;
+  const maxScale = config.maxScale ?? 1.4;
+
+  const rawUiScale = Math.min(scaleX, scaleY);
+  const uiScale = Phaser.Math.Clamp(rawUiScale, minScale, maxScale);
+  const vScale = scaleY;
+
+  const centerX = width * 0.5;
+  const centerY = height * 0.5;
+
+  const isLandscape = width > height;
+
+  return {
+    camera,
+    width,
+    height,
+    scaleX,
+    scaleY,
+    uiScale,
+    vScale,
+    centerX,
+    centerY,
+    isLandscape,
+  };
+}

package/skills/phaser.aicomponent/ref/globals.d.ts

@@ -0,0 +1,52 @@
+// 图片资源
+declare module "*.png" {
+  const src: string;
+  export default src;
+}
+declare module "*.webp" {
+  const src: string;
+  export default src;
+}
+declare module "*.jpg" {
+  const src: string;
+  export default src;
+}
+declare module "*.jpeg" {
+  const src: string;
+  export default src;
+}
+declare module "*.svg" {
+  const src: string;
+  export default src;
+}
+declare module "*.gif" {
+  const src: string;
+  export default src;
+}
+
+// 音频资源
+declare module "*.mp3" {
+  const src: string;
+  export default src;
+}
+declare module "*.ogg" {
+  const src: string;
+  export default src;
+}
+declare module "*.wav" {
+  const src: string;
+  export default src;
+}
+declare module "*.m4a" {
+  const src: string;
+  export default src;
+}
+
+// JSON 数据（关卡数据、配置等）
+declare module "*.json" {
+  const value: any;
+  export default value;
+}
+
+// 构建工具注入的全局变量
+declare const __DEV__: boolean;

package/skills/phaser.aicomponent/ref/index.css

@@ -0,0 +1,40 @@
+*,
+*::before,
+*::after {
+  margin: 0;
+  padding: 0;
+  box-sizing: border-box;
+  -webkit-tap-highlight-color: transparent;
+}
+
+html,
+body {
+  width: 100%;
+  height: 100%;
+  overflow: hidden;
+  background-color: #000;
+
+  /* 禁止移动端文字选中和长按菜单 */
+  -webkit-user-select: none;
+  user-select: none;
+  -webkit-touch-callout: none;
+
+  /* 禁止 iOS 橡皮筋回弹 */
+  overscroll-behavior: none;
+  touch-action: none;
+}
+
+#game-container {
+  width: 100%;
+  height: 100%;
+
+  /* 适配 iOS 安全区（刘海屏） */
+  padding-top: env(safe-area-inset-top);
+  padding-bottom: env(safe-area-inset-bottom);
+  padding-left: env(safe-area-inset-left);
+  padding-right: env(safe-area-inset-right);
+}
+
+canvas {
+  display: block;
+}

package/skills/phaser.aicomponent/ref/index.html

@@ -0,0 +1,14 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no, viewport-fit=cover" />
+    <meta name="apple-mobile-web-app-capable" content="yes" />
+    <meta name="apple-mobile-web-app-status-bar-style" content="black-translucent" />
+    <meta name="format-detection" content="telephone=no" />
+    <title>Phaser Game</title>
+  </head>
+  <body>
+    <div id="game-container"></div>
+  </body>
+</html>

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

@@ -0,0 +1,48 @@
+import Phaser from "phaser";
+import { BootScene } from "./scenes/BootScene";
+import { PreloaderScene } from "./scenes/PreloaderScene";
+import { GameScene } from "./scenes/GameScene";
+
+/**
+ * 创建并启动 Phaser 游戏实例。
+ *
+ * 设计分辨率 = viewport × 2（HiDPI 适配），Scale.FIT 自动铺满容器。
+ * 场景按 Boot → Preloader → Game 顺序启动。
+ */
+export const StartGame = (parent: string): Phaser.Game => {
+  const viewportWidth = window.innerWidth || 375;
+  const viewportHeight = window.innerHeight || 667;
+
+  const DESIGN_SCALE = 2;
+  const designWidth = Math.round(viewportWidth * DESIGN_SCALE);
+  const designHeight = Math.round(viewportHeight * 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,
+    },
+  };
+
+  const game = new Phaser.Game(config);
+
+  if (typeof __DEV__ !== "undefined" && __DEV__) {
+    (window as any).__PHASER_GAME__ = game;
+    (window as any).PhaserRef = Phaser;
+    console.log("[Game] Started", {
+      viewport: { w: viewportWidth, h: viewportHeight, dpr: window.devicePixelRatio },
+      design: { w: designWidth, h: designHeight },
+    });
+  }
+
+  return game;
+};

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

@@ -0,0 +1,16 @@
+import "./index.css";
+import { StartGame } from "./game";
+
+document.addEventListener("DOMContentLoaded", () => {
+  // Start the Phaser game immediately
+  StartGame("game-container");
+
+  // Reload on resize to recalculate design resolution
+  window.addEventListener("resize", () => {
+    window.location.reload();
+  });
+});
+
+if (__DEV__) {
+  console.log("Development mode");
+}

package/skills/phaser.aicomponent/ref/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "playable-ad",
+  "version": "1.0.0",
+  "description": "Playable Ad - Phaser 3",
+  "scripts": {
+    "dev": "webpack serve --mode development",
+    "build": "webpack --mode production"
+  },
+  "dependencies": {
+    "phaser": "^3.90.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.3.0",
+    "webpack": "^5.90.0",
+    "webpack-cli": "^5.1.0",
+    "webpack-dev-server": "^5.0.0",
+    "ts-loader": "^9.5.0",
+    "html-webpack-plugin": "^5.6.0",
+    "css-loader": "^6.10.0",
+    "style-loader": "^3.3.0"
+  }
+}

package/skills/phaser.aicomponent/ref/tsconfig.json

@@ -0,0 +1,25 @@
+{
+  "compilerOptions": {
+    "outDir": "./dist",
+    "target": "es5",
+    "downlevelIteration": true,
+    "lib": ["dom", "dom.iterable", "esnext"],
+    "allowJs": true,
+    "skipLibCheck": true,
+    "esModuleInterop": true,
+    "allowSyntheticDefaultImports": true,
+    "strict": false,
+    "forceConsistentCasingInFileNames": true,
+    "noFallthroughCasesInSwitch": true,
+    "strictPropertyInitialization": false,
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "sourceMap": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "paths": {
+      "assets/*": ["./assets/*"]
+    }
+  },
+  "exclude": ["node_modules", "tests"]
+}

package/skills/phaser.aicomponent/ref/webpack.config.js

@@ -0,0 +1,57 @@
+const path = require('path');
+const HtmlWebpackPlugin = require('html-webpack-plugin');
+const webpack = require('webpack');
+
+module.exports = (env, argv) => {
+  const isDev = argv.mode === 'development';
+
+  return {
+    entry: './src/main.ts',
+    output: {
+      filename: 'bundle.js',
+      path: path.resolve(__dirname, 'dist'),
+      clean: true,
+    },
+    resolve: {
+      extensions: ['.ts', '.js'],
+      alias: {
+        assets: path.resolve(__dirname, 'assets'),
+      },
+    },
+    module: {
+      rules: [
+        {
+          test: /\.ts$/,
+          use: 'ts-loader',
+          exclude: /node_modules/,
+        },
+        {
+          test: /\.css$/,
+          use: ['style-loader', 'css-loader'],
+        },
+        {
+          test: /\.(mp3|ogg|wav|m4a)$/,
+          type: 'asset/resource',
+        },
+        {
+          test: /\.(png|jpg|jpeg|webp|svg|gif)$/,
+          type: 'asset/resource',
+        },
+      ],
+    },
+    plugins: [
+      new HtmlWebpackPlugin({
+        template: './src/index.html',
+      }),
+      new webpack.DefinePlugin({
+        __DEV__: JSON.stringify(isDev),
+      }),
+    ],
+    devServer: {
+      static: './dist',
+      hot: true,
+      open: true,
+    },
+    devtool: isDev ? 'source-map' : false,
+  };
+};

package/skills/phaser_scene_lifecycle.aicomponent/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: phaser_scene_lifecycle.aicomponent
+description: Phaser 双场景架构骨架。定义 Preloader → Game 的标准两场景生命周期，Preloader 负责资产预加载，完成后自动切换到 Game 主场景。
+triggers: 需要设置 Phaser 项目的场景管理架构或场景切换流程时触发。
+---
+
+# Phaser 双场景生命周期（Phaser Dual Scene Lifecycle）
+
+## 说明
+
+标准 Phaser 试玩广告双场景架构：
+
+1. **Preloader 场景**：加载所有资产，显示加载 Loading UI，加载完成后调用 `sdk.start()` 并切换到 Game 场景
+2. **Game 场景**：主游戏场景，持有所有游戏对象和逻辑
+
+两个场景分别在 `preloader_scene.aicomponent` 和 `game_scene.aicomponent` 中实现。
+
+## Scaffold
+
+本 skill 为骨架层，不直接贡献文件——具体文件由 `preloader_scene` 和 `game_scene` 两个 skill 贡献。
+
+`src/game/index.ts`（来自 `phaser.aicomponent`）中通过 `scene: [Preloader, Game]` 注册两个场景。
+
+## Imports
+
+- `phaser.aicomponent`（硬依赖）
+
+## Skill Definition
+
+```yaml
+tools:
+  - read_file
+  - write_file
+inputs: []
+outputs:
+  - sceneArchitecture: Preloader → Game two-scene Phaser pattern
+```
+
+## Recipe
+
+| 决策 | 原因 |
+|------|------|
+| **双场景而非单场景** | Preloader 独立负责资产加载，避免主游戏场景在资源就绪前尝试渲染；架构模式明确，可测试各自生命周期 |
+| **架构文档 Skill（无代码产出）** | 场景架构是约定（谁先注册、谁负责切换），不是可复用的代码；文档 Skill 让 Agent 理解约束，具体实现由 preloader_scene 和 game_scene 两个 skill 贡献 |
+| **Preloader 调用 sdk.start()** | 资产加载完成是广告 SDK 的 ready 信号；集中在 Preloader 处理，避免在主场景中竞态 |
+
+## Adapter
+
+- **Role**: `sceneArchitecture` — Phaser Preloader→Game 双场景架构规范（无代码产出）
+- **Provides**: 场景注册约定、切换流程文档
+- **Requires**: `phaser.aicomponent`（硬依赖：Phaser.Scene + SceneManager API）
+- **Consumed by**: `preloader_scene.aicomponent`（按此约定实现 Preloader）、`game_scene.aicomponent`（按此约定实现 Game）
+- **Integration point**: `src/game/index.ts` → `scene: [Preloader, Game]` 注册顺序由本架构约定决定
+
+## 场景注册方式
+
+```typescript
+// src/game/index.ts (来自 phaser.aicomponent)
+scene: [Preloader, Game]   // Phaser 按顺序启动：先 Preloader，再 Game
+
+// Preloader.ts 加载完成后切换
+this.scene.start('Game');
+```

package/skills/phaser_scene_lifecycle.aicomponent/manifest.json

@@ -0,0 +1,33 @@
+{
+  "schemaVersion": 1,
+  "atomId": "phaser_scene_lifecycle.aicomponent",
+  "bundleType": "aicomponent",
+  "category": "scene",
+  "mode": "fixed",
+  "label": { "zh": "Phaser 双场景生命周期骨架", "en": "Phaser dual scene lifecycle skeleton" },
+  "tags": ["scene", "lifecycle", "preloader", "game-scene", "phaser", "skeleton"],
+  "bindingRoles": ["sceneLifecycle"],
+  "scaffold": {
+    "files": {},
+    "packageJson": {}
+  },
+  "imports": [
+    { "slot": "engine", "pinAtomId": "phaser.aicomponent", "edgeKind": "requires", "bindAs": "engine" }
+  ],
+  "exports": [
+    { "name": "SceneKeys", "kind": "enum", "location": "src/game/SceneKeys.ts" }
+  ],
+  "neutralDescriptor": {
+    "geometry": "two-scene Phaser architecture: Preloader scene handles asset loading then transitions to Game scene",
+    "layers": ["scene-routing", "asset-loading-gate", "scene-transition"],
+    "replaceable": ["scene list", "loading strategy"]
+  },
+  "usageHints": [
+    "Phaser 双场景标准模式：Preloader 负责资产加载 + 进度显示，完成后切换到 Game 主场景",
+    "src/game/index.ts（phaser.aicomponent）中配置 scene: [Preloader, Game]",
+    "SceneKeys 枚举统一管理场景名，避免字符串硬编码"
+  ],
+  "files": {
+    "skill": "SKILL.md"
+  }
+}

package/skills/pick_and_match_rules.aigameplay/SKILL.md

@@ -0,0 +1,113 @@
+---
+name: pick_and_match_rules.aigameplay
+description: 拾取三消玩法核心规则（PGS）。棋盘上有多种带颜色和形状的物品（可多层堆叠），玩家逐个点选物品放入底部篮子，篮子中凑齐 3 个颜色和形状都相同的物品即自动消除。在倒计时结束前清空棋盘所有物品即胜利；篮子满溢或超时则失败。
+triggers: 需要生成拾取三消、pick and match、triple sort、篮子消除、三消放篮子、tile match 类玩法的 PGS schema、关卡规则时触发。
+---
+
+# 拾取三消玩法（Pick & Match）
+
+## 玩法说明
+
+棋盘上有若干物品，每个物品有**颜色**和**形状**两个维度属性。物品可以多层堆叠（上层遮挡下层）。
+
+玩家每次从棋盘上点选一个**未被遮挡**的物品，物品飞入底部的**篮子（tray）**。篮子中的物品按同类聚合排列：
+
+- **匹配消除**：篮子中出现 3 个颜色和形状都相同的物品 → 自动消除这 3 个物品 → 篮子腾出空间
+- **篮子满溢**：篮子达到容量上限（默认 7 格）且无法消除 → 游戏失败
+- **胜利**：棋盘上所有物品都被拾取并消除
+- **失败**：篮子满溢 或 倒计时归零（仅当 `levelTime > 0`）
+
+## Recipe
+
+```json
+{
+  "kind": "pgs",
+  "pgsVersion": "1.0",
+  "gameplayType": "pick_and_match",
+  "rules": {
+    "matchCount": 3,
+    "trayCapacity": 7,
+    "layerStacking": true,
+    "groupingInsert": true,
+    "timerOptional": true
+  }
+}
+```
+
+完整 PGS Schema 见 `ref/pgs-schema.json`。
+
+## Result
+
+产物为 `ref/pgs-schema.json`，描述完整的拾取三消玩法规则，包含：
+
+- 实体定义（board / item / tray / timer）
+- 规则（可拾取判定 / 同类聚合插入 / 匹配检测 / 篮子溢出 / 输入锁）
+- 关卡数据 schema（ItemDef 格式，含层级）
+- 算法步骤（9 步主循环）
+- 胜负条件
+- 6 个测试用例（均满足 ≥9 物品最低约束）
+
+## 核心机制详解
+
+### 1. 物品属性
+
+每个物品有两个匹配维度：
+- **颜色**（color）：red / blue / green / yellow / purple / pink 等
+- **形状**（shape）：circle / square / triangle / star / diamond / heart 等
+
+**只有颜色和形状都相同的 3 个物品才会消除。**
+
+### 2. 多层堆叠
+
+物品可以叠放在其他物品上方。被上层物品遮挡的物品不可点击，需先拾取上层物品。这为关卡设计提供了策略深度。
+
+### 3. 同类聚合插入
+
+新物品放入篮子时，如果篮子中已有同类物品（颜色+形状相同），新物品自动插入到最后一个同类物品旁边，而非简单追加到末尾。这使得玩家更容易看到即将凑齐的组合。
+
+### 4. 关卡设计约束
+
+- 每种 (color, shape) 组合的物品数量**必须恰好为 3 个**
+- 棋盘物品总数**至少 9 个**（即至少 3 组不同组合 × 3），少于 9 个游戏过于简单无可玩性
+- 至少 **3 种**不同的 (color, shape) 组合，否则策略性不足
+
+## Binding
+
+```json
+{
+  "role": "gameplayRule",
+  "target": "src/game/",
+  "type": "gameplay-module-reference",
+  "constraints": {
+    "requiredComponents": [
+      "pick_match_tray.aicomponent",
+      "pick_match_board_renderer.aicomponent",
+      "pick_match_input_handler.aicomponent",
+      "level_lifecycle.aicomponent"
+    ]
+  }
+}
+```
+
+## Skill Definition
+
+```yaml
+tools:
+  - read_file
+  - write_file
+inputs:
+  - pgsSchema: ref/pgs-schema.json
+outputs:
+  - reducerTemplate: game logic reducer based on PGS schema
+```
+
+## 与其他玩法的区别
+
+| 维度 | 经典三消 (match3) | 路径消除 (path_elimination) | 拾取三消 (pick_and_match) |
+|-----|------------------|---------------------------|--------------------------|
+| 棋盘模型 | 固定网格，元素填满 | 动态网格，折线路径 | 动态网格，多层堆叠物品 |
+| 输入方式 | 交换相邻两个元素 | 点击路径箭头头部 | 点击物品拾取放入篮子 |
+| 匹配方式 | 3+ 同色连成线 | 方向出口空闲即消除 | 篮子中 3 个同色同形消除 |
+| 匹配维度 | 单维度（颜色/类型） | 无匹配（出口检测） | 双维度（颜色 × 形状） |
+| 失败条件 | 步数耗尽 | 生命归零 / 超时 | 篮子满溢 / 超时 |
+| 策略要素 | 连消 / 特殊块 | 消除顺序 / 路径阻挡 | 堆叠层级 / 篮子管理 |