# mogs-tools

mogs-tools 是一个 MOGS 安装与辅助开发工具，支持 Cocos Creator，Laya 游戏引擎，支持构建游戏项目到 cymini，微信，QQ 平台。

# 一、介绍

mogs-tools 是一个 MOGS 安装与辅助开发工具，提供：

安装指定版本的 MOGS SDK
在用户使用游戏引擎构建游戏项目时，按需将所需依赖包生成到输出目录中，开发者无需手动处理
在使用cocos预览时，自动附加 MOGS SDK 包，方便cocos开发者无需构建，使用预览功能即可调试
在开启微信开放域时，支持根据配置文件生成JSServer与好友互动模板，用于处理好友送心功能的检查逻辑等
在开启微信开放域时，支持在开放域下附加 MOGS SDK 包，用于直接在微信开发者工具下直接使用 MOGS SDK 中编写关于数据开放域部分的功能

它确保了 mogs 的版本管理，让您专注在游戏开发上，无障碍使用 MOGS SDK 提供的游戏接口。

# 二、环境需求

Node >= 7.9
npm 工具
git 工具

Node 与 npm 工具下载与安装，见：Node官网 (opens new window)

git 工具下载与安装，见：Git官网 (opens new window)

# 三、安装

在游戏项目根目录下，执行命令 npm init -y && npm i git+https://git.code.tencent.com/mogs/tools.git --save-dev ，可初始化 package.json 文件并安装本工具。其中：

npm init -y：用于初始化项目为一个 NPM 包，使得项目可以使用 NPM 包的方式管理模块。由于 MOGS SDK 使用 NPM 包的方式管理自身模块，因此您需要将游戏项目初始化为一个NPM包。

npm i git+https://git.code.tencent.com/mogs/tools --save-dev：用于安装 mogs-tools。

# 四、更新工具

当您需要更新工具时，可在游戏项目根目录下执行 npm run mogs-update，这将会同时更新 mogs-tools 与 SDK。

# 五、使用

# 1. 安装 sdk

工具安装完成后，安装 MOGS SDK，它们需要在游戏项目根目录下执行：

npm run mogs-install -- --version 1.0|1.1|...|stable|preview：安装指定版本 MOGS SDK，如：执行npm run mogs-install -- --version stable安装最新稳定版。此处的 1.0, 1.1, stable 等为版本号，其中 1.0, 1.1 等版本号是固定的，而 stable, preview 这两个版本号在安装前是变化的，安装后是固定的。举个例子，如当前 stable 为 0.2，则执行 npm run mogs-install -- --version stable 等价于执行 npm run mogs-install -- --version 0.2，即使后续 stable 变为 0.3，更新 MOGS SDK 也会在 0.2 上更新。

安装 MOGS SDK 后，工具会在游戏项目根目录下生成 mogs.json 文件，请在该文件中填入相关配置信息。如您未在该文件中填入相关配置信息，或填入信息错误，将在构建或运行时报错。 一个合法的 mogs.json 文件如下（请注意，如您将下述内容复制到您的 mogs.json 文件中，请注意去掉注释，因为 json 文件是不支持注释的）：

