跳至主要內容

关于 MKFramework 的设计想法

muzzik大约 21 分钟文章CocosCocosCreator游戏框架

MKFramework是我个人维护持续了几年的项目（虽然公开只有一年左右），最开始由于自己从事QP类游戏开发，我很喜欢MVVM，于是想把他做成 MVVM 框架，在论坛第一个 MVVM 框架出来的时候，我的框架已经快完成了，但是为了其他人项目的安全着想还是没有发布.. 后面又进行了数次大改动，现在说说自己对于代码框架开发的一些心得和想法

github：https://github.com/1226085293/MKFrameworkopen in new window
gitee：https://gitee.com/muzzik/MKFrameworkopen in new window
文档：https://muzzik.gitee.io/mk-framework/quick-start/open in new window

# 游戏框架需要有哪些功能？

作为一个游戏框架需要支持什么功能？我认为框架只是弥补引擎的不足和痛点，只需要解决用户高频使用的功能/缺点即可，而其他的功能让用户自行选择开源项目或者自定义

  • UI

屏幕适配，多节点实例化卡顿，规范生命周期函数（重复利用的节点脚本必须），点击返回按钮怎么关闭对应的UI，查找场景内指定模块，使用单脚本多预制体，支持脚本和预制体分离，UI层级控制

  • 音频

播放音频得添加组件，加载动态音频代码太多，播放多个音频会停止之前的音频，单AudioSource只能play单个音频，音频分组控制

  • 网络

XMLHttpRequest 代码太多需要封装，webscoket的心跳，重连，发送间隔控制，多种消息格式支持

  • 资源

资源管理，编辑器资源加载，无意义的/SpriteFrame后缀，同时间加载同一资源导致的引用计数错误，防止资源短时间内重复加载，Bundle热更

  • 多语言

多语言资源和文本垃圾堆积，编辑器预览，多语言布局，多语言节点

  • 新手引导

多实例新手引导，引导步骤脚本分离，引导步骤需要依赖节点，引导步骤的跳转和插入，暂停引导状态，更新引导数据

  • 事件

类型安全保证，事件键的提示

  • 存储

类型安全保证，怎么保证默认值的存在

  • 数据

共享数据的类型，多模块请求对方的异步数据

  • MVVM

解决数据更新展示问题，免去不必要的代码

# 各个模块的不同之处

以下主要讲解的是MK框架和其他框架不同的地方，大家都知道的功能讲出来那也没什么意义

UI

点击展开

1. 适配

  • 屏幕适配
    这个都说烂了，基本就是更宽定高，更高定宽，为了方便，可以监听切换场景事件后自动添加到 canvas

    cc.director.on(cc.Director.EVENT_AFTER_SCENE_LAUNCH, () => { ... });

    源码：mk_adaptation_canvasopen in new window

  • 节点适配
    除了屏幕适配，可能大家还没意识到，使用更多的是节点适配，比如背景，比如大小不同的商品图标

    适配尺寸

    1. canvas
    2. 父节点
    3. 自定义

    需要哪些适配模式呢？

    1. 缩放（占满空间）
    2. 自适应_展示完（展示全部内容，可能有上下左右黑边）
    3. 自适应_填充满（更宽定宽，更高定高，无黑边）
    4. 填充宽（保持大小比例占满宽度，可能有上下黑边）
    5. 填充高（保持大小比例占满高度，可能有左右黑边）

    这就是我的节点适配脚本可以做的事情

    源码：mk_adaptation_nodeopen in new window

2. 生命周期

为什么需要生命周期函数？又需要有哪些生命周期函数？

1. 为什么需要生命周期函数

在重复使用一个节点的时候，必然存在打开和关闭状态，其上的组件脚本中的 onEnable 和 onDisable 并不能代替打开和关闭回调。所以 必须存在 open 和 close 这两个最基本的生命周期函数！

2. 生命周期函数需要有哪些？

  • create
  • init(...)
  • open
  • close
  • late_close

除了最基本的 open 和 close，为什么还需要其他回调？一个一个说

create（初始化视图回调）

为什么需要在 create 中初始化视图，而不是 open 或者 onLoad？那就和生命周期函数调用顺序有关

生命周期调用顺序

  • open：子节点-->父节点
  • close：父节点->子节点

