原来是全局碰撞惹的祸

2024-07-31 10:48:42 +08:00
parent df8b52264e
commit 9aa9806b62
38 changed files with 1640 additions and 313 deletions
--- a/doc/core/common/audio.md
+++ b/doc/core/common/audio.md
@@ -0,0 +1,84 @@
+
+### 功能说明
+Oops Framework－音频管理模块主要处理游戏背景音乐、游戏音效两大类功能。
+
+### [演示程序](https://gitee.com/dgflash/oops-framework/tree/master/assets/demo/audio)
+
+### 使用说明
+##### 播放背景音乐
+```
+oops.audio.playMusic("audios/nocturne");
+```
+注：调用此方法后，后台会异步下载音乐资源，完成后开始播放音乐
+
+##### 背景音乐播放完成回调设置
+```
+oops.audio.setMusicComplete(() => {
+    console.log("音乐播放完成");
+});
+```
+   
+##### 获取或设置背景音乐音量
+```
+oops.audio.musicVolume = 0.5;
+```
+注：音量范围 (0 ~ 1)
+
+##### 背景音乐开关
+```
+oops.audio.switchMusic = false;
+```
+
+##### 获取或设置音乐播放进度
+```
+oops.audio.progressMusic = 0.5;
+```
+注：音量进度 (0 ~ 1)
+
+##### 播放音效
+```
+oops.audio.playEffect("audios/Gravel");
+```
+注：调用此方法后，后台会异步下载音乐资源，完成后开始播放音乐
+   
+##### 获取或设置音效音量
+```
+oops.audio.volumeEffect = 0.5;
+```
+注：音量范围 (0 ~ 1)
+
+##### 音效音乐开关
+```
+oops.audio.switchEffect = false;
+```
+
+##### 恢复暂停的所有音乐播放
+```
+oops.audio.resumeAll();
+```
+
+##### 暂停当前音乐与音效的播放
+```
+oops.audio.pauseAll();
+```
+
+##### 停止当前音乐与音效的播放
+```
+oops.audio.stopAll();
+```
+
+##### 停止当前音乐与音效的播放
+```
+oops.audio.stopAll();
+```
+
+##### 保存音乐音效的音量、开关配置数据到本地
+```
+oops.audio.save();
+```
+
+##### 本地加载音乐音效的音量、开关配置数据并设置到游戏中
+```
+oops.audio.load();
+```
+
--- a/doc/core/common/event.md
+++ b/doc/core/common/event.md
@@ -0,0 +1,44 @@
+### 功能说明
+Oops Framework－全局事件管理主要在设计上降低对象之间的耦合问题，避免相互调用API导致对象强依赖，从而在项目中后期需求变更或扩展时，增加维护成本。
+
+### 使用说明
+##### 注册持续监听的全局事件
+```
+export class RoleViewComp extends Component{
+    onLoad(){
+        // 监听全局事件
+        oops.message.on(GameEvent.GameServerConnected, this.onHandler, this);
+    }
+    
+    protected onDestroy() {
+        // 对象释放时取消注册的全局事件
+        oops.message.off(GameEvent.GameServerConnected, this.onHandler, this);
+    }
+    
+    private onHandler(event: string, args: any) {
+        switch (event) {
+            case GameEvent.GameServerConnected:
+                console.log("处理游戏服务器连接成功后的逻辑");
+                break;
+        }
+    }
+}
+```
+
+##### 注册只触发一次的全局事件
+```
+export class RoleViewComp extends Component{
+    onLoad(){
+        // 监听一次事件，事件响应后，该监听自动移除
+        oops.message.once(GameEvent.GameServerConnected, this.onHandler, this);
+    }
+    
+    private onHandler(event: string, args: any) {
+        switch (event) {
+            case GameEvent.GameServerConnected:
+                console.log("处理游戏服务器连接成功后的逻辑");
+                break;
+        }
+    }
+}
+```
--- a/doc/core/common/loader.md
+++ b/doc/core/common/loader.md
@@ -0,0 +1,91 @@
+### 功能说明
+Oops Framework－资源管理模块主要处理游戏各种类型的资源的加载与释放功能。
+
+### 使用说明
+##### 加载远程资源
+```
+var opt: IRemoteOptions = { ext: ".png" };
+var onComplete = (err: Error | null, data: ImageAsset) => {
+    const texture = new Texture2D();
+    texture.image = data;
+    
+    const spriteFrame = new SpriteFrame();
+    spriteFrame.texture = texture;
+    
+    var sprite = this.sprite.addComponent(Sprite);
+    sprite.spriteFrame = spriteFrame;
+}
+resLoader.loadRemote<ImageAsset>(this.url, opt, onComplete);
+```
+
+##### 加载资源包配置信息
+```
+var serverUrl = "http://192.168.1.13:8082/";        // 服务器地址
+var md5 = "8e5c0";                                  // Cocos Creator 构建后的MD5字符
+await resLoader.loadBundle(serverUrl,md5);
+```
+
+##### 加载单个资源
+```
+var path = "model";
+resLoader.load(path, sp.SkeletonData, (err: Error | null, sd: sp.SkeletonData) => {
+    if (err) {
+        console.error(`资源不存在`);
+        return;
+    }
+
+    this.spine.skeletonData = sd;
+});
+```
+
+加载其它bundle中资源
+```
+var path = "model";
+resLoader.load("bundleName", path, sp.SkeletonData, (err: Error | null, sd: sp.SkeletonData) => {
+    if (err) {
+        console.error(`资源不存在`);
+        return;
+    }
+
+    this.spine.skeletonData = sd;
+});
+```
+
+##### 加载一个文件夹中的资源
+```
+/** 加载进度事件 */
+var onProgressCallback = (finished: number, total: number, item: any) => {
+    console.log("资源加载进度", finished, total);
+}
+
+/** 加载完成事件 */
+var onCompleteCallback = () => {
+    console.log("资源加载完成");
+}
+resLoader.loadDir("game", onProgressCallback, onCompleteCallback);
+```
+
+##### 释放一个资源
+```
+resLoader.release("model", "resources");
+```
+注：第二个参数"resources"为默认值，为引擎默认bundle。如果需要释放其它bundle里的资源修改此参数即可
+
+##### 释放一个文件夹的资源
+```
+resLoader.releaseDir("model", "resources");
+```
+注：第二个参数"resources"为默认值，为引擎默认bundle。如果需要释放其它bundle里的资源修改此参数即可
+
+##### 获取缓存中资源
+```
+resLoader.get("common/anim/button_scale_start", AnimationClip, "resources")
+```
+注：第三个参数"resources"为默认值，为引擎默认bundle。如果需要获取其它bundle里的资源修改此参数即可
+
+
+##### 打印缓存中所有资源信息
+```
+resLoader.dump();   
+```
+注：用于调试时观察是资源是否正确释放
--- a/doc/core/common/log.md
+++ b/doc/core/common/log.md
@@ -0,0 +1,30 @@
+### 功能说明
+Oops Framework－日志管理主要封装console对象日志输出功能，方便在复杂的业务逻辑中，提供更很清晰的信息排查问题。
+
+### 使用说明
+##### 打印代码段的执行时间
+```
+oops.log.start();
+...
+省略N行代码
+...
+oops.log.end();
+```
+
+##### 打印表格
+```
+var object:any = {uid:1000, name:"oops"};
+oops.log.table(object);
+```
+
+##### 打印日志
+```
+oops.log.trace("默认标准日志");
+oops.log.logConfig("灰色配置日志");
+oops.log.logNet("橙色网络日志");
+oops.log.logModel("紫色数据日志");
+oops.log.logBusiness("蓝色业务日志");
+oops.log.logView("绿色视图日志");
+
+// 日志格式：[11:31:07:293][标准日志][Generator.ts->next]:'默认标准日志'
+```
--- a/doc/core/common/random.md
+++ b/doc/core/common/random.md
@@ -0,0 +1,44 @@
+### 功能说明
+Oops Framework－随机数生成管理模块，封装了[seedrandom](https://www.npmjs.com/package/seedrandom) 第三方随机数据库
+
+### 使用说明
+##### 设置随机种子
+```
+// 随机种子可由服务端派发给其它客户端，同样的种子，多端随机同样次数时，结果是相同的
+RandomManager.instance.setSeed(123456789);
+```
+
+##### 生成指定范围的随机整数
+```
+var min = 1;
+var max = 10;
+// [min,max) 得到一个两数之间的随机整数,这个值不小于min（如果min不是整数的话，得到一个向上取整的 min），并且小于（但不等于）max  
+RandomManager.instance.getRandomInt(min, max, 1);
+
+// [min,max] 得到一个两数之间的随机整数，包括两个数在内,这个值比min大（如果min不是整数，那就不小于比min大的整数），但小于（但不等于）max
+RandomManager.instance.getRandomInt(min, max, 2);
+
+// (min,max) 得到一个两数之间的随机整数
+RandomManager.instance.getRandomInt(min, max, 3);
+```
+
+##### 根据最大值，最小值范围生成随机数数组
+```
+var min = 1;
+var max = 10;
+var n = 10;
+// 生成10个1~10之间的随机数数组
+RandomManager.instance.getRandomByMinMaxList(min, max, n);
+```
+
+##### 获取数组中随机对象
+```
+var objs = [1,2,3,4,5,6,7,8,9]
+RandomManager.instance.getRandomByObjectList(objs, 3);
+```
+
+##### 定和随机分配
+```
+// 随机5个整数，5个数的和为100
+RandomManager.instance.getRandomBySumList(5,100);
+```
--- a/doc/core/common/storage.md
+++ b/doc/core/common/storage.md
@@ -0,0 +1,38 @@
+### 功能说明
+Oops Framework－本地存储模块主要封装了Cocos Crator引擎里sys.localStorage对象的跨平台平地存储功能，同时在此基础上添加了数据加密与不同帐号区分的功能。
+
+### 使用说明
+##### 初始化本地存储加密
+```
+oops.storage.init("key", "vi");
+```
+注：调试模式下不会触发数据加密，方便明文调试。发布模式自动启动数据加密
+
+##### 初始化本地存储加密
+```
+var uid = 10000;                // 用户唯一编号数据
+oops.storage.setUser(uid);
+```
+注：用于区分不同账号本地存储数据，避免同名key的数据被其它账号登录时覆盖
+
+##### 设置指定关键字的数据
+```
+oops.storage.set(key, value);
+```
+
+##### 获取指定关键字的数据
+```
+var data = oops.storage.get(key);
+```
+
+##### 删除指定关键字的数据
+```
+oops.storage.remove(key);
+```
+
+##### 清空整个本地存储
+```
+oops.storage.clear();
+```
+
+
--- a/doc/core/common/timer.md
+++ b/doc/core/common/timer.md
@@ -0,0 +1,92 @@
+### 功能说明
+Oops Framework－时间管理模块主要实现在游戏中不同类型的定时器功能。
+
+### 使用说明
+##### 获取游戏开始到现在逝去的时间
+```
+oops.timer.getTime();
+```
+
+##### 获取本地时间刻度
+```
+oops.timer.getLocalTime();
+```
+
+##### 注册一个固定间隔时间的触发器
+```
+oops.timer.schedule(()=>{
+    // 每秒触发一次
+}, 1000);
+```
+
+##### 注册一个只触发一次的延时的触发器
+```
+oops.timer.scheduleOnce(()=>{
+    // 1秒后触发一次后不会在触发
+}, 1000);
+```
+
+##### 删除一个时间触发器
+```
+var uuid = oops.timer.schedule(()=>{
+    // 每秒触发一次
+}, 1000);
+
+// 删除指定标识的触发器
+oops.timer.unschedule(uuid);
+```
+
+##### 删除所有时间触发器
+```
+oops.timer.unscheduleAll();
+```
+
+##### 在指定对象上注册一个倒计时的回调管理器
+```
+export class Test extends Component {
+    private timeId!: string;
+    
+    start() {
+        // 在指定对象上注册一个倒计时的回调管理器
+        this.timeId = oops.timer.register(this, "countDown", this.onSecond, this.onComplete);
+    }
+    
+    private onSecond() {
+        console.log("每秒触发一次");
+    }
+
+    private onComplete() {
+        console.log("倒计时完成触发");
+    }
+}
+```
+
+##### 在指定对象上注销一个倒计时的回调管理器
+```
+export class Test extends Component {
+    private timeId!: string;
+    
+    start() {
+        this.timeId = oops.timer.register(this, "countDown", this.onSecond, this.onComplete);
+    }
+    
+    onDestroy() {
+        // 在指定对象上注销一个倒计时的回调管理器
+        oops.timer.unRegister(this.timeId);
+    }
+}
+```
+
+##### 定时跳动组件
+```
+export class Test extends Component {
+    // 创建一个定时跳动组件
+    private timer: Timer = new Timer(1);
+
+    update(dt: number) {
+        if (this.timer.update(this.dt)) {
+            console.log(每一秒触发一次);
+        }
+    }
+}
+```
--- a/doc/core/gui/gui.md
+++ b/doc/core/gui/gui.md
@@ -0,0 +1,77 @@
+### 功能说明
+Oops Framework－界面管理模块，主要实现游戏中不同类型的窗口管理，例如常住主界面窗口、弹出窗口、模式窗口，系统提示窗口等。
+
+### 使用说明
+##### 窗口配置字段
+| 字段   | 介绍     |
+| ------ | -------- |
+| layer  | 窗口层级 |
+| prefab | 预制资源相对路径 |
+| bundle | 远程包名 |
+
+##### 窗口配置数据
+```
+/** 界面唯一标识 */
+export enum UIID {
+    /** 资源加载界面 */
+    Loading = 1,
+    /** 弹窗界面 */
+    Window,
+    /** 加载与延时提示界面 */
+    Netinstable
+}
+
+/** 打开界面方式的配置数据 */
+export var UIConfigData: { [key: number]: UIConfig } = {
+    [UIID.Loading]: { layer: LayerType.UI, prefab: "loading/prefab/loading", bundle: "resources" },
+    [UIID.Netinstable]: { layer: LayerType.PopUp, prefab: "common/prefab/netinstable" },
+    [UIID.Window]: { layer: LayerType.Dialog, prefab: "common/prefab/window" }
+}
+```
+
+##### 打开一个窗口
+```
+var uic: UICallbacks = {
+    // 窗口添加到界面完成事件
+    onAdded: (node: Node, params: any) => {
+        var comp = node.getComponent(LoadingViewComp) as ecs.Comp;
+    }
+    
+    // 窗口节点 destroy 之后回调
+    onRemoved:(node: Node | null, params: any) => {
+        
+    }
+};
+oops.gui.open(UIID.Loading, null, uic);
+```
+
+##### 异步函数打开一个窗口
+```
+var node = await oops.gui.openAsync(UIID.Loading);
+```
+
+##### 关闭一个窗口
+```
+oops.gui.remove(UIID.Loading);
+```
+
+##### 指定一个节点来删除窗口
+```
+oops.gui.removeByNode(cc.Node);
+```
+注：这里的Node必须是通过oops.gui.open或openAsync打开的才会执行关闭
+
+##### 缓存中是否存在指定标识的窗口
+```
+oops.gui.has(UIID.Loading);
+```
+
+##### 渐隐飘过提示
+```
+oops.gui.toast("提示内容");
+```
+
+##### 清除所有窗口
+```
+oops.gui.clear();
+```
--- a/doc/core/network.md
+++ b/doc/core/network.md
@@ -0,0 +1,109 @@
+### 功能说明
+Oops Framework－网络模块WebSocket处理客户端与服务之间保持长链接通讯。
+
+### 使用说明
+##### 自定义网络通讯数据协议（GZip压缩）
+```
+class GameProtocol extends NetProtocolPako { 
+    /** 心跳协议 */
+    getHearbeat(): NetData {
+        return `{"action":"LoginAction","method":"heart","data":"null","isCompress":false,"channelid":1,"callback":"LoginAction_heart"}`;
+    }
+}
+```
+
+##### 创建一个WebSocket网络连接对象
+```
+var net = new NetNodeGame();
+var ws = new WebSock();        // WebSocket 网络连接对象
+var gp = new GameProtocol();   // 网络通讯协议对象
+var gt = new NetGameTips()     // 网络提示对象
+net.init(ws, gp, gt);
+NetManager.getInstance().setNetNode(net, NetChannelType.Game);
+```
+
+##### 连接游戏服务器
+```
+var options = {
+    url: `ws://127.0.0.1:3000`,
+    autoReconnect: 0            // -1 永久重连，0不自动重连，其他正整数为自动重试次数
+}
+NetManager.getInstance().connect(options, NetChannelType.Game);
+```
+
+##### 断开游戏服务器连接
+```
+NetManager.getInstance().close(undefined, undefined, NetChannelType.Game);
+    
+```
+
+##### 游戏服务器提示
+```
+export class NetGameTips implements INetworkTips {
+    /** 连接提示 */
+    connectTips(isShow: boolean): void {
+        if (isShow) {
+            Logger.logNet("游戏服务器正在连接");
+            tips.netInstableOpen();
+        }
+        else {
+            Logger.logNet("游戏服务器连接成功");
+            tips.netInstableClose();
+            Message.dispatchEvent(GameEvent.GameServerConnected);
+        }
+    }
+
+    /** 重连接提示 */
+    reconnectTips(isShow: boolean): void { 
+        if (isShow) {
+            Logger.logNet("重连开始");
+        }
+        else {
+            Logger.logNet("重连成功");
+        }
+    }
+
+    /** 请求提示 */
+    requestTips(isShow: boolean): void {
+        if (isShow) {
+            Logger.logNet("请求数据开始");
+        }
+        else {
+            Logger.logNet("请求数据完成");
+        }
+    }
+
+    /** 响应错误码提示 */
+    responseErrorCode(code: number): void {
+        console.log("游戏服务器错误码", code);
+    }
+}
+```
+
+##### 请求服务器数据
+```
+var params: any = {
+    playerId: 10000
+}
+
+let onComplete = {
+    target: this,
+    callback: (data: any) => {
+        // 服务器返回数据
+        console.log(data);
+    }
+}
+// net为NetNodeGame对象
+net.req("LoginAction", "loadPlayer", params, onComplete);
+```
+
+##### 监听服务器推送数据
+```
+var onComplete = (data: any) => {
+    // 服务器返回数据
+    console.log(data);
+}
+
+// net为NetNodeGame对象
+net.setResponeHandler("notify", onComplete, this);
+```