Thunder Unity Avatar Server

Infrastructure and deployment for the Unity Avatar Server running the Genies SDK on Google Cloud.

What is this?

A Unity Windows application that provides avatar creation, customization, and rendering via a REST API. It runs on a GPU-enabled Google Cloud Compute Engine VM.

Architecture

Frontend (Next.js)                    Google Cloud Compute Engine
┌──────────────────┐                  ┌────────────────────────────┐
│ Browser           │                  │ unity-avatar-server VM     │
│   ↓               │                  │                            │
│ /api/unity/*      │───── HTTP ──────►│ :8081  Unity .exe          │
│ (proxy route)     │                  │   └─ Genies SDK            │
│                   │                  │   └─ HTTP REST API         │
│ .env:             │                  │                            │
│ AVATAR_SERVER_URL │                  │ Windows Server 2022        │
│ =http://34.60.    │                  │ NVIDIA L4 GPU (WDDM)      │
│  178.100:8081     │                  │ g2-standard-4              │
└──────────────────┘                  └────────────────────────────┘

Quick Reference

Property	Value
GCP Service	Compute Engine
GCP Project	vds-thunder
Zone	us-central1-a
Instance	unity-avatar-server
Machine	g2-standard-4 + NVIDIA L4
OS	Windows Server 2022
Port	8081
Current IP	34.60.178.100
Unity Build	gs://vds-thunder-unity-build/unity-build.zip

Repository Structure

├── unity-project/              # Unity project source code (open with Unity 6000.3.6f1)
│   ├── Assets/                 # Scenes, scripts, Genies SDK, and assets
│   ├── Packages/               # Unity package manifest
│   ├── ProjectSettings/        # Unity project settings
│   ├── Server/                 # Server-side scripts and configuration
│   ├── start-server.bat        # Batch script to start the server locally
│   └── start-server.ps1        # PowerShell script to start the server locally
├── startup-script.ps1          # PowerShell script that provisions the VM on boot
├── scripts/
│   ├── deploy.sh               # Create/update the GCP VM
│   └── manage.sh               # Start/stop/reset/status commands
├── proxy/
│   ├── route.ts                # Next.js proxy route (reference copy from frontend)
│   └── avatar-config.ts        # Avatar URL helpers (reference copy from frontend)
├── docs/
│   └── INFRASTRUCTURE.md       # Comprehensive infrastructure documentation
└── README.md

Unity Project

The unity-project/ folder contains the full Unity source project. To work with it:

1. Install Unity 6000.3.6f1 (exact version required)
2. Open unity-project/ as a Unity project
3. Unity will regenerate the Library/ folder on first open
4. The project uses the Genies SDK for avatar creation and customization
5. Build target: Windows x86_64 (Standalone)

Building

1. Open the project in Unity
2. Go to File > Build Settings
3. Select Windows, Mac, Linux > Target Platform: Windows > Architecture: x86_64
4. Click Build and choose an output folder
5. The resulting .exe and _Data/ folder are what gets deployed to the GCP VM

Deploying a new build

# Zip the build output
cd /path/to/build/output
zip -r unity-build.zip .

# Upload to GCS and restart VM
./scripts/manage.sh upload-build unity-build.zip
./scripts/manage.sh reset

Key Files

startup-script.ps1

The main automation script. Runs on every VM boot and handles:

1. NVIDIA GPU driver installation
2. VC++ Redistributable installation
3. Unity build download from GCS
4. Windows Firewall configuration
5. Auto-logon setup for unityuser (required for GPU graphics context)
6. Unity process launch in interactive desktop session

proxy/ (reference)

These files live in the frontend repo (vds-thunder-app). Copies are kept here for reference:

• route.ts — Next.js API route that proxies /api/unity/* to the Unity server
• avatar-config.ts — Helper functions for building avatar URLs

API Endpoints

Method	Endpoint	Description
GET	/api/health	Health check
GET	/api/avatar/current	Currently loaded avatar
POST	/api/avatar/create	Create avatar ({ gender: "male"/"female" })
POST	/api/avatar/{id}/customize	Apply customizations
GET	/api/avatar/{id}/preview	PNG preview image
GET	/api/avatar/{id}	GLB 3D model
GET	/api/assets/manifest	All customization assets

Quick Commands

# Check server health
curl http://34.60.178.100:8081/api/health

# Deploy (first time or update)
./scripts/deploy.sh

# Management
./scripts/manage.sh status        # Health + VM info
./scripts/manage.sh stop          # Stop VM (save costs)
./scripts/manage.sh start         # Start VM
./scripts/manage.sh reset         # Restart VM
./scripts/manage.sh update        # Update startup script + restart
./scripts/manage.sh upload-build path/to/unity-build.zip  # Upload new build

Important Notes

• Not a container. Unity + Genies SDK requires a full Windows desktop with GPU (D3D11). Cannot run in Docker.
• Single-tenant. Only one avatar loaded at a time per VM instance.
• GPU must be in WDDM mode (not TCC). The startup script handles this automatically.
• Auto-logon required. Unity needs an interactive desktop session to initialize D3D11 graphics.
• Ephemeral IP. External IP may change on stop/start. Reserve a static IP for production.

Full Documentation

See docs/INFRASTRUCTURE.md for comprehensive details.