为什么是这样的顺序？因为要保证在父模块 open 时能获取正常的子模块数据，反之亦然，如果子模块先 close，父模块获取子模块数据就会出错。

所以为什么要在 create 初始化视图？onLoad 只会调用一次，而 open 需要等待子模块 全部 open 完成，所以为了更新初始视图，只能用 create

init（初始化数据回调）

为什么需要它？init 的职责就是利用外部传递的数据进行初始化操作，

那么为什么不在 open 内进行初始化操作呢？open 的职责其实也是初始化，但是如果把使用初始化数据的初始化操作放在 open 内，你的模块需要从外部手动传递初始化数据的时候你该怎么做？

比如提前创建的模块，等待网络请求返回后再传递初始化数据。这时候就需要一个初始化函数，用于处理外部传递的数据进行初始化操作，而且可能在 open 后被调用多次，而 open 只会在模块打开时调用一次，所以就有了 init

late_close（关闭之后）

这个回调存在的意义就是框架为了在模块 close 之后清理模块的数据，比如事件，定时器，框架已经在父类中为你做了这些事情，所以你大部分时候不会使用到它

源码：mk_life_cycleopen in new window

3. 怎么驱动生命周期？

可以监听场景切换后的事件（cc.Director.EVENT_AFTER_SCENE_LAUNCH），然后进行递归调用生命周期

源码：mk_scene_driveopen in new window

3. UI 管理器

UI 管理器主要做的事情就是 预加载 / 创建(启动) / 回收 / 查找 模块，当然，为了更方便的使用，你需要设计一个好的接口

而我设计的接口有这几个

  • regis（注册）
  • unregis（取消注册）
  • open（打开）
  • close（关闭）
  • get（获取）

很简单对吧，它们做了什么事？让我娓娓道来~

regis

  1. 在 regis 时，UI 管理器会为这个模块的资源创建一个对象池，使用你传递的参数(或默认参数)进行预加载，完全可控，默认只创建一个对象
  2. regis 会保存某些固定的配置，防止你每次 open 时都传递这些参数，例如
    • repeat_b：是否允许重复创建多个模块，像子弹就需要，弹窗大部分都不需要，可以防止用户点击过快导致打开多个模块
    • parent：默认的父节点，当然 open 函数参数配置内也有 parent，按需覆盖或者空置

unregis

主要是为了释放 regis 传递的对象和对象池，在 regis 时会有一个跟随释放对象，对象池和资源会跟随这个对象（模块）一起释放。也就是前面生命周期内说的 late_close 会清理，如果它不为空，你就不需要手动调用 unregis

open

open 的职责就是从对象池中取出指定模块，然后执行生命周期。你以为就这些吗？不，在我们工作中，经常有一些全屏的 UI，这时候 我们是不需要展示全屏 UI 以下的内容的。这时候我们利用 UI 栈的数据，把全屏 UI 之前打开的模块全部隐藏，就节省了 DrawCall 占用 =.=👍

close

和 open 类似，不过是变成了回收模块

get

get 含义很简单，但是我重载了三次，有三个用法

  1. 获取当前所有的模块列表

    mk.ui_manage.get()

  2. 获取指定类型的模块

    mk.ui_manage.get(class)

  3. 获取指定类型的模块列表

    mk.ui_manage.get([class])

这就是接口设计的魅力，一个接口三个方式使用

单脚本多预制

如果我们需要一个脚本对应多个预制体资源，应该怎么做？拷贝多个脚本？不不不 🙅‍♂️，有更简单的方式，并且 MKFramework 已经实现了它

mk.ui_manage.regis(
	res_test,
	{
		default: "db://assets/resources/module/test/t1.prefab",
		new: "db://assets/resources/module/test/t2.prefab",
	},
	this
);

只需要在注册时这样做，你就可以使用 ui_manage.open 打开不同类型的模块，而且 无须你将脚本挂载到预制体上

mk.ui_manage.open(res_test, { type: "new" });

类型安全

UI 管理器是支持模块类型和初始化数据类型安全的，不必担心外部使用者导致的错误，当然这个功能完全是可选的，取决你是否声明了 init_data 和 type_s 的类型

源码：mk_ui_manageopen in new window

4. 纯代码开发

通过 ui_manage.open 打开模块，ui_manage 会在预制体实例化后自动挂载这个模块脚本（如果根节点不存在模块脚本）

