README.md

September 9, 2025 · View on GitHub

License

基本介紹

OxGKit 是基於 Unity 設計於遊戲開發常用的系統工具組 (皆為獨立工具)。

TODO 未來會補充 OxGKit 的文檔

Coding Style wiki

目前包含以下

[會持續擴充工具系統組]

工具系統介紹

LoggingSystem (dependence LWMyBox)

日誌系統，支持 Cipher & Plaintext (可以任意轉換)，支持動態配置與覆寫原有的日誌器功能，其他還有全域開關配置、全域級別配置、全域顏色配置、個別開關配置、個別級別配置、個別顏色配置。

  • 透過 Right-Click Create/OxGKit/Logging System/Create loggersconfig.conf (自動存於 StreamingAssets) 建立配置文件，方便真機修改 loggersconfig.conf 配置進行調適。
  • 透過 LoggingLauncher 進行配置或只直接修改 StreamingAssets/loggersconfig.conf 文件。

Build 激活宏

  • OXGKIT_LOGGER_ON

配置文件編碼格式轉換。

  • 提醒：發布建議使用 Cipher。

LoggingLauncher 配置介面，可以配置 logActive (開關)、logLevel (級別)、logColor (顏色)。

  • 透過 Package Manager -> Samples 匯入 LoggingLauncher Prefab，再拖曳至場景上激活環境配置 (僅需激活一次)，會自動嘗試加載 StreamingAssets/loggersconfig.conf 進行日誌開關控制。

Log Level 可切換為以下：

  • LogDebug (Print)
  • LogInfo (PrintInfo)
  • LogWarning (PrintWarning)
  • LogError (PrintError)
  • LogException (PrintException)

表格符號說明：

  • G = Global (全域設定 / Master Logging Level)。
  • P = Per-Logger (個別 Logger 的設定)。
  • Gx = 單一全域級別：LogDebug / LogInfo / LogWarning / LogError / LogException。
  • Px = 單一個別級別：LogDebug / LogInfo / LogWarning / LogError / LogException。
  • G ∩ P = 旗標交集 (bitwise AND)，代表同時被全域與個別允許的級別集合。

總結規則：只有當 G 與 P 都包含該級別時，該級別 (Log Level) 才會進行輸出。

全域 (G)個別 (P)生效級別 (輸出)
OffAny✗
AnyOff✗
AllAllDEBUG / INFO / WARNING / ERROR / EXCEPTION → ✓
All單一 PxPx → ✓
單一 GxAllGx → ✓
單一 Gx單一 Px若 Gx = Px → Gx → ✓；否則 ✗
任意集合 G任意集合 PG ∩ P → ✓；若無交集 → ✗

Log Color 可切換為以下：

  • Disabled
  • Enabled
  • EditorOnly (發布時，不進行 RichText 上色處理)
全域 (G)個別 (P)生效模式EditorPlayer / 發布
DisabledAnyDisabled✗✗
EnabledDisabledDisabled✗✗
EditorOnlyDisabledDisabled✗✗
EnabledEnabledEnabled✓✓
EnabledEditorOnlyEditorOnly✓✗
EditorOnlyEnabledEditorOnly✓✗
EditorOnlyEditorOnlyEditorOnly✓✗

新增 Logger 或移除 Logger，皆需呼叫 LoggingLauncher.TryLoadLoggers() 進行重載 (建議定義一個 default constructor，避免搭配 HybridCLR + Activator.CreateInstance(type) 出現錯誤)。

using OxGKit.LoggingSystem;

[LoggerName("MyLogger")]
public class MyLogger1 : Logging 
{
    // If use HybridCLR must create a default constructor
    public MyLogger1() { }
}

進行原有 Logger 的 Override

// Use same name to override MyLogger1
[LoggerName("MyLogger", true)]
public class OverrideMyLogger1 : Logging 
{
    // If use HybridCLR must create a default constructor
    public OverrideMyLogger1() { }

    public override void Log(object message)
    {
        UnityEngine.Debug.Log("[Override]" + message);
    }

    public override void LogInfo(object message)
    {
        UnityEngine.Debug.Log("[Override]" + message);
    }

