Choose your operating system:
Windows
macOS
Linux
本页面将介绍 远程控制API 提供的WebSocket消息类型。本页面结束时,会提供一个内含JavaScript函数的HTML示例文件,用以演示如何使用和测试这些WebSocket消息。
引擎中的WebSocket端口默认为30020。使用
ws://127.0.0.1:30020
地址连接到WebSocket服务器,开始发送消息。你可以为自己的项目更改WebSocket端口。
-
在编辑器的主菜单中,选择 编辑(Edit)> 编辑项目设置...(Edit Project Settings…) ,打开 项目设置(Project Settings) 窗口。
-
在 项目设置(Project Settings) 窗口中,在 插件(Plugins) 部分中选择 Web远程控制(Web Remote Control) 。
-
将字段 远程控制WebSocket服务器端口(Remote Control WebSocket Server Port) 的值更改为想要使用的端口。
WebSocket消息
远程控制API使用JSON格式发送WebSocket消息。所有发送到服务器的WebSocket消息必须是JSON对象,且具有以下属性:
属性 |
说明 |
---|---|
MessageName |
识别要发送的消息类型。选项包括:
|
参数 |
各个消息类型的参数。详情请参见以下各节。 |
Id |
可选:非常有用的标识符,供来自服务器的延迟响应所用。 |
WebSocket消息类型 - HTTP
使用此消息类型通过WebSocket消息调用HTTP路由。有关可调用的HTTP路由的详细信息,请参阅 远程控制API HTTP参考 。
JSON格式消息示例:
{
"MessageName": "http",
"Parameters": {
"Url": "/remote/object/property",
"Verb": "PUT",
"Body": {
"ObjectPath": "/Game/ThirdPersonBP/Maps/ThirdPersonExampleMap.ThirdPersonExampleMap:PersistentLevel.CubeMesh_5.StaticMeshComponent0",
"propertyName": "StreamingDistanceMultiplier",
"access": "READ_ACCESS"
}
}
}
WebSocket服务器将返回一条JSON消息,以响应调用:
{
"RequestId": -1,
"ResponseCode": 200,
"ResponseBody": {
"StreamingDistanceMultiplier": 1
}
}
WebSocket消息类型 - Preset.Register
使用此消息类型订阅 远程控制预设 发出的事件。JSON格式消息示例:
{
"MessageName": "preset.register",
"Parameters": {
"PresetName": "MyPreset"
}
}
以下各节描述由预设发出的事件及其JSON消息。
远程控制预设事件 - PresetFieldsChanged
每当预设中公开属性的值被修改时,都将发送此消息。
{
"Type": "PresetFieldsChanged",
"PresetName": "MyPreset",
"ChangedFields": [
{
"PropertyLabel": "Relative Rotation (LightSource_0)",
"ObjectPath": "/Game/ThirdPersonBP/Maps/ThirdPersonExampleMap.ThirdPersonExampleMap:PersistentLevel.LightSource_0.LightComponent0",
"PropertyValue": {
"Pitch": 14.4,
"Yaw": 0,
"Roll": 169.2
}
}
]
}
远程控制预设事件 - PresetFieldsAdded
每当预设中有新的公开属性加入时,都将发送此消息。响应仅包括属性添加到的组。
{
"Type": "PresetFieldsAdded",
"PresetName": "MyPreset",
"Description": {
"Name": "MyPreset",
"Path": "/Game/Presets/MyPreset.MyPreset",
"Groups": [
{
"Name": "Lighting",
"ExposedProperties": [
{
"DisplayName": "Light Color (LightSource_0)",
"UnderlyingProperty": {
"Name": "LightColor",
...
}
}
],
"ExposedFunctions": []
}
]
}
}
远程控制预设事件 - PresetFieldsRemoved
每当预设中的属性或函数被删除后,都将发送此消息。
{
"Type": "PresetFieldsRemoved",
"PresetName": "MyPreset",
"RemovedFields": [
"Light Color (LightSource_0)"
]
}
远程控制预设事件 - PresetFieldsRenamed
每当预设中的属性或函数被重命名后,都将发送此消息。
{
"Type": "PresetFieldsRenamed",
"PresetName": "MyPreset",
"RenamedFields": [
{
"OldFieldLabel": "Relative Rotation (LightSource_0)",
"NewFieldLabel": "Directional Light Rotation"
}
]
}
WebSocket消息类型 - Preset.Unregister
使用此消息类型取消订阅 远程控制预设 发出的事件。JSON格式消息示例:
{
"MessageName": "preset.unregister",
"Parameters": {
"PresetName": "MyPreset"
}
}
HTML/JavaScript示例文件
-
在名为 index.html 的文件中保存以下代码:
<!DOCTYPE html> <html> <head></head> <body> <h3 id="status">Connection Closed</h3> <input id="in"></input> <button id="btn" onclick="sendMessage()">Register Preset</button> <div id="holder"></div> <script> // WebSocket连接成功时,用于保存该连接的变量。 var connection = null; /** * 此函数发送WebSocket消息,以订阅远程控制预设发出的事件。 * 远程控制预设由用户在HTML输入字段中指定。 */ function sendMessage() { if (connection) { let input = document.getElementById("in"); const registerPayload = { "MessageName": "preset.register", "Parameters": { "PresetName": `${input.value}` } }; connection.send(JSON.stringify(registerPayload)); } } /** * 每次加载页面时都会调用此函数。 * 该函数设置一个WebSocket连接,如果连接成功,则更新页面并显示"连接打开(Connection Open)"。 * 从WebSocket服务器接收到的任何消息,都将从JSON转换成HTML元素并显示在页面上。 * 该函数还会在控制台中记录完整的JSON消息响应。 */ window.onload = function() { console.log("Starting test") connection = new WebSocket('ws://127.0.0.1:30020'); connection.onopen = function () { document.getElementById("status").innerHTML = "Connection Open"; }; connection.onerror = function (error) {}; connection.onmessage = function (message) { if (message.data instanceof Blob) { reader = new FileReader(); reader.onload = () => { let holder = document.getElementById("holder"); let par = document.createElement("pre"); par.style = style="white-space: pre-line"; let json = JSON.parse(reader.result); let text = json.Type; par.innerHTML = text; holder.appendChild(par); console.log(reader.result) }; reader.readAsText(message.data); } else {} }; connection.onclose = function(event) { console.log("WebSocket is closed now."); }; } </script> </body> </html>
-
在Web浏览器中打开index.html文件。如果能够成功连接WebSocket服务器,页面将显示 连接打开(Connection Open) 。
-
在输入字段中输入 远程控制预设 的名称,并更改预设的字段。
-
打开浏览器的控制台日志,确认记录了响应消息。