网络远程控制端点参考

网络远程控制系统所提供端点的详细信息。

Windows
MacOS
Linux

本文介绍网络远程控制系统提供的端点,并详细说明调用每个端点时需要包含的消息正文的格式。

PUT远程/object/调用

用此端点可调用编辑器当前内存中由指定 UObject 公开的函数:通常是当前关卡的Actor或项目中的资源。

可以调用蓝图中所有可调用的函数。包括在C++中用 BlueprintCallable 说明符定义的函数,或完全在蓝图中定义和实现的函数。

调用此端点时,必须传递拥有以下属性的JSON负载:

属性

说明

object路径(objectPath)

该路径对所要交互的 UObject 进行独特标记。欲了解查找此路径的更多信息,请参见下面的关于UObject路径

函数名称(functionName)

要从指定 UObject 调用的函数的命名。如函数在C++中定义,其原始命名可能与蓝图中显示的命名不符。在此情况下,请使用C++中定义的函数命名。

参数(parameters)

对需传递给函数的参数进行定义的object。

  • 此object中每个属性的命名应与调用的函数所接受参数的命名相同。

    如函数在C++中定义,原始参数命名可能与在蓝图编辑器中看到的值不匹配。在此情况下,请使用C++中定义的参数命名。例如,下面代码中,第二个参数需指定为 bSweep,从而与其C++定义相匹配,但其在同等蓝图节点中公开为 Sweep

  • 该属性的值可是任何简单值,例如数字或布尔值。或者,如函数要求传递object,可提供可以封装该object属性的JSON object。远程控制系统将使用提供的值,尝试创建必要类型的新object。例如,下面代码中,新位置(NewLocation) 被自动用于创建新矢量。

对于该函数接受的每个参数,不必在此object中包含属性。对于省略的参数,网络远程控制系统将构造适当类型的默认object。

生成事务(generateTransaction)

定义编辑器是否应在项目的事务历史中记录此函数调用。将此属性设为 true 具备以下效果:

  • 函数所做的任何更改均可撤销。对于该函数的调用,编辑器会对项目 撤销历史 面板中的条目进行记录。在虚幻编辑器中工作的用户可回滚更改的效果。无论调用何种函数,该条目的命名始终为 远程调用事务封装(Remote Call Transaction Wrap)
    撤销历史中列出的远程事务

  • 如处于多用户编辑 会话中,该更改将复制至其他连接的用户。

该调用会返回JSON负载,其中包含已调用函数的返回值、以及函数定义中指定的所有其他输出参数。

范例

请求正文:

{
    "objectPath" :"/Game/ThirdPersonBP/Maps/ThirdPersonExampleMap.ThirdPersonExampleMap:PersistentLevel.CubeMesh_5",
    "functionName" :"SetActorLocation",
    "parameters" :{
        "NewLocation" :{"X" :100, "Y" :0, "Z" :30},   // 这些值用于创建新矢量
        "bSweep" : true
    },
    "generateTransaction" : true
}

成功的请求在以下响应正文中给出 200 个状态:

{
    "SweepHitResult":{  
        "bBlockingHit":true,
        "bStartPenetrating":false,
        "FaceIndex":-1,
        "Time":0.338644,
        "Distance":170.822,
        "Location":{ "X":100, "Y":0, "Z":429.178 },
        "ImpactPoint":{ "X":169, "Y":30, "Z":354 },
        "Normal":{ "X":-1.51964e-11, "Y":4.01851e-8, "Z":1 },
        "ImpactNormal":{ "X":-1.51964e-11, "Y":4.01851e-8, "Z":1 },
        "TraceStart":{ "X":100, "Y":0, "Z":600 },
        "TraceEnd":{ "X":100, "Y":0, "Z":100 },
        "PenetrationDepth":0,
        "Item":-1,
        "PhysMaterial":"",
        "Actor":"/Game/ThirdPersonBP/Maps/ThirdPersonExampleMap.ThirdPersonExampleMap:PersistentLevel.Bump_StaticMesh",
        "Component":"/Game/ThirdPersonBP/Maps/ThirdPersonExampleMap.ThirdPersonExampleMap:PersistentLevel.Bump_StaticMesh.StaticMeshComponent0",
        "BoneName":"None",
        "MyBoneName":"None"
    },
    "ReturnValue":true
}

在此情况下,由于 Engine/Source/Runtime/Engine/Classes/GameFramework/Actor.h 文件中的 SetActorLocation() 函数的原始定义将其定义为输出参数:即对函数调用产生的数据值的非常量引用,所以 SweepHitResult 会包含在返回值中。

PUT远程/object/属性

使用此端点可访问编辑器当前内存中由指定UObject公开的属性值:通常是Actor或资源。

