📚 Client/GUI

在沙盘引擎当前版本GUI系统中，所有关于UI实例均是基于FairyGUI框架作为核心基础。

在此前提下，开发者可使用【FairyGUI编辑器】进行快速可视化的UI制作，同时搭配JavaScript代码直接操作FairyGUI对象以控制UI逻辑。

换句话说，沙盘引擎有关GUI部分，除了少数引擎内置代码外（如创建UI），其他代码部分均可通过FairyGUI原生代码\函数进行操作和调用。

let gui = GUI.Create("Package1", "Component1"); //引擎代码，以来创建一个UI对象
let button = gui.GetChild("n0"); //引擎代码，寻找加载UI中的某个子元件
 
button.onClick.Set(() => { //FairyGUI原生代码，按照JavaScript格式来写即可
    DLog("onClick!");
    button.TweenScale(Vector2(2, 2), 1); //部分情况下，FairyGUI代码需要提供的是 Vector2 对象
});

注意：沙盘引擎与FairyGUI同样建议使用【1个根组件+N个子组件】的方式进行UI创建，而不是分别在不同位置创建不同的UI小组件。

提示：在开始使用GUI相关功能之前，建议优先阅读《GUI功能参考》，以详细了解GUI功能作用及原理。

📒 Static Property

📘 GUI.MousePos

获取玩家鼠标坐标位置（2D平面坐标）。

GUI.MousePos: Vector

📘 GUI.MouseScroll

获取玩家鼠标滚轮滚动偏移量（自动归0）。

（向上 > 0 > 向下 ）

GUI.MouseScroll: float

📘 GUI.InputAwayTime

获取玩家输入（键盘）空闲时间（玩家在此时间内没有使用键盘）。

GUI.InputAwayTime: float

📘 GUI.ControlAwayTime

获取玩家控制（鼠标）空闲时间（玩家在此时间内没有使用及移动鼠标）。

GUI.ControlAwayTime: float

📒 Static Function

📘 GUI.SetPureMode()

设置GUI纯净模式开关（是否渲染UI），此属性可能有助于拍摄模式。

注意：此模式同时属于引擎内置功能，玩家可能通过快捷键或[Esc]进行开关。

function SetPureMode( active: bool )

📘 GUI.GetPureMode()

获取GUI纯净模式开关。

function GetPureMode(): bool

📘 GUI.SetCursor()

设置当前使用的光标ID，默认为0，具体类型样式参考《世界资源实例汇总》。

每次加载新的世界场景后，光标样式将重置到默认值。

function SetCursor( cursorID: int )

📘 GUI.GetCursor()

获取当前使用的光标ID，默认为0。

function GetCursor(): int

📘 GUI.SetCursorActive()

设置鼠标是否可见，通常游戏时不可见，菜单或需要操作UI时可见。

每次加载新的世界场景后，此属性将重置到默认值（可见）。

注意：当弹出操作UI时会自动转变为可见状态，开发者无需过多干预这部分逻辑。

function SetCursorActive( active: bool = true )

📘 GUI.GetCursorActive()

获取鼠标是否可见。

function GetCursorActive(): bool

📘 GUI.SetCrosshair()

设置准星样式ID，默认0。

function SetCrosshair( crosshair: int )

📘 GUI.GetCrosshair()

获取准星样式ID。

function GetCrosshair(): int

📘 GUI.SetCrosshairActive()

设置准星是否可见，默认false。

function SetCrosshairActive( active: bool )

📘 GUI.GetCrosshairActive()

获取准星是否可见。

function GetCrosshairActive(): bool

📘 GUI.SetCrosshairColor()

设置准星默认颜色，默认Color(255, 255, 255)。

function SetCrosshairColor( color: Color )

📘 GUI.GetCrosshairColor()

获取准星默认颜色。

function GetCrosshairColor(): Color

📘 GUI.SetCrosshairScale()

设置准星默认缩放大小，默认1.0。

function SetCrosshairScale( scale: float )

📘 GUI.GetCrosshairScale()

获取准星默认缩放。

function GetCrosshairScale(): float

📘 GUI.FocusCrosshair()

激活一次准星反馈，例如击中后的动画效果。

动画效果会在指定time时间后自动复原。

function FocusCrosshair( time: float = 0.5, crosshair: int = -1, scale: float = 1.2, color: Color = Color(255, 255, 255) )

• time：激活一次的动画时间
• crosshair：激活时的临时准星ID（默认-1，表示使用当前准星）
• scale：激活时的准星缩放（缩放大小，而非缩放倍数）
• color：激活时的准星颜色

📘 GUI.FocusCrosshairText()

激活一次准星文本反馈（准星下方的文本标签）。

如果time参数填写为0，则表示文本将持续存在，否则将在指定时间内淡出。

function FocusCrosshairText( text: string, time: float = 1.5 )

📒 Property

📘 gui.Package

获取当前GUI实例的包名（只读）。

gui.Package: string

📘 gui.Component

获取当前GUI实例的组件名（只读）。

gui.Component: string

📘 gui.Panel

获取当前GUI实例的UIPanel对象，通常情况下无需使用此属性。

gui.Panel: UIPanel

📘 gui.UI

获取当前GUI实例的根对象（GObject），通常情况下无需使用此属性。

gui.UI: GObject

📘 gui.SortingOrder

设置当前GUI实例的层级，默认为0（范围：-1~50），请勿频繁调用此代码。

gui.SortingOrder = 0; //int

📒 Static Function

📘 GUI.Create()

生成一个新的GUI实例。

function GUI.Create( package: string, component: string ): GUI

//创建一个包名为ABC、组件名为ComA的GUI实例
GUI.Create("ABC", "ComA");

📘 GUI.GetModelPreview()

获取指定已导入模型的缩略图（包括外部导入模型），返回类型为FGUI可读的NTexture，可供FGUI直接使用。

function GUI.GetModelPreview( model: int ): NTexture

let texture = GUI.GetModelPreview(2000);
xxxxx.texture = texture; //FGUI API

📘 GUI.TextureToUI()

将引擎内原生\外部导入的图片转换为FGUI可读类型（NTexture）。

function GUI.TextureToUI( texture: int ): NTexture

let texture = GUI.TextureToUI(10000);
xxxxx.texture = texture; //FGUI API

📒 Function

📘 gui.Remove()

移除并销毁当前GUI实例。

function gui.Remove()

📘 gui.GetChild()

寻找并获取当前GUI实例的指定子元件（对象），如不存在则返回null。

function gui.GetChild( child: string ): GObject //FairyGUI对象