跳到主要内容

模块介绍

重要 注意 提醒

Coding Style wiki​

基本说明​

各通用必备组件工具 (Essential)，皆为独立小工具，可依需求单独取用，包含以下：

  • Utilities (Runtime)

    • Adapter: UISafeAreaAdapter (UI 安全区域适配)。
    • Cacher: ARCCache<TKey, TValue>、LRUCache<TKey, TValue>、LRUKCache<TKey, TValue> (容量控制缓存容器)。
    • Requester: RequestAudio、RequestTexture2D、RequestSprite、RequestBytes、RequestText (基于 UniTask 的网络/文件请求 + 缓存)。
    • TextureAnim (CPU computation): 图片序列动画 (Image Sequence Animation)。
    • EasyAnim: 简易动画播放封装，必须在动画片段 (Clip) 上设置名为 AnimEnd 的动画事件 (Animation Event)，才会触发 animEnd 回调。
    • DontDestroy: 跨场景常驻对象标记。
    • UnityMainThread: UMT (Unity 主线程调度器)。

  • Editor

    • RectTransform: RectTransformAdjuster (快捷键: Shift+R, R: RectTransform)。
    • MissingScriptsFinder: 搜索 Missing Scripts。
    • SymlinkUtility: 文件夹符号链接工具。

  • 版本：v1.4.8 (com.michaelo.oxgkit.utilities)

  • 命名空间：OxGKit.Utilities (各工具皆有独立子命名空间，例如 OxGKit.Utilities.Cacher、OxGKit.Utilities.Requester)

注意 本模块依赖 UniTask、LWMyBox 与 OxGKit.LoggingSystem (作为日志输出)，需先安装依赖库 (详见 Installation)。

应用说明​

Runtime 工具​

  • Cacher：提供 ARC / LRU / LRU-K 三种淘汰策略的泛型缓存容器，操作皆有线程锁 (Thread Lock)，并支持自定义移除处理器 IRemoveCacheHandler<TKey, TValue> (默认为 UnityObjectRemoveCacheHandler<TKey, TValue>，淘汰时会自动 Destroy Unity 对象)。
  • Requester：基于 UniTask + UnityWebRequest 的资源请求器，支持 AudioClip、Texture2D、Sprite、byte[]、string 请求，并可搭配 ARC 或 LRU 缓存 (以 URL 为 Key)，具有超时 (默认 180 秒) 与取消 (CancellationTokenSource) 机制。
  • TextureAnim：以 CPU 计算的图片序列动画组件 (TextureAnimation)，支持 SpriteRenderer 与 Image，具有 Normal、Reverse、PingPong、PingPongReverse 播放模式，并支持编辑模式预览 (ExecuteInEditMode)。
  • EasyAnim：播放 + 结束回调的动画封装，分为 EasyAnimation (Animation 旧版动画) 与 EasyAnimator (Animator)。
  • Adapter：UISafeAreaAdapter 依据 Screen.safeArea 自动调整 UI 面板锚点，适配刘海与异形屏幕。
  • DontDestroy：于 Awake 时将对象标记为 DontDestroyOnLoad 并依配置重新命名。
  • UnityMainThread：UMT 主线程调度器，可将任意线程的工作排入 Unity 主线程执行 (亦支持协程管理)。

重要 使用 EasyAnim 时，必须在动画片段上设置名为 AnimEnd 的动画事件，动画播放至该事件时才会触发 animEnd 回调。

Editor 工具​

  • RectTransformAdjuster：选取 UI 对象后按下 Shift+R (或通过菜单 GameObject -> Adjust RectTransform Anchors)，将锚点 (Anchors) 对齐当前 Rect 并归零偏移，支持多选与 Undo。
  • MissingScriptsFinder：通过菜单 MissingScriptsFinder 搜索已加载场景、Build Settings 场景、项目全场景与全 Prefabs 中的 Missing Scripts。
  • SymlinkUtility：通过 Right-Click Create/Folder (Junction / Absolute Symlink / Relative Symlink) 创建文件夹符号链接，并于 Project 窗口显示 <=> 链接标记。

AI Agent Skills​

  • 通过 Package Manager -> Samples 导入 AI Agent Skills，内含 oxgkit-unity-skill (SKILL.md)，可让 AI Coding Agents (Claude Code、Codex CLI、Cursor 等) 学会本模块的正确用法 (参考 AI Agent Skills)。

模块日志​

  • 本模块的日志通过 OxGKit.LoggingSystem 输出，日志器名称为 OxGKit.Utilities.Logger，可在 LoggingLauncher 进行开关与级别配置。

简单使用​

Requester 请求资源 (搭配缓存)​

using Cysharp.Threading.Tasks;
using OxGKit.Utilities.Requester;
using UnityEngine;

// 启动时初始各资源类型的缓存 (ARC 或 LRU 择一)
Requester.InitARCCacheCapacityForTexture2d(60);

// 请求 Texture2D (以 URL 为 Key 进行缓存)
Texture2D t2d = await Requester.RequestTexture2D
(
    url,
    (texture) => Debug.Log("Loaded"),
    (error) => Debug.Log($"Error: {error.message}")
);

Cacher 缓存容器​

using OxGKit.Utilities.Cacher;

// 创建容量 60 的 LRU 缓存 (默认淘汰时会自动 Destroy Unity 对象)
var cache = new LRUCache<string, Texture2D>(60);
cache.Add(key, texture);
Texture2D t2d = cache.Get(key);

UMT 主线程调度​

using OxGKit.Utilities.UnityMainThread;

// 于任意线程排入工作, 将于 Unity 主线程的 Update 中执行
UMT.worker.AddJob(() =>
{
    // Do main thread job
});

EasyAnim 播放动画​

using OxGKit.Utilities.EasyAnim;

// EasyAnimation 传入 Clip 名称; EasyAnimator 传入 Trigger 参数名称
// (Clip 上必须设置名为 AnimEnd 的动画事件, 结束回调才会触发)
var easyAnim = this.GetComponent<EasyAnim>();
easyAnim.Play("Open", () =>
{
    // On animation end
});

[参考 Example]

Installation​

Install via git URL
Add https://github.com/michael811125/OxGKit.git?path=Assets/OxGKit/Utilities/Scripts to Package Manager

第三方库 (需自行安装; 如果搭配 OxGFrame 则不需要额外安装 UniTask)

Samples (Package Manager -> Samples)

模块 API​

Demo​

Utilities Demo (RectTransformAdjuster)