@coze-arch/cli 0.0.37 → 0.1.3-alpha.8d71d5

package/lib/__templates__/phaser/src/scene/DevLoadingScene.ts

@@ -0,0 +1,69 @@
+import Phaser from 'phaser';
+
+import { markEditable } from '@/utils';
+
+import { DEV_LOADING_RUNTIME_KEYS } from './BootScene';
+
+/**
+ * 本场景用于为兜底场景展示
+ */
+export class DevLoadingScene extends Phaser.Scene {
+  constructor() {
+    super('dev-loading');
+  }
+
+  create(): void {
+    const { centerX, centerY } = this.cameras.main;
+
+    markEditable(
+      'dev-loading.mascot',
+      this.add
+        .sprite(centerX, centerY - 82, DEV_LOADING_RUNTIME_KEYS.texture)
+        .setScale(0.64)
+        .play(DEV_LOADING_RUNTIME_KEYS.animation),
+      { label: '开发中吉祥物' },
+    );
+
+    markEditable(
+      'dev-loading.title',
+      this.add
+        .text(centerX, centerY + 92, '游戏开发中', {
+          color: '#18181b',
+          fontFamily: '"PingFang SC", "Microsoft YaHei", sans-serif',
+          fontSize: '32px',
+          fontStyle: 'bold',
+        })
+        .setOrigin(0.5),
+      { label: '开发中标题' },
+    );
+
+    markEditable(
+      'dev-loading.description',
+      this.add
+        .text(centerX, centerY + 138, '请稍后，游戏世界即将呈现', {
+          color: '#71717a',
+          fontFamily: '"PingFang SC", "Microsoft YaHei", sans-serif',
+          fontSize: '18px',
+        })
+        .setOrigin(0.5),
+      { label: '开发中说明文案' },
+    );
+
+    const loadingDots = Array.from({ length: 3 }, (_value, index) =>
+      this.add.circle(centerX + (index - 1) * 18, centerY + 178, 4, 0xf43f75),
+    );
+
+    loadingDots.forEach((dot, index) => {
+      this.tweens.add({
+        targets: dot,
+        alpha: 0.25,
+        scale: 0.7,
+        duration: 520,
+        delay: index * 160,
+        ease: 'Sine.inOut',
+        repeat: -1,
+        yoyo: true,
+      });
+    });
+  }
+}

package/lib/__templates__/phaser/src/style.css

@@ -0,0 +1,28 @@
+:root {
+  color-scheme: dark;
+  font-family: Arial, sans-serif;
+  background: #000;
+}
+
+* {
+  box-sizing: border-box;
+}
+
+html,
+body,
+#game {
+  width: 100%;
+  height: 100%;
+  margin: 0;
+  overflow: hidden;
+  background: #000;
+}
+
+#game {
+  min-width: 0;
+  min-height: 0;
+}
+
+#game canvas {
+  display: block;
+}

package/lib/__templates__/phaser/src/types.ts

@@ -0,0 +1,32 @@
+export type AssetSources = Readonly<Record<string, string>>;
+
+export interface AssetCollections {
+  images?: AssetSources;
+  imageSequences?: AssetSources;
+  videos?: AssetSources;
+  audios?: AssetSources;
+}
+
+export interface ImageSequenceManifest {
+  schema_version: string;
+  id: string;
+  type: 'image_sequence';
+  name: string;
+  properties: {
+    fps: number;
+    frame_count: number;
+  };
+  sources: readonly string[];
+}
+
+export type LoadedAsset =
+  | {
+      kind: 'image' | 'video' | 'audio';
+      key: string;
+    }
+  | {
+      kind: 'image-sequence';
+      key: string;
+      texture: string;
+      animation: string;
+    };

package/lib/__templates__/phaser/src/utils/asset-loader.ts

