Engine API - Calls
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.
Exposing
Calls allowing fine-tune what is send from the scene in response to get calls.
Adjustments
Calls exposed by the Pixotope Engine's adjustment system.
Cinematic
Other
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:
- compositing_mesh
- light_component
- light_actor
- compositing_plane
- material_handler
- post_process_handler
- camera_root
- tracked_camera
- world_settings
- level_blueprint
- bpe_manager
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 target all actors of a given type currently existing in the scene)
- first_of_type (followed by a type name will target the first actor of a given type currently existing in the scene)
- default_object (followed by a type name will target the default object of that type)
PropertyPath Property Path
parameter, 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.
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 field (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 field instead of Result. This field 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.
Filtering Results
Often a call will return too much data, and that might take too long parsing or be just unpleasant to work with. In order to filter only the fields you are interested in from your CallResult add a param named ResultFilter, with a array of json fields you want to be sent. Dot-separated paths to particular fields are supported.
For example: ResultFilter=["Object.Components.Name"] would result in only component names being sent on GetObject.
Avoiding Frame Drops
Add an optional param ParamSplitBetweenFrames to your call to configure on which array param should we try to split between and execute every element separately in order to avoid dropping frames. This will efectively treat every element of that array param together with other params as a separate API call, but it will combine the results into a single result message.
Avoiding Synchronization Delays
It is possible to bypass synchronization (and the resulting delay) for select Calls by adding a param NoSync set to true.