5. 层级管理

对于模块，框架提供了内置的层级管理，将层级划分为不同的类型，每个类型间隔指定的数量，当然，这些是你完全可控的！

使用时

当然你也可以在编辑器对它进行赋值

6. 快捷操作

MKFramework 将开发中高频的操作封装了一下，让你使用更简单，这里 diss 一下引擎开发团队，什么时候解决这个问题 https://forum.cocos.org/t/topic/154608open in new window

音频

点击展开

1. 结构

框架将每个音频都封装为一个音频单元，音频单元内存储着音频的所有信息。包括事件在内。类似 AudioSource，而音频管理器（mk.audio）则是控制音频单元的工具

创建音频单元

  • 编辑器
@property({ displayName: "音效", type: mk.audio_.unit })
effect = new mk.audio_.unit();
  • 脚本
// 单个音频
const effect = (await mk.audio.add("db://xxx.mp3", this))!;

// 多个音频
const effect_as = (await mk.audio.add(["db://xxx.mp3", ...], this))!;

// 文件夹音频
const effect_as = (await mk.audio.add("db://xxx", this, { dir_b: true }))!;

// 多个文件夹音频
const effect_as = (await mk.audio.add(["db://xxx", ...], this, { dir_b: true }))!;

使用

2. 解决多音频监听结束回调

为 playOneShot 添加结束回调

如果不指定 use_play_b 为 true，默认音频系统是使用 playOneShot 接口，而 playOneShot 也没有结束回调，所以框架内使用定时器为 playOneShot 模拟了结束事件

mk.audio.play(this.effect, { use_play_b: false });

AudioSource 对象池

如果你还需要对音频进行暂停操作，那么只能使用 play 接口，而单个 AudioSource 并不能支持多个音频同时使用 play 接口播放，为了解决这个问题，只能使用 AudioSource 对象池，在用户需要的时候手动指定使用 play 接口，例如

mk.audio.play(this.overlap_effect, { use_play_b: true });

3. 音频分组

MK框架支持音频多分组控制，什么是分组？音乐是分组，音效是分组，环境音也可以是分组，分组有多少，全看你定义多少。

当你需要同时控制多个音频时，你就需要用到音频分组了，比如 音乐 和 音效 是内置的音频分组，被称为音频类型，音频单元必须存在音频类型。但是不一定存在音频分组

功能

  1. 设置音量
  2. 设置播放状态（播放/停止）
  3. 添加/删除音频单元

规则

  1. 单个音频单元可以存在于多个分组内
  2. 音频单元的音量 = 其音频分组的音量相乘结果 * 自身音量
  3. 音频分组存在优先级，音频的播放/停止状态优先级高的音频分组决定

源码：mk_audio_baseopen in new window

网络

点击展开

1. 无须传递消息号的秘密

在平常使用中，收发网络消息通常需要手动传递消息号，但是MK框架避免了这个问题，那么是怎么完成的呢？

// 发送消息
this._ws2.message.send(test.test_c.create());

// 请求指定消息（等待返回、需在消息体添加消息序号并修改对应编解码）
this._ws2.message.request(test.test_c.create())?.then((value) => {
	this._log.log("收到请求消息", value);
});

// 监听指定消息
this._ws2.message.on(test.test_c, (value) => {
	this.data.chat2_ss.push("网络 2 收到：" + value.data);
});

答案

通过消息体获得消息号，就是这么简单，在创建 socket 的时候，可以传递这两个函数，一个用于获取消息 ID，一个用于获取消息序列号

怎么把消息号包含在消息体内？个人推荐的是使用 proto 的 默认值，

package test;
syntax = "proto3";

message test_c {
    int32 __id = 1 [default=100];
    string data = 2;
}

这个在我之前的文章讲过，我也开发了一个编译 protobuf 的插件，也支持生成默认值，有需要的可以自行购买

https://store.cocos.com/app/detail/5243open in new window

2. 模拟事件结构的网络消息

框架将网络消息事件封装为了一个事件对象，并增加 send 和 request 接口，让用户更熟悉

  • send：发送消息到服务器
  • emit：模拟服务器消息
  • request：发送消息到服务器并等待返回

3. 消息潮

如果你需要将多个消息同时发送，或者手动触发时发送，那么可以使用消息潮。

