zhanghongbo/MeowmentDebugTool

Fork 0

zhang hongbo 62f990f702 0.3更新，新增控制台

2025-12-22 15:29:55 +08:00

13 KiB

Raw Blame History

MeowMent Debug Tool（喵刻调试工具）

一个强大的 Unity 运行时调试工具，提供多标签页调试面板、控制台日志、可拖拽悬浮按钮、系统信息查看以及自定义调试按钮等功能。

版本： 0.3.0
适用平台： 全平台（Windows、Android、iOS等）
Unity版本： 2021.3 及以上

📋 目录

功能特性
给策划使用 - 基础功能
给客户端使用 - 初始化配置
给后端使用 - 添加自定义按钮
常见问题

🎯 功能特性

核心功能模块

参数查看：实时查看设备信息、系统信息，支持一键复制
自定义按钮：通过特性自动生成调试按钮，无需手动添加
工具栏：时间调整工具、截图隐藏功能
控制台：实时捕获Unity日志，支持过滤、搜索、查看堆栈
设置：运行时修改分辨率

UI特性

可拖拽悬浮按钮，自动吸附边缘
多标签页设计，清晰分类
Canvas层级30000，始终在最上层
支持自定义TextMeshPro字体

👥 给策划使用 - 基础功能

1. 如何打开调试工具

游戏运行后，屏幕左侧会显示一个蓝色圆形浮窗按钮：

点击浮窗 → 打开调试主窗口
拖动浮窗 → 改变位置（会自动吸附到屏幕边缘）
点击左上角X → 关闭主窗口，回到浮窗状态

2. 功能页面说明

调试窗口包含5个标签页：

📊 参数查看

设备信息：设备型号、系统版本、处理器、内存等
系统信息：Unity版本、图形API、显卡信息等
复制按钮：点击可复制信息到剪贴板，方便粘贴到bug报告

🎮 自定义按钮

显示后端程序员添加的调试功能按钮
点击按钮即可执行对应功能（如清理存档、添加道具等）
不同按钮有不同颜色，方便区分

常见按钮示例：

"清空玩家数据" - 重置游戏进度
"添加金币" - 增加游戏货币
"解锁所有关卡" - 开启所有内容
"重置今日任务" - 刷新每日任务

🛠️ 工具栏

时间调整：模拟时间流逝（用于测试时间相关功能）
暂时隐藏(5秒)：截图前点击此按钮，调试工具会隐藏5秒，方便截取干净的游戏画面

使用场景：

需要截图游戏画面时
点击"暂时隐藏(5秒)"
调试工具消失，快速截图
5秒后自动恢复，继续调试

📝 控制台

实时显示游戏日志，帮助定位问题：

Info（白色）：普通信息日志
Warning（黄色）：警告信息
Error（红色）：错误信息
Fatal（深红）：严重错误/异常

功能按钮：

清空：清除所有日志
锁定滚动：勾选后自动滚动到最新日志
过滤器：点击Info/Warning/Error切换显示对应类型日志

查看详情：

点击任意日志条目 → 下方显示完整堆栈信息
方便向程序员反馈详细错误

⚙️ 设置

分辨率调整：修改游戏窗口大小（仅编辑器/Windows有效）
当前分辨率显示：显示当前屏幕分辨率

3. 日常测试工作流

测试新功能：

打开调试工具
切换到"自定义按钮"页面
点击相关测试按钮（如"开启活动"）
观察游戏效果
如有问题，切换到"控制台"查看错误

截图报bug：

复现问题
点击"工具栏" → "暂时隐藏(5秒)"
截取游戏画面
切换回"控制台"截取错误日志
一起提交给程序

收集设备信息：

切换到"参数查看"
点击"复制设备信息"或"复制系统信息"
粘贴到bug报告中

💻 给客户端使用 - 初始化配置

1. 基础初始化

在游戏启动时（通常在启动场景的初始化脚本中）调用：

using UnityEngine;
using MeowmentDebugTool;
using TMPro;

public class GameInitializer : MonoBehaviour
{
    [SerializeField] private TMP_FontAsset customFont; // 拖入自定义字体
    
    void Start()
    {
        // 初始化调试工具
        UniversalDebugTool.Init();
        
        // 设置自定义字体（可选）
        if (customFont != null)
        {
            UniversalDebugTool.SetSDFFont(customFont);
        }
    }
}

2. API说明

`UniversalDebugTool.Init()`

初始化调试工具，自动创建：

Canvas（排序顺序30000）
主调试窗口
悬浮按钮
EventSystem（如果没有）

注意：

