虚幻引擎5文档已被迁移至 Epic开发者社区

Unreal Engine 4.26

Unreal Engine 4.27

Unreal Engine 5.0

Unreal Engine 5.1

Unreal Engine 5.2

Unreal Engine 5.3

> 建立你的开发流程 > 编辑器的脚本与自动化 > 网页远程控制 > 关于远程控制API WebSocket参考

Light Theme

Dark Theme

学习使用此测试功能，但在用它发布产品时请谨慎行事。

测试功能主要供您学习如何使用、规划工作流程和创建测试内容之用。 在实际生产中使用这些功能必须谨慎 ，因为我们仍在努力完善以使它们的性能、稳定性和平台支持达到发布水准。我们支持资源的向后兼容，这些功能的API也是稳定的。

关于远程控制API WebSocket参考

远程控制API提供的、用于远程控制引擎的WebSocket端点的详情。

Choose your operating system:

Windows

macOS

Linux

参见

本页面的内容

WebSocket消息
HTML/JavaScript示例文件

本页面将介绍 远程控制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	识别要发送的消息类型。选项包括： HTTP Preset.Register Preset.Unregister
参数	各个消息类型的参数。详情请参见以下各节。
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） 。
在输入字段中输入 远程控制预设 的名称，并更改预设的字段。
打开浏览器的控制台日志，确认记录了响应消息。

标签

Beta

Remote Control

欢迎帮助改进虚幻引擎文档！请告诉我们该如何更好地为您服务。

填写问卷调查

取消