@coze-arch/cli 0.0.36-alpha.1dcb49 → 0.0.36-alpha.64974b

package/lib/__templates__/phaser/scripts/dev.sh

@@ -2,10 +2,81 @@
 set -Eeuo pipefail
 
 COZE_WORKSPACE_PATH="${COZE_WORKSPACE_PATH:-$(pwd)}"
-PORT="${DEPLOY_RUN_PORT:-${PORT:-<%= port %>}}"
+PORT="${PORT:-<%= port %>}"
+DEPLOY_RUN_PORT="${DEPLOY_RUN_PORT:-${PORT}}"
 cd "${COZE_WORKSPACE_PATH}"
 
-COZE_PHASER_GAME_ENV=DEV pnpm vite \
-  --port "${PORT}" \
+get_listening_pids() {
+  local port="$1"
+
+  if command -v lsof >/dev/null 2>&1; then
+    lsof -tiTCP:"${port}" -sTCP:LISTEN 2>/dev/null || true
+  elif command -v ss >/dev/null 2>&1; then
+    ss -H -lntp 2>/dev/null \
+      | awk -v port="${port}" '$4 ~ ":"port"$"' \
+      | grep -o 'pid=[0-9]*' \
+      | cut -d= -f2 \
+      | sort -u || true
+  else
+    echo "Warning: neither lsof nor ss found, cannot check port ${port}." >&2
+  fi
+}
+
+kill_port_if_listening() {
+  local port="$1"
+  local pids
+
+  pids="$(get_listening_pids "${port}")"
+  if [[ -z "${pids}" ]]; then
+    echo "Port ${port} is free."
+    return
+  fi
+
+  echo "Port ${port} is in use by PIDs: ${pids//$'\n'/ } (SIGKILL)"
+  echo "${pids}" | xargs kill -9 2>/dev/null || true
+  sleep 1
+
+  pids="$(get_listening_pids "${port}")"
+  if [[ -n "${pids}" ]]; then
+    echo "Failed to clear port ${port}; remaining PIDs: ${pids//$'\n'/ }." >&2
+    return 1
+  fi
+
+  echo "Port ${port} cleared."
+}
+
+echo "Clearing port ${DEPLOY_RUN_PORT} before start."
+kill_port_if_listening "${DEPLOY_RUN_PORT}"
+
+<% if (process.env.NODE_ENV === 'test') { %>
+# Keep the process attached in tests so the test runner can collect logs and stop it.
+exec env COZE_PHASER_GAME_ENV=DEV pnpm vite \
+  --port "${DEPLOY_RUN_PORT}" \
   --host 127.0.0.1 \
   --strictPort
+<% } else { %>
+LOG_DIR="${COZE_WORKSPACE_PATH}/logs"
+LOG_FILE="${LOG_DIR}/phaser-dev.log"
+PID_FILE="${LOG_DIR}/phaser-dev.pid"
+mkdir -p "${LOG_DIR}"
+
+echo "Starting Phaser dev server on port ${DEPLOY_RUN_PORT}..."
+server_pid="$(COZE_PHASER_GAME_ENV=DEV node scripts/spawn-detached.cjs \
+  "${LOG_FILE}" pnpm vite \
+  --port "${DEPLOY_RUN_PORT}" \
+  --host 127.0.0.1 \
+  --strictPort)"
+echo "${server_pid}" > "${PID_FILE}"
+
+sleep 1
+if ! kill -0 "${server_pid}" 2>/dev/null; then
+  echo "Phaser dev server failed to start. See ${LOG_FILE}." >&2
+  tail -n 20 "${LOG_FILE}" >&2 || true
+  rm -f "${PID_FILE}"
+  exit 1
+fi
+
+echo "Phaser dev server started (PID: ${server_pid})."
+echo "Log file: ${LOG_FILE}"
+echo "PID file: ${PID_FILE}"
+<% } %>

package/lib/__templates__/phaser/scripts/prepare.ps1

@@ -0,0 +1,8 @@
+$ErrorActionPreference = "Stop"
+
+$workspace = if ($env:COZE_WORKSPACE_PATH) { $env:COZE_WORKSPACE_PATH } else { (Get-Location).Path }
+Set-Location $workspace
+
+Write-Host "Installing dependencies..."
+& pnpm install --prefer-frozen-lockfile --prefer-offline --reporter=append-only
+exit $LASTEXITCODE

