meta data for this page
  •  

📚 差别

这里会显示出您选择的修订版和当前版本之间的差别。

到此差别页面的链接

两侧同时换到之前的修订记录前一修订版
后一修订版		前一修订版
scripting:client:gui [2025/05/20 05:54] – bibiboxsscripting:client:gui [2025/08/09 20:20] (当前版本) – bibiboxs
行 1: 行 1:
 <markdown> <markdown>
 # Client/GUI # Client/GUI
- 
-在沙盘引擎当前版本GUI系统中，**所有关于UI实例均是基于[FairyGUI框架](https://fairygui.com/)作为核心基础**。 
- 
-在此前提下，开发者可**使用【FairyGUI编辑器】进行快速可视化的UI制作**，同时搭配`JavaScript`代码直接操作**`FairyGUI`对象**以控制UI逻辑。 
- 
-换句话说，沙盘引擎有关GUI部分，除了少数引擎内置代码外（如创建UI），其他代码部分均可通过`FairyGUI`原生代码\函数进行操作和调用。 
- 
-```javascript 
-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功能参考》](developer/function/gui "《GUI功能参考》")，以详细了解GUI功能作用及原理。**== 
  
  
行 77: 行 57:
 ```javascript ```javascript
 GUI.ControlAwayTime: float GUI.ControlAwayTime: float
 +```
 +
 +
 +
 +## Property
 +
 +### gui.Package
 +
 +> 获取当前GUI实例的包名（只读）。
 +
 +```javascript
 +gui.Package: string
 +```
 +
 +
 +
 +### gui.Component
 +
 +> 获取当前GUI实例的组件名（只读）。
 +
 +```javascript
 +gui.Component: string
 +```
 +
 +
 +
 +### gui.Panel
 +
 +> 获取当前GUI实例的`UIPanel`对象，通常情况下无需使用此属性。
 +
 +```javascript
 +gui.Panel: UIPanel
 +```
 +
 +
 +
 +### gui.UI
 +
 +> 获取当前GUI实例的根对象（`GObject`），通常情况下无需使用此属性。
 +
 +```javascript
 +gui.UI: GObject
 +```
 +
 +
 +
 +### gui.SortingOrder
 +
 +> 设置当前GUI实例的层级，默认为0（`范围：-1~50`），请勿频繁调用此代码。
 +
 +```javascript
 +gui.SortingOrder = 0; //int
 ``` ```
  
行 82: 行 114:
  
 ## Static Function ## Static Function
 +
 +### GUI.Create()
 +
 +> 生成一个新的**GUI实例**。
 +
 +```javascript
 +function GUI.Create( package: string, component: string ): GUI
 +```
 +
 +```javascript
 +//创建一个包名为ABC、组件名为ComA的GUI实例
 +GUI.Create("ABC", "ComA");
 +```
 +
 +
 +
 +### GUI.GetModelPreview()
 +
 +> 获取指定已导入模型的缩略图（包括外部导入模型），返回类型为FGUI可读的`NTexture`，可供FGUI直接使用。
 +
 +```javascript
 +function GUI.GetModelPreview( model: int ): NTexture
 +```
 +
 +```javascript
 +let texture = GUI.GetModelPreview(2000);
 +xxxxx.texture = texture; //FGUI API
 +```
 +
 +
 +
 +### GUI.TextureToUI()
 +
 +> 将引擎内原生\外部导入的图片转换为FGUI可读类型（`NTexture`）。
 +
 +```javascript
 +function GUI.TextureToUI( texture: int ): NTexture
 +```
 +
 +```javascript
 +let texture = GUI.TextureToUI(10000);
 +xxxxx.texture = texture; //FGUI API
 +```
 +
 +
 +
 +### GUI.RemoveAll()
 +
 +> 移除并销毁所有GUI实例（`gui.Remove()`）。
 +
 +```javascript
 +function GUI.RemoveAll()
 +```
 +
 +
 +
 +### GUI.WorldPosToUI()
 +
 +> 获取世界坐标（3D）转换后的UI（2D）坐标。
 +
 +```javascript
 +function GUI.WorldPosToUI( worldPos: Vector ): Vector2
 +```
 +
 +
 +
 +### GUI.PopupMenu()
 +
 +> 创建弹出菜单（类似右键菜单）。
 +
 +```javascript
 +function GUI.PopupMenu( data: any )
 +```
 +
 +```javascript
 +GUI.PopupMenu(
 +    {
 +        Title: "Test Menu",
 +        Width: 300,
 +        Items: [
 +            {
 +                Item: "Item 1",
 +                OnClick: () => {
 +                    Debug.Log("Clicked Item 1");
 +                }
 +            }, {
 +                Item: "Item 2",
 +                OnClick: () => {
 +                    Debug.Log("Clicked Item 2");
 +                }
 +            }, {
 +                Item: "-" //Seperator
 +            }, {
 +                Item: "Item 3",
 +                OnClick: () => {
 +                    Debug.Log("Clicked Item 3");
 +                }
 +            }
 +        ]
 +    }
 +);
 +```
 +
 +
 +
 +### GUI.HidePopup()
 +
 +> 关闭（隐藏）任何弹出类型的窗口、菜单。
 +
 +```javascript
 +function GUI.HidePopup()
 +```
 +
 +
  
 ### GUI.SetPureMode() ### GUI.SetPureMode()
  
 > 设置GUI纯净模式开关（是否渲染UI），此属性可能有助于拍摄模式。 > 设置GUI纯净模式开关（是否渲染UI），此属性可能有助于拍摄模式。
-> +>
 > **注意：此模式同时属于引擎内置功能，玩家可能通过快捷键或`[Esc]`进行开关。** > **注意：此模式同时属于引擎内置功能，玩家可能通过快捷键或`[Esc]`进行开关。**
  
 ```javascript ```javascript
-function SetPureMode( active: bool )+function GUI.SetPureMode( active: bool )
 ``` ```
  
行 100: 行 246:
  
 ```javascript ```javascript
-function GetPureMode(): bool+function GUI.GetPureMode(): bool
 ``` ```
  
行 112: 行 258:
  
 ```javascript ```javascript
-function SetCursor( cursorID: int )+function GUI.SetCursor( cursorID: int )
 ``` ```
  
行 122: 行 268:
  
 ```javascript ```javascript
-function GetCursor(): int+function GUI.GetCursor(): int
 ``` ```
  
行 136: 行 282:
  
 ```javascript ```javascript
-function SetCursorActive( active: bool = true )+function GUI.SetCursorActive( active: bool = true )
 ``` ```
  
行 146: 行 292:
  
 ```javascript ```javascript
-function GetCursorActive(): bool+function GUI.GetCursorActive(): bool
 ``` ```
  
行 156: 行 302:
  
 ```javascript ```javascript
-function SetCrosshair( crosshair: int )+function GUI.SetCrosshair( crosshair: int )
 ``` ```
  
行 166: 行 312:
  
 ```javascript ```javascript
-function GetCrosshair(): int+function GUI.GetCrosshair(): int
 ``` ```
  
行 176: 行 322:
  
 ```javascript ```javascript
-function SetCrosshairActive( active: bool )+function GUI.SetCrosshairActive( active: bool )
 ``` ```
  
行 186: 行 332:
  
 ```javascript ```javascript
-function GetCrosshairActive(): bool+function GUI.GetCrosshairActive(): bool
 ``` ```
  
行 196: 行 342:
  
 ```javascript ```javascript
-function SetCrosshairColor( color: Color )+function GUI.SetCrosshairColor( color: Color )
 ``` ```
  
行 206: 行 352:
  
 ```javascript ```javascript
-function GetCrosshairColor(): Color+function GUI.GetCrosshairColor(): Color
 ``` ```
  
行 216: 行 362:
  
 ```javascript ```javascript
-function SetCrosshairScale( scale: float )+function GUI.SetCrosshairScale( scale: float )
 ``` ```
  
行 226: 行 372:
  
 ```javascript ```javascript
-function GetCrosshairScale(): float+function GUI.GetCrosshairScale(): float
 ``` ```
  
行 238: 行 384:
  
 ```javascript ```javascript
-function FocusCrosshair( time: float = 0.5, crosshair: int = -1, scale: float = 1.2, color: Color = Color(255, 255, 255) )+function GUI.FocusCrosshair( time: float = 0.5, crosshair: int = -1, scale: float = 1.2, color: Color = Color(255, 255, 255) )
 ``` ```
  
行 245: 行 391:
 - **`scale`：**激活时的准星缩放（缩放大小，而非缩放倍数） - **`scale`：**激活时的准星缩放（缩放大小，而非缩放倍数）
 - **`color`：**激活时的准星颜色 - **`color`：**激活时的准星颜色
- 
  
  
行 256: 行 401:
  
 ```javascript ```javascript
-function FocusCrosshairText( text: string, time: float = 1.5 )+function GUI.FocusCrosshairText( text: string, time: float = 1.5 )
 ``` ```
  
  
  
-## Property+### GUI.IsOccupied()
  
-### gui.Package+> 获取当前是否UI界面被占用（使用中）。 
 +> 
 +> 举例：当界面**主菜单、游戏设置、多人游戏浏览器、NativeMenu**等**优先性界面**正在显示时，此方法将返回`true`。
  
-> 获取当前GUI实例的包名（只读）。+```javascript 
 +function GUI.IsOccupied(): bool 
 +``` 
 + 
 + 
 + 
 +### GUI.GetKey() 
 + 
 +> 获取**指定按键**是否正在按住。
  
 ```javascript ```javascript
-gui.Package: string+function GUI.GetKey( key: string, isForce: bool = false ): bool
 ``` ```
  
 +- `isForce`是否强制获取（不考虑UI占用状态）
  
  
-### gui.Component 
  
-> 获取当前GUI实例的组件名（只读）。+### GUI.GetKeyDown() 
 + 
 +> 获取**指定按键**是否正在按下。 
 +> 
 +> 注意：此方法仅在实时帧中有意义，单帧检测应该使用`GetKey()`。
  
 ```javascript ```javascript
-gui.Component: string+function GUI.GetKeyDown( key: string, isForce: bool = false ): bool
 ``` ```
  
 +- `isForce`是否强制获取（不考虑UI占用状态）
  
  
-### gui.Panel 
  
-> 获取当前GUI实例的`UIPanel`对象，通常情况下无需使用此属性。+### GUI.GetKeyUp() 
 + 
 +> 获取**指定按键**是否正在抬起。 
 +> 
 +> 注意：此方法仅在实时帧中有意义，单帧检测应该使用`GetKey()`。
  
 ```javascript ```javascript
-gui.Panel: UIPanel+function GUI.GetKeyUp( key: string, isForce: bool = false ): bool
 ``` ```
  
 +- `isForce`是否强制获取（不考虑UI占用状态）
  
  
-### gui.UI 
  
-> 获取当前GUI实例的根对象（`GObject`），通常情况下无需使用此属性。+### GUI.SetChatPanelActive() 
 + 
 +> 设置游戏聊天框启用开关，当聊天框被禁止后，玩家将无法显示或开启聊天框。 
 +> 
 +> *此功能主要用于主菜单界面，此时通常不希望玩家使用“聊天”功能，在`Main`场景中是默认被禁止的。*
  
 ```javascript ```javascript
-gui.UI: GObject+function GUI.SetChatPanelActive( active: bool )
 ``` ```
  
  
  
-### gui.SortingOrder+### GUI.GetChatPanelActive()
  
-> 设置当前GUI实例的层级，默认为0（`范围：-1~50`），请勿频繁调用此代码。+> 获取游戏聊天框开关。
  
 ```javascript ```javascript
-gui.SortingOrder = 0; //int+function GUI.GetChatPanelActive(): bool
 ``` ```
  
  
  
-## Static Function+### GUI.SetChatPanelPivot()
  
-### GUI.Create()+> 设置游戏聊天框锚点位置（强制），默认值为`-1`（遵循游戏默认设置），通过此方法设定位置后，即使玩家在游戏选项设置了锚点位置，也会优先使用当前方法所设置的位置。 
 +> 
 +> *此功能适用于部分U丰富的模组，可能不希望聊天框占用模组UI位置（例如血条、状态条、信息面板等），可以使用此方法强制设定聊天框位置。*
  
-> 生成一个新的GUI实例。+```javascript 
 +function GUI.SetChatPanelPivot( pivot: int = -1 ) 
 +```
  
 ```javascript ```javascript
-function GUI.Create( package: string, component: string ): GUI+GUI.SetChatPanelPivot(-1); //Use engine config (default) 
 +GUI.SetChatPanelPivot(0); //Change pivot to Left_Top 
 +GUI.SetChatPanelPivot(1); //Change pivot to Left_Center 
 +GUI.SetChatPanelPivot(2); //Change pivot to Left_Bottom
 ``` ```
 +
 +
 +
 +### GUI.GetChatPanelPivot()
 +
 +> 获取游戏聊天框锚点位置。
  
 ```javascript ```javascript
-//创建一个包名为ABC、组件名为ComA的GUI实例 +function GUI.GetChatPanelPivot(): int
-GUI.Create("ABC", "ComA");+
 ``` ```
  
  
  
-### GUI.GetModelPreview()+### GUI.CreateNativeView()
  
-> 获取指定已导入模型的缩略图（包括外部导入模型），返回类型为FGUI可读的`NTexture`，可供FGUI直接使用。+> 打开一个引擎内置UI面板（如设置、服务器列表、MOD管理器等）。
  
 ```javascript ```javascript
-function GUI.GetModelPreview( model: int ): NTexture+function GUI.CreateNativeView( int type, Action onDisable = null )
 ``` ```
 +
 +| ID   | 面板描述               |
 +| ---- | ---------------------- |
 +| 0    | 开发者界面（关于界面） |
 +| 1    | 游戏设置               |
 +| 2    | 多人游戏浏览器         |
 +| 4    | ~~MOD模组管理~~        |
 +
 +*尽管有些ID没有被表格记录，但有可能仍然是有内容的，但未被记录的ID通常不具备通用性意义，在打开时将会被引擎阻断。*
 +
 +
 +
 +### GUI.ExistNativeView()
 +
 +> 检查某个引擎内置UI界面是否存在（被打开）。
  
 ```javascript ```javascript
-let texture = GUI.GetModelPreview(2000); +function GUI.ExistNativeView( type: int ): bool
-xxxxx.texture = texture; //FGUI API+
 ``` ```
  
  
  
-### GUI.TextureToUI()+### GUI.DestroyNativeView()
  
-> 将引擎内原生\外部导入的图片转换为FGUI可读类型（`NTexture`）。+> 关闭一个引擎内置UI面板。
  
 ```javascript ```javascript
-function GUI.TextureToUI( texture: int ): NTexture+function GUI.DestroyNativeView(type: int = -1, hasEffect: bool = true) 
 +//如果不填写参数（-1），则默认关闭所有内置UI面板 
 +//如果hasEffect == false则立即关闭面板
 ``` ```
 +
 +
 +
 +### GUI.BindGameMenuButton()
 +
 +> 绑定当前场景自定义ESC菜单按钮。
 +>
 +> 此方法适用于对模组主菜单**没有特殊\高级自定义需求**（否则应该考虑使用FairyGUI自制菜单），可以通过此方法**快速**的建立一个**游戏原生主菜单**。
 +>
 +> **注意：此方法通常只需要在主菜单场景执行一次，绑定代码只在当前场景生效，==切换场景后将会自动重置默认绑定==。**
 +
 +[note2]
 +
 +此方法支持绑定内置（宏）按钮，这将直接引用引擎内置按钮（功能及翻译），详情可参考下方表格。
 +
 +**如果绑定的是一个内置按钮，则只需要填写参数0即可。**
 +
 +| 内置按钮（宏） | 说明                                                         |
 +| -------------- | ------------------------------------------------------------ |
 +| `@default`     | 绑定默认引擎菜单（游戏选项、多人游戏、地图编辑器、开发者名单、引擎首页、退出游戏……） |
 +| `@space`       | 绑定显示空行（分割显示）                                     |
 +| `@options`     | 游戏选项                                                     |
 +| `@multiplayer` | 多人游戏浏览器                                               |
 +| `@mapeditor`   | 地图编辑器                                                   |
 +| `@developers`  | 开发者名单                                                   |
 +| `@native`      | 沙盘引擎首页（模组选择页）                                   |
 +| `@quit`        | 退出游戏                                                     |
 +
 +[/note]
 +
 +[note3]
 +
 +注意：当玩家处于非主菜单（初始Main场景）界面时，引擎会自动补充**继续游戏**、**返回主菜单**额外的菜单按钮。
 +
 +[/note]
  
 ```javascript ```javascript
-let texture = GUI.TextureToUI(10000); +function GUI.BindGameMenuButton( titleOrKey: string, info: string = null, callback: Action = null ) 
-xxxxx.texture = texture; //FGUI API+``` 
 + 
 +以下是一个示例。 
 + 
 +```javascript 
 +function OnScriptLoad() 
 +{ 
 +    //Custom Item 
 + GUI.BindGameMenuButton("启动主机", "建立本地联机服务器", () => { 
 + CreateHost("mapname", "scriptname"); 
 + }); 
 + GUI.BindGameMenuButton("[color=#ffff00]加入本地服务器[/color]", "加入本地服务器（127.0.0.1）", () => { 
 + ConnectHost("127.0.0.1"); 
 + }); 
 +     
 +    //Internal Item 
 +    GUI.BindGameMenuButton("@space"); 
 +    GUI.BindGameMenuButton("@mapeditor"); 
 +} 
 +``` 
 + 
 + 
 + 
 +### GUI.UnbindAllGameMenuButton() 
 + 
 +> 取消绑定所有主菜单界面按钮项目（包括引擎默认按钮）。 
 +> 
 +> **注意：此方法会清空所有菜单按钮，如果希望重置为默认引擎按钮，应该手动执行一次`BindGameMenuButton("@default");`。** 
 + 
 +```javascript 
 +function GUI.UnbindAllGameMenuButton() 
 +``` 
 + 
 + 
 + 
 +### GUI.SetGameMenuTitle() 
 + 
 +> 设置游戏菜单**标题文本**（支持宏文本），留空参数则使用默认名称（模组名称）。 
 + 
 +```javascript 
 +function GUI.SetGameMenuTitle( text: string = null ) 
 +``` 
 + 
 + 
 + 
 +### GUI.GetGameMenuTitle() 
 + 
 +> 获取游戏菜单**标题文本**。 
 + 
 +```javascript 
 +function GUI.GetGameMenuTitle(): string 
 +``` 
 + 
 + 
 + 
 +### GUI.SetGameMenuStyle() 
 + 
 +> 设置游戏菜单**风格样式**，默认值为`0`。 
 + 
 +```javascript 
 +function GUI.SetGameMenuStyle( style: int ) 
 +``` 
 + 
 +| Style            | 样式                                                         | 
 +| ---------------- | ------------------------------------------------------------ | 
 +| -1==（已过时）== | 隐藏内置游戏菜单，通常配合`FairyGUI`高度自定义使用<br />（仅限Main主菜单，游戏世界仍然使用内置菜单风格） | 
 +| **0（默认）**    | **内置菜单风格，但使用`\GameMenu.png || \Cover.png`作为不透明底图** | 
 +| 1                | 内置风格菜单，但不显示背景图片，直接显示世界相机视角         | 
 + 
 + 
 + 
 +### GUI.GetGameMenuStyle() 
 + 
 +> 获取游戏菜单**风格样式**。 
 + 
 +```javascript 
 +function GUI.GetGameMenuStyle(): int
 ``` ```
  
行 364: 行 670:
 ### gui.Remove() ### gui.Remove()
  
-> 移除并销毁当前GUI实例。+> 移除并销毁当前**GUI实例**。
 > >
  
行 375: 行 681:
 ### gui.GetChild() ### gui.GetChild()
  
-> 寻找并获取当前GUI实例的指定子元件（对象），如不存在则返回`null`。+> 寻找并获取当前**GUI实例**的指定子元件（对象），如不存在则返回`null`。 
 +> 
 +> 有关**GUI实例**对象（`GUIPanel`），参考[GUI Element](scripting/client/guielement)。
  
 ```javascript ```javascript
-function gui.GetChild( child: string ): GObject //FairyGUI对象+function gui.GetChild( child: string ): GUIPanel
 ``` ```
 +
 +
 +