@@ -0,0 +1,319 @@
+import type Phaser from 'phaser';
+
+import { AUDIOS, IMAGES, IMAGE_SEQUENCES, VIDEOS } from '../assets';
+import type {
+  AssetCollections,
+  AssetSources,
+  ImageSequenceManifest,
+  LoadedAsset,
+} from '../types';
+
+const FRAME_KEY_MARKER = ':frame:';
+const MANIFEST_KEY_SUFFIX = ':manifest';
+
+const getFrameKey = (assetKey: string, frameIndex: number): string =>
+  `${assetKey}${FRAME_KEY_MARKER}${String(frameIndex + 1).padStart(4, '0')}`;
+
+const getManifestKey = (assetKey: string): string =>
+  `${assetKey}${MANIFEST_KEY_SUFFIX}`;
+
+const getFrameSource = (directory: string, frameIndex: number): string =>
+  `${directory}/frame_${String(frameIndex + 1).padStart(4, '0')}.png`;
+
+export const resolveAssetUrl = (source: string): string =>
+  new URL(source, document.baseURI).href;
+
+const isImageSequenceManifest = (
+  value: unknown,
+): value is ImageSequenceManifest => {
+  if (!value || typeof value !== 'object') {
+    return false;
+  }
+
+  const manifest = value as Partial<ImageSequenceManifest>;
+  return (
+    manifest.type === 'image_sequence' &&
+    typeof manifest.name === 'string' &&
+    typeof manifest.properties?.fps === 'number' &&
+    typeof manifest.properties.frame_count === 'number' &&
+    manifest.properties.frame_count > 0
+  );
+};
+
+const getImageSequenceManifest = (
+  scene: Phaser.Scene,
+  assetKey: string,
+): ImageSequenceManifest => {
+  const manifest: unknown = scene.cache.json.get(getManifestKey(assetKey));
+  if (!isImageSequenceManifest(manifest)) {
+    throw new Error(`Invalid image sequence manifest: ${assetKey}`);
+  }
+
+  return manifest;
+};
+
+const queueImageSequenceFrames = (
+  scene: Phaser.Scene,
+  assetKey: string,
+  directory: string,
+  manifest: ImageSequenceManifest,
+): void => {
+  Array.from(
+    { length: manifest.properties.frame_count },
+    (_value, frameIndex) => {
+      scene.load.image(
+        getFrameKey(assetKey, frameIndex),
+        resolveAssetUrl(getFrameSource(directory, frameIndex)),
+      );
+    },
+  );
+};
+
+const queueImages = (scene: Phaser.Scene, images: AssetSources): number => {
+  Object.entries(images).forEach(([assetKey, source]) => {
+    scene.load.image(assetKey, resolveAssetUrl(source));
+  });
+  return Object.keys(images).length;
+};
+
+const queueVideos = (scene: Phaser.Scene, videos: AssetSources): number => {
+  Object.entries(videos).forEach(([assetKey, source]) => {
+    scene.load.video(assetKey, resolveAssetUrl(source));
+  });
+  return Object.keys(videos).length;
+};
+
+const queueAudios = (scene: Phaser.Scene, audios: AssetSources): number => {
+  Object.entries(audios).forEach(([assetKey, source]) => {
+    scene.load.audio(assetKey, resolveAssetUrl(source));
+  });
+  return Object.keys(audios).length;
+};
+
+const queueImageSequences = (
+  scene: Phaser.Scene,
+  imageSequences: AssetSources,
+): number => {
+  return Object.entries(imageSequences).reduce(
+    (fileCount, [assetKey, directory]) => {
+      const manifestKey = getManifestKey(assetKey);
+      const cachedManifest: unknown = scene.cache.json.get(manifestKey);
+
+      if (isImageSequenceManifest(cachedManifest)) {
+        queueImageSequenceFrames(
+          scene,
+          assetKey,
+          directory,
+          cachedManifest,
+        );
+        return fileCount + cachedManifest.properties.frame_count;
+      }
+
+      scene.load.once(
+        `filecomplete-json-${manifestKey}`,
+        (_key: string, _type: string, data: unknown) => {
+          if (!isImageSequenceManifest(data)) {
+            throw new Error(`Invalid image sequence manifest: ${assetKey}`);
+          }
+
+          queueImageSequenceFrames(scene, assetKey, directory, data);
+        },
+      );
+
+      scene.load.json(
+        manifestKey,
+        resolveAssetUrl(`${directory}/manifest.json`),
+      );
+      return fileCount + 1;
+    },
+    0,
+  );
+};
+
+export const loadAssets = (
+  scene: Phaser.Scene,
+  collections: AssetCollections,
+): number =>
+  queueImages(scene, collections.images ?? {}) +
+  queueImageSequences(scene, collections.imageSequences ?? {}) +
+  queueVideos(scene, collections.videos ?? {}) +
+  queueAudios(scene, collections.audios ?? {});
+
+export const getImageSequenceRuntimeKeys = (
+  assetKey: string,
+): { texture: string; animation: string } => ({
+  texture: getFrameKey(assetKey, 0),
+  animation: `${assetKey}:animation`,
+});
+
+export const getAssetKeyFromFileKey = (fileKey: string): string =>
+  fileKey.split(FRAME_KEY_MARKER)[0]?.replace(MANIFEST_KEY_SUFFIX, '') ??
+  fileKey;
+
+export const getAssetLabelFromFileKey = (
+  fileKey: string,
+  collections: AssetCollections,
+): string => {
+  const assetKey = getAssetKeyFromFileKey(fileKey);
+
+  if (assetKey in (collections.images ?? {})) {
+    return `图片 ${assetKey}`;
+  }
+  if (assetKey in (collections.imageSequences ?? {})) {
+    return `帧动画 ${assetKey}`;
+  }
+  if (assetKey in (collections.videos ?? {})) {
+    return `视频 ${assetKey}`;
+  }
+  if (assetKey in (collections.audios ?? {})) {
+    return `音频 ${assetKey}`;
+  }
+
+  return assetKey;
+};
+
+export const registerImageSequenceAnimations = (
+  scene: Phaser.Scene,
+  imageSequences: AssetSources,
+): void => {
+  Object.keys(imageSequences).forEach(assetKey => {
+    const manifest = getImageSequenceManifest(scene, assetKey);
+    const animationKey = getImageSequenceRuntimeKeys(assetKey).animation;
+    if (scene.anims.exists(animationKey)) {
+      return;
+    }
+
+    scene.anims.create({
+      key: animationKey,
+      frames: Array.from(
+        { length: manifest.properties.frame_count },
+        (_value, frameIndex) => ({ key: getFrameKey(assetKey, frameIndex) }),
+      ),
+      frameRate: manifest.properties.fps,
+      repeat: -1,
+    });
+  });
+};
+
+const findAsset = (
+  assetKey: string,
+): { collections: AssetCollections; loadedAsset: LoadedAsset } => {
+  const matches: Array<{
+    collections: AssetCollections;
+    loadedAsset: LoadedAsset;
+  }> = [];
+
+  if (Object.hasOwn(IMAGES, assetKey)) {
+    matches.push({
+      collections: { images: { [assetKey]: IMAGES[assetKey] } },
+      loadedAsset: { kind: 'image', key: assetKey },
+    });
+  }
+  if (Object.hasOwn(IMAGE_SEQUENCES, assetKey)) {
+    matches.push({
+      collections: {
+        imageSequences: { [assetKey]: IMAGE_SEQUENCES[assetKey] },
+      },
+      loadedAsset: {
+        kind: 'image-sequence',
+        key: assetKey,
+        ...getImageSequenceRuntimeKeys(assetKey),
+      },
+    });
+  }
+  if (Object.hasOwn(VIDEOS, assetKey)) {
+    matches.push({
+      collections: { videos: { [assetKey]: VIDEOS[assetKey] } },
+      loadedAsset: { kind: 'video', key: assetKey },
+    });
+  }
+  if (Object.hasOwn(AUDIOS, assetKey)) {
+    matches.push({
+      collections: { audios: { [assetKey]: AUDIOS[assetKey] } },
+      loadedAsset: { kind: 'audio', key: assetKey },
+    });
+  }
+
+  if (matches.length === 0) {
+    throw new Error(`Asset not found: ${assetKey}`);
+  }
+  if (matches.length > 1) {
+    throw new Error(`Duplicate asset key: ${assetKey}`);
+  }
+
+  return matches[0];
+};
+
+const isAssetLoaded = (
+  scene: Phaser.Scene,
+  loadedAsset: LoadedAsset,
+): boolean => {
+  switch (loadedAsset.kind) {
+    case 'image':
+      return scene.textures.exists(loadedAsset.key);
+    case 'image-sequence':
+      return scene.anims.exists(loadedAsset.animation);
+    case 'video':
+      return scene.cache.video.exists(loadedAsset.key);
+    case 'audio':
+      return scene.cache.audio.exists(loadedAsset.key);
+  }
+};
+
+interface LoaderFileLike {
+  key: string;
+}
+
+export const loadAsset = async (
+  scene: Phaser.Scene,
+  assetKey: string,
+): Promise<LoadedAsset> => {
+  const { collections, loadedAsset } = findAsset(assetKey);
+  if (isAssetLoaded(scene, loadedAsset)) {
+    return loadedAsset;
+  }
+
+  return new Promise<LoadedAsset>((resolve, reject) => {
+    const cleanup = (): void => {
+      scene.load.off('complete', onComplete);
+      scene.load.off('loaderror', onLoadError);
+    };
+
+    const onComplete = (): void => {
+      cleanup();
+      try {
+        if (loadedAsset.kind === 'image-sequence') {
+          registerImageSequenceAnimations(
+            scene,
+            collections.imageSequences ?? {},
+          );
+        }
+        resolve(loadedAsset);
+      } catch (error) {
+        reject(error);
+      }
+    };
+
+    const onLoadError = (file: LoaderFileLike): void => {
+      if (getAssetKeyFromFileKey(file.key) !== assetKey) {
+        return;
+      }
+
+      cleanup();
+      reject(new Error(`Failed to load asset: ${assetKey}`));
+    };
+
+    scene.load.once('complete', onComplete);
+    scene.load.on('loaderror', onLoadError);
+
+    try {
+      loadAssets(scene, collections);
+      if (!scene.load.isLoading()) {
+        scene.load.start();
+      }
+    } catch (error) {
+      cleanup();
+      reject(error);
+    }
+  });
+};