package/lib/__templates__/phaser/scripts/spawn-detached.cjs

@@ -0,0 +1,29 @@
+const fs = require('node:fs');
+const { spawn } = require('node:child_process');
+
+const [logFile, command, ...args] = process.argv.slice(2);
+
+if (!logFile || !command) {
+  process.stderr.write(
+    'Usage: node scripts/spawn-detached.cjs <log-file> <command> [...args]\n',
+  );
+  process.exit(1);
+}
+
+const logFd = fs.openSync(logFile, 'a');
+const child = spawn(command, args, {
+  cwd: process.cwd(),
+  detached: process.platform !== 'win32',
+  env: process.env,
+  stdio: ['ignore', logFd, logFd],
+});
+
+fs.closeSync(logFd);
+child.unref();
+
+if (!child.pid) {
+  process.stderr.write('Failed to start detached process.\n');
+  process.exit(1);
+}
+
+process.stdout.write(String(child.pid));

package/lib/__templates__/phaser/scripts/start.ps1

@@ -0,0 +1,49 @@
+$ErrorActionPreference = "Stop"
+
+function Stop-ProcessTree([int] $processId) {
+  if ($processId -gt 0 -and (Get-Process -Id $processId -ErrorAction SilentlyContinue)) {
+    & taskkill.exe /PID $processId /T /F *> $null
+  }
+}
+
+function Stop-ListeningProcess([int] $port) {
+  $connections = Get-NetTCPConnection -LocalPort $port -State Listen -ErrorAction SilentlyContinue
+  $connections | Select-Object -ExpandProperty OwningProcess -Unique | ForEach-Object {
+    Stop-ProcessTree $_
+  }
+}
+
+$workspace = if ($env:COZE_WORKSPACE_PATH) { $env:COZE_WORKSPACE_PATH } else { (Get-Location).Path }
+$defaultPort = <%= port %>
+$port = if ($env:DEPLOY_RUN_PORT) { [int] $env:DEPLOY_RUN_PORT } elseif ($env:PORT) { [int] $env:PORT } else { $defaultPort }
+Set-Location $workspace
+Stop-ListeningProcess $port
+$env:COZE_PHASER_GAME_ENV = "PROD"
+
+<% if (process.env.NODE_ENV === 'test') { %>
+& pnpm vite preview --port $port --host 127.0.0.1 --strictPort
+exit $LASTEXITCODE
+<% } else { %>
+$logDirectory = if ($env:COZE_LOG_DIR) { $env:COZE_LOG_DIR } else { Join-Path $workspace "logs" }
+$logFile = Join-Path $logDirectory "phaser-start.log"
+$errorLogFile = Join-Path $logDirectory "phaser-start-error.log"
+$pidFile = Join-Path $logDirectory "phaser-start.pid"
+New-Item -ItemType Directory -Force -Path $logDirectory | Out-Null
+
+if (Test-Path $pidFile) {
+  Stop-ProcessTree ([int] (Get-Content $pidFile -Raw))
+  Remove-Item $pidFile -Force
+}
+
+$process = Start-Process -FilePath $env:ComSpec -ArgumentList @("/d", "/s", "/c", "pnpm vite preview --port $port --host 127.0.0.1 --strictPort") -WorkingDirectory $workspace -RedirectStandardOutput $logFile -RedirectStandardError $errorLogFile -PassThru
+$process.Id | Set-Content $pidFile
+Start-Sleep -Seconds 1
+if ($process.HasExited) {
+  Get-Content $errorLogFile -Tail 20 -ErrorAction SilentlyContinue
+  Remove-Item $pidFile -Force -ErrorAction SilentlyContinue
+  exit 1
+}
+
+Write-Host "Phaser production server started (PID: $($process.Id))."
+Write-Host "Log file: $logFile"
+<% } %>

package/lib/__templates__/phaser/scripts/start.sh

@@ -2,10 +2,81 @@
 set -Eeuo pipefail
 
 COZE_WORKSPACE_PATH="${COZE_WORKSPACE_PATH:-$(pwd)}"
