跳至主要内容

模塊介紹

重要 注意 提醒

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)