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.
Object Spawning
A group of calls allowing for spawning and deleting actors and components from the scene.
Object Getting
Calls allowing for getting the information about the scene.
World Settings
Calls allowing for manipulating World Settings.
Adjustments
Calls exposed by the Pixotope Engine's adjustment system.
Other
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
ObjectSearchas 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 Outlinerin 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
Otherwise the object search will by default look for the first actor in the scene of the given name.
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)
Property Path
PropertyPathparameter, required by many calls, is used to target certain properties(fields) on objects. For properties existing directly in particular object's class the property path will be just this properties' name. However for children of struct properties path will consist of consecutive property names separated with a dot. For example:
Parameters.Position.X(targeting float X in Position vector in Parameters struct).
Ignore Property Value
In case that we are sending SetProperty or SetSettings we might sometimes want our call to be ignored for particular properties. To achieve that pass
:::ignore:::string as a value.