# cat2D **Repository Path**: jcx6586408/cat2-d ## Basic Information - **Project Name**: cat2D - **Description**: No description available - **Primary Language**: Unknown - **License**: Not specified - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-01-27 - **Last Updated**: 2026-05-26 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # cat2d-engine 面向 **Web / 微信小游戏** 的 2D 游戏引擎;业务工程通过 **npm** 依赖使用,脚手架可一键生成项目结构。 在已有工程里添加依赖:`npm install cat2d-engine`。 --- ## 新建游戏并运行 ```bash npx cat2d-engine create my-game cd my-game npm install npm run dev ``` - 需要随工程带上 **`sdk/`** 时:`npx cat2d-engine create my-game --with-sdk` - 在**已有空目录**里初始化:`npx cat2d-engine init`(可选 `--with-sdk`) - 依赖安装后会执行 **`cat2d-engine setup`**,把引擎包内的 **`public/res`** 与 **`engine.config.json`** 拷到项目的 `public/`(也可随时手动执行 `npx cat2d-engine setup`) **微信小游戏打包**:构建配置在依赖包 **`cat2d-engine/platforms/wechat`**,在**游戏工程根**执行(需已 `npm install` 含 `vite`,且存在 `assets/game.ts` 或 `assets/game/index.ts`): ```bash npm run build:wx ``` (等价于 `node ./node_modules/cat2d-engine/bin/cli.js build wechat`,产物输出到 **`wechatgame/`**。可选:`npx cat2d-engine init wx` 仅创建 `wx/` 占位说明目录。) --- ## 模板与业务代码(你需要知道这一点) - 引擎仓库里有一份 **`engine-templates/`**:脚手架、同步命令会把其中的内容写到**游戏工程**的 **`assets/`**(例如 `assets/game/`、`assets/app/`),不要在引擎仓库路径里找 `templates` 子目录名混用。 - 业务侧推荐用 **`AppContext`** 统一管理各 Runtime 的生命周期;**战斗等「进某场景才需要」的 `attach`** 放在对应 **Scene**,不要都塞进全局初始化。 - **UI**:请用 **`engine.ui`**(或场景入参里的 **`SceneEnterContext.surface`**)做 UI 场景注册、跳转与 overlay;避免直接使用 **`uiSceneManager`** / **`addUIRootOverlay`**。与「设计稿中心为原点」一致的坐标包装由 **`engine.ui.mountOverlay`**(默认 `layout: 'center'`)与 **`UIScene`** 统一处理。 - 导入引擎请统一使用 **`import … from 'cat2d-engine'`**(由 Vite 等配置指向引擎入口)。 - **框架模态(确认 / 公告 / 设置)**:`engine-templates/modal` 在运行时优先从 **`projectUiEditorPrefabs`** 加载 `public/res/prefabs/` 下同名预制(`framework_confirm_modal.prefab.ts` 等);若未注册或节点不满足绑定约定,则自动回退为代码拼 UI。约定节点名见 `engine-templates/modal/frameworkModalPrefab.ts` 顶部注释。`setup` 会把包内默认预制拷入工程,可在 **UI 编辑器** 中改皮肤后保存到同路径。 --- ## 常用命令(CLI) 在游戏工程或引擎仓库根目录执行(已安装依赖时可用 `npx cat2d-engine …`): | 命令 | 作用 | |------|------| | `cat2d-engine setup` | 将包内 `public/res` 与 `engine.config.json` 拷到项目 `public/` | | `cat2d-engine add-sdk [目录] [--force]` | 把包内 `sdk/` 复制到**目标工程根目录**下的 `sdk/`,并把 import 统一成 `cat2d-engine`;不传目录则针对**当前目录**。已存在 `sdk/` 时默认跳过,需要覆盖时加 `--force` | | `cat2d-engine fix-sdk-imports` | 仅修正当前工程已有 `sdk/` 里的引擎相对路径导入(不复制目录) | | `cat2d-engine sync-templates [目录]` | 将包内 `engine-templates` 同步到目标工程的 `assets/`(默认 `examples/gameFrameworkTest`) | | `cat2d-engine game [--port 5173]` | 同步模板到 `examples/gameFrameworkTest` 并启动 Vite 开发服 | | `cat2d-engine table-export --input --out ` | 将目录下 `csv`/`xlsx` 导出为 `.ts` 配置表 | | `cat2d-engine create-modal ` | 在 `assets/modal//` 生成弹窗类脚手架(基于 `ModalBase`) | | `cat2d-engine convert-model ` | FBX → `mesh3d`(构建期资源) | | `cat2d-engine physics-polygon-export` | 贴图轮廓 → 物理多边形 JSON | 事后补装 **`sdk/`**(与 `init --with-sdk` / `create … --with-sdk` 等价来源):在**游戏工程根**执行 `npx cat2d-engine add-sdk` 即可;若从其它路径调用,可写 `npx cat2d-engine add-sdk path/to/my-game`。请确认 **`tsconfig.json`** 的 `include` 含 **`sdk/**/*.ts`**(脚手架模板已包含)。**引擎仓库**根目录还可用 **`npm run add-sdk:gft`**,一键写入 `examples/gameFrameworkTest/sdk`。 **配置表导出**:游戏工程脚手架已带 **`npm run export-tables`**(默认 `public/res/csv` → `src/tables/generated`);传 CLI 参数时请用 **`npm run export-tables -- --input … --out …`**。亦可 **`npx cat2d-engine table-export …`**,或在 **UI 编辑器**(Electron)**Edit → 导出配置表**。 --- ## 引擎仓库内开发(贡献者 / 本地联调) | 命令 | 作用 | |------|------| | `npm run dev` | 引擎调试页(含节点树等) | | `npm run build` | TypeScript 检查 + 预览(`artifacts/preview`)+ 模板 game(`artifacts/game`)+ 微信 UMD(`artifacts/engine`) | | `npm run build:wx-engine` | 仅生成微信用 UMD;平时也可被 `npm run build` 或 `build wechat` 自动触发(缺文件或引擎 `src` 比 UMD 新时会重建) | | `npm run game` | 同步模板到示例并启动示例 dev | 本地联调在游戏工程里使用 `"cat2d-engine": "file:../cat2-d"` 即可,**无需**再构建根目录 `dist`。微信包依赖上述 UMD:**产物已存在且未改引擎时不必每次先跑** `build:wx-engine`;改过引擎源码后请再跑一次以免 `engine.js` 陈旧。 --- ## 其它工具(按需查阅) 以下为**可选能力**,使用前再看即可;细节以命令行帮助与源码为准。 - **FBX → mesh3d**:`npx cat2d-engine convert-model `,默认输出到 `public/res/mesh/`。 - **贴图 → 物理多边形 JSON**:`physics-polygon-export`;Windows 可用根目录 **`physic_to_polygon.ps1`** + **`physic_to_polygon.config.json`** 调参。 - **Cocos 3.x 预制体转换**:`npx cat2d-engine cocos convert [--project ]`,选项较多,见命令行帮助或 `tools/cocosPrefabConvert.mjs`。 - **范例**:安装包内 `demos/`,或 `npx cat2d-engine example ` 复制到当前目录。 - **微信文本资源分包 / CDN 兜底**:见 `engine.config.json` 中 `resourceLoad`;微信构建使用包内 **`platforms/wechat`**,在游戏根执行 **`npm run build:wx`**(即 `cat2d-engine build wechat`)。 --- ## 最小接入示例 页面提供 ``,在入口中: ```js import cat, { run } from 'cat2d-engine'; run((ctx) => { // 注册场景、pushScene,最后 ctx.engine.start() }); ``` 可选:`run({ canvasId: 'gameCanvas', config: { designWidth: 750, designHeight: 1334 } }, (ctx) => { ... })`。分辨率与设计稿相关配置可放在 `public/engine.config.json`。 **物理(Matter)**:使用 `PhysicsWorld` 时在 **Scene 的 `onUpdate(dt)`** 里调用 `world.update(dt)`,与引擎帧 `dt` 一致。