Viz Arc User Guide

The Viz Arc Engine Service is a local control service that runs on the same machine as a Viz Engine and/or an Unreal Engine. It exposes an API to start, stop, query, and send commands to those engines, and to drive the Preview Studio process.

The service listens on port 5644 by default (configurable via the Windows registry value HKLM\SOFTWARE\vizrt\Viz Arc\UELoaderServerPort). All endpoints are served under /api/v1/. An interactive Swagger UI with full schemas and live "Try it out" support is available at http://<engine-host>:5644/swagger.

Intended audience: This API is intended for Viz Arc itself, automation systems, and custom integrations running on the local network.

InstalledVersions

Returns the Viz Engine and Unreal Engine installations detected on the local machine. Sources:

Viz Engine: HKLM\SOFTWARE\vizrt\VizEngine.
Unreal Engine: HKLM\SOFTWARE\EpicGames\Unreal Engine\<version>, cross-referenced with HKCU\SOFTWARE\Epic Games\Unreal Engine\Builds for the build UUID.

GET /api/v1/InstalledVersions

curl http://localhost:5644/api/v1/InstalledVersions | python -m json.tool

{
  "UnrealEngines": [
    { "Version": "5.3", "Path": "C:\\Program Files\\Epic Games\\UE_5.3", "UUID": "..." }
  ],
  "VizEngines": [
    { "Version": "5.2.0", "Path": "C:\\Program Files\\vizrt\\Viz3\\", "Executable": "viz.exe" }
  ]
}

CheckConnection

Lightweight health-check. Issues an IS_PLAY_MODE query on the given port and returns the raw plug-in reply.

GET /api/v1/CheckConnection?port=5647

Parameter	Type	Description
`port`	integer	Port on which the Viz Arc Unreal plug-in listens. Default `5647`.

curl http://localhost:5644/api/v1/CheckConnection?port=5647 | python -m json.tool

A reachable engine in PIE/game mode replies with "1"; a reachable Engine not in play mode replies with "0". If the plug-in is unreachable the service responds with 400 Bad Request.

Command

Sends one or more commands to a local Unreal Engine via the Viz Arc Unreal plug-in. Commands are forwarded to 127.0.0.1:<UnrealPluginPort>. If the Engine is not yet reachable, commands are queued and sent as soon as it connects.

A small set of commands are handled by the loader directly and not forwarded to the plug-in:

START <UnrealVersion> [project] [map] — launches the matching UE Editor.
LOADER KILL — kills all running UE Editor processes.
LOADER RESTART — kills and restarts UE with the last-loaded project/map.
ENSURE_PROJECT_LOAD <proj>;<mapFull>;<mapCmdB64>;<UnrealVersion> — ensures the requested project and map are loaded, launching UE if necessary.

POST /api/v1/Command

Field	Type	Description
`UnrealVersion`	string	UE version key from the registry (e.g. `"5.3"`). Required for `START`, `LOADER RESTART`, `ENSURE_PROJECT_LOAD`.
`UnrealPluginPort`	integer	Port on which the Viz Arc Unreal plug-in listens (default `5647`).
`DelayMS`	integer	Optional delay before sending (currently unused by the loader).
`ClearCommandQueue`	boolean	If `true`, any queued commands are dropped before the new ones are sent.
`Commands`	string[]	One or more command strings to execute in order.

Examples

Load a Map in the current Unreal Project:

curl -X POST http://localhost:5644/api/v1/Command \
  -H "Content-Type: application/json" \
  -d '{
    "UnrealVersion": "5.3",
    "UnrealPluginPort": 5647,
    "ClearCommandQueue": false,
    "Commands": ["SCENE SCENE*SCENE SET MyMap"]
  }'

Launch the Unreal Editor for the installed UE 5.3 with a given project and map:

curl -X POST http://localhost:5644/api/v1/Command \
  -H "Content-Type: application/json" \
  -d '{
    "UnrealVersion": "5.3",
    "UnrealPluginPort": 5647,
    "ClearCommandQueue": true,
    "Commands": [
      "START 5.3 \"C:\\Projects\\MyShow\\MyShow.uproject\" \"/Game/Maps/StudioA\""
    ]
  }'

QueryEngine

Sends a single synchronous query to the Viz Arc Unreal plug-in and returns its raw reply. Only the first element in Commands is executed; additional entries are ignored.

POST /api/v1/QueryEngine

Uses the same body shape as Command. For queries only UnrealPluginPort and Commands[0] are relevant.

Example

curl -X POST http://localhost:5644/api/v1/QueryEngine \
  -H "Content-Type: application/json" \
  -d '{
    "UnrealPluginPort": 5647,
    "Commands": ["IS_PLAY_MODE"]
  }'

Response

The raw string returned by the plug-in (for IS_PLAY_MODE, typically "0" or "1").

StartVizEngine

Starts a local Viz Engine instance with the requested configuration. The service first probes the target Engine on 127.0.0.1:<CommunicationPort> and queries its current config. If the running Engine is already using the requested ConfigPath, no new process is launched. Otherwise every running Viz / VizGui process is killed and a new viz.exe is started.

Request

POST /api/v1/StartVizEngine

Field	Type	Required	Description
`ConfigPath`	string	no	Absolute path to a Viz Engine config file (.cfg).
`Switches`	string	no	Additional command-line switches passed verbatim to `viz.exe`.
`Scene`	string	no	Scene to load on startup. Passed to `viz.exe` as `-o <Scene>`.
`CommunicationPort`	integer	no	Viz Engine command port used to probe whether an engine is already running with the requested config. Not passed to `viz.exe`. Default `6100`.

Example

curl -X POST http://localhost:5644/api/v1/StartVizEngine \
  -H "Content-Type: application/json" \
  -d '{
    "ConfigPath": "C:\\ProgramData\\Vizrt\\VizEngine\\config.cfg",
    "Switches": "",
    "Scene": "",
    "CommunicationPort": 6100
  }'

Response

Plain text describing the outcome:

"engine already running with config <path>": No process was started.
"started viz process <pid> <exe> <arguments>": A new engine was launched.
"config not found <path>": The requested ConfigPath does not exist.