Engine API
Introduction
The following document presents all the endpoints callable via Data Hub on a running Engine instance. All changes are applied immediately. However, changes to some properties of the World Settings in Live mode might result in a restart of Pixotope modules and a brief reduction in performance.
To learn about more advanced usage of these endpoints jump to: Advanced RPC Usage.
Object Setting
Calls allowing for scene manipulation.
SetProperty
Set a property value for a given actor. Apart from basic types, supports properties in structs, arrays and asset names.
Params:
ObjectSearch STRING ARRAY STRING Unique name of the target Actor, or Actor.Component, or a special_tag, or an array of multiple object searches. Hover over the star left of your property in the Engine to learn the desired value.
PropertyPath STRING ARRAY STRING Dot-separated path to the targeted property, or an array of such paths. Hover over the star left of your property in the Engine to learn the desired value.
Value STRING STRING ARRAY ANY The value to be applied. Strings are parsed into proper formats, but raw numbers should be (for the most part) supported too. If provided with an array will try to match to the array of PropertyPaths. Supports struct imports in both a format of JSON or the Unreal's text import format.
BroadcastUpdate BOOL OPTIONAL Should Engine send an Update message for changed values? Default: true
Example 1 - Set intensity on a light component. Call (you send) Topic: {"Type":"Call","Target":"TJCGWS040-Engine","RespondTo":"TJCGWS040-TestClient","Method":"SetProperty","ID":"000"} Message: {"Params":{"ObjectSearch":"SpotLight_1.LightComponent0","PropertyPath":"Intensity","Value":100}} CallResult (you can receive, if subscribed) Topic: {"Type":"CallResult","Target":"TJCGWS040-TestClient","ExecutedOn":"TJCGWS040-Engine","Method":"SetProperty","ID":"000"} Message: {"Result":[{}]} Update (you can receive, if subscribed) Topic: {"Type":"Update","Target":"BROADCAST","Source":"TJCGWS040-Engine","Name":"World.PropertyChanged"} Message: { "Value": { "Owner": "SpotLight_1.LightComponent0", "Name": "Intensity", "PrettyName": "Intensity", "Type": "float", "AdjustmentStatus": "MODIFIED", "Value": "100.000000" } } |
Example 2 - Set intensity and color of two light components at once. Don't broadcast updates. Call (you send) Topic: {"Type":"Call","Target":"TJCGWS040-Engine","RespondTo":"TJCGWS040-TestClient","Method":"SetProperty","ID":"000"} Message: {"Params":{"ObjectSearch":["SpotLight_1.LightComponent0","SpotLight2.LightComponent0"],"PropertyPath":["Intensity","LightColor"],"Value":[100,"(R=255,G=0,B=0)"],"BroadcastUpdate":false}} CallResult (you can receive, if subscribed) Topic: {"Type":"CallResult","Target":"TJCGWS040-TestClient","ExecutedOn":"TJCGWS040-Engine","Method":"SetProperty","ID":"000"} Message: {"Result":[{}]} |
Example 3 - Apply blue color grading to the graphics. Call (you send) Topic: {"Type":"Call","Target":"TJCGWS040-Engine","RespondTo":"TJCGWS040-TestClient","Method":"SetProperty","ID":"000"} Message: {"Params":{"ObjectSearch":"post_process_handler","PropertyPath":["Settings.bOverride_ColorGamma","Settings.ColorGamma.X","Settings.ColorGamma.Y","Settings.ColorGamma.Z"],"Value":[true,0.0,0.0,1.0]}} CallResult (you can receive, if subscribed) Topic: {"Type":"CallResult","Target":"TJCGWS040-TestClient","ExecutedOn":"TJCGWS040-Engine","Method":"SetProperty","ID":"000"} Message: {"Result":[{}]} Update (you can receive, if subscribed) Topic: {"Type":"Update","Target":"BROADCAST","Source":"TJCGWS040-Engine","Name":"World.PropertyChanged"} Message: { "Value": { "Owner": "PostProcessHandler_0", "ObjectSearchTag": "post_process_handler", "Path": "Settings.", "Name": "bOverride_ColorGamma", "PrettyName": "Override Color Gamma", "Type": "bool", "AdjustmentStatus": "MODIFIED", "Value": "True" } } Update (you can receive, if subscribed) Topic: {"Type":"Update","Target":"BROADCAST","Source":"TJCGWS040-Engine","Name":"World.PropertyChanged"} Message: { "Value": { "Owner": "PostProcessHandler_0", "ObjectSearchTag": "post_process_handler", "Path": "Settings.ColorGamma.", "Name": "X", "PrettyName": "X", "Type": "float", "AdjustmentStatus": "MODIFIED", "Value": "0.000000" } } Update (you can receive, if subscribed) Topic: {"Type":"Update","Target":"BROADCAST","Source":"TJCGWS040-Engine","Name":"World.PropertyChanged"} Message: { "Value": { "Owner": "PostProcessHandler_0", "ObjectSearchTag": "post_process_handler", "Path": "Settings.ColorGamma.", "Name": "Y", "PrettyName": "Y", "Type": "float", "AdjustmentStatus": "MODIFIED", "Value": "0.000000" } } Update (you can receive, if subscribed) Topic: {"Type":"Update","Target":"BROADCAST","Source":"TJCGWS040-Engine","Name":"World.PropertyChanged"} Message: { "Value": { "Owner": "PostProcessHandler_0", "ObjectSearchTag": "post_process_handler", "Path": "Settings.ColorGamma.", "Name": "Z", "PrettyName": "Z", "Type": "float", "AdjustmentStatus": "MODIFIED", "Value": "1.000000" } } |
SetPropertiesWithJSON
This call is scheduled for deprecation. Please use SetProperty with an array of property paths instead.
Set values for multiple properties.
Params:
JSON STRING ObjectSearch (string, optional), Value (string, optional), BroadcastUpdate (bool, optional, default: true), Properties (an array of objects with PropertyPath(string), and optional overrides for ObjectSearch, Value, and BroadcastUpdate)
BroadcastUpdate BOOL OPTIONAL Should Engine send an Update message for changed values? Default: true
ResetProperty
Reset a property value for a given actor.
Params:
ObjectSearch STRING ARRAY STRING Unique name of the target Actor, or Actor.Component, or a special_tag, or an array of multiple object searches. Hover over the star left of your property in the Engine to learn the desired value.
PropertyPath STRING ARRAY STRING Dot-separated path to the targeted property, or an array of such paths. Hover over the star left of your property in the Engine to learn the desired value.
BroadcastUpdate BOOL OPTIONAL Should Engine send an Update message for changed values? Default: true
Example - Reset the graphics color grading gamma. (Set in a SetProperty example.) Call (you send) Topic: {"Type":"Call","Target":"TJCGWS040-Engine","RespondTo":"TJCGWS040-TestClient","Method":"ResetProperty","ID":"000"} Message: {"Params":{"ObjectSearch":"post_process_handler","PropertyPath":"Settings.ColorGamma"}} CallResult (you can receive, if subscribed) Topic: {"Type":"CallResult","Target":"TJCGWS040-TestClient","ExecutedOn":"TJCGWS040-Engine","Method":"ResetProperty","ID":"000"} Message: {"Result":[{}]} |
CallFunction
Call a method on a given object. This is the main and recommended way of handling live input and controls.
Params:
ObjectSearch STRING ARRAY STRING Unique name of the target Actor, or Actor.Component, or a special_tag, or an array of multiple object searches. Hover over the star left of your property in the Engine to learn the desired value.
FunctionName STRING
FunctionArguments STRING ARRAY OPTIONAL
SetVisibility
Set actor's / component's visibility.
Params:
ObjectSearch STRING ARRAY STRING Unique name of the target Actor, or Actor.Component, or a special_tag, or an array of multiple object searches. Hover over the star left of your property in the Engine to learn the desired value. Actors only!
BroadcastUpdate BOOL OPTIONAL Should Engine send an Update message for changed values? Default: true
Visibility BOOL
ResetVisibility
Reset actor's / component's visibility.
Params:
ObjectSearch STRING ARRAY STRING Unique name of the target Actor, or Actor.Component, or a special_tag, or an array of multiple object searches. Hover over the star left of your property in the Engine to learn the desired value. Actors only!
BroadcastUpdate BOOL OPTIONAL Should Engine send an Update message for changed values? Default: true
SetMobility
Set actor's / component's mobility.
Params:
ObjectSearch STRING ARRAY STRING Unique name of the target Actor, or Actor.Component, or a special_tag, or an array of multiple object searches. Hover over the star left of your property in the Engine to learn the desired value. Actors only!
Mobility ENUM Allowed values: NO_TRANSFORM, STATIC, STATIONARY, or MOVABLE)
BroadcastUpdate BOOL OPTIONAL Should Engine send an Update message for changed values? Default: true
ResetMobility
Reset actor's / component's mobility.
Params:
ObjectSearch STRING ARRAY STRING Unique name of the target Actor, or Actor.Component, or a special_tag, or an array of multiple object searches. Hover over the star left of your property in the Engine to learn the desired value. Actors only!
BroadcastUpdate BOOL OPTIONAL Should Engine send an Update message for changed values? Default: true
SetTransform
Set actor's or component's relative transform.
Params:
ObjectSearch STRING ARRAY STRING Unique name of the target Actor, or Actor.Component, or a special_tag, or an array of multiple object searches. Hover over the star left of your property in the Engine to learn the desired value.
Transform FLOAT ARRAY OPTIONAL Consecutively: LocX, LocY, LocZ, RotX, RotY, RotZ, SclX, SclY, SclZ. Invalid or missing values will be ignored. Can be an array longer than 9 to apply different transforms when targetting multiple objects.
Location FLOAT ARRAY OPTIONAL Consecutively: LocX, LocY, LocZ. Invalid or missing values will be ignored.
Rotation FLOAT ARRAY OPTIONAL Consecutively: RotX, RotY, RotZ. Invalid or missing values will be ignored.
Scale FLOAT ARRAY OPTIONAL Consecutively: SclX, SclY, SclZ. Invalid or missing values will be ignored.
IgnorePattern BOOL ARRAY OPTIONAL Allows to ignore certain values from being applied. Consecutively: LocX, LocY, LocZ, RotX, RotY, RotZ, SclX, SclY, SclZ. Can be an array longer than 9 to apply different ignore patterns when targetting multiple objects. Default: all false
IsDelta BOOL OPTIONAL Should given transform values be added to the exiting transform. Default: false
IsLocalTranslation BOOL OPTIONAL If IsDelta, should we add location along local axis. Default: false
IsLocalRotation BOOL OPTIONAL If IsDelta, should we add rotation along local axis. Default: false
BroadcastUpdate BOOL OPTIONAL Should Engine send an Update message for changed values? Default: true
ResetTransform
Reset object's transform.
Params:
ObjectSearch STRING ARRAY STRING Unique name of the target Actor, or Actor.Component, or a special_tag, or an array of multiple object searches. Hover over the star left of your property in the Engine to learn the desired value.
ResetPattern BOOL ARRAY OPTIONAL Consecutively: LocX, LocY, LocZ, RotX, RotY, RotZ, SclX, SclY, SclZ. Default: all false
BroadcastUpdate BOOL OPTIONAL Should Engine send an Update message for changed values? Default: true
SetRenderLayer
Set actor's or component's render layer.
Params:
ObjectSearch STRING ARRAY STRING Unique name of the target Actor, or Actor.Component, or a special_tag, or an array of multiple object searches. Hover over the star left of your property in the Engine to learn the desired value.
BroadcastUpdate BOOL OPTIONAL Should Engine send an Update message for changed values? Default: true
RenderLayer ENUM Allowed values: FOREGROUND, AR_HOLDOUT, AR_SHADOW_CATCHER, VS_TRANSLUCENT, AR_TRANSLUCENT.
ResetRenderLayer
Reset actor's or component's render layer.
Params:
ObjectSearch STRING ARRAY STRING Unique name of the target Actor, or Actor.Component, or a special_tag, or an array of multiple object searches. Hover over the star left of your property in the Engine to learn the desired value.
BroadcastUpdate BOOL OPTIONAL Should Engine send an Update message for changed values? Default: true
ResetObject
Reset all object's adjustments.
Params:
ObjectSearch STRING ARRAY STRING Unique name of the target Actor, or Actor.Component, or a special_tag, or an array of multiple object searches. Hover over the star left of your property in the Engine to learn the desired value.
ShouldResetComponents BOOL OPTIONAL Default: true
BroadcastUpdate BOOL OPTIONAL Should Engine send an Update message for changed values? Default: true
Object Spawning
A group of calls allowing for spawning and deleting actors and components from the scene.
SpawnActor
Spawn a new actor.
Params:
ActorType STRING
BroadcastUpdate BOOL OPTIONAL Should Engine send an Update message for changed values? Default: true
SpawnComponent
Add a component to an actor.
Params:
ObjectSearch STRING ARRAY STRING Unique name of the target Actor, or Actor.Component, or a special_tag, or an array of multiple object searches. Hover over the star left of your property in the Engine to learn the desired value.
ComponentType STRING
BroadcastUpdate BOOL OPTIONAL Should Engine send an Update message for changed values? Default: true
DeleteSpawnedObject
Delete an existing actor. Works only for the actors previously spawned through the API.
Params:
ObjectSearch STRING ARRAY STRING Unique name of the target Actor, or Actor.Component, or a special_tag, or an array of multiple object searches. Hover over the star left of your property in the Engine to learn the desired value. API-spawned Actors only!
BroadcastUpdate BOOL OPTIONAL Should Engine send an Update message for changed values? Default: true
DeleteAllSpawnedActors
Delete all spawned actors.
Params:
BroadcastUpdate BOOL OPTIONAL Should Engine send an Update message for changed values? Default: true
RenameSpawnedActor
Rename a previously spawned actor.
Params:
ObjectSearch STRING ARRAY STRING Unique name of the target Actor, or Actor.Component, or a special_tag, or an array of multiple object searches. Hover over the star left of your property in the Engine to learn the desired value. API-spawned Actors only!
NewName STRING
BroadcastUpdate BOOL OPTIONAL Should Engine send an Update message for changed values? Default: true
SetActorParent
Set one actor to be another's parent.
No params.
Object Getting
Calls allowing for getting the information about the scene.
GetProperty
Send JSON describing a property to Data Hub.
Params:
ObjectSearch STRING ARRAY STRING Unique name of the target Actor, or Actor.Component, or a special_tag, or an array of multiple object searches. Hover over the star left of your property in the Engine to learn the desired value.
PropertyPath STRING ARRAY STRING Dot-separated path to the targeted property, or an array of such paths. Hover over the star left of your property in the Engine to learn the desired value.
RecursionDepth INT OPTIONAL Default: 1
GetFunction
Send JSON describing a function to Data Hub.
Params:
ObjectSearch STRING ARRAY STRING Unique name of the target Actor, or Actor.Component, or a special_tag, or an array of multiple object searches. Hover over the star left of your property in the Engine to learn the desired value.
FunctionName STRING
GetTransform
Send JSON describing actor's or component's relative transform to Data Hub.
Params:
ObjectSearch STRING ARRAY STRING Unique name of the target Actor, or Actor.Component, or a special_tag, or an array of multiple object searches. Hover over the star left of your property in the Engine to learn the desired value.
GetObject
Send JSON describing an object to Data Hub.
Params:
ObjectSearch STRING ARRAY STRING Unique name of the target Actor, or Actor.Component, or a special_tag, or an array of multiple object searches. Hover over the star left of your property in the Engine to learn the desired value.
RecursionDepth OPTIONAL DEFAULT:1
GetWorld
Send JSON describing the currently active world to Data Hub.
Params:
ShouldIncludeActors BOOL OPTIONAL Default: true
RecursionDepth INT OPTIONAL Default: 1
Example 1 - Get World's metadata only. Call (you send) Topic: {"Type":"Call","Target":"XXX-Engine","RespondTo":"XXX-Client","Method":"GetWorld","ID":"000"} Message: {"Params":{"ShouldIncludeActors":false}} CallResult (you can receive, if subscribed) Topic: {"Type":"CallResult","Target":"XXX-Client","ExecutedOn":"XXX-Engine","Method":"GetWorld","ID":"000"} Message: { "Result": [ { "World": { "Name": "LVL_PixotopeVSSample", "PrettyName": "LVL_PixotopeVSSample", "Type": "Editor", "CompositingMode": "Internal", "IsDirty": false } } ] } |
Example 2 - Get a list of actors. Call (you send) Topic: {"Type":"Call","Target":"XXX-Engine","RespondTo":"XXX-Client","Method":"GetWorld","ID":"000"} Message: {"Params":{"ShouldIncludeActors":true,"RecursionDepth":0}} CallResult (you can receive, if subscribed) Topic: {"Type":"CallResult","Target":"XXX-Client","ExecutedOn":"XXX-Engine","Method":"GetWorld","ID":"000"} Message: { "Result": [ { "World": { "Name": "LVL_PixotopeVSSample", "PrettyName": "LVL_PixotopeVSSample", "Type": "Editor", "CompositingMode": "Internal", "IsDirty": false, "Actors": [ { "Name": "WorldSettings_1", "PrettyName": "WorldSettings1", "Type": "WorldSettings", "AdjustmentStatus": "ORIGINAL", "Visibility": true, "Mobility": "NO_TRANSFORM", "RenderLayer": "NONE" } ] } } ] } |
World Settings
Calls allowing for manipulating World Settings.
ResetSettings
This call is scheduled for deprecation. Please use ResetProperty with an array of PropertyPaths instead.
Reset pixotope settings group.
Params:
SettingsGroup STRING Legacy grouping of settings. Please use a different call.
GetSettings
This call is scheduled for deprecation. Please use GetProperty instead with an array of PropertyPaths instead.
Send current values of a settings group to Data Hub.
Params:
SettingsGroup STRING Legacy grouping of settings. Please use a different call.
ShouldIncludeDetails BOOL OPTIONAL Default: true
Adjustments
Calls exposed by the Pixotope Engine's adjustment system.
GetPropertyAdjustmentStatus
Check if a particular property was modified. Possible AdjustmentStatus values: UNKNOWN, DEFAULT, MODIFIED, SPAWNED, EDITOR
Params:
ObjectSearch STRING ARRAY STRING Unique name of the target Actor, or Actor.Component, or a special_tag, or an array of multiple object searches. Hover over the star left of your property in the Engine to learn the desired value.
PropertyPath STRING ARRAY STRING Dot-separated path to the targeted property, or an array of such paths. Hover over the star left of your property in the Engine to learn the desired value.
GetVisibilityAdjustmentStatus
Check if a particular object's visibility was modified. Possible AdjustmentStatus values: UNKNOWN, DEFAULT, MODIFIED, SPAWNED, EDITOR
Params:
ObjectSearch STRING ARRAY STRING Unique name of the target Actor, or Actor.Component, or a special_tag, or an array of multiple object searches. Hover over the star left of your property in the Engine to learn the desired value.
GetMobilityAdjustmentStatus
Check if a particular object's mobility was modified. Possible AdjustmentStatus values: UNKNOWN, DEFAULT, MODIFIED, SPAWNED, EDITOR
Params:
ObjectSearch STRING ARRAY STRING Unique name of the target Actor, or Actor.Component, or a special_tag, or an array of multiple object searches. Hover over the star left of your property in the Engine to learn the desired value.
GetTransformAdjustmentStatus
Check if a particular object's transform was modified. Possible AdjustmentStatus values: UNKNOWN, DEFAULT, MODIFIED, SPAWNED, EDITOR
Params:
ObjectSearch STRING ARRAY STRING Unique name of the target Actor, or Actor.Component, or a special_tag, or an array of multiple object searches. Hover over the star left of your property in the Engine to learn the desired value.
GetRenderLayerAdjustmentStatus
Check if a particular object's render layer was modified. Possible AdjustmentStatus values: UNKNOWN, DEFAULT, MODIFIED, SPAWNED, EDITOR
Params:
ObjectSearch STRING ARRAY STRING Unique name of the target Actor, or Actor.Component, or a special_tag, or an array of multiple object searches. Hover over the star left of your property in the Engine to learn the desired value.
GetObjectAdjustmentStatus
Check if a particular object was modified. Possible AdjustmentStatus values: UNKNOWN, DEFAULT, MODIFIED, SPAWNED, EDITOR
Params:
ObjectSearch STRING ARRAY STRING Unique name of the target Actor, or Actor.Component, or a special_tag, or an array of multiple object searches. Hover over the star left of your property in the Engine to learn the desired value.
WasObjectSpawned
Check if a particular object was spawned with API.
Params:
ObjectSearch STRING ARRAY STRING Unique name of the target Actor, or Actor.Component, or a special_tag, or an array of multiple object searches. Hover over the star left of your property in the Engine to learn the desired value.
WasAnyObjectSpawned
Check if any object was spawned.
No params.
WasAnythingModifed
Check if any objects, parameters or settings were modified in this world.
No params.
ResetAllAdjustments
Reset all adjustments applied to this world.
Params:
BroadcastUpdate BOOL OPTIONAL Should Engine send an Update message for changed values? Default: true
BakeAllAdjustments
Bakes all adjustments permanently into the world. Works in the editor mode only.
No params.
Other
GetVersion
Returns Pixotope and Unreal Engine versions
No params.
ExecuteConsoleCommand
Execute a command in the engine console.
Params:
Command STRING An engine console command to execute.
BroadcastUpdate BOOL OPTIONAL Should Engine send an Update message for changed values? Default: true
GetCompositingMode
Send the compositing mode of current world. Possible return values: Internal, External
No params.
OpenLevel
Load a new level without closing the project.
Params:
LevelPath(example: Levels/TestMap0) STRING
ReopenLevel
Reload the current level without closing the project.
No params.
GetAutolayout
Feature under development.
Send a list of function descriptions that were marked for auto-layouting.
Params:
ObjectSearch STRING ARRAY STRING Unique name of the target Actor, or Actor.Component, or a special_tag, or an array of multiple object searches. Hover over the star left of your property in the Engine to learn the desired value.
GetSpecialObjectMappings
Get all the object names mapped to a certain object search tag.
Params:
ObjectSearchTag STRING Pixotope object search tag. For example: post_process_handler.
GetAllSpecialObjectMappings
Get all the object search tags with object names mapped to them.
No params.
BroadcastWorldUpdate
Force a broadcast for a particular property.
Params:
UpdateType STRING Only PropertyChanged supported for now.
ObjectSearch STRING ARRAY STRING Unique name of the target Actor, or Actor.Component, or a special_tag, or an array of multiple object searches. Hover over the star left of your property in the Engine to learn the desired value.
PropertyPath STRING ARRAY STRING Dot-separated path to the targeted property, or an array of such paths. Hover over the star left of your property in the Engine to learn the desired value.
SaveEditor
Trigger saving dirty editor packages.
No params.
Call Responses
Every executed call responds with a CallResult message that holds either relevant data or an error message.
Call Result
Every successful call result coming from the Engine holds a JSON array filed (called Result). It is an array because almost any executed Call can be scaled to target muliple objects.Error
If a call fails, the call result message holds an Error filed instead of Result. This filed can inform on what was the reason for the failure.Update
Certain calls can optionally broadcast meaningful Update messages throughout the network. It can be useful for keeping otherwise uninvolved client software up to date with what's happening in the engine.Adding Adjustments
Pixotope Engine has a feature allowing all the remote changes done in Live or Live Preview to be saved and later applied on start again. In order to add your Call as an adjustment add to it a param named IsAdjustment, set to true.
Advanced RPC Usage
Object Search
Many commands take ObjectSearch as their first argument. It allows to target world's actors, components, and some other special objects with the commands. Typically, in order to target actors, one can just type a unique name of this actor. To find out the unique name of an actor, move the mouse over the label of the actor in World Outliner in the Editor, and the unique name will be shown in the tooltip.ObjectSearch also accepts certain predefined names for targeting special objects:
- tracked_camera
- camera_root
- material_handler
- post_process_handler
- api_manager
- video_io_controller
- world_settings
- compositing_planes
- level_blueprint
- virtual_lights
Alternatively, it is possible to access the following advanced search modes:
- . (component search, by adding a dot after actors nameand following it with the component name, ex. SomeActor0.SomeComponent42)
- all_of_type (followed by a type name will return all actors of a given type currently existing in the scene)
- first_of_type (followed by a type name will return the first actor of a given type currently existing in the scene)