meta data for this page
  •  

📚 差别

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

到此差别页面的链接

两侧同时换到之前的修订记录前一修订版
后一修订版		前一修订版
scripting:world:core [2025/06/13 07:51] – ↷ 页面名由scripting:world:main改为scripting:world:core bibiboxsscripting:world:core [2025/12/03 10:50] (当前版本) – bibiboxs
行 1: 行 1:
 <markdown> <markdown>
-# World/Core*+# ==World/Core==
  
 ## Event ## Event
行 73: 行 73:
    
  
-### OnTimeChange( oldTime, newTime )+### OnWorldTimeChange( oldTime, newTime )
  
 > 当世界时间发生改变时调用。 > 当世界时间发生改变时调用。
  
 ```javascript ```javascript
-function OnTimeChange( oldTime, newTime )+function OnWorldTimeChange( oldTime, newTime )
 { {
     DLog("OldTime: " + oldTime.Hour + "-" + oldTime.Minute);     DLog("OldTime: " + oldTime.Hour + "-" + oldTime.Minute);
     DLog("NewTime: " + newTime.Hour + "-" + newTime.Minute);     DLog("NewTime: " + newTime.Hour + "-" + newTime.Minute);
 } }
 +```
 +
 +
 +
 +### OnWorldWeatherChange( oldWeather, newWeather )
 +
 +> 当世界天气发生改变时调用。
 +
 +```javascript
 +function OnWorldWeatherChange( oldWeather: int, newWeather: int )
 ``` ```
  
行 318: 行 328:
 ### SetTime() ### SetTime()
  
-> 设置当前游戏世界时间。+> 设置当前世界时间。
 > >
 > **注意：每次加载新世界场景后，时间都将重新替换为【地图文件配置——默认时间】。** > **注意：每次加载新世界场景后，时间都将重新替换为【地图文件配置——默认时间】。**
行 330: 行 340:
 ### GetWorldTime() ### GetWorldTime()
  
-> 获取游戏世界时间实例（`WorldTime`）。+> 获取当前世界时间实例（`WorldTime`）。
  
 ```javascript ```javascript
行 341: 行 351:
 ### SetWorldTimeRate() ### SetWorldTimeRate()
  
-> 设置当前游戏世界时间速率（游戏时间每分钟的时间间隔），默认为`1.0`。+> 设置游戏世界时间速率（游戏时间每分钟的时间间隔），默认为`1.0`。
 > >
 > 此方法是`SetGameRule("timerate")`的快捷API。 > 此方法是`SetGameRule("timerate")`的快捷API。
行 355: 行 365:
 ### GetWorldTimeRate() ### GetWorldTimeRate()
  
-> 获取游戏世界时间速率（游戏时间每分钟的时间间隔）。+> 获取世界时间速率（游戏时间每分钟的时间间隔）。
  
 ```javascript ```javascript
行 365: 行 375:
 ### SetWorldWeather() ### SetWorldWeather()
  
-> 设置游戏世界天气，具体参考[天气ID](reference/instances)文档。+> 设置世界天气，具体参考[天气ID](reference/instances)文档。
 > >
 > **注意：每次加载新世界场景后，天气都将重新替换为【地图文件配置——随机天气（天气池）】。** > **注意：每次加载新世界场景后，天气都将重新替换为【地图文件配置——随机天气（天气池）】。**
行 377: 行 387:
 ### GetWorldWeather() ### GetWorldWeather()
  
-> 获取游戏世界天气。+> 获取世界天气。
  
 ```javascript ```javascript
行 387: 行 397:
 ### GetRandomWorldWeather() ### GetRandomWorldWeather()
  
-> 随机获取游戏世界天气，获取方式根据参数决定。+> 随机获取世界天气，获取方式根据参数决定。
  
 ```javascript ```javascript
行 399: 行 409:
 ### SetWorldGravity() ### SetWorldGravity()
  