const message_tide = new mk.network.base_.send_tide(this._ws, -1);

message_tide.send("123");
message_tide.send("456");
message_tide.send("789");

message_tide.trigger();

根据定时器或者手动调用 trigger 才会进行发送操作

源码：mk_network_baseopen in new window

资源

点击展开

支持网络资源、本地资源、编辑器资源的加载和管理。bundle 和场景的加载/预加载/重载

1. 解决资源释放管理

怎么完全解决资源释放？那就是增加一个资源跟随释放对象，这是获取资源的接口

/**
	 * 获取资源
	 * @param path_s_ 资源路径
	 * @param type_ 资源类型
	 * @param target_ 跟随释放对象
	 * @param config_ 获取配置
	 * @returns
	 */
	get<T extends cc.Asset>(
		path_s_: string,
		type_: cc.Constructor<T>,
		target_: mk_asset_.follow_release_object | null,
		config_?: mk_asset_.get_config<T>
	): Promise<T | null> { ... }

target_ 即为跟随释放对象，类型为

/** 跟随释放类型 */
export type follow_release_object<CT = release_param_type> = {
	/**
	 * 跟随释放
	 * @param object_ 释放对象/释放对象数组
	 */
	follow_release<T extends CT>(object_: T): T;

	/**
	 * 取消释放
	 * @param object_ 取消释放对象/取消释放对象数组
	 */
	cancel_release<T extends CT>(object_: T): T;
};

即在资源加载完成后调用 follow_release，让对象自行管理释放时机，而MK框架的生命周期系统是在 late_close 中进行释放

2. 解决资源系统的 Bug

同时加载同一资源，返回的资源对象不一致

如果对首个返回的资源引用计数进行 + 1，那么后面返回的资源对象引用计数还是 0，为了解决这个问题。可以设置资源缓存表，在资源加载完成后再返回表内的资源，如果表内没有资源则存储到表内再返回

释放资源后立即加载会出现返回的资源已经无效

这个问题在框架内设置了一个资源释放缓冲时间，可以避免这个问题，但是仍然不能完全避免，因为没有资源释放完成的通知，需要引擎开发人员解决

3. 针对接口的优化

你可以怎么加载资源？看下面

mk.asset.get("db://assets/xxx.png", cc.SpriteFrame, this);
mk.asset.get("db://assets/xxx", cc.SpriteFrame, this);
mk.asset.get("xxx.png", cc.SpriteFrame, this);
mk.asset.get("xxx", cc.SpriteFrame, this);

支持 db 路径，后缀名，省略无意义的 /spriteFrame, /texture

4. Bundle 热更

MK框架抛弃了传统的版本文件对比热更。而是内置了 Bundle 热更方式，让你可以直接实现大厅子游戏，而免去学习使用版本文件热更。可控性更强且自由定制！

// 重载(热更) bundle 示例
await mk.bundle.reload({
	bundle_s: global_config.asset.bundle.config,
	origin_s: this.data.remote_url_s + "/" + global_config.asset.bundle.config,
	version_s: this.data.bundle_version_s,
});

只需要调用一个函数，即可实现热更 Bundle！

5. Bundle 管理器

Bundle 管理器是专门为子游戏设计的，用以初始化子游戏，存放公共数据，事件，存储的对象

Bundle 管理器的生命周期有 init, open, close

  • init：从其他 bundle 的场景切换到此 bundle 的场景之前调用
  • open：从其他 bundle 的场景切换到此 bundle 的场景时调用
  • close：从此 bundle 的场景切换到其他 bundle 的场景时调用

源码：mk_assetopen in new window
源码：mk_bundleopen in new window

多语言

点击展开

多语言文本、多语言图片、多语言节点

1. 避免垃圾的堆积

在使用多语言资源的时候，一般会把资源放在一块，以 Bundle 为单位或整包为单位，但是MK框架不一样，它可以模块为单位，也可以 Bundle 为单位！这意味着很少存在多语言垃圾堆积

多语言类型即为你注册的单位，而语言标识即为多语言键

2. 多语言节点

在开发过程中，存在一些多语言文本和图片不能解决的多语言展示问题，比如结构不一致的布局。节点位置、大小等等。这时候就可以使用多语言节点组件，将其挂载到父节点会自动根据当前语言显示或隐藏对应节点

