HumanBreak/docs/api/user-entry-data/Mota.md

Mota API 文档

本文档由 DeepSeek R1 模型生成并微调。

---

核心功能

模块化管理系统，提供跨进程模块注册与获取能力，支持数据端与渲染端分离架构。用于解决服务端录像验证与客户端渲染的模块隔离问题。

---

全局访问

// 浏览器环境
Mota.require('@motajs/client');

// ESM 环境
import { Mota } from '@motajs/core';

---

核心方法

require

function require<K extends keyof ModuleInterface>(key: K): ModuleInterface[K];
function require<T = unknown>(key: string): T;

功能
获取已注册的模块实例

参数	类型	说明
key	string	模块标识符或自定义命名空间

返回值
对应模块的导出对象

预定义模块列表：

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;
}

示例：

// 获取动画引擎
const Animate = Mota.require('MutateAnimate');

// 获取Vue实例
const Vue = Mota.require('Vue');

// 获取旧版UI系统
const LegacyUI = Mota.require('@motajs/legacy-ui');

---

register

function register<K extends keyof ModuleInterface>(
    key: K,
    data: ModuleInterface[K]
): void;
function register(key: string, data: unknown): void;

功能
注册模块到全局系统

参数	类型	说明
key	string	模块标识符
data	any	模块导出对象

注意事项

• 重复注册会触发控制台警告
• 推荐在游戏初始化阶段注册

示例：

// 注册自定义模块
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

function r<T = undefined>(fn: (this: T) => void, thisArg?: T): void;

功能
包裹只在渲染进程执行的代码

参数	类型	说明
fn	Function	需要渲染端执行的函数
thisArg	any	函数执行上下文

特性

• 在录像验证和服务端环境下不会执行
• 无返回值设计

示例：

// 播放仅客户端可见的特效
Mota.r(() => {
    const animate = Mota.require('MutateAnimate');
    animate(heroSprite).shake(5, 1000);
});

---

rf

function rf<F extends (...params: any) => any, T>(
    fn: F,
    thisArg?: T
): (...params: Parameters<F>) => ReturnType<F> | undefined;

功能
生成渲染进程安全函数

参数	类型	说明
fn	Function	需要包装的原函数
thisArg	any	函数执行上下文

返回值
经过安全包裹的函数，在非渲染环境调用返回 undefined

示例：

// 创建安全渲染函数
const safeAlert = Mota.rf((msg: string) => {
    alert(`客户端提示: ${msg}`);
});

// 调用时自动判断执行环境
safeAlert('仅在客户端显示'); // 服务端返回 undefined

---

架构示意图

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. 性能优化
   高频调用模块建议缓存引用：

   // 推荐
   const Animate = Mota.require('MutateAnimate');
   
   // 不推荐
   function update() {
       const Animate = Mota.require('MutateAnimate'); // 每次调用都查找
   }
   

4. 错误处理
   使用 try-catch 包裹高风险模块获取：

   try {
       const LegacyUI = Mota.require('@motajs/legacy-ui');
   } catch (e) {
       fallbackUI();
   }