Unity Protocol Map

Last reviewed: 2026-07-05

Topology

Port setting	Default	Python socket	Unity socket	Purpose
`zmq.command_port`	`5560`	REQ connect	REP bind	Commands and command replies.
`zmq.status_port`	`5561`	PULL bind	PUSH connect	Render status events.
`zmq.heartbeat_port`	`5562`	PULL bind	PUSH connect	Heartbeat/ready events.

Source: src/anuva_python_server/config/settings.py, src/anuva_python_server/unity/zmq_client.py.

Command	Helper	Payload	Tests
`render.start`	`send_render_start()`	`configPath`, `configUrl`, `outputPath`, `jobType`, `render`	`tests/integration/test_unity_zmq_client.py`
`render.cancel`	`send_render_cancel()`	`reason`	`tests/integration/test_unity_zmq_client.py`, `tests/unit/test_output_and_completion.py`
`unity.shutdown`	`send_unity_shutdown()`	`reason`	`tests/integration/test_unity_zmq_client.py`
`unity.ping`	`send_unity_ping()`	`{}`	`tests/integration/test_unity_zmq_client.py`

Event	Consumed by	Effect
`unity.ready`	`UnitySupervisor.wait_for_ready()`, dashboard monitor	Marks Unity connected/ready.
`unity.heartbeat`	`UnitySupervisor.record_event()`	Updates heartbeat timestamp and rendering state if payload `state == rendering`.
`render.accepted`	`JobRunner._wait_for_unity_render_completion()`	Updates Web App `inProgress` with Unity accepted message.
`render.progress`	`JobRunner._wait_for_unity_render_completion()`	Normalizes progress from `0..1` or `0..100`, forwards message/phase.
`render.completed`	`JobRunner._wait_for_unity_render_completion()`	Resolves output path, validates/uploads/completes.
`render.failed`	`JobRunner._wait_for_unity_render_completion()`	Fails current job with Unity error payload.

UnityZmqClient writes per-job JSONL records to jobs/<job-id>/logs/zmq_messages.jsonl when a message has a jobId or payload.currentJobId.

Gap	Status
Strict schema for command replies	Partial: decoded as generic `ProtocolMessage`.
Dedicated event for cancellation acknowledgement	Unknown/Partial: cancellation reads command reply payload heuristically.
Version negotiation	Planned/Partial: `protocolVersion` is included but not negotiated.
Real Unity compliance tests	External/Unknown.