package/lib/__templates__/phaser/src/utils/index.ts

@@ -0,0 +1,2 @@
+export * from './asset-loader';
+export * from './mark-editable';

package/lib/__templates__/phaser/src/utils/mark-editable.ts

@@ -0,0 +1,13 @@
+import type Phaser from 'phaser';
+
+export interface MarkEditableOptions {
+  label?: string;
+}
+
+export const markEditable = <T extends Phaser.GameObjects.GameObject>(
+  locator: string,
+  gameObject: T,
+  options?: MarkEditableOptions,
+): T =>
+  window.PhaserBridge?.markEditable?.(locator, gameObject, options) ??
+  gameObject;

package/lib/__templates__/phaser/template.config.js

@@ -0,0 +1,43 @@
+
+
+
+
+
+
+
+
+
+export const paramsSchema = {
+  type: 'object',
+  properties: {
+    appName: {
+      type: 'string',
+      minLength: 1,
+      pattern: '^[a-z0-9-]+$',
+      description:
+        'Application name (lowercase, alphanumeric and hyphens only)',
+    },
+    port: {
+      type: 'number',
+      default: 5000,
+      minimum: 1024,
+      maximum: 65535,
+      description: 'Development and preview server port',
+    },
+  },
+  required: [],
+  additionalProperties: false,
+};
+
+const config = {
+  description:
+    'Phaser（2D 游戏）：`coze-dev init ${COZE_WORKSPACE_PATH} --template phaser`\n' +
+    '- 适用：基于 Phaser 3、Vite 和 TypeScript 的 2D Web 游戏。',
+  paramsSchema,
+  defaultParams: {
+    appName: 'phaser-game',
+    port: 5000,
+  },
+};
+
+export default config;

