@quybt93/pcgf 0.0.1

package/installer/install.js

@@ -0,0 +1,201 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { resolveAndInstallDeps } from './deps.js';
+import { copyDirectory, ensureDir, listSkillNames, pathExists, readJson, writeJson } from './fs-utils.js';
+import { INSTALL_DIR_NAME, installRoot, manifestPath, packageRoot, pluginRoot } from './paths.js';
+import { scaffoldFoundation } from './scaffold.js';
+
+function packageVersion() {
+  const pkg = readJson(path.join(packageRoot, 'package.json'), { version: '0.0.0' });
+  return pkg.version || '0.0.0';
+}
+
+function assertPluginPresent() {
+  if (!pathExists(pluginRoot)) {
+    throw new Error(`Plugin source missing at ${pluginRoot}`);
+  }
+  if (!pathExists(path.join(pluginRoot, 'skills'))) {
+    throw new Error(`Plugin skills missing at ${path.join(pluginRoot, 'skills')}`);
+  }
+}
+
+function removePath(targetPath) {
+  fs.rmSync(targetPath, { recursive: true, force: true });
+}
+
+function copyPluginBundle(projectDir) {
+  const root = installRoot(projectDir);
+  const targetPlugin = path.join(root, 'plugin');
+
+  ensureDir(root);
+  // Full replace so renamed/deleted skills & templates do not linger.
+  removePath(targetPlugin);
+  copyDirectory(pluginRoot, targetPlugin);
+
+  // Keep consuming repos lean: drop demo/test trees from the installed copy.
+  for (const relative of ['examples', 'tests']) {
+    removePath(path.join(targetPlugin, relative));
+  }
+
+  return targetPlugin;
+}
+
+function installCursorSkills(projectDir, pluginDir, previousSkillNames = []) {
+  const skillsSource = path.join(pluginDir, 'skills');
+  const skillsTarget = path.join(projectDir, '.cursor', 'skills');
+  const skillNames = listSkillNames(skillsSource);
+  const stale = previousSkillNames.filter((name) => !skillNames.includes(name));
+
+  ensureDir(skillsTarget);
+  for (const skillName of stale) {
+    removePath(path.join(skillsTarget, skillName));
+  }
+  for (const skillName of skillNames) {
+    removePath(path.join(skillsTarget, skillName));
+    copyDirectory(path.join(skillsSource, skillName), path.join(skillsTarget, skillName));
+  }
+
+  return { target: '.cursor/skills', skills: skillNames, removedStale: stale };
+}
+
+function installCodexMarketplace(projectDir) {
+  const marketplaceDir = path.join(projectDir, '.agents', 'plugins');
+  const marketplaceFile = path.join(marketplaceDir, 'marketplace.json');
+  const pluginRelative = path
+    .relative(marketplaceDir, path.join(projectDir, INSTALL_DIR_NAME, 'plugin'))
+    .replaceAll('\\', '/');
+
+  const marketplace = {
+    name: 'phaser-casual-game-factory-local',
+    interface: {
+      displayName: 'Phaser Casual Game Factory (project)',
+    },
+    plugins: [
+      {
+        name: 'phaser-casual-game-factory',
+        source: {
+          source: 'local',
+          path: pluginRelative,
+        },
+        policy: {
+          installation: 'AVAILABLE',
+          authentication: 'ON_INSTALL',
+        },
+        category: 'Developer Tools',
+      },
+    ],
+  };
+
+  writeJson(marketplaceFile, marketplace);
+  return { target: '.agents/plugins/marketplace.json' };
+}
+
+function writeInstallReadme(projectDir) {
+  const readmePath = path.join(installRoot(projectDir), 'README.md');
+  const contents = `# Phaser Casual Game Factory install
+
+This folder was created by \`pcgf install\` (BMAD-style project install).
+
+- \`plugin/\` — skills, templates, references for agents and scaffolding
+- \`manifest.json\` — install record (version, tools, scaffold)
+
+## Next steps
+
+1. Open this project in Cursor/Codex.
+2. Ask the agent to use skill \`phaser-casual-game-factory\`.
+3. If foundation was scaffolded, merge \`FACTORY_RENDERER_DEFAULTS\` into Phaser config and register LoadingOverlay last.
+4. Re-run install later to refresh skills/templates **without overwriting game src**:
+
+\`\`\`bash
+npx pcgf install --yes --no-scaffold
+\`\`\`
+
+5. Full wipe then reinstall (stale skills / bad scaffold):
+
+\`\`\`bash
+npx pcgf clean --yes
+npx pcgf install --yes --scaffold
+\`\`\`
+
+Use \`pcgf clean --yes --with-scaffold\` to also delete \`src/factory/\` before reinstall.
+
+From Git (other machines, GitLab SSH):
+
+\`\`\`bash
+npx --yes --package=git+ssh://git@git.skylinkmedia.asia:h5-game/unityhn/plugin-casual-game-factory.git pcgf install --yes --no-scaffold
+\`\`\`
+
+Use \`--scaffold\` only for a brand-new game or when the user asks to regenerate \`src/factory/\`.
+`;
+  fs.writeFileSync(readmePath, contents, 'utf8');
+}
+
+export function readExistingManifest(projectDir) {
+  return readJson(manifestPath(projectDir), null);
+}
+
+export async function runInstall(options) {
+  assertPluginPresent();
+
+  const projectDir = path.resolve(options.directory);
+  ensureDir(projectDir);
+
+  const existing = readExistingManifest(projectDir);
+  const action = existing ? options.action || 'update' : 'install';
+  const previousSkillNames = existing?.skills ?? [];
+
+  const pluginDir = copyPluginBundle(projectDir);
+  writeInstallReadme(projectDir);
+
+  const toolResults = {};
+  for (const toolId of options.tools) {
+    if (toolId === 'cursor') {
+      toolResults.cursor = installCursorSkills(projectDir, pluginDir, previousSkillNames);
+    } else if (toolId === 'codex') {
+      toolResults.codex = installCodexMarketplace(projectDir);
+    } else {
+      throw new Error(`Unsupported tool: ${toolId}`);
+    }
+  }
+
+  let scaffoldResult = null;
+  if (options.scaffold) {
+    scaffoldResult = scaffoldFoundation(projectDir);
+  }
+
+  const depsResult = await resolveAndInstallDeps(projectDir, {
+    confirm: Boolean(options.installDeps),
+    createIfMissing: options.createPackageJson !== false,
+  });
+
+  if (scaffoldResult) {
+    scaffoldResult.deps = depsResult;
+  }
+
+  const manifest = {
+    name: 'phaser-casual-game-factory',
+    version: packageVersion(),
+    action,
+    installedAt: new Date().toISOString(),
+    previousVersion: existing?.version ?? null,
+    directory: projectDir,
+    tools: options.tools,
+    scaffold: Boolean(options.scaffold),
+    installDeps: Boolean(options.installDeps),
+    depsStatus: depsResult.status,
+    pluginPath: path.join(INSTALL_DIR_NAME, 'plugin').replaceAll('\\', '/'),
+    skills: listSkillNames(path.join(pluginDir, 'skills')),
+  };
+
+  writeJson(manifestPath(projectDir), manifest);
+
+  return {
+    action,
+    projectDir,
+    installDir: installRoot(projectDir),
+    manifest,
+    toolResults,
+    scaffoldResult,
+    depsResult,
+  };
+}

