135 lines
4.7 KiB
Markdown
135 lines
4.7 KiB
Markdown
# Aliciza X Framework 快速入口
|
||
|
||
## 1. 框架简介
|
||
|
||
`com.alicizax.unity.framework` 是一套面向 Unity 项目的模块化基础框架，围绕 **根节点统一启动、服务容器统一获取、运行时模块按需组合** 的设计思想构建。
|
||
框架通过 `RootModule` 建立全局运行时入口，通过 `AppServices` / `GameApp` 暴露常用服务访问点，再由 UI、资源、音频、本地化、场景、流程、池化、定时器等模块分别承载具体业务能力。
|
||
|
||
### 核心设计理念
|
||
|
||
- **组合优先**：各模块以组件或服务形式注册，按项目需要启用。
|
||
- **职责分层**：区分 `Core / Runtime / Editor / Plugins`，运行时与编辑器逻辑边界清晰。
|
||
- **统一入口**：通过 `GameApp`、服务定位与根模块生命周期减少业务侧样板代码。
|
||
- **面向工程化**：覆盖资源加载、UI 绑定、流程切换、调试监视、池化复用等常见项目基础设施。
|
||
|
||
## 2. 推荐阅读顺序
|
||
|
||
1. [Foundation](./Core/Foundation.md)
|
||
2. [Resource](./Runtime/Resource.md)
|
||
3. [Timer](./Runtime/Timer.md)
|
||
4. [UI](./Runtime/UI.md)
|
||
5. 其余业务模块
|
||
|
||
## 3. 模块目录
|
||
|
||
### Core
|
||
|
||
- [Foundation](./Core/Foundation.md)：根模块、服务容器、通用基础设施与核心抽象。
|
||
- [Event](./Core/Event.md)：结构体事件总线、事件订阅与调试监视。
|
||
- [ObjectPool](./Core/ObjectPool.md)：通用对象池与可复用实例管理。
|
||
- [GameObjectPool](./Core/GameObjectPool.md)：面向预制体/场景对象的 GameObject 级池化系统。
|
||
|
||
### Runtime
|
||
|
||
- [Audio](./Runtime/Audio.md)：音频播放、分组音量、播放句柄与运行时控制。
|
||
- [Debugger](./Runtime/Debugger.md)：运行时调试面板、监控入口与调试扩展。
|
||
- [Localization](./Runtime/Localization.md)：本地化表、语言切换与文本刷新机制。
|
||
- [Procedure](./Runtime/Procedure.md)：流程/状态节点切换与启动流程组织。
|
||
- [Resource](./Runtime/Resource.md)：资源系统封装、包初始化、资源加载与实例化。
|
||
- [Scene](./Runtime/Scene.md)：场景加载、场景域切换与场景生命周期协作。
|
||
- [Timer](./Runtime/Timer.md)：统一定时器服务、延时/循环/取消与时间驱动逻辑。
|
||
- [UI](./Runtime/UI.md)：UI 窗口、Widget、Holder 绑定、层级管理与动画过渡。
|
||
|
||
### Editor
|
||
|
||
- [EditorTools](./Editor/EditorTools.md)：Inspector、事件监视器、UI 绑定生成器与本地化编辑工具。
|
||
|
||
### Plugins
|
||
|
||
- [Plugins](./Plugins/Plugins.md)：第三方程序集、代码生成器与插件职责说明。
|
||
|
||
## 4. 整体协作关系
|
||
|
||
```text
|
||
RootModule
|
||
└── AppServiceRoot
|
||
└── AppServices / GameApp
|
||
├── Resource
|
||
├── Timer
|
||
├── UI
|
||
├── Audio
|
||
├── Localization
|
||
├── Procedure
|
||
├── ObjectPool / GameObjectPool
|
||
└── Scene
|
||
```
|
||
|
||
### 常见依赖关系
|
||
|
||
- `UI` 通常依赖 `Resource` 加载界面资源，并依赖 `Timer` 驱动过渡或延迟行为。
|
||
- `Scene` 常与 `Resource` 协作处理场景包加载，与 `Procedure` 协作组织关卡切换。
|
||
- `Localization` 常与 `UI` 或 `UX` 文本组件协作，负责语言刷新。
|
||
- `GameObjectPool` 常与 `Resource` 协作完成预制体异步加载与回收复用。
|
||
|
||
## 5. 最小接入步骤
|
||
|
||
### 场景基础组件
|
||
|
||
推荐在启动场景中至少挂载：
|
||
|
||
- `RootModule`
|
||
- `ResourceComponent`
|
||
- `TimerComponent`
|
||
- `UIComponent`
|
||
|
||
### 启动顺序建议
|
||
|
||
```text
|
||
RootModule -> ResourceComponent -> TimerComponent -> UIComponent -> 其他业务模块
|
||
```
|
||
|
||
### 最小示例
|
||
|
||
```csharp
|
||
using AlicizaX;
|
||
using AlicizaX.Resource.Runtime;
|
||
using Cysharp.Threading.Tasks;
|
||
using UnityEngine;
|
||
|
||
public sealed class BootstrapExample : MonoBehaviour
|
||
{
|
||
private async void Start()
|
||
{
|
||
IResourceService resourceService = GameApp.Resource;
|
||
await resourceService.InitPackageAsync();
|
||
await GameApp.UI.ShowUI<MainMenuWindow>();
|
||
}
|
||
}
|
||
```
|
||
|
||
## 6. 常见问题
|
||
|
||
### `GameApp.xxx` 为空
|
||
|
||
- 对应模块组件尚未挂载或未完成初始化。
|
||
- `RootModule` 尚未建立根服务容器。
|
||
- 获取时机早于模块注册阶段。
|
||
|
||
### UI 无法打开
|
||
|
||
- `UIComponent` 未配置 `UIRoot`。
|
||
- UI 资源路径或 `UIResAttribute` 配置错误。
|
||
- UI 绑定代码未生成，或 `UIWidget<T>` 泛型未引用正确的 Holder 类型。
|
||
|
||
### 资源加载失败
|
||
|
||
- 资源包尚未初始化。
|
||
- 资源路径与包内地址不一致。
|
||
- 运行环境缺少对应包或依赖资源。
|
||
|
||
## 7. 下一步
|
||
|
||
- 从 [Foundation](./Core/Foundation.md) 理解根模块与服务注册方式。
|
||
- 从 [Resource](./Runtime/Resource.md) 理解资源系统初始化与加载链路。
|
||
- 从 [UI](./Runtime/UI.md) 理解 UIHolder 自动生成、`UIWidget<T>` 绑定与窗口生命周期。
|