docs: update readme

README.md

@@ -4,62 +4,59 @@
 
 ## 项目结构
 
-`public`: mota-js 样板所在目录，该塔对样板的目录进行了一定的魔改，其中插件全部移动到`src/plugin/game`文件夹中，并使用了`es模块化`
+`public`: mota-js 样板所在目录。
+`packages`: 核心引擎代码 monorepo。
+`packages-user`: 用户代码 monorepo。
+`src`: 游戏入口代码。
 
-`src`: 游戏除样板核心代码外所有内容所在目录，所有内容支持`typescript`。其中包含以下内容：
+由于样板由此项目分离而来（类似于 `vscode` 与 `monaco-editor` 的关系），因此将用户代码部分与核心引擎分开编写。不过由于旧样板限制与重构的不完全，引擎中还有部分内容会引用旧样板内容。
 
-1. `core`: 游戏除样板外的的核心代码，包括加载和一些基础功能等
+`packages` `packages-user` 可以单独打包为库模式，`src` 单向引用 `packages-user`，`packages-user` 单向引用 `packages`，`src` 为游戏的入口代码。
-2. `plugin`: 所有相关插件的源码，其中包含多个文件夹，内有不同的内容，其中`game`文件夹与游戏进程有关，不能涉及`dom`等`node`无法运行的操作，否则录像验证会报错
-3. `ui`: 所有 ui 的 vue 源码
-4. `panel`: ui 中用到的部分面板
-5. `components`: 所有 ui 的通用组件
-6. `data`: 数据文件，包含百科全书的内容、成就的内容等
-7. `fonts`: ui 中用到的字体文件
-8. `types`: mota-js 的类型声明文件
-9. `source`: mota-js 的图块等资源的类型声明文件，会通过热重载更新
-10. `initPlugin.ts`: 所有插件的入口文件
-11. `main.ts`: 主入口，会将`App.vue`与`App2.vue`渲染到 html 上
 
-`script`: 在构建、发布等操作时会用到的 node 脚本
+## 开发环境
 
-`vite.config.ts`: `vite`的配置文件
+- `node.js ^18.0.0 || ^20.0.0 || >=22.0.0`
+- `pnpm >= 10.0.0`
+- 任意支持 `ES2024` 特性的浏览器
 
-`mota.config.ts`: 魔塔配置文件
+**建议使用 `vscode`，搭配 `prettier` `eslint` 插件**
 
 ## 开发说明
 
-1. 首先请确保你安装了`node.js`与`pnpm`
+1. 将项目拉取到本地。
-2. 将项目拉到你的设备上
+2. 运行 `pnpm i` 安装所有依赖，如有要求运行 `pnpm approve-builds`，请允许全部。
-3. 运行`pnpm i`以安装所有依赖包
+3. 运行 `pnpm dev` 进入开发环境。
-4. 在根目录运行`pnpm run dev`以启动`vite`服务和样板的`http`服务与热重载服务
-5. 打开`vite`提供的网址即可进入游戏
-6. 打开样板服务提供的网址即可进入编辑器
 
 ## 构建说明
 
-1. 运行`pnpm run build`以打包以`/games/HumanBreak/`为目录的构建包
+- `pnpm build:packages`: 构建所有 `packages` 文件夹下的内容，使用库模式。
-2. 运行`pnpm run build-local`以打包以`/`为目录的本地构建包
+- `pnpm build:game`: 构建为可以直接部署构建包。
-3. 运行`pnpm run build-gh`以打包以`/HumanBreak/`为目录的可部署到`github pages`的构建包
+- `pnpm build:lib`: 构建所有 `packages` `packages-user` 文件夹下的内容，使用库模式。
 
-### 构建流程
+## 开发原则
 
-1. 运行`vue-tsc`检查类型是否正确
+- 模块无副作用原则：
-2. 运行`vite`的构建工具，打包除`public`外的内容
+    - 所有模块不包含副作用内容，全部由函数、类、常量的声明组成，不出现导出的变量声明、代码执行内容，允许但不建议编写类的静态块。
-3. 运行`script/build.ts`，首先去除未使用的文件（即全塔属性中未注册的文件），然后压缩字体，再用`rollup` `terser`及`babel`压缩插件与`main.js`
+    - 如果需要模块初始化，编写一个 `createXxx` 函数，然后在 `index.ts` 中整合，再逐级向上传递，直至遇到包含 `create` 函数的 `index.ts`，所有初始化将会统一在顶层模块中执行。
-
+- 命名规则：
-## 热重载说明
+    - 变量、成员、一般常量、方法、函数使用小驼峰。
-
+    - 类、接口、类型别名、命名空间、泛型、枚举、组件使用大驼峰。
-支持以下内容的热重载：
+    - 不变常量使用全大写命名法，单词之间使用下划线连接。
-
+    - 专有名词缩写如 `HTTP`, `URI` 全部大写。
-1. `vite`热重载
+    - 会被 `implements` 的接口使用大写 `I` 开头。
-2. 楼层热重载
+    - `id`, `class` 等 `HTML/CSS` 内容使用连字符命名法。
-3. 脚本编辑热重载
+    - 不使用下划线命名法。
-4. 道具、怪物、图块属性热重载
+- 注释：
-5. styles.css
+    - 常用属性成员、方法、接口、类型必须添加 `jsDoc` 注释。
-
+    - 长文件可使用 `#region` 分段，非必要则不写 `#endregion`。
-以下内容修改后会自动刷新页面
+    - TODO 使用 `// TODO:` 或 `// todo:` 格式。
-
+    - 单行注释的双斜杠与注释内容之间添加一个空格，多行注释只允许出现 `jsDoc` 注释，如果需要多行非 `jsDoc` 注释，使用多个单行注释。
-1. `vite`提供的自动刷新页面
+- 类型：
-2. 全塔属性
+    - 不允许出现非必要的 `any` 类型。
-3. libs/下的文件
+    - 所有类的成员必须显式声明类型。
-4. main.js
+    - 如果有无法避免出现类型错误的地方，使用 `// @ts-expect-error` 标记，并填写原因。
+    - 没用到的变量、方法使用下划线开头。
+    - 合理运用 `readonly` `protected` `private` 关键字。
+    - 函数不建议使用过多可选参数，如果可选参数过多，可以考虑换用对象。
+- 代码格式：
+    - 严格遵循 `eslint` 配置，不允许出现 `eslint` 报错。