package/installer/paths.js

@@ -0,0 +1,17 @@
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const installerDir = path.dirname(fileURLToPath(import.meta.url));
+
+export const packageRoot = path.resolve(installerDir, '..');
+export const pluginRoot = path.join(packageRoot, 'plugins', 'phaser-casual-game-factory');
+export const INSTALL_DIR_NAME = '_pcgf';
+export const MANIFEST_NAME = 'manifest.json';
+
+export function installRoot(projectDir) {
+  return path.join(projectDir, INSTALL_DIR_NAME);
+}
+
+export function manifestPath(projectDir) {
+  return path.join(installRoot(projectDir), MANIFEST_NAME);
+}

package/installer/scaffold.js

@@ -0,0 +1,274 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { copyFile, ensureDir, pathExists } from './fs-utils.js';
+import { pluginRoot } from './paths.js';
+
+const DIRECTORIES = [
+  'src/app',
+  'src/core',
+  'src/scenes',
+  'src/systems',
+  'src/ui',
+  'src/config',
+  'src/factory/loading-view',
+  'src/factory/boot',
+  'src/factory/boot/brand',
+  'src/factory/phaser',
+  'src/factory/motion',
+  'src/factory/ui',
+  'assets/audio',
+  'assets/images',
+  'public/assets/ui',
+  'public/assets/sfx',
+  'tests',
+];
+
+const TEMPLATE_COPIES = {
+  'templates/loading-view/types.ts': 'src/factory/loading-view/types.ts',
+  'templates/loading-view/loading-view-model.ts': 'src/factory/loading-view/loading-view-model.ts',
+  'templates/loading-view/presets.ts': 'src/factory/loading-view/presets.ts',
+  'templates/loading-view/progress.ts': 'src/factory/loading-view/progress.ts',
+  'templates/loading-view/index.ts': 'src/factory/loading-view/index.ts',
+  'templates/boot/play-boot-loading-view.ts': 'src/factory/boot/play-boot-loading-view.ts',
+  'templates/boot/close-styles.ts': 'src/factory/boot/close-styles.ts',
+  'templates/boot/iris-close.ts': 'src/factory/boot/iris-close.ts',
+  'templates/boot/map-dom-rect-to-game.ts': 'src/factory/boot/map-dom-rect-to-game.ts',
+  'templates/boot/index.ts': 'src/factory/boot/index.ts',
+  'templates/boot/brand-shims.d.ts': 'src/factory/boot/brand-shims.d.ts',
+  'templates/boot/brand/BootLoadingScreen.js': 'src/factory/boot/brand/BootLoadingScreen.js',
+  'templates/boot/brand/SplashFullscreenBg.js': 'src/factory/boot/brand/SplashFullscreenBg.js',
+  'templates/boot/brand/brand-defaults.js': 'src/factory/boot/brand/brand-defaults.js',
+  'templates/phaser/loading-overlay-scene.ts': 'src/factory/phaser/loading-overlay-scene.ts',
+  'templates/phaser/hybrid-loading-layer.css': 'src/factory/phaser/hybrid-loading-layer.css',
+  'templates/phaser/scene-keys.ts': 'src/factory/phaser/scene-keys.ts',
+  'templates/phaser/scene-registration.ts': 'src/factory/phaser/scene-registration.ts',
+  'templates/motion/types.ts': 'src/factory/motion/types.ts',
+  'templates/motion/phaser-ui-motion.ts': 'src/factory/motion/phaser-ui-motion.ts',
+  'templates/motion/index.ts': 'src/factory/motion/index.ts',
+  'templates/ui/audio-settings.ts': 'src/factory/ui/audio-settings.ts',
+  'templates/ui/settings-popup-phaser.ts': 'src/factory/ui/settings-popup-phaser.ts',
+  'templates/ui/settings-popup-dom.ts': 'src/factory/ui/settings-popup-dom.ts',
+  'templates/ui/bind-factory-dom-press.ts': 'src/factory/ui/bind-factory-dom-press.ts',
+  'templates/ui/ui-sfx.ts': 'src/factory/ui/ui-sfx.ts',
+  'templates/ui/factory-cream-casual.css': 'src/factory/ui/factory-cream-casual.css',
+  'templates/ui/index.ts': 'src/factory/ui/index.ts',
+  'templates/ui-reskin/compare.html': 'public/ui-reskin-compare.html',
+};
+
+const SCENE_ORDER = `// Default scenes: Boot → Home → Game.
+// FactoryLoadingOverlay is a technical Loading View (register last), not a destination.
+export const CASUAL_GAME_SCENE_ORDER = [
+  'Boot',
+  'Home',
+  'Game',
+  'FactoryLoadingOverlay',
+] as const;
+`;
+
+const RENDERER_DEFAULTS = `import type * as Phaser from 'phaser';
+
+// Required when a bitmap-masked Phaser LoadingView reveals an HTML Home.
+export const FACTORY_RENDERER_DEFAULTS = {
+  transparent: true,
+} satisfies Pick<Phaser.Types.Core.GameConfig, 'transparent'>;
+`;
+
+const GAME_SESSION = `export interface GameSessionState {
+  levelId: string;
+  score: number;
+  isPaused: boolean;
+  startedAt: number;
+}
+`;
+
+const BOOT_SCENE_STUB = `import * as Phaser from 'phaser';
+import { FactoryLoadingOverlayScene } from '../factory/phaser/loading-overlay-scene';
+import { LOADING_TIMING_PRESETS, LoadingViewModel, type LoadingViewTask } from '../factory/loading-view';
+import {
+  BOOT_CLOSE_STYLE,
+  createBootIrisClose,
+  playBootLoadingView,
+} from '../factory/boot';
+
+/**
+ * Boot → Home close styles (pick one):
+ * - BOOT_CLOSE_STYLE.iris (default) — frog bitmap iris 0 → full
+ * - BOOT_CLOSE_STYLE.slideUp — DOM splash slides up (associatio-match)
+ */
+const BOOT_CLOSE = BOOT_CLOSE_STYLE.iris;
+
+/**
+ * Boot → Home uses company Studio25 brand LoadingView via playBootLoadingView.
+ * Rename to BootScene.ts and wire real asset/data tasks.
+ */
+export class BootScene extends Phaser.Scene {
+  constructor() {
+    super('Boot');
+  }
+
+  create(): void {
+    void this.runBoot();
+  }
+
+  private async runBoot(): Promise<void> {
+    const game = this.game;
+    let releaseAssets!: () => void;
+    const assetsReady = new Promise<void>((resolve) => {
+      releaseAssets = resolve;
+    });
+
+    const ensureOverlay = async (): Promise<FactoryLoadingOverlayScene> => {
+      const overlay = game.scene.getScene(
+        FactoryLoadingOverlayScene.KEY,
+      ) as FactoryLoadingOverlayScene;
+      if (!game.scene.isActive(FactoryLoadingOverlayScene.KEY)) {
+        game.scene.run(FactoryLoadingOverlayScene.KEY);
+        await Promise.race([
+          new Promise<void>((resolve) =>
+            overlay.events.once(Phaser.Scenes.Events.CREATE, () => resolve()),
+          ),
+          new Promise<void>((resolve) => window.setTimeout(resolve, 800)),
+        ]);
+      }
+      game.scene.bringToTop(FactoryLoadingOverlayScene.KEY);
+      return overlay;
+    };
+
+    const tasks: LoadingViewTask[] = [
+      {
+        id: 'boot-assets',
+        weight: 2,
+        run: async ({ reportProgress }) => {
+          // Queue/start Phaser loader here and report real progress.
+          reportProgress(1);
+          releaseAssets();
+        },
+      },
+      {
+        id: 'home-scene',
+        weight: 2,
+        afterOpen: true,
+        run: async ({ reportProgress }) => {
+          await assetsReady;
+          if (!game.scene.isActive('Home')) game.scene.start('Home');
+          if (BOOT_CLOSE === BOOT_CLOSE_STYLE.iris) await ensureOverlay();
+          reportProgress(1);
+        },
+      },
+    ];
+
+    await playBootLoadingView(
+      new LoadingViewModel(
+        {
+          ...LOADING_TIMING_PRESETS.bootToHome,
+          description: 'Loading…',
+          ...(BOOT_CLOSE === BOOT_CLOSE_STYLE.slideUp
+            ? { closeDurationMs: 650 }
+            : {}),
+        },
+        tasks,
+      ),
+      {
+        frogSrc: '/logo-frog.png',
+        closeStyle: BOOT_CLOSE,
+        runIrisClose: createBootIrisClose({
+          game,
+          maskKey: 'factory_transition_mask',
+          ensureOverlay,
+        }),
+      },
+    );
+  }
+}
+`;
+
+const HOME_SCENE_STUB = `import * as Phaser from 'phaser';
+
+/** Transparent Phaser shell — HTML Home View may sit beneath the canvas. */
+export class HomeScene extends Phaser.Scene {
+  constructor() {
+    super('Home');
+  }
+
+  create(): void {
+    this.cameras.main.setBackgroundColor({ r: 0, g: 0, b: 0, a: 0 });
+  }
+}
+`;
+
+const GAME_SCENE_STUB = `import * as Phaser from 'phaser';
+
+/** Gameplay scene — wire systems here; navigate Home↔Game via LoadingView. */
+export class GameScene extends Phaser.Scene {
+  constructor() {
+    super('Game');
+  }
+
+  create(): void {
+    // Placeholder play area.
+  }
+}
+`;
+
+function writeUtf8(filePath, contents) {
+  ensureDir(path.dirname(filePath));
+  fs.writeFileSync(filePath, contents, 'utf8');
+}
+
+export function scaffoldFoundation(projectDir) {
+  for (const relativeDir of DIRECTORIES) {
+    ensureDir(path.join(projectDir, relativeDir));
+  }
+
+  writeUtf8(path.join(projectDir, 'src/app/scene-order.ts'), SCENE_ORDER);
+  writeUtf8(path.join(projectDir, 'src/app/phaser-renderer.ts'), RENDERER_DEFAULTS);
+  writeUtf8(path.join(projectDir, 'src/core/game-session.ts'), GAME_SESSION);
+  writeUtf8(path.join(projectDir, 'src/scenes/BootScene.stub.ts'), BOOT_SCENE_STUB);
+  writeUtf8(path.join(projectDir, 'src/scenes/HomeScene.stub.ts'), HOME_SCENE_STUB);
+  writeUtf8(path.join(projectDir, 'src/scenes/GameScene.stub.ts'), GAME_SCENE_STUB);
+
+  for (const [sourceRelative, targetRelative] of Object.entries(TEMPLATE_COPIES)) {
+    const sourcePath = path.join(pluginRoot, sourceRelative);
+    if (!pathExists(sourcePath)) {
+      throw new Error(`Missing scaffold template: ${sourceRelative}`);
+    }
+    copyFile(sourcePath, path.join(projectDir, targetRelative));
+  }
+
+  const lobbyBg = path.join(
+    pluginRoot,
+    'examples',
+    'factory-browser-demo',
+    'public',
+    'assets',
+    'ui',
+    'BG_lobby.png',
+  );
+  if (pathExists(lobbyBg)) {
+    copyFile(lobbyBg, path.join(projectDir, 'public', 'assets', 'ui', 'BG_lobby.png'));
+  }
+
+  // Studio25 brand frog — Boot View art (+ Home↔Game overlay may reuse the file).
+  const logoFrog = path.join(
+    pluginRoot,
+    'examples',
+    'factory-browser-demo',
+    'public',
+    'logo-frog.png',
+  );
+  if (pathExists(logoFrog)) {
+    copyFile(logoFrog, path.join(projectDir, 'public', 'logo-frog.png'));
+  }
+
+  for (const sfxName of ['ui_click.mp3', 'ui_close.mp3']) {
+    const sfxSrc = path.join(pluginRoot, 'assets', 'sfx', sfxName);
+    if (pathExists(sfxSrc)) {
+      copyFile(sfxSrc, path.join(projectDir, 'public', 'assets', 'sfx', sfxName));
+    }
+  }
+
+  return {
+    copiedTemplates: Object.keys(TEMPLATE_COPIES).length,
+    createdDirs: DIRECTORIES.length,
+  };
+}

