RoboXR Viroo — Unity Project

Technical Documentation & Architecture Overview | Generated 2026-05-18

Table of Contents

Project Overview
Technology Stack
Asset & Code Structure
Scenes
Key Scripts
AAXLP Module
REACH / VR Builder Integration
VIROO Packages
Full Package List
MCP for Unity
Applied Compiler Fixes
Known Issues
Referenced Manuals

1. Project Overview

Unity Version

6.3 LTS

Project Path

C:\RoboXR_Working\RoboXR_Viroo

Render Pipeline

URP 17.3.0

Active Scene

01 Alpha Scene

Compiler Status

✓ Clean

RoboXR Viroo is an industrial VR training application built on the VIROO Studio 2.6 multi-user XR framework. The project combines three integrated modules:

AAXLP — AI-Assisted XR Layout Planning: lets users design factory floor layouts in VR using voice commands, ChatGPT, and drag-and-drop item placement.
REACH — Robot & XR Interaction via VR Builder: process-based training scenarios authored with a node editor, including robot arm interaction, completable sequences, and role-based permission management.
VIROO Studio — the multi-user, multi-platform collaborative XR runtime that handles networking, scene loading, user sessions, and VR device management.

2. Technology Stack

🎮 Engine & Rendering

Unity 6.3 LTS
URP 17.3.0
ProBuilder (mesh editing)
XR Interaction Toolkit 3.3.1

🌐 Networking & XR

VIROO Studio 2.6.941
com.virtualware.networking
SignalR protocols
OpenXR / SteamVR

🤖 AI / LLM

LLMUnity (local LLM)
Unity Sentis 2.2.0 (Inference Engine)
Whisper Tiny (STT)
OpenAI Unity (ChatGPT)

🔧 Tooling

Visual Scripting 1.9.9
DOTween (animation)
glTFast 6.14.1 (model import)
Addressables (asset loading)

🖥 Target Platforms

Windows PC (Desktop)
VR Headsets (OpenXR)
Multi-user via VIROO cloud

📦 Package Sources

Unity Registry
VIROO Azure DevOps registry
OpenUPM (UniTask, LitMotion)
GitHub (MCP-Unity, OpenAI)

3. Asset & Code Structure

Assets/Code/Runtime

File	Purpose
`AssemblyGroup.cs`	Groups assembly parts together
`AssemblyPart.cs`	Individual part in assembly sequence
`AssemblyTarget.cs`	Snap target for part placement
`Completables/`	Completable sequence data & UI (Audio, Click, Video, Trigger, PartOnTarget)
`GrabbableConfiguration.cs`	XR grab settings per object
`XRSocketInteractorWithTag.cs`	Tag-filtered XR socket
`XRTargetFilterByPartType.cs`	Filters snap targets by part type
`XRTargetFilterByPose.cs`	Filters snap targets by pose proximity

Assets/Code/Editor

File	Purpose
`AssemblyPartsEditor.cs`	Custom inspector for assembly configuration
`AutoAssignGUIDs.cs`	Auto-assigns unique IDs to scene objects
`FindMissingScripts.cs`	Editor tool to detect missing script references

Assets/Scripts (Runtime)

File	Role
`ScenarioManager.cs`	Controls scenario flow across 3 learning scenarios
`CommonVariables.cs`	Shared global state/variables
`ItemHandler.cs`	AAXLP: spawn, move, rotate, delete factory items
`RoomGenerator.cs`	AAXLP: generates room from layout data
`WallPlacer.cs`	AAXLP: places boundary walls
`BoundaryChecker.cs`	AAXLP: prevents item placement outside bounds
`PathVisualizer.cs`	AAXLP: draws connections between items
`AinakJSONReader.cs`	AAXLP: loads saved layout JSON files
`ChatGPTController.cs`	AAXLP: sends voice commands to OpenAI, parses response
`CommandWheel.cs`	AAXLP: radial menu for item commands
`FileControl.cs`	AAXLP: saves/loads layout files
`DoWhenLookedAt.cs`	Gaze-triggered interactions
`VRLaserPointer.cs`	Laser pointer for VR UI interaction
`VoiceCommandController.cs`	Routes voice input to action handlers
`SubtitleManager.cs`	Displays subtitles for narration/voice
`Notification.cs`	In-world notification display
`InputManager.cs`	Handles keyboard/controller input
`MouseLook.cs`	Desktop placeholder camera look (VIROO takes over in VR)
`Menu.cs`	Main menu logic
`Settings.cs`	App settings (volume, quality, snapping)

