2026-04-01 13:20:06 +08:00

4.7 KiB

Raw Blame History

Aliciza X Framework 快速入口

1. 框架简介

com.alicizax.unity.framework 是一套面向 Unity 项目的模块化基础框架，围绕 根节点统一启动、服务容器统一获取、运行时模块按需组合 的设计思想构建。
框架通过 RootModule 建立全局运行时入口，通过 AppServices / GameApp 暴露常用服务访问点，再由 UI、资源、音频、本地化、场景、流程、池化、定时器等模块分别承载具体业务能力。

核心设计理念

组合优先：各模块以组件或服务形式注册，按项目需要启用。
职责分层：区分 Core / Runtime / Editor / Plugins，运行时与编辑器逻辑边界清晰。
统一入口：通过 GameApp、服务定位与根模块生命周期减少业务侧样板代码。
面向工程化：覆盖资源加载、UI 绑定、流程切换、调试监视、池化复用等常见项目基础设施。

2. 推荐阅读顺序

Foundation
Resource
Timer
UI
其余业务模块

3. 模块目录

Core

Foundation：根模块、服务容器、通用基础设施与核心抽象。
Event：结构体事件总线、事件订阅与调试监视。
ObjectPool：通用对象池与可复用实例管理。
GameObjectPool：面向预制体/场景对象的 GameObject 级池化系统。

Runtime

Audio：音频播放、分组音量、播放句柄与运行时控制。
Debugger：运行时调试面板、监控入口与调试扩展。
Localization：本地化表、语言切换与文本刷新机制。
Procedure：流程/状态节点切换与启动流程组织。
Resource：资源系统封装、包初始化、资源加载与实例化。
Scene：场景加载、场景域切换与场景生命周期协作。
Timer：统一定时器服务、延时/循环/取消与时间驱动逻辑。
UI：UI 窗口、Widget、Holder 绑定、层级管理与动画过渡。

Editor

EditorTools：Inspector、事件监视器、UI 绑定生成器与本地化编辑工具。

Plugins

Plugins：第三方程序集、代码生成器与插件职责说明。

4. 整体协作关系

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

启动顺序建议

RootModule -> ResourceComponent -> TimerComponent -> UIComponent -> 其他业务模块

最小示例

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 理解根模块与服务注册方式。
从 Resource 理解资源系统初始化与加载链路。
从 UI 理解 UIHolder 自动生成、UIWidget<T> 绑定与窗口生命周期。

4.7 KiB Raw Blame History Unescape Escape