meta data for this page
  •  

📚 差别

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

到此差别页面的链接

两侧同时换到之前的修订记录前一修订版
后一修订版		前一修订版
scripting:client:gui [2023/09/16 11:10] – bibiboxsscripting:client:gui [2025/08/09 20:20] (当前版本) – bibiboxs
行 2: 行 2:
 # Client/GUI # Client/GUI
  
-在沙盘引擎当前版本GUI系统中，**所有关于UI实例均是基于[FairyGUI框架](https://fairygui.com/)作为核心基础**。 
  
-在此前提下，开发者可**使用【FairyGUI编辑器】进行快速可视化的UI制作**，同时搭配`JavaScript`代码直接操作`FairyGUI对象`以控制UI逻辑。 
  
-换句话说，沙盘引擎有关GUI部分，除了少数引擎内置代码外（如创建UI），其他代码部分均可通过`FairyGUI`原生代码\函数进行操作和调用。+## Static Property
  
-```javascript +### GUI.MousePos
-let gui = GUI.Create("Package1", "Component1"); //引擎代码，以来创建一个UI对象 +
-let button = gui.GetChild("n0"); //引擎代码，寻找加载UI中的某个子元件+
  
-button.onClick.Set(() => { //FairyGUI原生代码，按照JavaScript格式来写即可 +> 获取玩家鼠标坐标位置（2D平面坐标）。 
-    DLog("onClick!"); + 
-    button.TweenScale(Vector2(2, 2), 1); //部分情况下，FairyGUI代码需要提供的是 Vector2 对象 +```javascript 
-});+GUI.MousePos: Vector
 ``` ```
  
-==**注意：沙盘引擎与`FairyGUI`同样建议使用【1个根组件+N个子组件】的方式进行UI创建，而不是分别在不同位置创建不同的UI小组件。**== 
  
-==**提示：在开始使用GUI相关功能之前，建议优先阅读[《GUI功能参考》](developer/mod/gui "《GUI功能参考》")，以详细了解GUI功能作用及原理。**== 
  
 +### GUI.MouseScroll
  
 +> 获取玩家**鼠标滚轮滚动偏移量**（自动归0）。
 +>
 +> **（向上 > 0 > 向下 ）**
  
 +```javascript
 +GUI.MouseScroll: float
 +```
  
  
-## Property 
  
-### GUI.MousePos+### GUI.FixedMouseScroll
  
-> 获取玩家鼠标坐标位置。+> 获取玩家**鼠标滚轮滚动（修正）偏移量**（自动归0），此属性停留在UI时永远返回`0`（避免误操作）。 
 +> 
 +> **（向上 > 0 > 向下 ）**
  
 ```javascript ```javascript
-GUI.MousePos: Vector+GUI.FixedMouseScroll: float
 ``` ```
  
  
  
-### GUI.MouseScroll+### GUI.InputAwayTime
  
-> 获取玩家鼠标滚轮滚动偏移量（自动归0）。+> 获取玩家输入（键盘）空闲时间（玩家在此时间内没有使用键盘）。
 > >
-> **（向上 > 0 > 向下 ）** 
  
 ```javascript ```javascript
-GUI.MouseScroll: float+GUI.InputAwayTime: float
 ``` ```
  
  
  
----+### GUI.ControlAwayTime 
 + 
 +> 获取玩家控制（鼠标）空闲时间（玩家在此时间内没有使用及移动鼠标）。 
 + 
 +```javascript 
 +GUI.ControlAwayTime: float 
 +``` 
 + 
 + 
 + 
 +## Property
  
 ### gui.Package ### gui.Package
行 106: 行 117:
 ### GUI.Create() ### GUI.Create()
  
-> 生成一个新的GUI实例。+> 生成一个新的**GUI实例**。
  
 ```javascript ```javascript