-> 设置游戏世界物理重力，分别为`横向X、纵向Y、前后Z`，默认为`Vector(0.0, -1.0, 0.0)`（正常下落的引力，且没有方向偏移）。+> 设置世界物理重力，分别为`横向X、纵向Y、前后Z`，默认为`Vector(0.0, -1.0, 0.0)`（正常下落的引力，且没有方向偏移）。
  
 ```javascript ```javascript
行 409: 行 419:
 ### GetWorldGravity() ### GetWorldGravity()
  
-> 获取游戏世界物理重力。+> 获取世界物理重力。
  
 ```javascript ```javascript
行 419: 行 429:
 ### SetWorldBrightness() ### SetWorldBrightness()
  
-> 设置游戏世界亮度偏移，默认为`1.0`。+> 设置世界亮度偏移，默认为`1.0`。
 >  > 
 > 对于特定的场景或游戏玩法（如丧尸游戏），开发者可能希望将此值调低以营造更好的黑夜效果。 > 对于特定的场景或游戏玩法（如丧尸游戏），开发者可能希望将此值调低以营造更好的黑夜效果。
行 431: 行 441:
 ### GetWorldBrightness() ### GetWorldBrightness()
  
-> 获取游戏世界亮度偏移。+> 获取世界亮度偏移。
  
 ```javascript ```javascript
行 442: 行 452:
 ### SetWorldColor() ### SetWorldColor()
  
-> 设置游戏世界叠加色调，默认为白色`Color(255, 255, 255)`。+> 设置世界叠加色调，默认为白色`Color(255, 255, 255)`。
 > >
  
行 453: 行 463:
 ### GetWorldColor() ### GetWorldColor()
  
-> 获取游戏世界叠加色调。+> 获取世界叠加色调。
  
 ```javascript ```javascript
行 463: 行 473:
 ### SetWorldFogColor() ### SetWorldFogColor()
  
-> 设置游戏世界雾颜色，默认为白色`Color(180, 180, 180)`。+> 设置世界雾颜色，默认为白色`Color(180, 180, 180)`。
 >  > 
 > 此方法是`SetGameRule("fogcolor")`的快捷方法。 > 此方法是`SetGameRule("fogcolor")`的快捷方法。
行 475: 行 485:
 ### GetWorldFogColor() ### GetWorldFogColor()
  
-> 获取游戏世界雾颜色。+> 获取世界雾颜色。
  
 ```javascript ```javascript
行 485: 行 495:
 ### SetWorldSolarColor() ### SetWorldSolarColor()
  
-> 设置游戏世界日月颜色（太阳&月亮），默认为淡黄色`Color(255, 240, 126)`。+> 设置世界日月颜色（太阳&月亮），默认为淡黄色`Color(255, 253, 235)`。
  
 ```javascript ```javascript
行 495: 行 505:
 ### GetWorldSolarColor() ### GetWorldSolarColor()
  
-> 获取游戏世界日月颜色（太阳&月亮）。+> 获取世界日月颜色（太阳&月亮）。
  
 ```javascript ```javascript
行 505: 行 515:
 ### SetWorldSolarScale() ### SetWorldSolarScale()
  
-> 设置游戏世界日月尺寸缩放（太阳&月亮），默认为`1.0`，限制范围`0.0~10.0`。+> 设置世界日月尺寸缩放（太阳&月亮），默认为`1.0`，限制范围`0.0~10.0`。
  
 ```javascript ```javascript
行 515: 行 525:
 ### GetWorldSolarScale() ### GetWorldSolarScale()
  