-PORT="${DEPLOY_RUN_PORT:-${PORT:-<%= port %>}}"
+PORT="${PORT:-<%= port %>}"
+DEPLOY_RUN_PORT="${DEPLOY_RUN_PORT:-${PORT}}"
 cd "${COZE_WORKSPACE_PATH}"
 
-COZE_PHASER_GAME_ENV=PROD pnpm vite preview \
-  --port "${PORT}" \
+get_listening_pids() {
+  local port="$1"
+
+  if command -v lsof >/dev/null 2>&1; then
+    lsof -tiTCP:"${port}" -sTCP:LISTEN 2>/dev/null || true
+  elif command -v ss >/dev/null 2>&1; then
+    ss -H -lntp 2>/dev/null \
+      | awk -v port="${port}" '$4 ~ ":"port"$"' \
+      | grep -o 'pid=[0-9]*' \
+      | cut -d= -f2 \
+      | sort -u || true
+  else
+    echo "Warning: neither lsof nor ss found, cannot check port ${port}." >&2
+  fi
+}
+
+kill_port_if_listening() {
+  local port="$1"
+  local pids
+
+  pids="$(get_listening_pids "${port}")"
+  if [[ -z "${pids}" ]]; then
+    echo "Port ${port} is free."
+    return
+  fi
+
+  echo "Port ${port} is in use by PIDs: ${pids//$'\n'/ } (SIGKILL)"
+  echo "${pids}" | xargs kill -9 2>/dev/null || true
+  sleep 1
+
+  pids="$(get_listening_pids "${port}")"
+  if [[ -n "${pids}" ]]; then
+    echo "Failed to clear port ${port}; remaining PIDs: ${pids//$'\n'/ }." >&2
+    return 1
+  fi
+
+  echo "Port ${port} cleared."
+}
+
+echo "Clearing port ${DEPLOY_RUN_PORT} before start."
+kill_port_if_listening "${DEPLOY_RUN_PORT}"
+
+<% if (process.env.NODE_ENV === 'test') { %>
+# Keep the process attached in tests so the test runner can collect logs and stop it.
+exec env COZE_PHASER_GAME_ENV=PROD pnpm vite preview \
+  --port "${DEPLOY_RUN_PORT}" \
   --host 127.0.0.1 \
   --strictPort
+<% } else { %>
+LOG_DIR="${COZE_WORKSPACE_PATH}/logs"
+LOG_FILE="${LOG_DIR}/phaser-start.log"
+PID_FILE="${LOG_DIR}/phaser-start.pid"
+mkdir -p "${LOG_DIR}"
+
+echo "Starting Phaser production server on port ${DEPLOY_RUN_PORT}..."
+server_pid="$(COZE_PHASER_GAME_ENV=PROD node scripts/spawn-detached.cjs \
+  "${LOG_FILE}" pnpm vite preview \
+  --port "${DEPLOY_RUN_PORT}" \
+  --host 127.0.0.1 \
+  --strictPort)"
+echo "${server_pid}" > "${PID_FILE}"
+
+sleep 1
+if ! kill -0 "${server_pid}" 2>/dev/null; then
+  echo "Phaser production server failed to start. See ${LOG_FILE}." >&2
+  tail -n 20 "${LOG_FILE}" >&2 || true
+  rm -f "${PID_FILE}"
+  exit 1
+fi
+
+echo "Phaser production server started (PID: ${server_pid})."
+echo "Log file: ${LOG_FILE}"
+echo "PID file: ${PID_FILE}"
+<% } %>

package/lib/__templates__/phaser/scripts/validate.ps1

@@ -0,0 +1,7 @@
+$ErrorActionPreference = "Stop"
+
+$workspace = if ($env:COZE_WORKSPACE_PATH) { $env:COZE_WORKSPACE_PATH } else { (Get-Location).Path }
+Set-Location $workspace
+
+& pnpm validate
+exit $LASTEXITCODE

package/lib/__templates__/phaser/src/global.d.ts