Visual Scripting — ScriptMachines

Assets/ScriptMachines

AT_Completable_Sequence — main sequence state machine
AT_GrabbableObject — per-object grab state
AT_GrabbablesManager — manages all grabbables in scene
AT_DisplayResults — end-of-sequence results UI
Completables/: Audio, Click, Video, Trigger, PartOnTarget, PlayableDirector, ICompletable

Assets/ScriptMachines_Common

FadeWhenVirooReady — fade-in on session start
Viroo_XRInteractionConfiguration_SM — XRIT setup
Utilities/ComponentsExtensions_Library
Utilities/Serialization_Library
Utilities/CreateOrSetDictionaryKeyValue
Utilities/TransformDeltaThreshold

4. Scenes

Scene File	Purpose	Status
`01 Alpha Scene.unity`	Active development scene — currently open in Unity	Active
`VIROO Main.unity`	Main VIROO-managed scene (networking, XR bootstrap)	Production
`VR.unity`	AAXLP entry point — contains Manager with ChatGPTController, ItemHandler, WallPlacer; must have OpenAI API key configured	Production
`main.unity`	Application bootstrap / launcher scene	Production

5. Key Script Notes

The VR scene's Manager GameObject is the central hub for AAXLP: it holds ChatGPTController, ItemHandler, WallPlacer, RoomGenerator, and all event wiring. OpenAI API key must be set here before testing.

ScenarioManager drives the three educational scenarios sequentially. It references VIROO session events to synchronize across users.

MouseLook.cs & OnFootController.cs are desktop-only placeholders — the VIROO XR rig replaces these in full VR deployment.

6. AAXLP Module — AI-Assisted XR Layout Planning

AAXLP is a factory floor layout planning tool with AI-assisted item placement, voice commands, and scenario-based training. It is fully embedded in the project (not a separate installed package).

System Architecture Diagram (from manual)

Load / Create Layout

Load Previous Layout → AinakJSONReader + RoomGenerator
Make New Layout → WallPlacer + RoomGenerator

Layout Editing

Spawn / Move / Rotate / Delete → ItemHandler + CommandWheel
Boundary Avoidance → BoundaryChecker
Manage Connections → PathVisualizer

Voice AI Pipeline

Voice Input → RunWhisper (STT Whisper Tiny)
Internet Upload → ChatGPTController
Command Parse → ChatGPTController

Unity Events (20+ endpoints)

AinakJSONReader: onLayoutLoaded, onLayoutSaved, onItemsProcessed
ItemHandler: onItemSpawn, onItemDelete, onItemMove, onItemRotate
CommandWheel: onStartedMoving, onFinishedMoving, onConnected
ChatGPTController: onResponseFinishedProcessing
Menu: onPause, onReset, onExit, onLoadingStarted/Ended

Required Unity Layers (AAXLP-specific, must be set manually)

Layer Index	Name
16	Floor
17	Placing
18	Ceiling
19	Wall
20	Boundary
21	WallPoint

AAXLP Configuration Checklist

Enter OpenAI API key + Org ID in ChatGPTController on the Manager object in the VR scene
Set Active Input Handling to Both in Project Settings → Player → Other Settings
Add tag VIROORoot and assign to Root GameObject in VR scene
Remove Space from "Alt Positive Button" of Submit input in Input Manager
Layers 16–21 must match exactly as above

3D Factory Items (in project)