-> 获取游戏世界日月尺寸缩放（太阳&月亮）。+> 获取世界日月尺寸缩放（太阳&月亮）。
  
 ```javascript ```javascript
 function GetWorldSolarScale(): float function GetWorldSolarScale(): float
 +```
 +
 +
 +
 +### SetWorldCloudColor()
 +
 +> 设置世界云层颜色，默认为浅灰色`Color(180, 180, 180)`。
 +
 +```javascript
 +function SetWorldCloudColor( color: Color )
 +```
 +
 +
 +
 +### GetWorldCloudColor()
 +
 +> 获取世界**云层颜色**。
 +
 +```javascript
 +function GetWorldCloudColor(): Color
 +```
 +
 +
 +
 +### SetWorldCloudDensity()
 +
 +> 设置世界**云层密度（强度）**，默认为`0.5`，限制范围`0.0~1.0`。
 +
 +```javascript
 +function SetWorldCloudDensity( density: float )
 +```
 +
 +
 +
 +### GetWorldCloudDensity()
 +
 +> 获取世界**云层密度（强度）**。
 +
 +```javascript
 +function GetWorldCloudDensity(): float
 ``` ```
  
行 525: 行 575:
 ### SetSkybox() ### SetSkybox()
  
-> 设置游戏世界天空盒，默认为`0`。+> 设置世界天空盒，默认为`0`。
  
 ```javascript ```javascript
行 535: 行 585:
 ### GetSkybox() ### GetSkybox()
  
-> 获取游戏世界天空盒。+> 获取世界天空盒。
  
 ```javascript ```javascript
行 545: 行 595:
 ### SetSkyboxColor() ### SetSkyboxColor()
  
-> 设置游戏世界天空盒叠加色调，默认为`Color(128, 128, 128)`。+> 设置世界天空盒叠加色调，默认为`Color(128, 128, 128)`。
  
 ```javascript ```javascript
行 555: 行 605:
 ### GetSkyboxColor() ### GetSkyboxColor()
  
-> 获取游戏世界天空盒叠加色调。+> 获取世界天空盒叠加色调。
  
 ```javascript ```javascript
 function GetSkyboxColor(): Color function GetSkyboxColor(): Color
 +```
 +
 +
 +
 +### SetSkyboxNightColor()
 +
 +> 设置世界天空盒叠加色调（夜间\黑暗），默认为`Color(0, 0, 60)`。
 +> 
 +> 注意：阴天、雨天等天气变化时（变暗），也会受到此颜色的影响。
 +
 +```javascript
 +function SetSkyboxNightColor( color: Color )
 +```
 +
 +
 +
 +### GetSkyboxNightColor()
 +
 +> 获取世界天空盒叠加色调（夜间\黑暗）。
 +
 +```javascript
 +function GetSkyboxNightColor(): Color
 ``` ```
  
行 575: 行 647:
 ### GetSkyboxOffset() ### GetSkyboxOffset()
  
-> 获取游戏世界天空盒偏移（高度）。+> 获取世界天空盒偏移（高度）。
  
 ```javascript ```javascript
行 585: 行 657:
 ### SetSkyboxRotateSpeed() ### SetSkyboxRotateSpeed()
  
-> 设置游戏世界天空盒旋转速度，默认`1.0`。+> 设置世界天空盒旋转速度，默认`1.0`。
 > >
 > 如果设置为`0`则固定角度，如果设置为`-1`则使用地图默认速度。 > 如果设置为`0`则固定角度，如果设置为`-1`则使用地图默认速度。
行 597: 行 669:
 ### GetSkyboxRotateSpeed() ### GetSkyboxRotateSpeed()
  
-> 获取游戏世界天空盒旋转速度。+> 获取世界天空盒旋转速度。
  
 ```javascript ```javascript
行 683: 行 755:
 ### Message() ### Message()
  
-> 给全服在线玩家发送一条公屏消息（在消息框中）。+> 给全部玩家发送一条公屏消息（在消息框中）。
  
 ```javascript ```javascript
行 693: 行 765:
 ### Announce() ### Announce()
  
