Skip to content

README.md

Latest commit

 

History

History
160 lines (116 loc) · 5.83 KB

README.md

File metadata and controls

160 lines (116 loc) · 5.83 KB
Game Frame X Logo

GameFrameX UI FairyGUI

License Version Unity Version Documentation

All-in-One Solution for Indie Game Development · Empowering Indie Developers' Dreams


Documentation · Quick Start · QQ Group: 467608841 / 233840761


English | 简体中文 | 繁體中文 | 日本語 | 한국어

Project Overview

GameFrameX UI FairyGUI is a Unity UI adapter that wraps the FairyGUI framework into the GameFrameX modular game framework. It provides complete UI lifecycle management (open/close/recycle/animate) with async asset loading via YooAsset.

Key Features

  • Complete UI Lifecycle — Open, close, recycle, and animate UI forms with a unified API
  • Async Asset Loading — YooAsset-backed async loading for FairyGUI packages and resources
  • Object Pooling — UI form instances are pooled for reuse, minimizing GC allocations
  • Singleton Deduplication — Automatically prevents duplicate form creation
  • Loading Queue — Coalesces concurrent open requests for the same form
  • Attribute-Driven Configuration — Control UI groups, show/hide animations via C# attributes
  • MVVM Binding Support — Automatic cleanup of bindable property events with BindablePropertyExtension
  • Dual Asset Loading — Supports both Resources.Load and YooAsset AssetBundle loading
  • IL2CPP Safe — Preserve attributes prevent code stripping on IL2CPP builds

Architecture

┌─────────────────────────────────────────────┐
│              Your UI Panels (FUI)            │
├─────────────────────────────────────────────┤
│                  UIManager                   │
│    (Open / Close / Recycle / Loading Queue)  │
├──────────┬──────────┬───────────────────────┤
│ FormHelper│UIGroup   │ PackageComponent      │
│ (Create/  │Helper    │ (AddPackage /         │
│  Release) │(Depth)   │  RemovePackage)       │
├──────────┴──────────┴───────────────────────┤
│         FairyGUI Runtime + YooAsset          │
└─────────────────────────────────────────────┘
Component Description
UIManager Central UI manager handling open/close/recycle lifecycle
FUI Base class for all FairyGUI panels — inherit from this
FairyGUIPackageComponent MonoBehaviour managing FairyGUI package loading/unloading
FairyGUIFormHelper Handles form instantiation, creation, and release
FairyGUIUIGroupHelper Manages UI group depth and layering
FairyGUILoadAsyncResourceHelper Bridges FairyGUI resource requests to YooAsset
FairyGUIPathFinderHelper Path-based GObject lookup utility

Quick Start

Installation

Edit your Unity project's Packages/manifest.json and add the scopedRegistries section:

{
  "scopedRegistries": [
    {
      "name": "GameFrameX",
      "url": "https://gameframex.upm.alianblank.uk",
      "scopes": [
        "com.gameframex"
      ]
    }
  ]
}

scopes controls which packages are resolved through this registry. Only packages whose names start with com.gameframex will be fetched from it.

Then add the package to dependencies:

{
  "dependencies": {
    "com.gameframex.unity.ui.fairygui": "3.3.2"
  }
}

Usage Examples

Show/Hide Animations

Use attributes to configure animations:

[OptionUIShowAnimation(typeof(FadeInAnimation))]
[OptionUIHideAnimation(typeof(FadeOutAnimation))]
public class AnimatedPanel : FUI { }

Path-Based Object Lookup

// Get the hierarchical path of a GObject
string path = gObject.GetUIPath();

// Resolve a GObject from path
GObject obj = FairyGUIPathFinderHelper.GetUIFromPath("GRoot/Group/MyButton");

MVVM Binding with Auto-Cleanup

// Automatically unregisters events when the GObject is destroyed
myProperty.ClearWithGObjectDestroyed(gObject);

Platform Support

Platform Supported
Android ✅
iOS ✅
Windows ✅
macOS ✅
WebGL ✅

Minimum Unity version: 2019.4

Documentation & Resources

Community & Support

Changelog

See CHANGELOG.md for release history.

License

See LICENSE.md for license information.