    public override void LogWarning(object message)
    {
        UnityEngine.Debug.LogWarning("[Override]" + message);
    }

    public override void LogError(object message)
    {
        UnityEngine.Debug.LogError("[Override]" + message);
    }

    public override void LogException(Exception exception)
    {
        UnityEngine.Debug.LogException(exception);
    }
}

如果搭配 HybridCLR 有主工程跟熱更工程的區分，必須手動拆分創建 AOT 跟 Hotfix 的 Loggers 初始流程，可以參考以下：

// HybridCLR (必須取消 LoggingLauncher 上的 "Initialize On Awake" 選項):
LoggingLauncher.CreateLogger<LoggingDemoLogger1>();
LoggingLauncher.CreateLogger<LoggingDemoLogger2>();
LoggingLauncher.CreateLogger<LoggingDemoLogger3>();
LoggingLauncher.CreateLogger<LoggingDemoLogger4>();
LoggingLauncher.TryLoadLoggers();

動態配置日誌器，參考如下：

// Reload LoggersConfig at Runtime (方式一)
var loggersConfig = new LoggersConfig
(
    new LoggerSetting("LoggingDemo.Logger1", true, LogLevel.Log),
    new LoggerSetting("LoggingDemo.Logger2", true, LogLevel.LogWarning),
    new LoggerSetting("LoggingDemo.Logger3", true, LogLevel.Off)
);
LoggingLauncher.SetLoggersConfig(loggersConfig);

// Reload LoggersConfig at Runtime (方式二)
LoggingLauncher.ConfigureLogger("LoggingDemo.Logger1", false);
LoggingLauncher.ConfigureLogger("LoggingDemo.Logger2", true, LogLevel.LogWarning | LogLevel.LogError);
LoggingLauncher.ConfigureLogger("LoggingDemo.Logger3", false);

以下是在 AOT 工程中初始 AOT 工程的 Loggers (如果 Hotfix 工程的 Loggers 需要再 Hotfix 工程中初始)：

[參考 Example]

Installation

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

第三方庫 (需自行安裝)

LoggingSystem Demo

https://github.com/michael811125/OxGKit/assets/30960759/51ecddd7-5241-43e9-9104-de45cbc5f68d

LoggingSystem Build Test

https://github.com/michael811125/OxGKit/assets/30960759/cef1a484-d617-466d-bf3e-6104032d7c3f

InfiniteScrollView (dependence UniTask, OxGKit.LoggingSystem)

無限列表 (魔改版)，基於原生 UGUI 能夠簡單的繼承或使用現有的 Infinite ScrollView，以物件池的概念進行物件有效循環利用。

Reference: howtungtung - InfiniteScrollView

[參考 Example]

Installation

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

第三方庫 (需自行安裝)

※備註 : Right-Click Create/OxGKit/Infinite ScrollView... (Template cs)

ActionSystem (dependence UniTask, OxGKit.LoggingSystem)

動作序列系統，能夠自行定義 Action 並且自行組合運行組，預設 Actions 有 SequenceAction, ParallelAction, ParallelDelayAction, DelayAction, DelegateAction，另外如果針對動畫需要進行拼湊處理，也可以使用 ActionSystem 作為運行。

  • 透過 Right-Click Create/OxGKit/Action System/Template Action.cs 實作自定義 Action。

[參考 Example]

Installation

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

第三方庫 (需自行安裝)

ActionSystem Demo

https://github.com/michael811125/OxGKit/assets/30960759/169d91ea-3709-420c-8751-f50119e97d35

※備註 : Right-Click Create/OxGKit/Action System... (Template cs)

NoticeSystem or RedDotSystem (dependence OxGKit.LoggingSystem)

通知系統 (也稱紅點系統)，支援動態新增刪除通知條件，可以自行定義通知條件，再針對 NoticeItem 進行條件持有註冊，當 NoticeItem 身上其中持有任一符合條件則通知顯示圖示 (紅點)。

  • 透過 Right-Click Create/OxGKit/Notice System/Template Notice Condition.cs 實作通知條件。
  • 將 NoticeItem prefab 拖曳至 UI 上，自行指定 ICON，再取得 NoticeItem 身上的組件進行條件註冊 (當 OnDestroy 時，會自動 Deregister)。
  • 當有數據狀態變更時，必須通知特定條件 ID 進行 Notify，將會透過條件 ID 進行查找持有的 NoticeItems，並且進行刷新顯示。