Prefabs/Factory Planning

Assembly-Desk
Forklift
Robotic-Arm
Tool-Rack

Prefabs/New Models

AgvMover, ForkLift, PalletJack
AssemblyDesk, Table_small, Table_office
Conveyor_straight, Box_platform
RoboticArm, RoboticArm_Wall
Human (worker avatar)
MachineM, MaxMover
Doors: doorBasic, doorRoller, doorRoller_tall

Project Assets (raw imports)

UR_UR12e.glb — Universal Robots UR12e arm
gripper-visualization.glb
AGV.glb
InjectionMoldZelleEnvironment (Blender)
Industrial Floor, ASST Security Cabin
light_barrier.glb
display stand, hanging_monitor

Building Modules (Prefabs/Modules)

Walls: W2_H4_WALL, W4_H4_WALL, W4_H4_WINDOW
Corners: W2_H4_D2_Corner, CEIL_CORNER
Ceiling: CEIL_WALL_FILL
Structure: H_BEAM, H_PILAR, LAMP

7. REACH / VR Builder Integration (D9 Manual)

The D9 integration package connects VR Builder (node-based training scenario authoring) with VIROO Studio for multi-user VR training sessions. "REACH" refers to the RoboXR deliverable context.

Process Architecture

Process → Chapters → Steps → Behaviors + Conditions
Each Step is a node in the Process Editor
Behaviors: make things happen (ExecuteVIROOActions, etc.)
Conditions: gate progression (GripButton, PushButton, PullLever, SetSlider, TurnKnob)
Parallel Execution Nodes for simultaneous paths

VIROO-Specific Conditions

Grip Button Condition
Pull Lever Condition
Push Button Condition
Set Slider Condition
Turn Knob Condition
Execute VIROO Actions Behavior

Role & Permission System

Roles configured in Project Settings → VR Builder → Roles and Permissions
SetDefaultUserRoles component (Root → VR Builder → PERMISSION_HANDLER)
SetUserRolesOnInteract — assigns role on hover/select/activate
Policies: Grab Objects, Touch Objects, Grab/Touch Object Group

Scene Requirements

Root parent GameObject required
Tag VIROORoot on Root object
Layer 8 assigned to floor objects
Generate Object ID for all Process Scene Objects via VIROO Network Object component
Process Scene Object component on every interactable

Multi-User Limitation: VR Builder process state is NOT automatically synchronized across all users in multi-user VIROO sessions. The VIROO integration replicates the majority of VR Builder's core functionality but multi-user sync of process execution requires additional configuration.

8. VIROO Packages (PackageCache)

Core VIROO

Package	Role
`com.viroo.studio@2.6.941`	Core VIROO Studio XR framework
`com.viroo.interactions`	VIROO XR interaction layer
`com.viroo.sceneloader`	Multi-scene loading pipeline
`com.viroo.vivox`	Spatial voice chat
`com.viroo.shared.arena`	Shared virtual arena/space
`com.nmerso`	VIROO Community package

Virtualware Infrastructure

Package	Role
`com.virtualware.networking`	Low-level networking layer
`com.virtualware.dependencyinjection`	DI container
`com.virtualware.localization`	Multi-language support + TMP
`com.virtualware.download`	Asset download manager
`com.virtualware.rest`	REST API client
`com.virtualware.logging`	Structured logging

VIROO packages are served from the Azure DevOps scoped registry: pkgs.dev.azure.com/virtualwaregroup/.../Viroo@Release/npm/registry/

9. Full Package Manifest (manifest.json)