package/installer/tools.js

@@ -0,0 +1,38 @@
+export const TOOLS = {
+  cursor: {
+    id: 'cursor',
+    label: 'Cursor',
+    target: '.cursor/skills',
+    description: 'Copy factory skills into .cursor/skills for project-scoped Cursor agents.',
+  },
+  codex: {
+    id: 'codex',
+    label: 'Codex',
+    target: '.agents/plugins/marketplace.json',
+    description: 'Register a repo-scoped Codex marketplace that points at _pcgf/plugin.',
+  },
+};
+
+export const TOOL_IDS = Object.keys(TOOLS);
+
+export function parseTools(value) {
+  if (!value || String(value).trim() === '') {
+    return [];
+  }
+  const ids = String(value)
+    .split(',')
+    .map((part) => part.trim().toLowerCase())
+    .filter(Boolean);
+  const unknown = ids.filter((id) => !TOOLS[id]);
+  if (unknown.length > 0) {
+    throw new Error(`Unknown tools: ${unknown.join(', ')}. Valid: ${TOOL_IDS.join(', ')}`);
+  }
+  return [...new Set(ids)];
+}
+
+export function formatToolsHelp() {
+  return TOOL_IDS.map((id) => {
+    const tool = TOOLS[id];
+    return `  ${id.padEnd(10)} ${tool.description} (${tool.target})`;
+  }).join('\n');
+}

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@quybt93/pcgf",
+  "version": "0.0.1",
+  "description": "Phaser Casual Game Factory — BMAD-style installer (npx @quybt93/pcgf install).",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "pcgf": "bin/pcgf.js"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20.12.0"
+  },
+  "files": [
+    "bin",
+    "installer",
+    "plugins",
+    ".agents"
+  ],
+  "scripts": {
+    "pcgf": "node ./bin/pcgf.js"
+  },
+  "keywords": [
+    "pcgf",
+    "phaser",
+    "casual-game",
+    "codex-plugin",
+    "cursor-skills",
+    "installer"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git@git.skylinkmedia.asia:h5-game/unityhn/plugin-casual-game-factory.git"
+  }
+}

