Python Server Integration

Last reviewed: 2026-06-30

Protocol Summary

Unity communicates with anuva-python-server over ZeroMQ using JSON envelopes. This doc is cross-checked against C:/Anuva/dev/anuva-python-server/docs/state/UnityProtocolMap.md and docs/core/UnityCommunicationProtocol.md in the Python Server repo.

Channel	Direction	Python socket	Unity socket	Default
Command	Python to Unity	REQ connect	REP bind	tcp://127.0.0.1:5560
Status	Unity to Python	PULL bind	PUSH connect	tcp://127.0.0.1:5561
Heartbeat	Unity to Python	PULL bind	PUSH connect	tcp://127.0.0.1:5562

Unity implementation: Assets/Anuva/Scripts/AnuvaPythonServerCommunication.cs.

Commands Accepted By Unity

Command	Payload fields consumed by Unity	Behavior
render.start	outputPath, jobType, configPath, configUrl	Acks command, prepares config/assets, starts playback/capture.
render.cancel	reason	Stops playback/preparation/capture and emits render.failed with JOB_CANCELLED.
unity.shutdown	reason	Sets state to shutdown_requested, exits play mode in editor or calls Application.Quit().
unity.ping	none	Emits unity.ready with pong: true.

Python docs also list render.start.payload.render; Unity does not currently extract or apply that object.

Events Sent By Unity

Event	Payload	Source
unity.ready	unityInstanceId, appVersion, protocolVersion, capabilities, optional pong	SendUnityReady()
unity.heartbeat	state, fps, currentJobId	SendUnityHeartbeat()
unity.commandAck	accepted, optional error	Command reply on REP socket
render.accepted	unityJobId	Remote render start accepted
render.progress	progress, phase, message	Timeline progress loop
render.completed	outputPath, durationSec, frameCount, fileSizeBytes	AVPro final file callback
render.failed	errorCode, errorMessage, optional details	Validation, capture, cancel, or preparation failure

Local Testing Flow

Flow	Unity side	Python side
Full renderer against Python	Scene with PresentationController and enablePythonServerCommunication = true	Python worker waits for unity.ready, sends render.start, waits for completion.
Fake Unity protocol testing	Assets/Anuva/Scenes/Anuva_Simulator_Scene.unity with AnuvaUnityVideoGeneratorSimulator	Python integration tests and manual commands can validate protocol without full render.
Local playback without Python	enablePythonServerCommunication = false	No Python required; config/media must be reachable.

Operational Gaps

• Inspected render scenes serialize enablePythonServerCommunication: 0; production server-driven scene setup is Unknown / not confirmed in repo.
• No command-line parser was found for Python process launch arguments such as ports, worker id, or content server URL.
• Version negotiation is not implemented; protocolVersion is included but not negotiated.
• Strict schema validation of command payloads is partial; Unity uses a generic mini JSON parser plus string lookups.