System Architecture

Last reviewed: 2026-06-30

Runtime Shape

The runtime centers on PresentationController. The controller is a Unity MonoBehaviour responsible for setup, config loading, asset preloading, capture, playback, bot motion, camera transitions, and optional Python Server communication.

Layer	Implemented pieces	Notes
Unity scenes	Assets/Anuva/Scenes/Anuva_DemoSet_Scene.unity, Anuva_TataMotors_Scene.unity, XCam_*, Anuva_Simulator_Scene.unity; build settings list Assets/Scenes/SampleScene.unity.	Canonical production build scene is Unknown / not confirmed in repo.
Runtime controller	PresentationController	Main integration point for local and remote playback.
Protocol endpoint	AnuvaPythonServerCommunication	NetMQ REP/PUSH sockets on localhost defaults.
Camera system	CamController, CameraShots.json, Cinemachine cameras/targets.	Directing shot strings in config are mapped through Unity-side fallback shot selection, not a one-to-one config enum.
Bot system	AnuvaBotAnimator, bot motion plan generator/loader/tester, pose policy JSON.	Anuva_TataMotors_Scene contains bot animator wiring; some scenes have no bot animator reference.
Screen system	Direct material texture display plus Vuplex/Reveal and Anuva.VirtualScreens generated HTML bridge.	Multiple generations coexist.
Capture	AVPro CaptureFromScreen and audio capture helpers.	Capture component can be assigned or auto-added by PresentationController.

Startup Modes

Mode	Entry	Flow
Local playback	Scene with PresentationController, enablePythonServerCommunication = false	Start() initializes cameras and communication settings, loads PresentationConfig.json from StreamingAssets, resolves bot motion plan, preloads assets, then plays if playOnStart is true.
Remote render	Scene with PresentationController, enablePythonServerCommunication = true	Start() initializes ZeroMQ and waits for render.start. On command, Unity loads remote/local config, preloads media, starts capture/playback, and reports status.
Protocol simulator	Assets/Anuva/Scenes/Anuva_Simulator_Scene.unity	AnuvaUnityVideoGeneratorSimulator mimics Unity over ZeroMQ without running the full renderer.

Data Flow

1. PresentationController.Start() initializes RuntimeAPI, bot animator reference, first camera shot, ZeroMQ if enabled, and InitializePresentation().
2. InitializePresentation() creates display/capture/audio targets.
3. If Python communication is disabled, it loads Assets/StreamingAssets/PresentationConfig.json.
4. If Python communication is enabled, it waits in idle for render.start.
5. Config loading uses UnityWebRequest.Get() and JsonUtility.FromJson<PresentationConfig>().
6. Bot motion plan resolution tries a sibling PresentationBotMotionPlan.json, then generates a plan if missing and generation is enabled.
7. Scene assets are preloaded from each scene's first image URL and voiceover audio URL.
8. Playback builds an ordered timeline, begins AVPro capture when enabled, triggers each scene, plays audio and bot motion, advances camera shots, waits through audio/pause durations, then stops capture.
9. Remote rendering reports render.accepted, periodic render.progress, and render.completed or render.failed.

Lifecycle Diagram

sequenceDiagram
  participant Python as Python Server
  participant Unity as PresentationController
  participant ZMQ as AnuvaPythonServerCommunication
  participant Capture as AVPro Capture

  Unity->>Unity: Start / EnsurePresentationTargets
  alt Python communication enabled
    Unity->>ZMQ: Bind command REP, connect status/heartbeat PUSH
    ZMQ-->>Python: unity.ready / unity.heartbeat
    Python->>ZMQ: render.start
    ZMQ->>Unity: HandleRenderStartRequested
    Unity->>Unity: Load config, resolve bot plan, preload media
  else Local playback
    Unity->>Unity: Load StreamingAssets/PresentationConfig.json
  end
  Unity->>Capture: Configure and StartCapture
  Unity->>Unity: Play scenes, audio, camera, screens, bot motion
  Unity->>Capture: StopCapture
  Capture-->>Unity: CompletedFileWritingAction
  Unity-->>Python: render.completed or render.failed

External Dependencies

Dependency	Role
Unity 6000.3.14f1	Project editor version.
URP 17.3.0	Render pipeline.
Cinemachine 3.1.7	Virtual camera and procedural camera targets.
DOTween	Camera and bot tweening.
AVPro Movie Capture	Final MP4 capture and audio capture.
Vuplex WebView	Web/HTML screen rendering.
OneJS	Present in scenes as JSRunner; exact production role Unknown / not confirmed in repo.
NetMQ / AsyncIO	ZeroMQ protocol implementation via NuGetForUnity.
Magic Lightmap Switcher, Bakery, Beautify, ShinySSRR	Lighting/VFX/post-processing support in scenes.

Confirmed Architecture Gaps

• ProjectSettings/EditorBuildSettings.asset enables only Assets/Scenes/SampleScene.unity, not a first-party Anuva render scene.
• The inspected PresentationController scene instances have Python communication disabled in serialized data.
• Command-line argument parsing for Python-provided host/port/job context is Unknown / not confirmed in repo.
• No first-party NUnit/EditMode/PlayMode test assembly was discovered under Assets/Anuva.