-> 给全服在线玩家发送一条**公告\大文字**消息，具体类型样式参考[《世界资源实例汇总》](https://sengine.mp-gamer.com/reference/instances)。+> 给全部玩家发送一条**公告\大文字**消息，具体类型样式参考[《世界资源实例汇总》](https://sengine.mp-gamer.com/reference/instances)。
  
 ```javascript ```javascript
行 703: 行 775:
 ### Subtitle() ### Subtitle()
  
-> 给全服在线玩家发送一条**底部字幕**消息。+> 给全部玩家发送一条**底部字幕**消息。
  
 ```javascript ```javascript
行 965: 行 1037:
 ```javascript ```javascript
 function ResumeWorldSound( uuid: string ): bool //返回false表示不存在UUID实例 function ResumeWorldSound( uuid: string ): bool //返回false表示不存在UUID实例
-``` 
- 
- 
- 
-### SetWorldSound() 
- 
-> 设置一个**服务器世界声音实例**的网络世界`World`（不同世界将无法听到声音）。 
- 
-```javascript 
-function SetWorldSound( uuid: string, world: int ): bool //返回false表示不存在UUID实例 
 ``` ```
  
行 1013: 行 1075:
  
  
-### SetPropSourceData()+### WriteHostFile()
  
-> 设置**指定游戏道具**默认原始数据（重写），建议场景初始化时使用，本次场景内有效。+> 写入文件（或以`/`结尾的文件夹）到模组**主机目录**`Mod/Host`，写入文件尺寸限制4MB，如果文件已存在则会覆盖。
 > >
-> **注意：由于`PropData`的数据类型，通过此方法设置数据后，仅会在`character.SetProp()`时赋予最新的道具数据，如果数据在`character.SetProp()`后才进行修改，则之前生成的Prop不会使用最新数据。**+> 此功能通常用于实现**游戏存档\配置**等，可以使用`Json`功能进行序列化。
  
 ```javascript ```javascript
-function SetPropSourceData( prop: int, keyPath: string, value: any )+function WriteHostFile( localPath: string, content: string = null )
 ``` ```
  
-```javascript 
-SetPropSourceData(277, "Multiple", 100); //set RPG multiple to 100 
-``` 
  
  
 +### ReadHostFile()
  
-### GetPropSourceData()+> 从模组**主机目录**（`Mod/Host`）读取文件（文本内容），如果文件不存在则返回**空白文本**。
  
-> 获取**指定游戏道具**最新默认原始数据，如果未被`SetPropSourceData`重写过，则返回引擎原始数据。+```javascript 
 +function ReadHostFile( localPath: string ): string 
 +```
  
 ```javascript ```javascript
-function GetPropSourceData( prop: int, keyPath: string ): any+ReadFile( "Test.txt" ); //read: Mod/Space/Test.txt
 ``` ```
  
  
  
-### ClearPropSourceData()+### CopyHostFile()
  
-> 清空**指定游戏道具**修改数据，恢复使用引擎原始数据。 +> 从模组**主机目录**（`Mod/Host`）复制文件到新位置。
-> +
-> **注意：此方法不会更新已被生成的Prop。**+
  
 ```javascript ```javascript
-function ClearPropSourceData( prop: int )+function CopyHostFile( localPath: string, pasteLocalPath: string ): bool
 ``` ```
  
 +```javascript
 +CopyHostFile( "Test.txt", "Test2.txt" );
 +```
  
  
-### ClearAllPropSourceData() 
  
-> 清空**全部游戏道具**修改数据，恢复使用引擎原始数据。 +### RenameHostFile() 
-> + 
-> **注意：此方法不会更新已被生成的Prop。**+> 从模组**主机目录**（`Mod/Host`）修改文件名称到新位置。
  
 ```javascript ```javascript
-function ClearAllPropSourceData()+function RenameHostFile( localPath: string, renameLocalPath: string, isReplace: bool = false ): bool
 ``` ```
  
 +- `isReplace`如果目标文件已存在，是否强制替换
  
  
-### WriteFile() 
  
-> 写入一个文件到模组空间目录`Mod/Space`，安全起见，写入文件尺寸限制2MB，且有最大文件数量限制（`Space`目录最多可写`50`个文件）。 +### ExistHostFile() 
-> + 
-> 此功能通常用于实现**游戏\服务器存档、配置**等写入，建议使用JSON功能进行序列化。+> 判断模组**主机目录**（`Mod/Host`）文件（或以`/`结尾的文件夹）是否存在。
  
 ```javascript ```javascript
-function WriteFile( fileName: string, content: string )+function ExistHostFile( localPath: string ): bool
 ``` ```
  
  
  
-### ReadFile()+### DeleteHostFile()
  
-> 从模组空间目录（`Mod/Space`）读取一个文件（文本内容），如果文件不存在则返回空白文本。+> 删除模组**主机目录**（`Mod/Host`）文件（或以`/`结尾的文件夹，以及所有子文件）。 
 +> 
 +> 注意：删除操作是**不可恢复**的，谨慎使用。
  
 ```javascript ```javascript
-function ReadFile( fileName: string ): string+function DeleteHostFile( localPath: string )
 ``` ```
  
-```javascript +
-ReadFile( "Test.txt" ); //read: Mod/Space/Test.txt +
-```+
  
 ### SetModArchive() ### SetModArchive()
  
 +> **此方法已在V0.83移除。**
 +>
 > 设置并覆盖**当前模组**的持久化存储数据（字符串，可通过Json扩展，最长限制512字符）。 > 设置并覆盖**当前模组**的持久化存储数据（字符串，可通过Json扩展，最长限制512字符）。
 > >
 > 数据内容存储到`ModArchive.json`文件，**任意模组之间可相互获取，但只有当前模组可写入自身数据**。 > 数据内容存储到`ModArchive.json`文件，**任意模组之间可相互获取，但只有当前模组可写入自身数据**。
-> 
-> ==（出于安全考虑，此方法仅限World端使用，Client端是只读的）== 
  
 ```javascript ```javascript
行 1103: 行 1165:
 ### GetModArchive() ### GetModArchive()
  
 +> **此方法已在V0.83移除。**
 +>
 > 尝试读取**指定模组**的持久化存储数据（可通过`SetModArchive()`写入修改），如不存在则返回空文本。 > 尝试读取**指定模组**的持久化存储数据（可通过`SetModArchive()`写入修改），如不存在则返回空文本。
 > >
行 1109: 行 1173:
 ```javascript ```javascript
 function GetModArchive( package: string = null ): string function GetModArchive( package: string = null ): string
-``` 
- 
- 
- 
-### SetSaveItem() 
- 
-> 设置并覆盖【存档数据槽（`Slot`）】指定`Key`的项目，并以最终Json的格式存储，仅支持基础类型（`string\number\bool...`）。 
-> 
-> 存档槽默认参数为`0`，如果只用于本地持久化数据存储，或者不需要多存档槽的设计，可以忽略`Slot`参数。 
-> 
-> **注意：此方法最多支持50个存档槽（文件），以及单文件最大1MB的写入空间。有关持久化存档相关内容，无论是单存档、多存档或其他使用场景，都可尝试此方案进行存储。** 
-> 
-> ==（出于安全考虑，此方法仅限World端使用，Client端是只读的）== 
- 
-```javascript 
-function SetSaveItem( key: string, value: object, slot: int = 0 ) 
-``` 
- 
-```javascript 
-SetSaveItem("gold", 1000, 0); //Save file to 'SaveData/SaveData_0.json' 
-SetSaveItem("playerlevel", 3, 5); //Save file to 'SaveData/SaveData_5.json' 
-``` 
- 
- 
- 
-### RemoveSaveItem() 
- 
-> 移除【存档数据槽（`Slot`）】指定`Key`的项目**（并非删除存档，而是删除存档中的一个项）**。 
-> 
-> ==（出于安全考虑，此方法仅限World端使用，Client端是只读的）== 
- 
-```javascript 
-function RemoveSaveItem( key: string, slot: int = 0 ) 
-``` 
- 
-```javascript 
-SetSaveItem("playerlevel", 3, 10); //Set level to 3 
-RemoveSaveItem("playerlevel", 10); //Remove 'playerlevel' item 
-``` 
- 
- 
- 
-### GetSaveItem() 
- 
-> 尝试读取【存档数据槽（`Slot`）】指定`Key`的项目内容，如不存在则返回`defaultValue`。 
- 
-```javascript 
-function GetSaveItem( key: string, slot: int = 0, defaultValue: any = null ): any 
-``` 
- 
-```javascript 
-SetSaveItem("gold", 1000); //Save file to 'Host/SaveData_0.json' 
-DLog("Your coin: " + GetSaveItem("gold")); 
-``` 
- 
- 
- 
-### ExistSaveItem() 
- 
-> 判断【存档数据槽（`Slot`）】指定`Key`的**项目内容是否为空（`bool`）**。 
- 
-```javascript 
-function ExistSaveItem( key: string, slot: int = 0 ): bool 
-``` 
- 
-```javascript 
-DLog(ExistSaveItem("gold")); 
-``` 
- 
- 
- 
-### ExistSaveData() 
- 
-> 判断【存档数据槽（`Slot`）】存档文件是否已被创建（`bool`）。 
- 
-```javascript 
-function ExistSaveData( slot: int = 0 ): bool 
-``` 
- 
- 
- 
-### DeleteSaveData() 
- 
-> 删除【存档数据槽（`Slot`）】存档文件，包括其文件内所有数据。 
-> 
-> ==（出于安全考虑，此方法仅限World端使用）== 
- 
-```javascript 
-function DeleteSaveData( slot: int = 0 ): bool 
 ``` ```
  
行 1204: 行 1179:
 ### SendSocketData() ### SendSocketData()
  
-> 发送Socket\Network网络通信数据。+> 发送`Socket\Network`网络通信数据。
 > >
 > **在当前版本下，此方法主要用于外部UDP传输。** > **在当前版本下，此方法主要用于外部UDP传输。**
 > >
-> **对应接收事件：`OnDataServerReceive`**+> **对应接收事件：`OnDataServerReceive`。**
  
 ```javascript ```javascript
行 1221: 行 1196:
  
  
-### SetNavMeshDirtyByPos()+### ReplaceTerrainLayer()
  
-> 重置指定坐标的NavMesh脏数据，该区域范围内的NavMesh（如存在）将会在后续自动重建。 +> 尝试**替换修改**地形层贴图，具体参考[地形层贴图ID](reference/instances)文档。 
-> +>  
-> 此方法通常不需要手动调用，除非希望动态生成对象参与NavMesh寻路逻辑，这样就需要在合适的时机对发生变化的区域进行重建，因为区域的NavMesh可能在之前已经烘焙完成。+> 注意：此方法会产生些许开销，如果一个层的`layer`已经被替换 ，那么下一次需要使用新的`layer`来进行后续替换。 
 + 
 +[note] 
 +在游戏场景运行时，会对**使用较少**的贴图自动进行**剔除优化**，因此可能少数情况下会出现**无法找到贴图**的提示。 
 +[/note]
  
 ```javascript ```javascript
-function SetNavMeshDirtyByPos( pos: Vector )+function ReplaceTerrainLayer( layer: int, newLayer: int )
 ``` ```
  
  
  
-### GetNavMeshRandomPoint() 
  
-> 获取指定坐标范围内的随机NavMesh坐标点（已烘焙）。 
-> 
-> 如果范围内不存在合适的坐标，将返回`VECTOR_NULL`。 
  
-```javascript 
-function GetNavMeshRandomPoint( pos: Vector, radius: float ): Vector 
-``` 
  
  
  
-### IsValidNavMeshPoint() 
  
-> 判断指定坐标是否已被烘焙完成（即合理的寻路坐标）。 
-> 
-> 如果返回`false`则表示此区域没有被烘焙，关于AI的移动逻辑也无法到达目标。 
  
-[note2] 
- 
-通常情况下，关于AI的移动将会在设置目标点时自动请求烘焙（可能会在数秒内完成），如果确实需要主动激活某处NavMesh烘焙，请使用`SetNavMeshDirtyByPos()`。 
- 
-[/note] 
- 
-```javascript 
-function IsValidNavMeshPoint( pos: Vector ): bool 
-```