源码：languageopen in new window

新手引导

点击展开

支持多实例，任意步骤的(插入/删除)，(暂停/完成)引导，支持任意步骤跳转后的状态还原(操作单元)，引导步骤脚本分离，支持组件式挂载。它可以完成你的任何需求

1. 引导步骤脚本

框架将每个引导步骤都分为单独的脚本，继承于 mk.guide_step_base，而 mk.guide_step_base 继承于 cc.Component，这意味着你可以把它挂载到节点上

注册引导步骤

guide_manage.regis([new resources_guide_step1()]);

regis 是可以调用多次的，所以你也可以从节点上面 getComponent 然后 regis

引导步骤脚本内容

@ccclass
class resources_guide_step1 extends resources_guide_step_base {
	step_n = 1;
	next_step_ns = [2];
	scene_s = "main.main";
	operate_ss = [resources_guide_operate.key.隐藏所有按钮, resources_guide_operate.key.按钮1];
	/* ------------------------------- 生命周期 ------------------------------- */
	load(): void | Promise<void> {
		const button = this.operate_tab[resources_guide_operate.key.按钮1];

		button?.once(cc.Button.EventType.CLICK, async () => {
			this._next();
		});
	}
}

export default resources_guide_step1;
  • step_n：步骤标识
  • next_step_ns：下个步骤数组（包含可能跳转的步骤用于预加载）
  • scene_s：bundle名.场景名，用于自动跳转场景
  • operate_ss：引导单元列表

2. 使用引导单元实现任意步骤的跳转

引导操作单元是什么？它可以是一个加载 UI 的操作，也可以是一次更新视图的操作，我们每个引导步骤都有一个自己的操作列表，在切换步骤时执行步骤生命周期前初始化

操作单元接口

class guide_operate {
	// 重置：操作单元同时存在于上下两个步骤时执行
	reset?: ()=> void;

	// 加载：操作单元不存在于上个步骤时执行
	load: ()=> void;

	// 卸载：操作单元不存在于下个步骤时执行
	unload?: ()=> void;
}

我们可以把所有操作单元放在一个对象中，方便使用，例如

const operate_tab = {
	说明弹窗: new guide_operate({
		load: ()=> {...}
	}),
	手指动画: new guide_operate({
		load: ()=> {...}
	}),
	...
};

使用引导单元时，可以把清理操作或者多次会用到的操作添加到里面（operate_ss ），在步骤切换时会自动加载

3. 避免误触

在引导步骤切换时，为了防止误触可能需要添加场景节点遮罩，而你可以监听引导系统的事件完成它！

/** 事件协议 */
export interface event_protocol {
	/** 暂停 */
	pause(): void;
	/** 恢复 */
	resume(): void;
	/**
	 * 切换步骤前
	 * @param next_step_n 下个步骤
	 * @remarks
	 * set_step 时执行
	 */
	before_switch(next_step_n: number): void;
	/**
	 * 加载步骤
	 * @remarks
	 * 加载步骤(场景/操作)前调用
	 */
	loading_step(): void;
	/**
	 * 卸载步骤后
	 * @param step 卸载的步骤
	 */
	after_unload_step(step: mk_guide_step_base): void;
	/**
	 * 加载步骤完成
	 * @remarks
	 * 步骤 load 执行后调用
	 */
	loading_step_complete(): void;
	/** 中断 */
	break(): void;
	/** 完成 */
	finish(): void;
}

你可以在 before_switch 打开遮罩、在 loading_step_complete 和 break 关闭遮罩

4. 引导步骤的插入/删除

只需要修改引导步骤脚本的 step_n 和 next_step_ns 即可

5. 更新引导数据

在引导步骤完成后或者请求引导步骤奖励，应该怎么做？

const guide_manage = new mk.guide_manage({
		operate_tab: operate.tab,
		end_step_n: 4,
		step_update_callback_f: () => true,
	});

你只需自定义 step_update_callback_f 函数即可

/**
* 步骤更新回调
 * @param step_n
 * @returns null/undefined：更新失败，中断引导
 * @remarks
 * - 默认返回 true
 *
 * - 可在此内更新服务端数据并请求奖励
 *
 * - 步骤可使用 this.step_update_data 获取返回数据
 */
step_update_callback_f?(step_n: number): any;