如果访问的UObject是一个C++类的实例,它将包含在C++内被定义为属性,且可被蓝图访问的所有类成员,但受以下限制。

如果访问的UObject是一个蓝图类的实例,它将该类拥有的所有蓝图变量,但受以下限制。

此端点只能访问符合特定标准的属性:

  • 必须将该属性定义为 public,但不能为 privateprotected

  • 不得定义任何 BlueprintGetterBlueprintSetter 函数。如定义,必须在这些函数中使用上文中的 remote/object/call 端点,不得直接使用 remote/object/property 端点尝试读取或写入数值。

  • 如要在编辑器中访问该object,该属性必须设为 EditAnywhere。为修改该值,请勿将属性设为 EditConst

  • 如在 -游戏 模式或编辑器中运行(PIE)模式下访问object,其属性必须设为 BlueprintVisible。为修改该值,请勿将属性设为 BlueprintReadOnly

根据请求消息的构建方式,您可以:

  • 请求object公开的所有可用属性及其当前值。

  • 请求任何至少提供读取权限的属性的值。

  • 设置任何提供写入权限的属性的值。

调用此端点时,必须传递拥有以下属性的JSON负载:

属性

说明

object路径(objectPath)

该路径对所要交互的 UObject 进行独特标记。欲了解查找此路径的更多信息,请参见下面的关于UObject路径

属性(property)

要读取或修改的属性命名。如在 READ_ACCESS 的调用中忽略此属性,该响应将列出指定 UObject 上所有可用的可读属性。

访问(access)

定义对该属性发出的访问请求的类型。可为以下任意值:

  • READ_ACCESS 为正在请求的属性,或指定的 UObject 上的所有属性指定当前的值。

  • WRITE_ACCESS 为在 属性值(propertyValue) object中定义的一个或多个属性指定新值。

  • WRITE_TRANSACTION_ACCESSWRITE_ACCESS 相同,但会在项目的事务历史中记录属性值的更改。此操作与 remote/object/call 端点的 生成事务(generateTransaction) 相似。其拥有以下效果:

    • 编辑器处理属性修改的方式与虚幻编辑器 细节(Details) 面板中的修改方式完全相同。这可能需要调用编辑器中的更多代码,以便处理链接至该属性的更改前和更改后事件。

    • 如处于多用户编辑 会话中,该更改将被复制至其他连接的用户。

    • 此选项可撤销更改。如将此属性设置为 true,编辑器会在项目的 撤消历史(Undo History) 面板的条目中记录此属性的更改。在虚幻编辑器中工作的用户可回滚更改的效果。该条目的命名始终为 远程设置Object属性(Remote Set Object Property)
      远程设置Object属性

属性值(propertyValue)

使用 WRITE_ACCESSWRITE_TRANSACTION_ACCESS 发出请求时,可使用此object指定所要修改的属性、以及要为每个属性设置的新值。

必须是JSON object,其中每个字段的命名均与指定 UObject 上的可写属性的命名相匹配,且每个字段的值均是要为该属性所设的新值。

该调用会返回JSON负载,其中包含请求的信息或写入请求的结果。

范例

读取所有属性

请求正文:

{
    "objectPath" :"/Game/ThirdPersonBP/Maps/ThirdPersonExampleMap.ThirdPersonExampleMap:PersistentLevel.CubeMesh_5",
    "access" :"READ_ACCESS"
}

成功的请求在以下响应正文中给出 200 个状态:

{
    "bStaticMeshReplicateMovement": false,
    "NavigationGeometryGatheringMode":"Default",
    "PrimaryActorTick":{
        "TickGroup":"TG_PrePhysics",
        "EndTickGroup":"TG_PrePhysics",
        "bTickEvenWhenPaused": false,
        "bCanEverTick": false,
        "bStartWithTickEnabled": true,
        "bAllowTickOnDedicatedServer": true,
        "TickInterval":0
    },
    "bHidden": false,
    "bOnlyRelevantToOwner": false,
    "bAlwaysRelevant": false,
    "bReplicateMovement": false,
    "bNetLoadOnClient": true,
    "bNetUseOwnerRelevancy": false,
    "bRelevantForLevelBounds": true,
    "bReplayRewindable": false,
    "bAllowTickBeforeBeginPlay": false,
    "bBlockInput": false,
    "bCanBeDamaged": false,
    "bFindCameraComponentWhenViewTarget": true,
    "bGenerateOverlapEventsDuringLevelStreaming": false,
    "bIgnoresOriginShifting": false,
    "bEnableAutoLODGeneration": true,
    "bIsEditorOnlyActor": false,
    "ReplicatedMovement":{
        "LinearVelocity":{ "X":0, "Y":0, "Z":0 },
        "AngularVelocity":{ "X":0, "Y":0, "Z":0 },
        "Location":{ "X":0, "Y":0, "Z":0 },
        "Rotation":{ "Pitch":0, "Yaw":0, "Roll":0 },
        "bSimulatedPhysicSleep": false,
        "bRepPhysics": false,
        "LocationQuantizationLevel":"RoundWholeNumber",
        "VelocityQuantizationLevel":"RoundWholeNumber",
        "RotationQuantizationLevel":"ByteComponents"
    },
    "InitialLifeSpan":0,
    "NetDormancy":"DORM_Awake",
    "SpawnCollisionHandlingMethod":"AlwaysSpawn",
    "AutoReceiveInput":"Disabled",
    "InputPriority":0,
    "NetCullDistanceSquared":2.25e+08,
    "NetUpdateFrequency":100,
    "MinNetUpdateFrequency":2,
    "NetPriority":1,
    "SpriteScale":1,
    "Tags": []
}