@@ -19,6 +19,9 @@ declare global {
     markEditable?: <T extends Phaser.GameObjects.GameObject>(
       stableId: string,
       gameObject: T,
+      options?: {
+        label?: string;
+      },
     ) => T;
     markImageAssetMap?: (images: Record<string, string>) => void;
     markImageSequenceAssetMap?: (

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

@@ -95,6 +95,7 @@ export class BootScene extends Phaser.Scene {
         .sprite(centerX, centerY - 58, DEV_LOADING_RUNTIME_KEYS.texture)
         .setScale(0.56)
         .play(DEV_LOADING_RUNTIME_KEYS.animation),
+      { label: '加载吉祥物' },
     );
 
     this.loadingText = markEditable(
@@ -107,11 +108,13 @@ export class BootScene extends Phaser.Scene {
           LOADING_TEXT_STYLE,
         )
         .setOrigin(0.5),
+      { label: '加载状态文案' },
     );
 
     this.progressBar = markEditable(
       'boot.loading-progress-bar',
       this.add.graphics(),
+      { label: '加载进度条' },
     );
     this.renderProgressBar(0);
 
@@ -120,6 +123,7 @@ export class BootScene extends Phaser.Scene {
       this.add
         .text(centerX, centerY + 190, '0%', LOADING_TEXT_STYLE)
         .setOrigin(0.5),
+      { label: '加载进度文本' },
     );
   }
 

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

@@ -21,6 +21,7 @@ export class DevLoadingScene extends Phaser.Scene {
         .sprite(centerX, centerY - 82, DEV_LOADING_RUNTIME_KEYS.texture)
         .setScale(0.64)
         .play(DEV_LOADING_RUNTIME_KEYS.animation),
+      { label: '开发中吉祥物' },
     );
 
     markEditable(
@@ -33,6 +34,7 @@ export class DevLoadingScene extends Phaser.Scene {
           fontStyle: 'bold',
         })
         .setOrigin(0.5),
+      { label: '开发中标题' },
     );
 
     markEditable(
@@ -44,6 +46,7 @@ export class DevLoadingScene extends Phaser.Scene {
           fontSize: '18px',
         })
         .setOrigin(0.5),
