AncTe/HumanBreak
1
1
Fork 0
mirror of https://github.com/unanmed/HumanBreak.git synced 2025-04-11 15:47:06 +08:00
Code Issues Actions Packages Projects Releases Wiki Activity

docs: 差异说明与系统说明

Browse Source
This commit is contained in:
unanmed 2025-03-09 23:44:14 +08:00
parent 5c520e3d52
commit 05e254fee0
10 changed files with 259 additions and 3 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
.gitignore vendored
View File

@ -49,4 +49,5 @@ script/people.ts
user.ts
.antlr
graph.svg
docs/.vitepress
docs/.vitepress/cache
docs/.vitepress/dist

59
docs/.vitepress/config.ts Normal file
View File

@ -0,0 +1,59 @@
import { defineConfig } from 'vitepress';
// https://vitepress.dev/reference/site-config
export default defineConfig({
title: 'HTML5 魔塔样板 V2.B',
description: 'HTML5 魔塔样板 V2.B 帮助文档',
base: '/_docs/',
themeConfig: {
// https://vitepress.dev/reference/default-theme-config
nav: [
{ text: '主页', link: '/' },
{ text: '指南', link: '/guide/diff' },
{ text: 'API', link: '/api/' }
],
sidebar: {
'/guide/': [
{
text: '深度指南',
items: [
{ text: '差异说明', link: '/guide/diff' },
{ text: '系统说明', link: '/guide/system' }
]
}
]
},
socialLinks: [
{ icon: 'github', link: 'https://github.com/unanmed/HumanBreak' }
],
search: {
provider: 'local',
options: {
locales: {
zh: {
translations: {
button: {
buttonText: '搜索文档',
buttonAriaLabel: '搜索文档'
},
modal: {
noResultsText: '无法找到相关结果',
resetButtonTitle: '清除查询条件',
footer: {
selectText: '选择',
navigateText: '切换'
}
}
}
}
}
}
}
},
locales: {
root: {
lang: 'zh',
label: '中文'
}
}
});

5
docs/api/index.md Normal file
View File

@ -0,0 +1,5 @@
---
lang: zh-CN
---
# API 列表

0
docs/guide/audio.md Normal file
View File

34
docs/guide/diff.md Normal file
View File