6. 多边形遮罩、触摸屏蔽

使用 mk_polygon_mask 组件，支持多边形遮罩，节点跟踪、触摸屏蔽

源码：guideopen in new window

事件

点击展开

类型安全且兼容 cc.EventTarget 的事件系统

1. 类型安全

使用

interface main_event_protocol {
	test(a: number): void;
}

const event = new mk.event_target<main_event_protocol>();

提示

emit

on

2. 增强接口：request（请求）

有时候需要等待事件返回值，那么就可以使用 request，同样也支持类型安全

源码：mk_event_targetopen in new window

存储

点击展开

1. 类型安全

不需要有各种类型的 getXXX / setXXX，只需要一个 get 和 set 函数，即可实现类型安全

get

set

2. 怎么保证默认值存储

构造函数必须填写默认值，避免 get 获取到空数据

源码：mk_storageopen in new window

数据

点击展开

一般模块间共享的数据放在第三方脚本，但是异步数据怎么办呢？可以使用 mk.data_sharer 创建一个共享数据

同步数据

get

data.xxx;

set

data.xxx = ...;

异步数据

get

await data.request(data.key.xxx)

set

data.xxx = ...;

源码：mk_data_shareropen in new window

MVVM

点击展开

使用 mvvm 也非常简单，MK框架提供了一个最基础的工具，mk.monitor，用于对数据的监听

const data = {
	a: 0,
	b: "test",
};

mk.monitor.on(data, "a", (new_value, old_value) => {
	console.log(new_value, old_value);
});

有了数据监听，你可以把它封装为任何使用方式，比如框架示例项目中的 tool_monitor_trigger 组件，就是一个封装的例子

下面是一个简单的 tool_monitor_trigger 事件定义，根据数据来显示或者隐藏节点。只需要导出一个 namespace 即可增加一个方法，目前最为灵活的 mvvm 实现方式，没有之一。

export namespace 显示隐藏 {
	@ccclass("data_method_boolean/显示隐藏")
	export class ccclass_params extends tool_monitor_trigger_event {
		@property({ displayName: "反向" })
		reverse_b = false;
	}

	export function on<T, T2 extends keyof T>(target_: T, key_: T2, node_: cc.Node, params_: ccclass_params): void {
		mk.monitor
			.on(
				target_,
				key_,
				(value) => {
					node_.active = params_?.reverse_b ? !value : Boolean(value);
				},
				target_
			)
			?.call(target_, target_[key_]);
	}
}

你也可以将 mk.monitor 的使用封装为装饰器，全看你的喜好

源码：mk_monitoropen in new window

# 框架的结构

框架包含了两个 Bundle

  • @config：全局配置
  • @framework：框架代码

为什么框架不打包为一个 js 和 d.ts？或者使用 npm 包的方式进行安装？因为 MK框架推荐你进行自定义，而且自定义框架提供了构建 d.ts 的工具，即改即用，灵活强大

# 框架的安装与使用

依赖环境

  • Nodejs

安装步骤

  1. 终端执行 npm i -g @muzzik/mk-install ，等待安装完成
  1. 终端执行 npx mk-install ，输入你的 CocosCreator 项目路径
  2. 关闭编辑器，输入 install 后回车，等待安装完成

注意：如果安装位置存在文件，原始文件将被保存到 项目路径/temp/mk-install-backup 下

使用

在脚本中使用输入 mk 即可出现类型提示

这是因为框架使用了导入映射open in new window，所以需要使用 mk 导入，为什么一定要导入？因为框架内的 d.ts 为了类型安全导入了脚本 global_config，否则是可以做成全局变量的。

# 框架文档的搭建

为什么选择 Vuepress？因为快速且有丰富的模板

网站

搭建工具：Vuepress
地址：https://muzzik.gitee.io/mk-framework/quick-start/open in new window

API

搭建工具：Vuepress、typedoc、Github Actions
typedoc 路径：示例项目/tool/typedoc。
github actions 路径：.github\workflows\deploy-docs.yml

在每次提交代码到 main 分支后，github actions 会自动构建文档上传到 gitee pages，自动更新文档。但是目前还没有搭建多版本文档

# 代码交流

QQ群：200351945open in new window

有任何问题欢迎批评，只有批评才能让产品进步

📣 觉得很赞？分享给你的朋友吧！