# LitGameFramework

**Repository Path**: hsdkdf/lit-game-framework

## Basic Information

- **Project Name**: LitGameFramework
- **Description**: Unity游戏框架
- **Primary Language**: C#
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2024-12-26
- **Last Updated**: 2025-11-05

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Unity微信小游戏框架
## 简介
Unity版本 2021.3.45f1 <br>
该框架旨在帮助开发者快速进行微信小游戏开发，具有以下特点<br>
- 代码简洁清晰<br>
- 支持热更新<br>
- 支持快速调试<br>
- 支持多种打包方式<br>
- 支持本地CDN<br>
- 支持Nakama后端框架<br>

成功上线游戏 [《红驴驴绿驴驴》](https://www.taptap.cn/app/735878)

### 第三方工具(已全部集成到框架中，无需单独从远端拉取)<br>
| 名称 | 作用 | 地址 |
| --- | --- | --- |
| YooAsset | 资源管理 | https://www.yooasset.com/ |
| HybridCLR | 代码热更 | https://hybridclr.doc.code-philosophy.com|
| UniTask | 异步操作 | https://github.com/Cysharp/UniTask |
| IngameDebugConsole | GM工具 | https://github.com/yasirkula/UnityIngameDebugConsole |
| JsonDotNet | 序列化 | https://github.com/JamesNK/Newtonsoft.Json |
| Unity/团结快速适配方案 | 小游戏转换 |https://wechat-miniprogram.github.io/minigame-unity-webgl-transform |

## 快速上手

### 初始化项目
```
菜单栏 HybridCLR=>Installer...
勾选 <Copy libil2cpp from local>，并选择框架中制作制作好的版本，在目录 <LitFramework/libil2cpp> 中
点击Install安装，HybridCLR会自动复制il2cpp到项目本地路径
```

### 添加游戏
```
GameEntrance.cs 为游戏入口脚本，请在其StartGame方法中启动游戏的业务逻辑
例如：打开游戏场景，打开主界面UI、登录UI等
```

### 启动游戏
```
切换到初始场景 LitMenu => Entrance
切换到Editor环境 LitMenu => Environment => 修改Env为Editor
运行Unity
```

### APP构建
游戏提供了多种构建方式，以Android为例<br>
```
构建应用 LitBuild => Android => Dev => App
查看构建结果 LitBuild => OpenFolder
启动CDN LitMenu => CDN => Start
```

### 微信小游戏构建
```
构建微信小游戏前需要去[微信公众平台](https://mp.weixin.qq.com/wxamp/home)注册账号并创建应用
注册完成后将应用appId配置到上面提到的ProjectConfig脚本中
然后使用LitBuild或Python构建均可
构建结果为微信小游戏项目，因此还需要安装[微信开发者工具](https://developers.weixin.qq.com/miniprogram/dev/devtools/download.html)
启动CDN LitMenu => CDN => Start
使用微信开发者工具打开项目，注意事项：
- 若使用本地CDN手机需要与电脑连接到同一局域网
- 若使用本地CDN资源下载失败，可以尝试详情中勾选不校验合法域名
- 调试模式下首包会比较大，建议在详情中勾选将上限调整为8M
最后点击预览，手机微信扫码即可
```

### Demo
```
可以在demo分支查看示例
```

## 项目详解

### 示意图
项目结构<br>
```
UnityProject
    |--- Assets
            |--- InApp App中内容
            |--- InBundle Bundle中内容
            |--- Third 第三方工具
    |--- CDN 本地DN路径
    |--- Build 构建结果路径
    |--- Packages 第三方包
    |--- libi2cpp HybridCLR特制版il2cpp
```
启动流程<br>
```
GameManager.Start 启动GameState状态机 =>
GameState_Init 游戏初始化 =>
GameState_ForceUpdate 强更新检查 =>
GameState_HotUpdate 启动热更新状态机 =>
    |^^^^^^^^^^^^^^^^^ 热更新流程 ^^^^^^^^^^^^^^^^^|
    | AssetState_Init 初始化                       |
    | AssetState_UpdateVersion 获取远端版本        |
    | AssetState_UpdateManifest 获取资源清单       |
    | AssetState_DownloadFiles 下载资源文件        |
    | AssetState_ClearCache 无下载资源跳过该步骤    |
    | AssetState_UpdateOver  热更新结束            |
    |^^^^^^^^^^^^^^^^^ 热更新结束 ^^^^^^^^^^^^^^^^^|
GameState_Hybrid 初始化热更程序集 =>
HotUpdate.Start 初始化热更框架 =>
GameEntrance.Start 游戏业务入口
```
### 命名空间
|命名空间|说明|
|---|---|
|LitFramework | 在App中的脚本所在命名空间 |
|HBFramework | 在Bundle中的脚本所在命名空间 |
|BuildTools | 构建工具类所在命名空间 |

### InApp
>App中结构比较简单，仅提供必要的启动逻辑

|名称|说明|
|---|---|
|FSM|有限状态机|
|AssetManager|资源管理器，仅提供异步加载方式|
|GameManager|游戏管理器，控制游戏的初始化及启动流程|
|SingletonManager|用来创建和管理游戏中的单例|
|DeviceUtility|提供了获取设备id的方法|
|ProjectConfig|项目配置（下面详细介绍）|
|ProjectEnvironment|项目环境（下面详细介绍）|

**ProjectConfig.cs (项目配置)**

|通用配置|类型|说明|
|---|---|---|
|appVersion|string|App版本|
|projectName|string|项目名称|
|cdn|string|CDN地址|
|development|bool|是否构建development版本|
|autoProfile|string|自动附加到UnityProfiler|
|targetFrameRate|int|帧率|
|resolution|Vector2|应用分辨率|
|openGM|bool|是否开启GM|

|HybridCLR配置|类型|说明|
|---|---|---|
|useBytes|bool|使用bytes加载代码|
|aotDllList|string|补充元数据列表|

|YooAsset配置|类型|说明|
|---|---|---|
|playMode|EPlayMode|YooAsset运行模式|
|packageName|string|资源包名|

|Android配置|类型|说明|
|---|---|---|
|useCustomKeystore|bool|是否使用keystore|
|keystoreName|string|keystore名字|
|keystorePass|string|keystore密码|
|keyaliasName|string|keyalias名字|
|keyaliasPass|string|keyalias密码|
|versionCode|int|版本号|

|Ios配置|类型|说明|
|---|---|---|
|TODO|TODO|TODO|

|微信小游戏配置|类型|说明|
|---|---|---|
|appId|string|小游戏应用Id|
|profilingFuncs|bool|profilingFuncs|
|profilingMemory|bool|profilingMemory|

**ProjectEnvironment.cs (项目环境)**

|环境枚举|说明|
|---|---|
|Editor|程序人员使用的编辑器环境|
|Editor_Art|美术人员使用的编辑器环境，以bytes方式加载代码|
|Android_Dev|Android开发环境|
|Android_Release|Android发布环境|
|Ios_Dev|Ios开发环境|
|Ios_Release|Ios发布环境|
|WxMiniGame_Dev|微信小游戏开发环境|
|WxMiniGame_Release|微信小游戏发布环境|

### InBundle
>**框架主体**及**所有业务逻辑的代码和资源**都在Bundle中

#### LitFramework

**目前提供的管理器**
|Managers|说明|
|---|---|
|AudioManager|音频管理器，播放游戏中的音乐音效|
|FPSManager|帧率管理器，计算并显示当前帧率|
|LogManager|日志管理器，记录游戏运行过程中的日志|
|MessageManager|消息管理器，游戏中消息的发送与监听|
|PanelManager|界面管理器，维护游戏中的UI|
|SingletonManager|单例管理器，创建销毁游戏中的单例|
|SSceneManager|场景管理器，TODO|
|StorageManager|存档管理器，管理游戏本地存档|
|TimeManager|时间管理器，获取本地时间和服务器时间|
|TimerManager|计时器管理器，管理游戏中的延时、计时操作|
|Proxy|代理，代码InApp中的管理器：GameManager、AssetManager|

**集成了一些常用工具**
|Tools|说明|
|---|---|
|AStar|A*寻路|
|BehaviourTree|行为树，用于AI制作|
|ComponentFinder|组件查找器，挂载预制体上，用于对其中组件的查找|
|CustomCollider|自定义碰撞器（待完善）|
|FSM|有限状态机，用于项目流程控制或AI制作|
|ObjectPool|对象池工具，由接口方式实现|
|ObserverComponents|事件监听组件，通过动态挂载快速实现UI点击、拖拽等事件监听|
|UIEventFilter|UI事件过滤器，使用顶层UI过滤玩家操作，用于新手引导中的点击限制|
|Utility|一些更小的工具类：例如AES加密解密、持久化文件操作、网络时间获取等等|

**此外框架中还内置了常用的UI界面**
|Panels|说明|
|---|---|
|Panel_GM|GM界面，可输入GM指令|
|Panel_Mask|遮罩界面，用于阻隔玩家操作|
|Panel_TextTip|文字提示界面|
|Panel_DialogTip1|带有一个选项的对话框界面|
|Panel_DialogTip2|带有两个选项的对话框界面|
|Panel_Loading|加载界面|
|Panel_Setting|设置界面|

界面预制体所在目录 InBundle/Framework/Prefabs/UI，开发者可根据游戏风格进行修改

#### Game
GameEntrance为游戏入口类，可以在其StartGame方法中启动游戏的业务逻辑

## LitMenu（菜单工具）
>LitMenu中提供了一些基本工具
```
LitMenu
    |--- Entrance 打开入口场景
    |--- Environment 打开项目环境配置
    |--- Presistent 缓存文件相关
            |--- OpenFolder 打开缓存文件所在目录
            |--- Clear 清理所有缓存文件
    |--- Table
            |--- OpenFolder 打开表所在目录
            |--- Generate Luban读表
    |--- CDN
          |--- Start 启动服务
          |--- OpenFolder 打开资源所在目录
          |--- OpenBrowser 在浏览器中打开
```

## LitBuild（构建工具）
>LitBuild中提供了多种构建方式
```
LitBuild
    |--- OpenFolder 打开构建结果目录
    |--- Android
            |--- Dev
                  |--- App 打包Android应用
                  |--- Project 打包Android工程
                  |--- Bundle 打包资源并同步到本地CDN
            |--- Release
                  |--- App打包Android应用
                  |--- Project 打包Android工程
                  |--- Bundle 打包资源并同步到本地CDN
    |--- Ios
            |--- Dev
                  |--- Project 打包XCode工程
                  |--- Bundle 打包资源并同步到本地CDN
            |--- Release
                  |--- Project 打包XCode工程
                  |--- Bundle 打包资源并同步到本地CDN
    |--- WxMiniGame
            |--- Dev
                  |--- Project 打包微信小游戏工程
                  |--- Bundle 打包资源并同步到本地CDN
            |--- Release
                  |--- Project 打包微信小游戏工程
                  |--- Bundle 打包资源并同步到本地CDN
```
## 微信能力支持
>为方便小游戏开发者进行快速开发，框架也接入了常用的微信平台能力
### 分享
### 排行榜
### 数据域

## 网络支持
nakama分支提供了网络部分的支持<br>
关于nakama请参考 [官方文档](https://heroiclabs.com/docs/nakama/client-libraries/unity/)<br>

## Jenkins支持
需要安装jenkins环境 [官方文档](https://www.jenkins.io/)<br>
需要Python环境 [官方文档](https://www.python.org/)<br>
框架中提供了Shell脚本可用于jenkins构建项目<br>

**Shell脚本能力**
```
BuildScripts
      |--- build-unity.sh 执行Unity编辑器方法的shell
      |--- build_android-dev.sh 打包AndroiDev
      |--- build_android-release.sh 打包AndroiRelease
      |--- build_ios-dev.sh 打包IOSDev
      |--- build_ios-release.sh 打包IOSRelease
      |--- build_wxminigame-dev.sh 打包微信小游戏Dev
      |--- build_wxminigame-release.sh 打包微信小游戏Release
      |--- feishu
            |--- robot_image.py 飞书发送图片机器人
            |--- robot_message.py 飞书发送消息机器人
      |--- wx
            |--- robot_wx_preview.js 微信小游戏预览机器人
            |--- robot_wx_upload.js 微信小游戏上传机器人
```

**使用示例**
$Type 为打包参数 应用/资源
```
#打包AndroiDev
#!/bin/bash -il
sh BuildScripts/build-android-dev.sh $Type
```

## 常见问题
TODO