package/lib/__templates__/phaser/tsconfig.json

@@ -0,0 +1,23 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "useDefineForClassFields": true,
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "baseUrl": ".",
+    "paths": {
+      "@/*": ["src/*"]
+    },
+    "allowImportingTsExtensions": true,
+    "isolatedModules": true,
+    "moduleDetection": "force",
+    "noEmit": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true,
+    "types": ["node"]
+  },
+  "include": ["src", "vite.config.ts"]
+}

package/lib/__templates__/phaser/vite.config.ts

@@ -0,0 +1,96 @@
+import { cp } from "node:fs/promises";
+import path from "node:path";
+import { defineConfig, type Plugin } from "vite";
+import serveStatic from "serve-static";
+
+const DEV_PHASER_BRIDGE_URL =
+  "https://lf-coze-web-cdn.coze.cn/obj/eden-cn/lm-lgvj/ljhwZthlaukjlkulzlp/coze-game/js/phaser-bridge.min.js";
+
+function injectDevPhaserBridge(): Plugin {
+  return {
+    name: "phaser-dev-bridge",
+    transformIndexHtml() {
+      return [
+        {
+          tag: "script",
+          attrs: { src: DEV_PHASER_BRIDGE_URL },
+          injectTo: "head",
+        },
+      ];
+    },
+  };
+}
+
+function mountDevAssets(directory: string): Plugin {
+  const serveAssets = serveStatic(directory, {
+    cacheControl: false,
+    dotfiles: "allow",
+    fallthrough: false,
+    index: false,
+    redirect: false,
+    setHeaders(response) {
+      response.setHeader("Cache-Control", "no-cache");
+    },
+  });
+
+  return {
+    name: "phaser-dev-assets",
+    configureServer(server) {
+      server.middlewares.use("/assets", (request, response, next) => {
+        const isRead = request.method === "GET" || request.method === "HEAD";
+        if (!isRead || request.url?.includes("?")) {
+          response.statusCode = 404;
+          response.end("Not Found\n");
+          return;
+        }
+        serveAssets(request, response, next);
+      });
+    },
+  };
+}
+
+function copyGameAssets(directory: string): Plugin {
+  return {
+    name: "phaser-build-assets",
+    async writeBundle(outputOptions) {
+      const outputDirectory = path.resolve(
+        import.meta.dirname,
+        outputOptions.dir ?? "dist",
+      );
+
+      await cp(directory, path.join(outputDirectory, "assets"), {
+        recursive: true,
+        force: true,
+        filter(source) {
+          return path.basename(source) !== ".DS_Store";
+        },
+      });
+    },
+  };
+}
+
+export default defineConfig(() => {
+  const isDev = process.env.COZE_PHASER_GAME_ENV === "DEV";
+  const assetsDirectory = path.join(import.meta.dirname, "assets");
+
+  return {
+    resolve: {
+      alias: {
+        "@": path.resolve(import.meta.dirname, "src"),
+      },
+    },
+    server: {
+      // 游戏需用户手动刷新，防止游玩过程中丢失游戏状态
+      hmr: false,
+    },
+    plugins: [
+      copyGameAssets(assetsDirectory),
+      ...(isDev
+        ? [
+            injectDevPhaserBridge(),
+            mountDevAssets(assetsDirectory),
+          ]
+        : []),
+    ],
+  };
+});