读取单个属性

请求正文:

{
    "objectPath" :"/Game/ThirdPersonBP/Maps/ThirdPersonExampleMap.ThirdPersonExampleMap:PersistentLevel.CubeMesh_5.StaticMeshComponent0",
    "property" :"StreamingDistanceMultiplier",
    "access" :"READ_ACCESS",
}

成功的请求在以下响应正文中给出 200 个状态:

{
    "StreamingDistanceMultiplier":1
}

写入属性

请求正文:

{
    "objectPath" :"/Game/ThirdPersonBP/Maps/ThirdPersonExampleMap.ThirdPersonExampleMap:PersistentLevel.CubeMesh_5.StaticMeshComponent0",
    "access" :"WRITE_ACCESS",
    "propertyName" :"StreamingDistanceMultiplier",
    "propertyValue" :{
        "StreamingDistanceMultiplier" :2
    }
}

成功的请求会在空的响应正文中给出 200 个状态:

关于UObject路径

虚幻编辑器加载到内存中的每个资源和Actor均有一个路径对其进行唯一标识。此类路径主要用于编辑器内部,所以其不会以一种易于访问的方式直接向用户公开。而且它们是根据内部规则以编程方式确定,所以不易预测。

通常,这些object的路径遵循以下格式:

/path/PackageName.ObjectName:SubObjectName.SubObject

在C++中使用引擎的程序员可能认出这种格式与 FindObject()StaticFindObject() 等函数所接受的格式相同。

例如,解构上面请求范例中显示的Actor路径:

/Game/ThirdPersonBP/Maps/

内容浏览器中资源的路径。

ThirdPersonExampleMap.ThirdPersonExampleMap:

包的名称及其包含的object(对于许多资源而言这都是相同的)。

PersistentLevel.CubeMesh_5.StaticMeshComponent0

通过子object的层级,到达所要影响的object的路径。

这些路径不易查看,但以下部分将讲述一些获取方法。

撤销历史中的路径

修改UObject时,可在 撤销历史(Undo History) 面板中查看其路径。

  1. 点击面板右下角的过滤器图标,并启用 显示事务细节(Show transactions details)

    显示事务细节

  2. 对要访问的资源或Actor进行细微更改,例如将Actor移动至新位置。此操作在 撤销历史(Undo History)中会记录为新事务。

  3. 事务细节(Transaction Details) 面板中,将鼠标悬停在 已修改对象和属性(Modified objects and properties) 列的条目上。提示文本会包含高亮object的路径。

    提示文本中显示的Object路径

编辑脚本编辑工具中的路径

根据要远程执行的任务类型,网络应用程序应当了解当前关卡中可用的Actor或内容浏览器中存在的资源的路径,这可能很有帮助。为实现这一点,编辑器脚本编辑工具(Editor Scripting Utilities) 插件公开了一些实用函数,可用其与资源和关卡进行交互。

例如,EditorScriptingUtilities 模块中的 EditorLevelLibrary 类公开 GetAllLevelActors 函数,可对其进行全程调用,获取当前关卡中所有Actor的路径列表。向 remote/object/call 端点发送以下请求正文:

{
    "objectPath" :"/Script/EditorScriptingUtilities.Default__EditorLevelLibrary",
    "functionName":"GetAllLevelActors"
}

响应正文中的 返回值(ReturnValue) 域提供该关卡中所有Actor的一组路径。例如:

{
    "ReturnValue": [
        "/Game/ThirdPersonBP/Maps/ThirdPersonExampleMap.ThirdPersonExampleMap:PersistentLevel.LightmassImportanceVolume_0",
        "/Game/ThirdPersonBP/Maps/ThirdPersonExampleMap.ThirdPersonExampleMap:PersistentLevel.AtmosphericFog_1",
        "/Game/ThirdPersonBP/Maps/ThirdPersonExampleMap.ThirdPersonExampleMap:PersistentLevel.SkySphereBlueprint",
        "/Game/ThirdPersonBP/Maps/ThirdPersonExampleMap.ThirdPersonExampleMap:PersistentLevel.SphereReflectionCapture",
        "/Game/ThirdPersonBP/Maps/ThirdPersonExampleMap.ThirdPersonExampleMap:PersistentLevel.NetworkPlayerStart",
        "/Game/ThirdPersonBP/Maps/ThirdPersonExampleMap.ThirdPersonExampleMap:PersistentLevel.DocumentationActor1",
        "/Game/ThirdPersonBP/Maps/ThirdPersonExampleMap.ThirdPersonExampleMap:PersistentLevel.Linear_Stair_StaticMesh",
        "/Game/ThirdPersonBP/Maps/ThirdPersonExampleMap.ThirdPersonExampleMap:PersistentLevel.Bump_StaticMesh",
        "/Game/ThirdPersonBP/Maps/ThirdPersonExampleMap.ThirdPersonExampleMap:PersistentLevel.LeftArm_StaticMesh",
        "/Game/ThirdPersonBP/Maps/ThirdPersonExampleMap.ThirdPersonExampleMap:PersistentLevel.RightArm_StaticMesh",
        "/Game/ThirdPersonBP/Maps/ThirdPersonExampleMap.ThirdPersonExampleMap:PersistentLevel.Ramp_StaticMesh",
        "/Game/ThirdPersonBP/Maps/ThirdPersonExampleMap.ThirdPersonExampleMap:PersistentLevel.CubeMesh_5",
        "/Game/ThirdPersonBP/Maps/ThirdPersonExampleMap.ThirdPersonExampleMap:PersistentLevel.LightSource_0",
        "/Game/ThirdPersonBP/Maps/ThirdPersonExampleMap.ThirdPersonExampleMap:PersistentLevel.PostProcessVolume_0",
        "/Game/ThirdPersonBP/Maps/ThirdPersonExampleMap.ThirdPersonExampleMap:PersistentLevel.SkyLight_0",
        "/Game/ThirdPersonBP/Maps/ThirdPersonExampleMap.ThirdPersonExampleMap:PersistentLevel.Floor_1",
        "/Game/ThirdPersonBP/Maps/ThirdPersonExampleMap.ThirdPersonExampleMap:PersistentLevel.Wall7_4",
        "/Game/ThirdPersonBP/Maps/ThirdPersonExampleMap.ThirdPersonExampleMap:PersistentLevel.Wall9",
        "/Game/ThirdPersonBP/Maps/ThirdPersonExampleMap.ThirdPersonExampleMap:PersistentLevel.Wall10",
        "/Game/ThirdPersonBP/Maps/ThirdPersonExampleMap.ThirdPersonExampleMap:PersistentLevel.Wall11",
        "/Game/ThirdPersonBP/Maps/ThirdPersonExampleMap.ThirdPersonExampleMap:PersistentLevel.TextRenderActor_1",
        "/Game/ThirdPersonBP/Maps/ThirdPersonExampleMap.ThirdPersonExampleMap:PersistentLevel.MyBlueprint_5",
        "/Game/ThirdPersonBP/Maps/ThirdPersonExampleMap.ThirdPersonExampleMap:PersistentLevel.ThirdPersonCharacter_167"
    ]
}

欲了解安装 编辑器脚本编写工具(Editor Scripting Utilities) 插件的详细信息,请参见脚本编写和编辑器自动化

蓝图函数库路径

为了使用静态方法远程调用自定义蓝图函数库 ,对象路径必须指向类默认对象(CDO) ,也就是UCLASS维持的对象。指向CDO的对象路径必须遵循以下格式:

/Script/ModuleName.Default_ClassName

下列表格描述了 如何确定蓝图函数库的模块名称和类名。

模块名称(ModuleName)

模块名称(ModuleName)是DLL的名称,它包含了你所寻找的类。在Visual Studio项目中,有一个和模块同名的 .build.cs 文件,明确了该模块的构建方式以及该模块的依赖项。

类名(ClassName)

类名(ClassName)是类的名称,拥有一个UCLASS宏。

Select Skin
Light
Dark

欢迎来到全新虚幻引擎4文档站!

我们正在努力开发新功能,包括反馈系统,以便您能对我们的工作作出评价。但它目前还未正式上线。如果您对此页面有任何意见与在使用中遭遇任何问题,请前往文档反馈论坛告知我们。

新系统上线运行后,我们会及时通知您的。

发表反馈意见