[參考 Example]

Installation

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

第三方庫 (需自行安裝)

NoticeSystem Demo

https://github.com/michael811125/OxGKit/assets/30960759/c6966327-3ede-432e-b8fe-bee53f629f25

※備註 : Right-Click Create/OxGKit/Notice System... (Template cs)

InputSystem (dependence Unity New InputSystem, OxGKit.LoggingSystem)

輸入控制系統，支援 Unity New InputSystem，如果使用 Unity New InputSystem 需自行建立 Unity New InpuptSystem 的控制表 (Control Maps)，並且還有提供使用於 Unity New InputSystem 的 Binding Composite 腳本模板，最後再由 Input Action 派送輸入訊號控制由訂閱者訂閱，進而做到遊戲中的控制邏輯不需要知道平台裝置區分，皆由 Input Action 進行整合，當然 Input Action 也支援其他輸入控制插件，作為單純的輸入控制派送者。

  • 透過 Right-Click Create/OxGKit/Input System/Template Input Action.cs 實作 InputAction 介面。
  • 調用 Inputs API (using.OxGkit.InputSystem)

主要層級驅動區分為以下

  • For Unity New InputSystem
    • Control Maps (Input Action Asset)
    • Binding Composites
  • For Any Inputs
    • Input Actions (此為獨立作為通用訊號派送者，不依賴任何輸入控制插件，皆可自由實現)

[參考 Example]

Installation

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

第三方庫 (需自行安裝)

InputSystem Demo

https://github.com/michael811125/OxGKit/assets/30960759/20548ee4-b77b-4cda-8d49-c82b16deddb7

※備註 : Right-Click Create/OxGKit/Input System... (Template cs)

TweenSystem (dependence DoTween Pro, LWMyBox, OxGKit.Utilities)

補間動畫 (僅支持 DoTween Pro)。

  • Add Component/OxGKit/TweenSystem/DoTweenAnim
  • Add Component/OxGKit/TweenSystem/DoTweenAnimEvent

Highly Recommended brunomikoski - Animation Sequencer

Preview Mode (Only DoTweenAnim component is supported)

※Note: The DoTweenAnimEvent only plays at runtime.

[參考 Example]

Installation

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

第三方庫 (需自行購買安裝)

第三方庫 (需自行安裝)

Create DoTween Assemblies

TweenSystem Demo

https://github.com/michael811125/OxGKit/assets/30960759/6bf690b6-c4d0-40f6-b3c9-b50ab62562e8

ButtonSystem

ButtonPlus 是基於繼承 Unity UGUI 的 Button 進行擴展的，功能擴展支持各 Long Click 等行為。

[參考 Example]

Installation

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

ButtonSystem Demo

https://github.com/michael811125/OxGKit/assets/30960759/891291af-1bb4-4515-bec6-a9877f4ca254

TimeSystem

各種 DeltaTimer, RealTimer, DTUpdater, RTUpdater, IntervalTimer, IntervalSetter, NtpTime (clock sync with NTP server) 關於時間的控制器。

[參考 Example]

Installation

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

TimeSystem Demo

https://github.com/michael811125/OxGKit/assets/30960759/ee085eb4-f803-45e5-9593-b481a4b5a821

CursorSystem

Cursor 游標管理器，支持靜態與動態游標與各種狀態行為切換 (例如經營模擬類的遊戲，需要有各種游標狀態等...)。

[參考 Example]

Installation

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

CursorSystem Demo

https://github.com/user-attachments/assets/49e2a081-6d31-4ba6-8bb8-be60a148742c

PoolSystem

簡易 GameObject 物件池，支持異步分散幀加載 (負載平衡)。

[參考 Example]

Installation

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

PoolSystem Demo

https://github.com/user-attachments/assets/822d2431-0ee4-487c-9331-b62257ba95fd

SingletonSystem

