# 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>` 绑定与窗口生命周期。