meta data for this page
  •  

📚 差别

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

到此差别页面的链接

两侧同时换到之前的修订记录前一修订版
后一修订版		前一修订版
developer:define [2025/07/24 19:55] – 移除 - 外部编辑 (Unknown date) 127.0.0.1developer:define [2025/12/03 17:03] (当前版本) – bibiboxs
行 1: 行 1:
 +<markdown>
 +# 宏文本
  
 +> 沙盘引擎 内置了一些**“宏代码（Define）”**，搭配相关API使用，可以将指定宏文本转换为实时获取结果的文本。
 +>
 +> **常用案例：网络传输后的本地翻译、内置信息获取（如玩家人数、版本等）、绑定按键映射等。**
 +
 +
 +
 +## 常规宏文本
 +
 +[note2]
 +
 +**常规宏文本的表示方式：`%define_key%`**
 +
 +[/note]
 +
 +
 +
 +### 本地翻译案例
 +
 +例如开发者制作了一个团队射击游戏，通常会在有玩家被击杀后输出杀敌信息到公屏，代码看起来应该像这样：
 +
 +```javascript
 +if(killer.Entity.Group == 1)
 +{
 + Message("CT-Team: " + killer.Entity.Name + " killed " + player.Entity.Name );
 +}else if(killer.Entity.Group == 2){
 +    Message("T-Team: " + killer.Entity.Name + " killed " + player.Entity.Name );
 +}
 +```
 +
 +这样的代码本身没有什么问题，但是如果希望**不同地区玩家最终看到的是本地翻译后的结果**，这就需要使用宏定义来实现。
 +
 +首先，开发者应该按照规范自定义好语言文件，然后记住要使用的语言Key（例如：`Mod.TeamGroup.CT | T`）。
 +
 +```javascript
 +if(killer.Entity.Group == 1)
 +{
 + Message("%Mod.TeamGroup.CT%: " + killer.Entity.Name + " killed " + player.Entity.Name );
 +}
 +}else if(killer.Entity.Group == 2){
 +    Message("%Mod.TeamGroup.T%: " + killer.Entity.Name + " killed " + player.Entity.Name );
 +}
 +```
 +使用此方式发送的消息（`Message | Announce | Subtitle...`）会自动将宏文本（`%xxx%`）进行识别，如果语言Key正确且存在，则会在消息到达玩家本地后，自动识别为玩家本地的语言。
 +
 +**这样即可解决不同地区的玩家最终得到不同的翻译结果。**
 +
 +
 +
 +### 内置信息案例
 +
 +例如开发者希望输出一些内置信息，可参考引擎已存在的**本地宏文本（可参考下方）**，按需进行使用。
 +
 +```javascript
 +Message("Your EngineVersion: %EngineVersion%"); //"Your EngineVersion: V0.77"
 +Message("Current Players: %PlayerCount%"); //"Current Players: 1"
 +```
 +
 +
 +
 +### 绑定按键案例
 +
 +有时开发者希望提醒玩家：“按下[?]键使用某功能”，如果开发者直接绑定按键代码，可以直接告知玩家服务器绑定的按键。
 +
 +但如果开发者使用更为标准的`BindNativeKey`绑定按键流程（允许玩家自定义按键），这就有可能出现玩家修改了默认按键的情况，此情况下需要获取到实时正确的按键代码，此问题可通过**本地按键宏文本**来解决。
 +
 +```javascript
 +Message("Press %KEY_World_Use% use!"); //"Press "F" use!
 +```
 +
 +[note2]
 +
 +需要注意的是，如何让引擎知道这是一个**本地按键宏文本**？
 +
 +**没错，任何以`KEY_`开头的宏文本均被优先认为是按键宏文本。**
 +
 +[/note]
 +
 +
 +
 +## 引擎宏示例
 +
 +> 特别提醒：由于宏的机制，宏文本应该用于最终本地玩家解析，因此最终获取的结果也是本地玩家解析后的结果。
 +
 +| 宏文本            | 功能说明                             |
 +| ----------------- | ------------------------------------ |
 +| `%Language%`      | 正在使用的引擎语言名称               |
 +| `%ModLanguage%`   | 正在使用的模组语言名称               |
 +| `%PlayerCount%`   | 当前世界玩家数量                     |
 +| `%EngineVersion%` | 引擎版本信息                         |
 +| `%EngineEdition%` | 游戏授权版本（标准版、白金版）       |
 +| `%Engine%`        | 引擎版权信息                         |
 +| `%EveryOne%`      | 翻译：`Native.Common.LocalDefine[0]` |
 +| `%PlayerName%`    | 本地玩家名称                         |
 +| `%FPS%`           | 本地游戏帧数                         |
 +
 +
 +
 +## 宏文本API
 +
 +> 默认情况下，宏文本可以直接在`Message | Announce | Subtitle...`等功能自动进行解析，但如果有特殊或手动解析的需求，可以使用[相关API](scripting/native/core#formatdefinetext)过滤一次字符串。
 +
 +**宏文本解析API：`FormatDefineText( text: string, includeColor: bool = true );`**
 +
 +
 +
 +## 资源引用宏
 +
 +[note2]
 +
 +**资源引用宏与常规宏文本的用法有些差异，其更多应用于UI部分。**
 +
 +[/note]
 +
 +
 +
 +### UI引用案例
 +
 +在游戏UI设计过程中，有时可能希望使用一些资源图片加入到UI文本中，这可以很简单的利用**资源引用宏**的机制来实现。
 +
 +> 得益于FairyGUI支持UBB语法的机制，沙盘引擎内置UI（如NativeMenu）支持UBB语法的图片置入。
 +>
 +> 图片语法：
 +> ```
 +> <img src='imgurl' width='48' height='48'/>
 +> ```
 +
 +开发者可通过此方法进行UI文本的图文混合搭配，但有时可能希望使用本地模组的相关Texture资源，这只需要将`imgurl`替换为**资源引用宏**即可，此方法同样支持ID_10000+的模组自定义资源。
 +
 +例如：使用TextureID_100的图片资源
 +```
 +Text: "<img src='sesprite://100' width='48' height='48'/> Test Title"
 +```
 +
 +
 +
 +
 +### 资源宏示例
 +
 +| 宏文本                        | 功能说明                 |
 +| ----------------------------- | ------------------------ |
 +| `sesprite://` +`textureID`   | 获取指定Texture+ID资源   |
 +| `secursor://` +`textureID`    | 获取指定Cursor+ID资源    |
 +| `seradaricon://` +`textureID` | 获取指定RadarIcon+ID资源 |
 +| `seprop://` +`textureID` | 获取指定Prop+ID资源 |
 +| `semodel://` +`textureID` | 获取指定Model+ID资源 |
 +
 +
 +
 +
 +
 +
 +
 +
 +
 +
 +
 +
 +
 +</markdown>