DOCSEARCHbyAlgolia
Submit Docs

FairyGUI for Unity

repository·master·Indexed 25 days ago

https://github.com/fairygui/fairygui-unity

A cross-platform UI editor and framework for Unity (2018 and above) that optimizes UI production via a designer-friendly workflow and FairyBatching for DrawCall optimization. It features rich text, virtual lists, unified input for touch and VR, and supports Lua integration via ToLua and XLUA, allowing for event listening, Window class extension, and custom component extensions in Lua.

Tokens
1.4K
Snippets
2
Records
6
Agent score
34%

What's inside FairyGUI

  1. Overview of FairyGUI for Unity

    master

    FairyGUI is a cross-platform UI editor and framework designed to bridge the gap between designers and programmers. It aims to reduce programming time by providing a workflow closer to the designer's intent compared to traditional Unity engines like NGUI or UGUI.

    Key features include:

    • Performance: Uses FairyBatching technology for efficient DrawCall optimization.
    • Built-in UI Features: Supports rich text (including images and animations), emoji input, virtual lists, loop lists, pixel-level hit testing, curved UI, gestures, typing effects, and interspersing particles/models with UI.
    • Unified Input: Encapsulates mouse, single touch, multi-touch, and VR handle input, allowing developers to use consistent code for all interaction types.

  2. Setup Lua support for FairyGUI

    master

    To use FairyGUI with Lua, follow these steps based on your Lua environment:

    For ToLua users

    1. Add FAIRYGUI_TOLUA to your Unity Scripting Define Symbols.
    2. Add the following FairyGUI types to your CustomSettings.cs file to generate binding files:
        _GT(typeof(EventContext)),
    _GT(typeof(EventDispatcher)),
    _GT(typeof(EventListener)),
    _GT(typeof(InputEvent)),
    _GT(typeof(DisplayObject)),
    _GT(typeof(Container)),
    _GT(typeof(Stage)),
    _GT(typeof(FairyGUI.Controller)),
    _GT(typeof(GObject)),
    _GT(typeof(GGraph)),
    _GT(typeof(GGroup)),
    _GT(typeof(GImage)),
    _GT(typeof(GLoader)),
    _GT(typeof(GMovieClip)),
    _GT(typeof(TextFormat)),
    _GT(typeof(GTextField)),
    _GT(typeof(GRichTextField)),
    _GT(typeof(GTextInput)),
    _GT(typeof(GComponent)),
    _GT(typeof(GList)),
    _GT(typeof(GRoot)),
    _GT(typeof(GLabel)),
    _GT(typeof(GButton)),
    _GT(typeof(GComboBox)),
    _GT(typeof(GProgressBar)),
    _GT(typeof(GSlider)),
    _GT(typeof(PopupMenu)),
    _GT(typeof(ScrollPane)),
    _GT(typeof(Transition)),
    _GT(typeof(UIPackage)),
    _GT(typeof(Window)),
    _GT(typeof(GObjectPool)),
    _GT(typeof(Relations)),
    _GT(typeof(RelationType)),
    _GT(typeof(Timers)),
    _GT(typeof(GTween)),
    _GT(typeof(GTweener)),
    _GT(typeof(EaseType)),
    _GT(typeof(TweenValue)),
    _GT(typeof(UIObjectFactory)),

    For XLUA users

    No additional Scripting Define Symbols are required.

    Common Step

    Place FairyGUI.lua into your Lua file directory.

  4. Listen to FairyGUI events in Lua

    master

    You can add and remove event listeners in Lua.

    Standard Method

    Use the :Add(callback) method on an event. The callback can optionally accept an EventContext parameter.

    require 'FairyGUI'

function OnClick(context)
    print('you click'..context.sender)
end

UIPackage.AddPackage('Demo')
local view = UIPackage.CreateObject('Demo', 'DemoMain')
GRoot.inst:AddChild(view)

view.onClick:Add(OnClick)
-- To remove: view.onClick:Remove(OnClick)
-- To replace: view.onClick:Set(OnClick)

    ToLua: Callbacks with 'self'

    If you are using ToLua, you can pass self to the listener to support class-based callbacks:

    function TestClass:OnClick(context)
    print('you click'..context.sender)
end

-- Pass the function and the self object
self.view.onClick:Add(TestClass.OnClick, self)
self.view.onClick:Remove(TestClass.OnClick, self)
    view.onClick:Add(OnClick)

  5. Extend the Window class in Lua

    master

    You can create and extend FairyGUI Window classes in Lua by using fgui.window_class(). This is useful for overriding lifecycle methods like OnInit, OnShown, and OnHide.

    Creating a Base Window

    WindowBase = fgui.window_class()

function WindowBase:ctor()
end

function WindowBase:OnInit()
    self.contentPane = UIPackage.CreateObject("Basics", "WindowA")
end

function WindowBase:OnShown()
end

function WindowBase:OnHide()
end

function WindowBase:DoShowAnimation()
    self:OnShown()
end

function WindowBase:DoHideAnimation()
    self:HideImmediately()
end

-- Instantiate and show
local win = WindowBase.New()
win:Show()

    Inheriting from a Window class

    MyWindow = fgui.window_class(WindowBase)

function MyWindow:OnInit()
    -- Call parent method
    WindowBase.OnInit(self)
end
    MyWindow = fgui.window_class(WindowBase)

  6. Create custom component extensions in Lua

    master

    You can extend FairyGUI components (like GButton or GComponent) in Lua using fgui.extension_class. This allows you to add custom methods and properties to specific UI resources.

    1. Define the Extension Class

    Note that the ctor function is called after the component is already constructed.

    -- Use GButton for buttons, GComponent for general components
MyButton = fgui.extension_class(GButton)

function MyButton:ctor()
    print(self:GetChild('n1'))
end

-- Add custom methods
function MyButton:Test()
    print('test')
end

-- Add custom properties (ToLua specific)
local get = tolua.initget(MyButton)
local set = tolua.initset(MyButton)
get.myProp = function(self)
    return self._myProp
end
set.myProp = function(self, value)
    self._myProp = value
    self:GetChild('n1').text = value
end

    2. Register the Extension

    Register the class before creating any objects of that type. Use the resource path (e.g., ui://PackageName/ComponentName).

    fgui.register_extension("ui://PackageName/MyButton", MyButton)

    3. Usage

    Once registered, any object created from that resource will have access to the extension.

    local myButton = someComponent:GetChild("myButton")
myButton:Test()
myButton.myProp = 'hello'

local myButton2 = UIPackage.CreateObject("PackageName", "MyButton")
myButton2:Test()
myButton2.myProp = 'world'