只需调用一次
工具会自动DontDestroyOnLoad，场景切换不销毁
未调用Init()前不显示任何UI

`UniversalDebugTool.SetSDFFont(TMP_FontAsset fontAsset)`

设置所有UI文本的字体：

包括已创建的UI和后续创建的按钮
支持中文、特殊字符
建议使用支持中文的SDF字体

字体推荐：

思源黑体 SDF
阿里巴巴普惠体 SDF
或项目现有的中文字体

3. 条件编译（推荐）

为了确保打包时不包含调试代码：

void Start()
{
    #if MEOWMENT_DEBUG_TOOL
    UniversalDebugTool.Init();
    UniversalDebugTool.SetSDFFont(customFont);
    #endif
}

说明：

MEOWMENT_DEBUG_TOOL 宏在包安装时自动定义
移除包时自动移除，不影响项目编译
正式包不会包含调试工具代码

4. 完整示例

using UnityEngine;
using MeowmentDebugTool;
using TMPro;

public class Test : MonoBehaviour
{
    public TMP_FontAsset fontAsset;
    
    void Start()
    {
        #if MEOWMENT_DEBUG_TOOL
        // 初始化调试工具
        UniversalDebugTool.Init();
        
        // 设置字体
        if (fontAsset != null)
        {
            UniversalDebugTool.SetSDFFont(fontAsset);
        }
        #endif
    }
}

🔧 给后端使用 - 添加自定义按钮

1. 基础用法

使用 [DebugButton] 特性标记静态方法，调试工具会自动生成按钮：

using UnityEngine;

public static class PlayerDebugFunctions
{
    [DebugButton("清空玩家数据")]
    private static void ClearPlayerData()
    {
        PlayerPrefs.DeleteAll();
        Debug.Log("玩家数据已清空");
    }
    
    [DebugButton("添加1000金币")]
    private static void AddCoins()
    {
        PlayerData.Coins += 1000;
        Debug.Log($"当前金币：{PlayerData.Coins}");
    }
}

运行效果：

在"自定义按钮"页面会出现两个按钮
点击按钮执行对应方法

2. 特性参数详解

[DebugButton(string displayName = "", float r = 0.8f, float g = 0.8f, float b = 0.8f)]

参数说明：

displayName：按钮显示文字（不填则使用方法名）
r, g, b：按钮背景颜色（RGB值，范围0-1）

示例：不同颜色按钮

public static class GameDebugFunctions
{
    // 绿色按钮 - 安全操作
    [DebugButton("保存游戏", 0.2f, 0.6f, 0.2f)]
    private static void SaveGame()
    {
        GameManager.Save();
    }
    
    // 红色按钮 - 危险操作
    [DebugButton("删除存档", 0.9f, 0.2f, 0.2f)]
    private static void DeleteSave()
    {
        GameManager.DeleteSave();
    }
    
    // 蓝色按钮 - 功能测试
    [DebugButton("跳到第10关", 0.2f, 0.5f, 0.9f)]
    private static void JumpToLevel10()
    {
        LevelManager.LoadLevel(10);
    }
    
    // 默认颜色（灰色）
    [DebugButton("打印游戏状态")]
    private static void PrintGameState()
    {
        Debug.Log($"Level: {GameManager.CurrentLevel}");
    }
}

3. 使用输入对话框

需要用户输入参数时，使用 ShowInputDialog：

using TMPro;

public static class AdvancedDebugFunctions
{
    [DebugButton("设置玩家等级")]
    private static void SetPlayerLevel()
    {
        UniversalDebugTool.ShowInputDialog(
            "输入等级",
            onConfirmAction: text =>
            {
                if (int.TryParse(text, out int level))
                {
                    PlayerData.Level = level;
                    Debug.Log($"等级已设置为：{level}");
                }
                else
                {
                    Debug.LogWarning("请输入有效数字");
                }
            },
            initialValue: "1",
            contentType: TMP_InputField.ContentType.IntegerNumber
        );
    }
    
    [DebugButton("设置玩家名称")]
    private static void SetPlayerName()
    {
        UniversalDebugTool.ShowInputDialog(
            "输入名称",
            onConfirmAction: name =>
            {
                PlayerData.Name = name;
                Debug.Log($"名称已设置为：{name}");
            },
            initialValue: PlayerData.Name,
            contentType: TMP_InputField.ContentType.Standard
        );
    }
}

4. 条件编译（推荐）

为了确保正式版不包含调试代码：

public static class ItemDebugFunctions
{
    #if MEOWMENT_DEBUG_TOOL
    [DebugButton("添加道具")]
    private static void AddItem()
    {
        ItemManager.AddItem(1001, 10);
    }
    #endif
}