package/plugins/phaser-casual-game-factory/.codex-plugin/plugin.json

@@ -0,0 +1,27 @@
+{
+  "name": "phaser-casual-game-factory",
+  "version": "0.0.1",
+  "description": "Reusable architecture, workflow, and starter templates for building polished Phaser casual games.",
+  "author": {
+    "name": "Casual Game Factory"
+  },
+  "license": "MIT",
+  "keywords": ["phaser", "casual-game", "game-ui", "web-game", "typescript"],
+  "skills": "./skills/",
+  "interface": {
+    "displayName": "Phaser Casual Game Factory",
+    "shortDescription": "Build reusable Phaser casual games.",
+    "longDescription": "A reusable foundation for Phaser casual games: Boot→Home→Game lifecycle, preferred MVVM/RxJS for reactive UI, Studio25 Boot brand skill, UI reskin navigator (theme/assets/feeling/SFX), Home↔Game overlay transitions, GitLab side-branch merge requests, responsive layout, input, audio, persistence, UI patterns, and implementation checklists.",
+    "developerName": "Casual Game Factory",
+    "category": "Developer Tools",
+    "capabilities": ["Interactive", "Write"],
+    "brandColor": "#6D5EF5",
+    "defaultPrompt": [
+      "Create a Phaser casual game with Boot, Home, and Game scenes from the factory architecture.",
+      "Add a scene-safe LoadingView with real task progress and smooth destination reveal.",
+      "Reskin this Phaser game UI via pcgf-ui-reskin (theme, asset pack, feeling, SFX) and show compare.html.",
+      "Add a polished responsive UI to this Phaser game.",
+      "Review this Phaser game for reusable architecture issues."
+    ]
+  }
+}