{
    // 环境，可选值为 "dev" | "test" | "business"
    "env": "dev",
    "cymini": {
        // 有乐平台下的 gameId，无论是构建到有乐平台，还是进行预览，都需要填写该值
        // 如果需要进行预览但是不填写该值，会导致无法预览，如无该值可暂时随意填写一个数字
        "gameId": 123
    },
    "wx": {
        // 微信小游戏平台下的 appId
        "appId": "12312"
    },
    "qq": {
        // QQ小游戏平台下的 appId
        "appId": "1231"
    },
    // 代理服务器地址，如果您不需要使用代理服务器，该字段可直接删除
    // 对于 MAC 系统，本工具的内部网络模块，git 工具与 npm 工具会默认使用本字段的值作为代理服务器地址
    // 对于 Windows 系统，本工具的内部网络模块会默认使用本字段的值作为代理服务器地址，git 工具 与 npm 工具遵循全局设置
    "http_proxy": "http://127.0.0.1:12639",
    // 好友
    "userInteraction": {
      "key": "date",
      "limit": 5,
      "repeatedSendLimit": 1
    },
    // 好友交互行为模板
    "modifyFriendInteractiveStorageTemplates": [{
      // 这个 key 与接口中同名参数相对应，不同的 key 对应不同的模板
      // 目前 key 只能为 1
      "key": "1",
      // 互动行为
      "action": "赠送",
      // 互动物品
      "object": "金币",
      // 物品比率，opNum * ratio 代表物品个数
      "ratio": 10
    }],
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39

# 2. 更新与升级 sdk

npm run mogs-upgrade -- --version 1.0|1.1|...|stable|preview：升级 MOGS SDK 到指定版本
npm run mogs-update：更新 MOGS SDK

# 3. 其他命令

npm run mogs-tools -- -build-cymini：构建友乐游戏项目后，执行该命令会在 index.html 中注入 MOGS 所需的 script，开发者一般无需手动执行本命令
npm run mogs-tools -- -build-wx：构建微信小游戏项目后，执行该命令会在微信小游戏项目根目录生成 miniprogram_npm 目录，开发者一般无需手动执行本命令
npm run mogs-tools -- -build-qq：构建 QQ 小游戏项目后，执行该命令会在 QQ 小游戏项目根目录生成 miniprogram_npm 目录，开发者一般无需手动执行本命令
npm run mogs-tools -- -generate-wx-sdk-open-pkg：在微信小游戏项目输出目录的开放域目录中生成包 sdk-open, sdk-open-wx, sdk-core
npm run mogs-tools -- -generate-qq-sdk-open-pkg：在 QQ 小游戏项目输出目录的开放域目录中生成包 sdk-open, sdk-open-qq, sdk-core
npm run mogs-tools -- -inject-wx-interaction：在微信小游戏项目开启开放数据域的情况下，根据 mogs.json 中的注入 jsserver 以及修改 game.json，用于辅助实现提供好友送心功能的逻辑。
npm run mogs-tools -- -generate-cocos-jsplugin：根据used-mogs-packages.json中的内容生成js插件。为不支持npm包的引擎使用(例如cocos 3.0)
npm run mogs-tools -- -generate-preview-templates：根据mogs.json中的内容生成本地开发时的预览模板。为不支持npm包的引擎使用(例如cocos 3.0)
npm run mogs-tools -- -batchset-cocos-jsplugin：批量引擎的导入js插件(Import As Plugin)，免去手动设置。为不支持npm包的引擎使用(例如cocos 3.0)
npm run mogs-tools -- -clean-temp：清除临时目录
npm run mogs-tools -- -debug-info：生成 debug 信息文件，开发者一般无需执行本命令
npm run mogs-tools -- -help：输出帮助

# 六、常见问题

# 无法安装 MOGS SDK 且为内网开发者

对于内网开发者（外网开发者请忽略此段），为了使本工具在使用 npm 工具、git 工具等时能连接到外网，还需要在 mogs.json 中增加字段 A"http_proxy" ，在其中填入系统代理服务器地址（如果您是腾讯内网开发者，可在 8000 服务中查找文章“App 代理设置指引”找到代理服务器地址）。如若代理服务器地址为 127.0.0.1:8080，可以增加字段及值 "http_proxy": "http://127.0.0.1:8080"。如果内网开发者没有配置该字段，在构建游戏项目时，很可能会出现网络正常但是工具提示网络连接失败，或长时间卡住的情况。另外，如果您是 Windows 平台下的开发者，或按上述方法配置后工具仍无法连接到外网，请考虑手动为 npm 工具与 git 工具配置代理。

# 手动处理 MOGS 构建

一般情况下，使用游戏引擎构建游戏项目时，本工具会自动处理 MOGS 有关依赖，开发者无需手动处理。如需要手动处理，可以执行本工具提供的以下三个命令，其含义已在其他命令中阐述，需在游戏引擎构建游戏项目完成后使用。

npm run mogs-tools -- -build-cymini
npm run mogs-tools -- -build-wx
npm run mogs-tools -- -build-qq

# 引擎无法使用npm包，如何使用MOGS SDK

以cocos 3D 和 cocos 3.0.0为例，通过js插件的方式来使用MOGS SDK。安装MOGS TOOLS和MOGS SDK后，工具会在游戏项目目录下生成 used-mogs-packages.json, 修改该文件填入项目开发要使用到的MOGS SDK包名列表以及目标构建平台。一个合法的 used-mogs-packages.json 示例文件内容如下（请注意去掉注释，因为 json 文件是不支持注释的）：

{
    // 业务方使用到的模块，请先在此处声明需要用到的模块，便于后续生成js插件，模块名可在项目目录中的 node_modules/@timi 中查找
    "packageNames": [
        "@timi/mogs-sdk-account"
    ],
    // 平台合法值 cymini | wx ｜ qq
    "platform": "cymini"
}

1
2
3
4
5
6
7
8

建议安装完成MOGS TOOLS和SDK后执行 npm run mogs-tools -- -generate-preview-templates 用来根据mogs.json中的内容生成本地开发时的预览模板
进行业务开发时，可先确定需要使用的MOGS的包名以及开发平台，各功能模块和包名关系可咨询MOGS人员，之后可运行 npm run mogs-tools -- -generate-cocos-jsplugin 生成引擎需要用到的js插件，MOGS会在如下图的目录中生成文件
生成js插件文件后，需要打开引擎使得引擎加载这些文件，打开引擎后执行 npm run mogs-tools -- -batchset-cocos-jsplugin 以批量设置上图中的文件为引擎的js插件

MOGS SDK的用法

// creator3d项目只能使用左边访问 sdk 接口，访问的效果等价于右边
let { sdk } =  window.mogsRequire('@timi/mogs-sdk-core'); //等价于npm包场景的 import mogs from "@timi/mogs-sdk";
let { accountSystem } = window.mogsRequire('@timi/mogs-sdk-account');  //等价于npm包场景的 import { accountSystem } from "@timi/mogs-sdk";

1
2
3

# 七、开发资料

gm命令小程序 →