單例模式，支持 MonoSingleton (MonoBehaviour), NewSingleton (class)。

[參考 Example]

Installation

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

SaverSystem

簡易儲存系統，支持以文本形式儲存，預設提供 EditorPrefsSaver, PlayerPrefsSaver，可自行擴展。

Installation

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

LocalizationSystem

本地化系統，支持自定義解表方式與自定義支持語系。

必須實現以下回調進行初始配置：

  • Localization.onAddSupportedLanguages
  • Localization.onParsingLanguageData
  • Localization.onChangeLanguage
#region Localization Config
/// <summary>
/// Initialize localization config
/// </summary>
public static void InitializeLocalization()
{
    // Add supproted languages
    Localization.onAddSupportedLanguages = AddSupportedLanguages;

    // Parsing language table data
    Localization.onParsingLanguageData = ParsingLanguageData;
}

/// <summary>
/// Handle by Localization.onAddSupportedLanguages
/// </summary>
/// <param name="supportedLanguages"></param>
public static void AddSupportedLanguages(HashSet<LangType> supportedLanguages)
{
    supportedLanguages.Add(LangType.English);
    supportedLanguages.Add(LangType.ChineseTraditional);
    supportedLanguages.Add(LangType.ChineseSimplified);
    supportedLanguages.Add(LangType.Japanese);
    supportedLanguages.Add(LangType.Korean);
}

/// <summary>
/// Handle by Localization.onParsingLanguageData
/// </summary>
/// <param name="langType"></param>
/// <param name="langData"></param>
/// <returns></returns>
public static bool ParsingLanguageData(LangType langType, Dictionary<string, string> langData)
{
    // Your lang sheet (can load from json or server)
    if (langSheet.ContainsKey(langType.ToString()))
    {
        // The ref langData will be cached by Localization 
        foreach (var pair in langSheet[langType.ToString()])
            langData.TryAdd(pair.Key, pair.Value);
        return true;
    }
    return false;
}
#endregion

#region UI View Logic
/// <summary>
/// Init events
/// </summary>
private void _InitEvents()
{
    // Refresh lang text callback
    Localization.onChangeLanguage += this._RefreshLanguage;
}

/// <summary>
/// Handle by Localization.onChangeLanguage
/// </summary>
private void _RefreshLanguage(LangType langType)
{
    if (this.texts != null)
    {
        this.texts[0].text = Localization.GetStringByCode("Str1");
        this.texts[1].text = Localization.GetStringByCode("Str2");
        this.texts[2].text = Localization.GetStringByCode("Str3");
    }
}
#endregion

Localization Demo

[參考 Example]

Installation

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

VirtualJoystick

UGUI 虛擬搖桿系統 (調整版)，支持 Fixed、Floating 顯示。

Reference: annulusgames - EnhancedOnScreenStick

[參考 Example]

Installation

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

Utilities (dependence UniTask)

各通用組件 (Essential)。

  • Utilities
    • Adapter: UISafeAreaAdapter.
    • Cacher: ARCCache<TKey, TValue>, LRUCache<TKey, TValue>, LRUKCache<TKey, TValue>.
    • Requester: RequestAudio, RequestTexture2D, RequestSprite, RequestBytes, RequestText.
    • TextureAnim (CPU computation): Image sequence animation.
    • EasyAnim: Must set an animation event on the clip with the function name AnimEnd to invoke the animEnd callback.
    • DontDestroy.
    • UnityMainThread: UMT.
  • Editor
    • RectTransform: RectTransformAdjuster (Hotkey: Shift+R, R: RectTransform).
    • MissingScriptsFinder.
    • SymlinkUtility.

[參考 Example]

Installation

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

第三方庫 (獨立安裝時，需自行安裝; 如果搭配 OxGFrame 則不需要額外安裝 UniTask)

Utilities Demo (RectTransformAdjuster)

https://github.com/michael811125/OxGKit/assets/30960759/cd43fc8b-c6f7-4878-990b-99dcacb8ed1f

Unity 版本

建議使用 Unity 2022.3.59f1(LTS) or higher 版本 - Unity Download

paypal_logo_x128

buymeacoffee_qrcode_x128

License

This library is under the MIT License.