mirror of
https://github.com/unanmed/HumanBreak.git
synced 2025-11-04 15:12:58 +08:00
252 lines
5.7 KiB
Markdown
252 lines
5.7 KiB
Markdown
# Mota API 文档
|
||
|
||
本文档由 `DeepSeek R1` 模型生成并微调。
|
||
|
||
---
|
||
|
||
## 核心功能
|
||
|
||
模块化管理系统，提供跨进程模块注册与获取能力，支持数据端与渲染端分离架构。用于解决服务端录像验证与客户端渲染的模块隔离问题。
|
||
|
||
---
|
||
|
||
## 全局访问
|
||
|
||
```typescript
|
||
// 浏览器环境
|
||
Mota.require('@motajs/client');
|
||
|
||
// ESM 环境
|
||
import { Mota } from '@motajs/core';
|
||
```
|
||
|
||
---
|
||
|
||
## 核心方法
|
||
|
||
### `require`
|
||
|
||
```typescript
|
||
function require<K extends keyof ModuleInterface>(key: K): ModuleInterface[K];
|
||
function require<T = unknown>(key: string): T;
|
||
```
|
||
|
||
**功能**
|
||
获取已注册的模块实例
|
||
|
||
| 参数 | 类型 | 说明 |
|
||
| ----- | -------- | -------------------------- |
|
||
| `key` | `string` | 模块标识符或自定义命名空间 |
|
||
|
||
**返回值**
|
||
对应模块的导出对象
|
||
|
||
**预定义模块列表**：
|
||
|
||
```typescript
|
||
interface ModuleInterface {
|
||
// ---------- 样板库
|
||
'@motajs/client': typeof Client;
|
||
'@motajs/client-base': typeof ClientBase;
|
||
'@motajs/common': typeof Common;
|
||
'@motajs/legacy-client': typeof LegacyClient;
|
||
'@motajs/legacy-common': typeof LegacyCommon;
|
||
'@motajs/legacy-system': typeof LegacySystem;
|
||
'@motajs/legacy-ui': typeof LegacyUI;
|
||
'@motajs/render': typeof Render;
|
||
'@motajs/render-core': typeof RenderCore;
|
||
'@motajs/render-elements': typeof RenderElements;
|
||
'@motajs/render-style': typeof RenderStyle;
|
||
'@motajs/render-vue': typeof RenderVue;
|
||
'@motajs/system': typeof System;
|
||
'@motajs/system-action': typeof SystemAction;
|
||
'@motajs/system-ui': typeof SystemUI;
|
||
// ---------- 用户扩展
|
||
'@user/client-modules': typeof ClientModules;
|
||
'@user/data-base': typeof DataBase;
|
||
'@user/data-fallback': typeof DataFallback;
|
||
'@user/data-state': typeof DataState;
|
||
'@user/data-utils': typeof DataUtils;
|
||
'@user/legacy-plugin-client': typeof LegacyPluginClient;
|
||
'@user/legacy-plugin-data': typeof LegacyPluginData;
|
||
// ---------- 必要的第三方库
|
||
MutateAnimate: typeof MutateAnimate;
|
||
Vue: typeof Vue;
|
||
Lodash: typeof Lodash;
|
||
}
|
||
```
|
||
|
||
**示例**：
|
||
|
||
```typescript
|
||
// 获取动画引擎
|
||
const Animate = Mota.require('MutateAnimate');
|
||
|
||
// 获取Vue实例
|
||
const Vue = Mota.require('Vue');
|
||
|
||
// 获取旧版UI系统
|
||
const LegacyUI = Mota.require('@motajs/legacy-ui');
|
||
```
|
||
|
||
---
|
||
|
||
### `register`
|
||
|
||
```typescript
|
||
function register<K extends keyof ModuleInterface>(
|
||
key: K,
|
||
data: ModuleInterface[K]
|
||
): void;
|
||
function register(key: string, data: unknown): void;
|
||
```
|
||
|
||
**功能**
|
||
注册模块到全局系统
|
||
|
||
| 参数 | 类型 | 说明 |
|
||
| ------ | -------- | ------------ |
|
||
| `key` | `string` | 模块标识符 |
|
||
| `data` | `any` | 模块导出对象 |
|
||
|
||
**注意事项**
|
||
|
||
- 重复注册会触发控制台警告
|
||
- 推荐在游戏初始化阶段注册
|
||
|
||
**示例**：
|
||
|
||
```typescript
|
||
// 注册自定义模块
|
||
class MyCustomModule {
|
||
static version = '1.0.0';
|
||
}
|
||
Mota.register('@user/custom-module', MyCustomModule);
|
||
|
||
// 使用自定义模块
|
||
const custom = Mota.require('@user/custom-module');
|
||
console.log(custom.version); // 输出 1.0.0
|
||
```
|
||
|
||
---
|
||
|
||
## 渲染进程控制
|
||
|
||
### `r`
|
||
|
||
```typescript
|
||
function r<T = undefined>(fn: (this: T) => void, thisArg?: T): void;
|
||
```
|
||
|
||
**功能**
|
||
包裹只在渲染进程执行的代码
|
||
|
||
| 参数 | 类型 | 说明 |
|
||
| --------- | ---------- | -------------------- |
|
||
| `fn` | `Function` | 需要渲染端执行的函数 |
|
||
| `thisArg` | `any` | 函数执行上下文 |
|
||
|
||
**特性**
|
||
|
||
- 在录像验证和服务端环境下不会执行
|
||
- 无返回值设计
|
||
|
||
**示例**：
|
||
|
||
```typescript
|
||
// 播放仅客户端可见的特效
|
||
Mota.r(() => {
|
||
const animate = Mota.require('MutateAnimate');
|
||
animate(heroSprite).shake(5, 1000);
|
||
});
|
||
```
|
||
|
||
---
|
||
|
||
### `rf`
|
||
|
||
```typescript
|
||
function rf<F extends (...params: any) => any, T>(
|
||
fn: F,
|
||
thisArg?: T
|
||
): (...params: Parameters<F>) => ReturnType<F> | undefined;
|
||
```
|
||
|
||
**功能**
|
||
生成渲染进程安全函数
|
||
|
||
| 参数 | 类型 | 说明 |
|
||
| --------- | ---------- | ---------------- |
|
||
| `fn` | `Function` | 需要包装的原函数 |
|
||
| `thisArg` | `any` | 函数执行上下文 |
|
||
|
||
**返回值**
|
||
经过安全包裹的函数，在非渲染环境调用返回 `undefined`
|
||
|
||
**示例**：
|
||
|
||
```typescript
|
||
// 创建安全渲染函数
|
||
const safeAlert = Mota.rf((msg: string) => {
|
||
alert(`客户端提示: ${msg}`);
|
||
});
|
||
|
||
// 调用时自动判断执行环境
|
||
safeAlert('仅在客户端显示'); // 服务端返回 undefined
|
||
```
|
||
|
||
---
|
||
|
||
## 架构示意图
|
||
|
||
```mermaid
|
||
graph TD
|
||
subgraph 数据端
|
||
Validator[录像验证系统]
|
||
CoreLogic[核心逻辑]
|
||
end
|
||
|
||
subgraph 渲染端
|
||
UI[用户界面]
|
||
Effects[特效系统]
|
||
Render[渲染引擎]
|
||
end
|
||
|
||
MotaSystem -->|require/register| Validator
|
||
MotaSystem -->|r/rf| Render
|
||
CoreLogic -->|跨进程通信| Effects
|
||
```
|
||
|
||
---
|
||
|
||
## 注意事项
|
||
|
||
1. **模块隔离**
|
||
数据端模块与渲染端模块物理隔离，数据端不可直接引用渲染端，而渲染端是可以直接引用数据端的
|
||
|
||
2. **版本兼容**
|
||
遗留系统模块（legacy-\*）将在未来版本逐步废弃，这些模块也不再提供 API 文档，如果需要自行阅读源码。
|
||
|
||
3. **性能优化**
|
||
高频调用模块建议缓存引用：
|
||
|
||
```typescript
|
||
// 推荐
|
||
const Animate = Mota.require('MutateAnimate');
|
||
|
||
// 不推荐
|
||
function update() {
|
||
const Animate = Mota.require('MutateAnimate'); // 每次调用都查找
|
||
}
|
||
```
|
||
|
||
4. **错误处理**
|
||
使用 try-catch 包裹高风险模块获取：
|
||
```typescript
|
||
try {
|
||
const LegacyUI = Mota.require('@motajs/legacy-ui');
|
||
} catch (e) {
|
||
fallbackUI();
|
||
}
|
||
```
|