行 115: 行 126:
 //创建一个包名为ABC、组件名为ComA的GUI实例 //创建一个包名为ABC、组件名为ComA的GUI实例
 GUI.Create("ABC", "ComA"); 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纯净模式开关（是否渲染UI），此属性可能有助于拍摄模式。
 +>
 +> **注意：此模式同时属于引擎内置功能，玩家可能通过快捷键或`[Esc]`进行开关。**
 +
 +```javascript
 +function GUI.SetPureMode( active: bool )
 +```
 +
 +
 +
 +### GUI.GetPureMode()
 +
 +> 获取GUI纯净模式开关。
 +
 +```javascript
 +function GUI.GetPureMode(): bool
 +```
 +
 +
 +
 +### GUI.SetCursor()
 +
 +> 设置当前使用的光标ID，默认为`0`，具体类型样式参考[《世界资源实例汇总》](reference/instances)。
 +>
 +> 每次加载新的世界场景后，光标样式将重置到默认值。
 +
 +```javascript
 +function GUI.SetCursor( cursorID: int )
 +```
 +
 +
 +
 +### GUI.GetCursor()
 +
 +> 获取当前使用的光标ID，默认为`0`。
 +
 +```javascript
 +function GUI.GetCursor(): int
 +```
 +
 +
 +
 +### GUI.SetCursorActive()
 +
 +> 设置鼠标是否可见，通常游戏时不可见，菜单或需要操作UI时可见。
 +>
 +> 每次加载新的世界场景后，此属性将重置到默认值（可见）。
 +>
 +> 注意：当弹出操作UI时会自动转变为可见状态，开发者无需过多干预这部分逻辑。
 +
 +```javascript
 +function GUI.SetCursorActive( active: bool = true )
 +```
 +
 +
 +
 +### GUI.GetCursorActive()
 +
 +> 获取鼠标是否可见。
 +
 +```javascript
 +function GUI.GetCursorActive(): bool
 +```
 +
 +
 +
 +### GUI.SetCrosshair()
 +
 +> 设置准星样式ID，默认`0`。
 +
 +```javascript
 +function GUI.SetCrosshair( crosshair: int )
 +```
 +
 +
 +
 +### GUI.GetCrosshair()
 +
 +> 获取准星样式ID。
 +
 +```javascript
 +function GUI.GetCrosshair(): int
 +```
 +
 +
 +
 +### GUI.SetCrosshairActive()
 +
 +> 设置准星是否可见，默认`false`。
 +
 +```javascript
 +function GUI.SetCrosshairActive( active: bool )
 +```
 +
 +
 +
 +### GUI.GetCrosshairActive()
 +
 +> 获取准星是否可见。
 +
 +```javascript
 +function GUI.GetCrosshairActive(): bool
 +```
 +
 +
 +
 +### GUI.SetCrosshairColor()
 +
 +> 设置准星默认颜色，默认`Color(255, 255, 255)`。
 +
 +```javascript
 +function GUI.SetCrosshairColor( color: Color )
 +```
 +
 +
 +
 +### GUI.GetCrosshairColor()
 +
 +> 获取准星默认颜色。
 +
 +```javascript
 +function GUI.GetCrosshairColor(): Color
 +```
 +
 +
 +
 +### GUI.SetCrosshairScale()
 +
 +> 设置准星默认缩放大小，默认`1.0`。
 +
 +```javascript
 +function GUI.SetCrosshairScale( scale: float )
 +```
 +
 +
 +
 +### GUI.GetCrosshairScale()
 +
 +> 获取准星默认缩放。
 +
 +```javascript
 +function GUI.GetCrosshairScale(): float
 +```
 +
 +
 +
 +### GUI.FocusCrosshair()
 +
 +> 激活一次准星反馈，例如击中后的动画效果。
 +>
 +> 动画效果会在指定`time`时间后自动复原。
 +
 +```javascript
 +function GUI.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，则表示文本将持续存在，否则将在指定时间内淡出。
 +
 +```javascript
 +function GUI.FocusCrosshairText( text: string, time: float = 1.5 )
 +```
 +
 +
 +
 +### GUI.IsOccupied()
 +
 +> 获取当前是否UI界面被占用（使用中）。
 +>
 +> 举例：当界面**主菜单、游戏设置、多人游戏浏览器、NativeMenu**等**优先性界面**正在显示时，此方法将返回`true`。
 +
 +```javascript
 +function GUI.IsOccupied(): bool
 +```
 +
 +
 +
 +### GUI.GetKey()
 +
 +> 获取**指定按键**是否正在按住。
 +
 +```javascript
 +function GUI.GetKey( key: string, isForce: bool = false ): bool
 +```
 +
 +- `isForce`是否强制获取（不考虑UI占用状态）
 +
 +
 +
 +### GUI.GetKeyDown()
 +
 +> 获取**指定按键**是否正在按下。
 +>
 +> 注意：此方法仅在实时帧中有意义，单帧检测应该使用`GetKey()`。
 +
 +```javascript
 +function GUI.GetKeyDown( key: string, isForce: bool = false ): bool
 +```
 +
 +- `isForce`是否强制获取（不考虑UI占用状态）
 +
 +
 +
 +### GUI.GetKeyUp()
 +
 +> 获取**指定按键**是否正在抬起。
 +>
 +> 注意：此方法仅在实时帧中有意义，单帧检测应该使用`GetKey()`。
 +
 +```javascript
 +function GUI.GetKeyUp( key: string, isForce: bool = false ): bool
 +```
 +
 +- `isForce`是否强制获取（不考虑UI占用状态）
 +
 +
 +
 +### GUI.SetChatPanelActive()
 +
 +> 设置游戏聊天框启用开关，当聊天框被禁止后，玩家将无法显示或开启聊天框。
 +>
 +> *此功能主要用于主菜单界面，此时通常不希望玩家使用“聊天”功能，在`Main`场景中是默认被禁止的。*
 +
 +```javascript
 +function GUI.SetChatPanelActive( active: bool )
 +```
 +
 +
 +
 +### GUI.GetChatPanelActive()
 +
 +> 获取游戏聊天框开关。
 +
 +```javascript
 +function GUI.GetChatPanelActive(): bool
 +```
 +
 +
 +
 +### GUI.SetChatPanelPivot()
 +
 +> 设置游戏聊天框锚点位置（强制），默认值为`-1`（遵循游戏默认设置），通过此方法设定位置后，即使玩家在游戏选项设置了锚点位置，也会优先使用当前方法所设置的位置。
 +>
 +> *此功能适用于部分U丰富的模组，可能不希望聊天框占用模组UI位置（例如血条、状态条、信息面板等），可以使用此方法强制设定聊天框位置。*
 +
 +```javascript
 +function GUI.SetChatPanelPivot( pivot: int = -1 )
 +```
 +
 +```javascript
 +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
 +function GUI.GetChatPanelPivot(): int
 +```
 +
 +
 +
 +### GUI.CreateNativeView()
 +
 +> 打开一个引擎内置UI面板（如设置、服务器列表、MOD管理器等）。
 +
 +```javascript
 +function GUI.CreateNativeView( int type, Action onDisable = null )
 +```
 +
 +| ID   | 面板描述               |
 +| ---- | ---------------------- |
 +| 0    | 开发者界面（关于界面） |
 +| 1    | 游戏设置               |
 +| 2    | 多人游戏浏览器         |
 +| 4    | ~~MOD模组管理~~        |
 +
 +*尽管有些ID没有被表格记录，但有可能仍然是有内容的，但未被记录的ID通常不具备通用性意义，在打开时将会被引擎阻断。*
 +
 +
 +
 +### GUI.ExistNativeView()
 +
 +> 检查某个引擎内置UI界面是否存在（被打开）。
 +
 +```javascript
 +function GUI.ExistNativeView( type: int ): bool
 +```
 +
 +
 +
 +### GUI.DestroyNativeView()
 +
 +> 关闭一个引擎内置UI面板。
 +
 +```javascript
 +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
 +function GUI.BindGameMenuButton( titleOrKey: string, info: string = null, callback: Action = null )
 +```
 +
 +以下是一个示例。
 +
 +```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
 ``` ```
  
行 123: 行 670:
 ### gui.Remove() ### gui.Remove()
  
-> 移除并销毁当前GUI实例。+> 移除并销毁当前**GUI实例**。
 > >
  
行 134: 行 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
 ``` ```
 +
 +
 +
 +
 +
 +
 +
 +
 +
  
  
 </markdown> </markdown>