@ -0,0 +1,34 @@
---
lang: zh-CN
---
# 差异说明
本文档暂时只会对新样板新增内容进行说明，其余请查看[旧样板文档](https://h5mota.com/games/template/_docs/#/)。
本指南建立在你已经大致了解 js 的基础语法的基础上。如果还不了解可以尝试对指南内容进行模仿，或者查看[人类塔解析](https://h5mota.com/bbs/thread/?tid=1018&p=1)
如果你有能力直接使用源码版样板进行创作，也可以直接 fork 或 clone 2.B 样板[存储库](https://github.com/unanmed/HumanBreak/tree/template-v2.B)。2.B 样板使用了 vite 作为了构建工具，同时使用了 ts 等作为了开发语言。
本文将描述 2.B 样板与 2.10.3 及 2.A 样板的差异。
## 注意事项
对于新样板，由于拥有了近乎完整的类型标注，因此更推荐使用 `VS Code` 进行代码编写，这样你可以获取到完整的类型标注，而由于类型标注的复杂性，样板编辑器完全无法部署，因此样板编辑器不会有任何新版的类型标注。在之后的更新中，样板 API 会进行大幅度的改动，因此每次更新都可能会弃用一部分 API，同时这些 API 会在若干个版本后被彻底删除。因此如果你的代码中使用到了弃用的 API，请尽快更换写法以保证可以向后接档。
## 主要差异
- 开发语言换为 TypeScript，可以享受到完整的类型支持
- 使用全新的 UI 编写方式，速度快，效率高
- 模块化，可以使用 ES6 模块化语法
- 移除插件系统，可以自定义代码目录结构，更加自由
- 优化渲染端（client 端）与数据端（data 端）的通讯，渲染段现在可以直接引用数据端，不过数据端还不能直接引用渲染端
## 差异内容
相比于 2.10.3 及 2.A，有如下改动：
- [系统说明](./system)
- [UI 编写](./ui)
- [UI 系统](./ui-system)
- [音频系统](./audio)

157
docs/guide/system.md Normal file
View File

@ -0,0 +1,157 @@
---
lang: zh-CN
---
# 系统说明
本文将介绍 2.B 的系统都做了哪些更改
## 模块化
2.B 样板现在已经迁移至了 monorepo，将代码模块化，共分为 20 余个模块，每个模块的具体内容可以参考 API 文档，模块列表如下：
- [@motajs/client](../api/motajs-client)
- [@motajs/client-base](../api/motajs-client-base)
- [@motajs/common](../api/motajs-common)
- [@motajs/legacy-client](../api/motajs-legacy-client)
- [@motajs/legacy-common](../api/motajs-legacy-common)
- [@motajs/legacy-data](../api/motajs-legacy-data)
- [@motajs/legacy-system](../api/motajs-legacy-system)
- [@motajs/legacy-ui](../api/motajs-legacy-ui)
- [@motajs/render](../api/motajs-render)
- [@motajs/render-core](../api/motajs-render-core)
- [@motajs/render-elements](../api/motajs-render-elements)
- [@motajs/render-style](../api/motajs-render-style)
- [@motajs/render-vue](../api/motajs-render-vue)
- [@motajs/system](../api/motajs-system)
- [@motajs/system-action](../api/motajs-system-action)
- [@motajs/system-ui](../api/motajs-system-ui)
- [@motajs/types](../api/types)
- [@user/client-modules](../api/user-client-modules)
- [@user/data-base](../api/user-data-base)
- [@user/data-fallback](../api/user-data-fallback)
- [@user/data-state](../api/user-data-state)
- [@user/data-utils](../api/user-data-utils)
- [@user/entry-client](../api/user-entry-client)
- [@user/entry-data](../api/user-entry-data)
- [@user/legacy-plugin-client](../api/user-legacy-plugin-client)
- [@user/legacy-plugin-data](../api/user-legacy-plugin-data)
## Mota 全局变量
与 2.A 不同，2.B 对 `Mota` 全局变量做了简化，不再拥有 `Mota.Plugin` `Mota.Package` `Mota.requireAll` 属性与方法，它们全部整合至了 `Mota.require` 方法中，同时该方法的用法与 2.A 也不同，在 2.A 中，我们往往使用 `Mota.require('var', 'xxx')` 的方式调用，繁琐且不直观。在 2.B 中，我们可以直接填入模块名称，就可以获取到其内容了，例如：
```ts
const { hook, loading } = Mota.require('@user/data-base'); // 获取 hook 与 loading
const { Font } = Mota.require('@motajs/render'); // 获取 Font 字体类
```
我们只需要填写一个参数，而不需要填写两个参数了，更加直观，而且与 ES6 模块语法类似，便于转换。
多数情况下，我们是不需要使用 `Mota` 全局变量的。不过，还是有一些特殊情况需要使用该全局变量才可以，这些情况包括：
- 在数据端调用渲染端接口，数据端需要跑录像验证，因此不能直接引入渲染端接口，需要通过此全局变量才可以。
- 在 `libs` `functions.js` 中调用接口，这两个地方暂时还没有模块化，因此无法直接引入，需要通过此全局变量调用。
## 渲染端与数据端通信
一般情况下，渲染端**可以**直接引入数据端的内容，例如你可以在 `@user/client-modules` 里面直接引入 `@user/data-state` 的接口，这是没有问题的。不过，由于数据端需要在服务器上跑录像验证，因此**不能**直接引入渲染端的内容，否则会导致验证报错。如果需要在数据端引用渲染端接口，我们需要这么做：
```ts
// @user/data-state 中的某文件
const num = 100;
Mota.r(() => {
// 使用 r 方法包裹，这样这个函数就会在渲染端运行，可以有返回值，但是在录像验证中只会是 undefined
const { Font } = Mota.require('@motajs/render');
const font = new Font('Verdana', 18);
// 函数内也可以调用外部变量，例如这里就调用了外部的 num 变量，但是极度不推荐在渲染端修改数据端的内容
// 否则很可能导致录像不能运行，这里这个例子就会导致录像运行出错，因为录像验证时并不会执行这段代码，
// 勇士的血量也就不会变大，于是就出错了。
core.status.hero.hp += num;
});
```
除此之外，我们还可以使用钩子来进行数据通信。示例如下：
```ts
// 渲染端和数据端都可以使用这个方式引入
import { hook } from '@user/data-base';
// 也可以通过 Mota.require 方法引入
const { hook } = Mota.require('@user/data-base');
// 监听战后函数，每次与怪物战斗后，都会执行这个函数
// 每个钩子的参数定义可以参考 package-user/data-base/src/game.ts GameEvent 接口
hook.on('afterBattle', enemy => {
console.log('与怪物战斗：', enemy.id);
});
```
## 加载流程
与 2.A 相比，加载流程也不太一样，下面是 2.B 的加载流程：
1. 加载 `index.html`
2. 加载 2.x 样板的第三方库
3. 如果是游戏中，加载 `src/main.ts`
1. 加载渲染端入口
2. 加载数据端入口
3. 并行初始化数据端，写入 `Mota` 全局变量
4. 初始化完毕后执行 `loading.emit('dataRegistered')` 钩子
5. 并行初始化渲染端
6. 初始化完毕后执行 `loading.emit('clientRegistered')` 钩子
7. 二者都初始化完毕后执行 `loading.emit('registered')` 钩子
8. 执行数据端各个模块的初始化函数
9. 执行渲染段各个模块的初始化函数
4. 如果是录像验证中：
1. 加载数据端入口
2. 初始化数据端，写入 `Mota` 全局变量
3. 初始化完毕后执行 `loading.emit('dataRegistered')` 与 `loading.emit('registered')` 钩子
4. 执行数据端各个模块的初始化函数
5. 执行 `main.js` 初始化
6. 加载全塔属性
7. 加载 `core.js` 及其他 `libs` 中的脚本
8. 加载完毕后执行 `loading.emit('coreInit')` 钩子
9. 开始资源加载
10. 自动元件加载完毕后执行 `loading.emit('autotileLoaded')` 钩子
11. 资源加载完毕后执行 `loading.emit('loaded')` 钩子
12. 进入标题界面
## 函数重写
在 2.B 模式下，如果想改 `libs` 的内容，如果直接在里面改会很麻烦，而且两端通讯也不方便，因此我们建议在 `package-user` 中对函数重写，这样的话就可以使用模块化语法，更加方便。同时，2.B 也提供了函数重写接口，他在 `@motajs/legacy-common` 模块中，我们可以这么使用它：
```ts
// 新建一个 ts 文件，例如叫做 override.ts，放在 client-modules 文件夹下
import { Patch, PatchClass } from '@motajs/legacy-common';
// 新建函数，这个操作是必要的，我们不能直接在顶层使用这个接口
export function patchMyFunctions() {
// 创建 Patch 实例，参数表示这个 Patch 示例要重写哪个文件中的函数
// 如果需要复写两个文件，那么就需要创建两个实例
const patch = new Patch(PatchClass.Control);
// 使用 add 函数来重写，第一个参数会有自动补全
// 如果要重写的函数以下划线开头，可能会有报错
// 这时候需要去 types/declaration 中对应的文件中添加声明
patch.add('getFlag', (name, defaultValue) => {
// 重写 getFlag，如果变量是数字，那么 +100 后返回
const value = core.status.?hero.?flags[name] ?? defaultValue;
return typeof value === 'number' ? value + 100 : value;
});
}
```
然后，我们找到 `client-modules` 文件夹下的 `index.ts` 文件，然后在 `create` 函数中调用 `patchMyFunctions`，这样我们的函数重写就完成了。
::: warning
**注意**，在渲染端重写的函数在录像验证中将无效，因为录像验证不会执行任何渲染端内容！
:::
## 目录结构
我们建议每个文件夹中都有一个 `index.ts` 文件，将本文件夹中的其他文件经由此文件导出，这样方便管理，同时结构清晰。可以参考 `packages-user/client-modules` 文件夹中是如何做的。

0
docs/guide/ui-system.md Normal file
View File

0
docs/guide/ui.md Normal file
View File

2
docs/index.md
View File

@ -4,7 +4,7 @@ layout: home
hero:
name: 'mota-js'
text: 'HTML5魔塔样板V2.A'
text: 'HTML5魔塔样板V2.B'
tagline: HTML5魔塔样板从 2.x 到 3.0 的过渡版本
actions:
- theme: brand

2
public/main.js
View File

@ -1,4 +1,4 @@
///<reference path="../src/types/core.d.ts" />
///<reference path="../types/declaration/core.d.ts" />
function main() {
//------------------------ 用户修改内容 ------------------------//