Unity Communication Protocol

Last reviewed: 2026-07-05

Communication Model

The Unity protocol uses ZeroMQ with JSON envelopes.

Channel	Direction	Socket model	Current binding expectation	Source
Command	Python to Unity	Python REQ, Unity REP	Python connects to tcp://{host}:{command_port}; Unity binds	src/anuva_python_server/unity/zmq_client.py
Status events	Unity to Python	Unity PUSH, Python PULL	Python binds tcp://{host}:{status_port}; Unity connects	src/anuva_python_server/unity/zmq_client.py
Heartbeat events	Unity to Python	Unity PUSH, Python PULL	Python binds tcp://{host}:{heartbeat_port}; Unity connects	src/anuva_python_server/unity/zmq_client.py

Default ports are command 5560, status 5561, and heartbeat 5562, all on 127.0.0.1.

Message Envelope

Status: Implemented in src/anuva_python_server/unity/protocol.py.

All protocol messages use a JSON object with these common fields:

Field	Required	Notes
id	Yes	Non-empty message id.
type	Yes	Command or event type string.
timestamp	Yes	Timezone-aware timestamp.
payload	Yes	Message-specific object.
jobId	No	Present for render job messages.
workerId	No	Included by Python commands when configured.
unityInstanceId	No	Used by Unity identity events if available.
correlationId	No	Used to connect command replies/events.
protocolVersion	No	Python commands default to 1.0.

Tests: tests/unit/test_unity_protocol.py, tests/integration/test_unity_zmq_client.py.

Implemented Commands

Type	Direction	Payload shape in code/tests	Status
render.start	Python to Unity	configPath, configUrl, outputPath, jobType, render	Implemented
render.cancel	Python to Unity	reason	Implemented
unity.shutdown	Python to Unity	reason	Implemented
unity.ping	Python to Unity	Empty object	Implemented

Command replies are decoded as generic ProtocolMessage, not a strict command-ack enum. Tests use reply types such as unity.commandAck, render.cancel.reply, and payload values like {"accepted": true}.

Implemented Events

Type	Direction	Payload fields observed in tests/code	Status
unity.ready	Unity to Python	unityInstanceId, appVersion, protocolVersion	Implemented
render.accepted	Unity to Python	unityJobId optional	Implemented
render.progress	Unity to Python	progress, message or phase	Implemented
render.completed	Unity to Python	outputPath, optional durationSec, frameCount, fileSizeBytes	Implemented
render.failed	Unity to Python	errorCode, errorMessage	Implemented
unity.heartbeat	Unity to Python	state, fps, currentJobId observed in tests	Implemented

Lifecycle Order

Typical order:

1. Unity emits unity.ready.
2. Python sends render.start.
3. Unity command socket replies with an accepted command response.
4. Unity emits render.accepted.
5. Unity emits zero or more render.progress events.
6. Unity emits render.completed or render.failed.
7. Python validates/uploads/completes or fails the job.

Cancellation order:

1. Python detects or receives a cancellation condition.
2. If Unity is rendering, Python sends render.cancel.
3. Python treats replies with accepted, cancelled, or status accepted, acknowledged, cancelled, or ok as acknowledged.
4. If cancellation is not acknowledged and unity.terminate_on_cancel_ack_timeout is true, the supervisor stops Unity.

Source Files To Inspect

• src/anuva_python_server/unity/protocol.py
• src/anuva_python_server/unity/zmq_client.py
• src/anuva_python_server/unity/supervisor.py
• src/anuva_python_server/jobs/runner.py
• tests/unit/test_unity_protocol.py
• tests/integration/test_unity_zmq_client.py
• tests/unit/test_output_and_completion.py

Operational map: UnityProtocolMap.