upyrc 0.12.0

Python wrapper around the Unreal engine remote control API and remote python execution.

ℹ️ Check the wiki page ℹ️

UnrealRemoteControlWrapper

A (work in progress) python 3 wrapper around Unreal remote control api. It allows to control Unreal engine remotly, from a dcc ( maya, blender, houdini, etc. ), or a webapp, or any other sources, using a simple python api.

It also provide a wrapper around the python remote execution option you can find in the python plugin settings in Unreal. This allow you to execute python code from a different python process by sending commands, file path, or python code as string.

upyrc is available on pip:

python -m pip install upyrc

Test data

:arrow_right: A test data Unreal 5.3 project is available here: https://github.com/cgtoolbox/UnrealRemoteControlTestData

Python remote execution (upyre)

This module allows a user to execute python code remotely on a unreal engine session.

⚠️ It needs to have the python plugin enabled on unreal, as well as the -allow python remote execution- option set on.

In order to create a connection, we need to fetch the settings of the python plugin, this can be done by giving the full path to a uproject to the create config object:

from upyrc import upyre
config = upyre.RemoteExecutionConfig.from_uproject_path(r"D:/Projects/UpyreTest/UpyreTest.uproject")

You can also create the config manually with the right values, such as multicast_group ip and port, multicast_bind_adress or ip_muticast_ttl. Those values can be found in the project settings of the python plugin. config = upyre.RemoteExecutionConfig(mutlicast_group=("239.0.0.1", 6766), multicast_bind_adress="0.0.0.0")

To open a connection, you have to use PythonRemoteConnection object, it can be used as context manager like this:

with upyre.PythonRemoteConnection(config) as conn:
    result = conn.execute_python_command("unreal.log('hello form python !')", exec_type=upyre.ExecTypes.EXECUTE_FILE, raise_exc=True)
    print(result)

Or you can call open_connection() and close_connection() manually when needed.

conn = upyre.PythonRemoteConnection(config) 
conn.open_connection()
# do commands here
conn.close_connection()

To check help on exec_types, you can call help(ExecTypes). Help is available on other objects as well.

Code template are available as jinja files, they can be directly used using helper functions, to execute utility blueprints, set variables, or print logs. For more infos, check test_remote_exection_templates.py.

DataExchange:

To exchange data between the two python processes, a json pipe is available, or it can be done using printing some data in the standard output and fetch them back using dedicated methods.

# In the remote python process (not Unreal).

# open_json_output_pipe=True open the pipe and create a temp json file which can be
# accessed by both processes.
with upyre.PythonRemoteConnection(config, open_json_output_pipe=True) as conn:

    conn.write("my_data", 123) # Write data in the json file

# In the python command you execute Unreal side, data can be fetched using:

from upyre_json_pipe import json_pipe
json_pipe.read("my_data") # -> return 123
json_pipe.write("unrealside_data", "foo")  # Data written in the json file, can be fetch by the remote process with conn.read("unrealside_data")

Or using the standard print function:

# In the python command you execute Unreal side (my_command.py):
print("mydata=bar")

# In the remote python process (not Unreal).
with upyre.PythonRemoteConnection(config, open_json_output_pipe=True) as conn:
    cmd_result = conn.execute_python_command("my_command.py")
    cmd_result.get_first_output_with_identifier("mydata") # -> returns "bar"

This is a one way only data exchange, and only string data are supported atm.

(But a json string can be sent that way)

Python remote control (uprc, HTTP api):

⚠️ It needs to have the remote API plugin installed on your Unreal project, as well as the server started, you can do that on the cmd:

WebControl.StartServer
WebControl.EnableServerOnStartup

By default, the script use these values bellow as host and port, it matches the default value of the remote plugin from Unreal install, it needs to be set to your values if needed:

DEFAULT_HOST = "127.0.0.1"
DEFAULT_PORT = 30010

Http api endpoints documentation.

Features

✔️ Get remote UObject by path.

✔️ Run query with various filter (class, path, package etc.) to get UObjects.

✔️ Get / Set UObject properties.

✔️ Run UObject functions.

✔️ Get remote blueprint actor and run functions.

✔️ Get remote presets.

✔️ Get / Set remote preset properties, functions, actors.

✔️ Get utilities EditorActorSubsystem and EditorAssetLibrary.

✔️ Batch process is supported.

❌ Get thumbnail not supported.

Basic usage

More infos on file: test_remote_control.py

As well as help() on objects:

help(upyrc.URConnection)
help(upyrc._URemoteObject)
# etc..

Contact

🔗 www.cgtoolbox.com

✉️ [e-mail]