+      { label: '开发中说明文案' },
     );
 
     const loadingDots = Array.from({ length: 3 }, (_value, index) =>

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

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

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

@@ -4,8 +4,7 @@ import { defineConfig, type Plugin } from "vite";
 import serveStatic from "serve-static";
 
 const DEV_PHASER_BRIDGE_URL =
-  "https://unpkg.byted-static.com/coze-game/phaser-bridge/0.0.2-alpha.2cf8ee/dist/index.js";
-const DEV_IMAGE_DELAY_MS = 200;
+  "https://lf-coze-web-cdn.coze.cn/obj/eden-cn/lm-lgvj/ljhwZthlaukjlkulzlp/coze-game/js/phaser-bridge.min.js";
 
 function injectDevPhaserBridge(): Plugin {
   return {
@@ -70,28 +69,6 @@ function copyGameAssets(directory: string): Plugin {
   };
 }
 
-function delayDevImages(): Plugin {
-  return {
-    name: "phaser-dev-image-delay",
-    configureServer(server) {
-      server.middlewares.use((request, _response, next) => {
-        const pathname = request.url?.split("?", 1)[0] ?? "";
-        const isImageRequest =
-          (request.method === "GET" || request.method === "HEAD") &&
-          pathname.includes("/assets/image/") &&
-          /\.(?:avif|gif|jpe?g|png|webp)$/i.test(pathname);
-
-        if (!isImageRequest) {
-          next();
-          return;
-        }
-
-        setTimeout(next, DEV_IMAGE_DELAY_MS);
-      });
-    },
-  };
-}
-
 export default defineConfig(() => {
   const isDev = process.env.COZE_PHASER_GAME_ENV === "DEV";
   const assetsDirectory = path.join(import.meta.dirname, "assets");
@@ -111,7 +88,6 @@ export default defineConfig(() => {
       ...(isDev
         ? [
             injectDevPhaserBridge(),
-            delayDevImages(),
             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 = ["sh", "-c", "python -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 = ["sh", "-c", "python -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
+._*

package/lib/__templates__/phaser-static/assets/image_sequence/coze-game-loading/manifest.json

@@ -0,0 +1,11 @@
+{
+  "schema_version": "1.0",
+  "id": "coze-game-loading",
+  "type": "image_sequence",
+  "properties": {
+    "fps": 12.0,
+    "frame_count": 24
+  },
+  "name": "Coze Game Loading",
+  "sources": []
+}

package/lib/__templates__/phaser-static/debug-runtime/flow-graph.json

@@ -0,0 +1,20 @@
+{
+  "schema_version": 1,
+  "graphs": [
+    {
+      "id": "main",
+      "label": "主流程",
+      "nodes": [
+        {
+          "id": "start",
+          "label": "开始游戏",
+          "input_schema": {
+            "type": "object",
+            "properties": {}
+          }
+        }
+      ],
+      "transitions": []
+    }
+  ]
+}

package/lib/__templates__/phaser-static/index.html

@@ -0,0 +1,17 @@
+<!doctype html>
+<html lang="zh-CN">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <meta name="description" content="Phaser 纯静态游戏模板" />
+    <title><%= appName %></title>
+    <link rel="icon" href="data:," />
+    <link rel="stylesheet" href="./src/style.css" />
+    <script src="https://unpkg.byted-static.com/phaser/3.90.0/dist/phaser.min.js"></script>
+    <script src="https://lf-coze-web-cdn.coze.cn/obj/eden-cn/lm-lgvj/ljhwZthlaukjlkulzlp/coze-game/js/phaser-bridge.min.js"></script>
+  </head>
+  <body>
+    <main id="game" aria-label="Phaser game canvas"></main>
+    <script type="module" src="./src/main.js"></script>
+  </body>
+</html>

package/lib/__templates__/phaser-static/scripts/serve.ps1

@@ -0,0 +1,7 @@
+$ErrorActionPreference = "Stop"
+
+$port = if ($env:DEPLOY_RUN_PORT) { $env:DEPLOY_RUN_PORT } else { "8000" }
+
+Write-Host "Starting Phaser static server on port $port..."
+& python -m http.server $port --bind 0.0.0.0
+exit $LASTEXITCODE

package/lib/__templates__/phaser-static/src/assets.js

@@ -0,0 +1,15 @@
+export const IMAGES = {};
+
+export const IMAGE_SEQUENCES = {
+  'coze-game-loading': 'assets/image_sequence/coze-game-loading',
+};
+
+export const VIDEOS = {};
+
+export const AUDIOS = {};
+
+// 注册素材到 PhaserBridge，可以在扣子网页游戏开发中定位
+window.PhaserBridge?.markImageAssetMap?.(IMAGES);
+window.PhaserBridge?.markImageSequenceAssetMap?.(IMAGE_SEQUENCES);
+window.PhaserBridge?.markVideoAssetMap?.(VIDEOS);
+window.PhaserBridge?.markAudioAssetMap?.(AUDIOS);

package/lib/__templates__/phaser-static/src/main.js

@@ -0,0 +1,26 @@
+import { Phaser } from './phaser.js';
+import { BootScene } from './scene/BootScene.js';
+import { DevLoadingScene } from './scene/DevLoadingScene.js';
+
+const createGame = () =>
+  new Phaser.Game({
+    type: Phaser.AUTO,
+    pixelArt: true,
+    parent: 'game',
+    // TODO 根据游戏的要求进行尺寸
+    width: 540,
+    height: 960,
+    backgroundColor: '#ffffff',
+    scale: {
+      mode: Phaser.Scale.FIT,
+      autoCenter: Phaser.Scale.CENTER_BOTH,
+    },
+    scene: [BootScene, DevLoadingScene],
+  });
+
+// 注册游戏到 PhaserBridge，可以在扣子网页游戏开发中编辑评论
+if (window.PhaserBridge) {
+  window.PhaserBridge.bind({ launchGame: createGame });
+} else {
+  createGame();
+}

package/lib/__templates__/phaser-static/src/phaser.js

@@ -0,0 +1,7 @@
+const Phaser = window.Phaser;
+
+if (!Phaser) {
+  throw new Error('Phaser CDN failed to load before the game module.');
+}
+
+export { Phaser };