package/lib/__templates__/phaser-static/.coze

@@ -0,0 +1,15 @@
+[project]
+entrypoint = "index.html"
+requires = ["python-3.12"]
+project_type = "game"
+game_type = "phaser"
+
+[dev]
+build = []
+run = ["python3", "-m", "http.server", "${DEPLOY_RUN_PORT}", "--bind", "0.0.0.0"]
+run_win = ["powershell.exe", "-NoProfile", "-ExecutionPolicy", "Bypass", "-File", "./scripts/serve.ps1"]
+
+[deploy]
+build = []
+run = ["python3", "-m", "http.server", "${DEPLOY_RUN_PORT}", "--bind", "0.0.0.0"]
+run_win = ["powershell.exe", "-NoProfile", "-ExecutionPolicy", "Bypass", "-File", "./scripts/serve.ps1"]

package/lib/__templates__/phaser-static/README.md

@@ -0,0 +1,40 @@
+# <%= appName %>
+
+这是一个基于浏览器原生 JavaScript ESM 的 Phaser 2D 游戏项目，由扣子编程 CLI 创建。
+
+Phaser 3.90.0 与 Phaser Bridge 从 CDN 加载；项目不依赖 npm、Vite 或 TypeScript。请用静态 HTTP 服务访问，直接打开 `index.html` 不支持 ESM 模块与素材加载。
+
+## 快速开始
+
+```bash
+coze-dev dev
+coze-dev build
+coze-dev start
+```
+
+`build` 没有编译步骤；开发与生产预览均由 Python `http.server` 提供静态文件服务。
+
+## 文件结构
+
+```text
+├── assets/                     # 图片、序列帧、视频和音频
+├── debug-runtime/              # 调试 Flow
+├── src/assets.js               # 素材 key 与路径
+├── src/main.js                 # 游戏入口
+├── src/phaser.js               # Phaser 全局对象的 ESM 包装
+├── src/scene/BootScene.js      # 启动与全量加载
+└── src/utils/asset-loader.js   # 批量和单素材加载
+```
+
+- 素材按类型放在 `assets/`，并登记到 `src/assets.js` 对应的分类表。
+- 序列帧只登记文件夹；Loader 从 `manifest.json` 读取帧数和帧率。
+- `BootScene` 加载游戏素材；运行时可用 `loadAsset(this, key)` 单独加载。
+- 所有本地模块都使用原生 ESM 的显式 `.js` 后缀。
+
+## 可视化编辑标识
+
+用 `markEditable` 标记可在编辑器中调整的对象；第三个参数可选，仅用于编辑器展示名称：
+
+```js
+markEditable('ui.start-button', button, { label: '开始按钮' });
+```

package/lib/__templates__/phaser-static/_gitignore

@@ -0,0 +1,6 @@
+.codegraph/
+.cozeproj/reduction
+.preview
+
+.DS_Store
+._*