5. 高级技巧

技巧1：分类管理

按功能模块创建不同的类：

// 玩家相关
public static class PlayerDebug { ... }

// 关卡相关
public static class LevelDebug { ... }

// 道具相关  
public static class ItemDebug { ... }

技巧2：快速测试流程

[DebugButton("快速进入战斗")]
private static void QuickEnterBattle()
{
    // 1. 设置测试数据
    PlayerData.Level = 10;
    PlayerData.Coins = 9999;
    
    // 2. 解锁功能
    FeatureManager.UnlockAll();
    
    // 3. 跳转场景
    SceneManager.LoadScene("Battle");
}

技巧3：开发辅助

[DebugButton("开启所有调试选项")]
private static void EnableAllDebug()
{
    GameConfig.ShowFPS = true;
    GameConfig.GodMode = true;
    GameConfig.UnlimitedEnergy = true;
    Debug.Log("所有调试选项已开启");
}

6. 实战示例

using UnityEngine;
using UnityEngine.SceneManagement;
using TMPro;

public static class SampleDebugFunctions
{
    #region 玩家数据
    [DebugButton("重置游戏", 0.9f, 0.3f, 0.3f)]
    private static void ResetGame()
    {
        PlayerPrefs.DeleteAll();
        SceneManager.LoadScene(0);
        Debug.Log("游戏已重置");
    }
    
    [DebugButton("满级满资源", 0.2f, 0.8f, 0.2f)]
    private static void MaxEverything()
    {
        PlayerData.Level = 99;
        PlayerData.Coins = 999999;
        PlayerData.Gems = 99999;
        Debug.Log("已设置为满级满资源");
    }
    #endregion
    
    #region 关卡测试
    [DebugButton("跳关", 0.3f, 0.6f, 0.9f)]
    private static void JumpToLevel()
    {
        UniversalDebugTool.ShowInputDialog(
            "输入关卡号",
            text =>
            {
                if (int.TryParse(text, out int level))
                {
                    LevelManager.LoadLevel(level);
                }
            },
            "1",
            TMP_InputField.ContentType.IntegerNumber
        );
    }
    
    [DebugButton("解锁所有关卡", 0.2f, 0.8f, 0.8f)]
    private static void UnlockAllLevels()
    {
        for (int i = 0; i < 100; i++)
        {
            LevelManager.UnlockLevel(i);
        }
        Debug.Log("已解锁所有关卡");
    }
    #endregion
    
    #region 系统测试
    [DebugButton("清理未使用资源", 0.9f, 0.5f, 0.3f)]
    private static void UnloadUnusedAssets()
    {
        Resources.UnloadUnusedAssets();
        Debug.Log("已清理未使用的资源");
    }
    
    [DebugButton("触发GC")]
    private static void ForceGC()
    {
        System.GC.Collect();
        Debug.Log("已触发垃圾回收");
    }
    #endregion
}

❓ 常见问题

Q1: 字体显示方块/乱码怎么办？

A: 调用 UniversalDebugTool.SetSDFFont() 设置支持中文的SDF字体。

Q2: 自定义按钮不显示？

A: 检查：

方法是否为 static
是否添加了 [DebugButton] 特性
是否在 #if MEOWMENT_DEBUG_TOOL 内

Q3: 第二次点击"暂时隐藏"无效？

A: 等待上一次隐藏结束，或查看控制台是否有"已经在隐藏状态中"的警告。

Q4: 如何在正式版移除调试工具？

A: 删除Packages目录下的工具包文件夹即可，#if MEOWMENT_DEBUG_TOOL 包裹的代码会自动失效。

Q5: 控制台日志太多怎么办？

点击"清空"按钮清除日志
使用过滤器只显示Error/Warning
工具默认只保留最新100条日志

Q6: 可以在多个场景使用吗？

A: 可以，工具使用DontDestroyOnLoad，场景切换不会销毁。

📝 更新日志

[0.3.0] - 2025-12-22

✨ 新增控制台模块，实时显示Unity日志
✨ 新增暂时隐藏功能，方便截图
🔨 重构代码架构，模块化设计
🐛 修复多个UI布局问题

[0.2.2] - 2025-12-19

🔨 默认显示浮窗而非主窗口
🐛 优化初始化逻辑

详见 CHANGELOG.md

📦 依赖

Unity 2021.3+
TextMesh Pro (com.unity.textmeshpro)
Unity UI (com.unity.ugui)

📧 联系方式

如有问题或建议，请联系开发团队。

祝调试顺利！ 🐱

13 KiB Raw Blame History Unescape Escape