Package	Version / Source	Category
com.gamelovers.mcp-unity	GitHub (CoderGamester)	MCP/Dev Tool
com.demigiant.dotween	file:.tgz (local)	Animation
com.srcnalt.openai-unity	GitHub	AI
com.unity.asset-manager-for-unity	1.9.1	Tooling
com.unity.cloud.gltfast	6.14.1	3D Import
com.unity.formats.fbx	5.1.4	3D Import
com.unity.multiplayer.center	1.0.1	Networking
com.unity.render-pipelines.universal	17.3.0	Rendering
com.unity.sentis	2.2.0 (Inference Engine)	AI/ML
com.unity.visualscripting	1.9.9	Visual Scripting
com.unity.xr.interaction.toolkit	3.3.1	XR
com.viroo.studio	2.6.941	VIROO
com.viroo.studio.extensions.visualscripting	2.6.7	VIROO
com.viroo.studio.visualscripting	2.6.941	VIROO

10. MCP for Unity (Claude Code Integration)

Unity Editor is connected to Claude Code via the MCP for Unity server, enabling AI-assisted scene editing, script generation, and console monitoring directly from the Claude Code CLI.

Package

com.gamelovers.mcp-unity (CoderGamester)
Server: Node.js (built into PackageCache)
Protocol: WebSocket + stdio

Claude Code Config

"mcp-unity": {
  "type": "stdio",
  "command": "node",
  "args": ["C:/RoboXR_Working/RoboXR_Viroo/
    Library/PackageCache/
    com.gamelovers.mcp-unity@a32e47d4ec87/
    Server~/build/index.js"]
}

11. Applied Compiler Fixes

Fix 1 — DefaultSceneManager.cs (UniTask 2.5.10 compatibility)
File: Library/PackageCache/com.virtualware.networking@a3f9fa8c6640/Runtime/Client/SceneManagement/DefaultSceneManager.cs
Problem: CS0311 — AsyncOperation does not implement IEnumerator, so direct await via GetAwaiter<T> failed.
Fix: Changed both LoadScene and UnloadScene to use .ToUniTask().AsTask().

Fix 2 — LinkXmlFileResolver.cs (System.IO.Abstractions 22.x breaking change)
File: Library/PackageCache/com.virtualware.networking@a3f9fa8c6640/Editor/LinkXmlFileResolver.cs
Problem: CS1069 — IFileSystem was moved to the Testably.Abstractions.FileSystem.Interface assembly in 22.x and was no longer available via the standard System.IO.Abstractions namespace.
Fix: Replaced the entire file to use System.IO.Path directly (no external dependency needed for this use case).

Important: Both fixes are in the Library/PackageCache folder. This folder is regenerated when Unity clears its library or reinstalls packages. If either fix disappears after a reinstall, re-apply both changes. A permanent solution would be to add a local package override in the Packages/ folder.

12. Known Issues

Issue	Severity	Status
Visual Scripting `SerializationException: Unable to find type 'Viroo.VisualScripting.Extensions.XRIT.*'` — appears in Unity Console as warnings after project load	Warning	Cosmetic — caused by VS type database caching old XRIT types after XRI upgraded from 3.2.1 → 3.3.1. Does not affect runtime. Fix: Tools → Visual Scripting → Regenerate Nodes
PackageCache fixes (above) are not persistent across Library regeneration	Medium	Document fix locations; re-apply if Unity reinstalls packages
REACH robot package (CustomIkSolver.exe, VORAUS WebSocket) not yet installed in this project	Pending	Available in D:\Downloads\download reach\
MCP WebSocket drops between Claude Code sessions	Expected	Start new Claude Code session to reconnect; MCP server auto-reconnects in Unity

13. Referenced Manuals & Resources

File	Content	Pages
`01.D9_REACH_VIROO-Integration-Manual.pdf`	VIROO + VR Builder integration: architecture, installation, process editor, permission system, VIROO-specific behaviors & conditions, multi-user limitations, best practices	18
`02.How-to-use AAXLP Software Module.pdf`	AAXLP installation checklist, layer configuration, OpenAI setup, testing guide, system architecture diagram, script responsibilities, Unity Events reference, custom model integration guide	7
`RoboXR educational template draft.docx.pdf`	Project educational template / scenario design document	—
`RoboXR scenes.pdf`	Scene overview documentation	—
`Credentials for viroo etc.txt`	VIROO portal credentials and access info	—