Master-Arbeit-Tom-Hempel/Unity-Master/Assets/README_AvatarSync.md

Avatar Sync System

A complete system for synchronizing Ready Player Me avatar data between multiple Unity clients through a Python server.

Overview

This system consists of:

• Python Server: avatar_sync_server.py - Hosts avatar data for multiple players
• Unity Writer: AvatarDataWriter.cs - Captures local avatar data and saves to JSON
• Unity Uploader: AvatarDataUploader.cs - Uploads avatar data to server
• Unity Downloader: AvatarDataDownloader.cs - Downloads remote player data from server
• Unity Reader: AvatarDataReader.cs - Applies remote avatar data to local avatars

Quick Start

1. Start the Python Server

# Install Python 3.6+ if not already installed
python avatar_sync_server.py

# Or specify custom host/port
python avatar_sync_server.py --host 0.0.0.0 --port 8080

The server will display URLs like:

• Local: http://127.0.0.1:8080
• Network: http://192.168.1.100:8080 (your local IP)

2. Set Up Unity Clients

Player 1 Setup (Data Sender)

1. Add AvatarDataWriter to your player avatar GameObject
2. Configure the writer to capture your avatar's data
3. Add AvatarDataUploader to any GameObject
4. Configure the uploader:
   • Server Host: Your server IP (e.g., 192.168.1.100)
   • Server Port: 8080
   • Upload As Player: player1
   • Local Data File: avatar_sync_data.json

Player 2 Setup (Data Receiver)

1. Add AvatarDataDownloader to any GameObject
2. Configure the downloader:
   • Server Host: Your server IP
   • Server Port: 8080
   • Target Player: player1 (to receive Player 1's data)
   • Auto Download: ✓ Enable
3. Add AvatarDataReader to your sync avatar GameObject
4. Configure the reader:
   • File Name: player1.json (matches downloader output)

Detailed Setup

Python Server Configuration

The server provides these endpoints:

• GET /player1 - Get Player 1's avatar data
• GET /player2 - Get Player 2's avatar data
• POST /player1 - Update Player 1's avatar data
• POST /player2 - Update Player 2's avatar data
• GET /status - Server status and player info

Unity Inspector Settings

AvatarDataWriter

• Avatar Root: The root GameObject of your avatar
• Write Every Frame: Enable for real-time updates
• Sync World Position: ✓ Enable to sync avatar position
• Sync World Rotation: ✓ Enable to sync avatar rotation
• Enable Debug Mode: Enable for troubleshooting

AvatarDataUploader

• Server Host: IP address of the Python server
• Server Port: Port number (default 8080)
• Upload As Player: Your player ID (player1 or player2)
• Auto Upload: Enable for automatic uploading
• Upload Interval: How often to upload (0.1 = 10 times per second)
• Local Data File: JSON file to upload (avatar_sync_data.json)

AvatarDataDownloader

• Server Host: IP address of the Python server
• Server Port: Port number (default 8080)
• Target Player: Which player's data to fetch (player1 or player2)
• Auto Download: Enable for automatic downloading
• Download Interval: How often to download (0.1 = 10 times per second)
• Local File Name: Leave empty to auto-generate filename

AvatarDataReader

• Target Avatar Root: The avatar GameObject to animate
• File Name: JSON file to read (e.g., player1.json)
• Smooth Transitions: Enable for smooth interpolation
• Sync World Position: ✓ Enable to apply world position
• Sync World Rotation: ✓ Enable to apply world rotation

Network Setup

Local Network (Same WiFi)

1. Find your computer's IP address:
   • Windows: ipconfig
   • Mac/Linux: ifconfig
2. Use this IP in Unity clients (e.g., 192.168.1.100)
3. Make sure firewall allows connections on port 8080

Internet/Remote Setup

1. Forward port 8080 on your router to your server computer
2. Use your public IP address in Unity clients
3. Consider using a dynamic DNS service for easier access

Data Flow

Player 1 Avatar → AvatarDataWriter → avatar_sync_data.json
                                          ↓
avatar_sync_data.json → AvatarDataUploader → HTTP POST → Python Server
                                                             ↓
Python Server → HTTP GET → AvatarDataDownloader → player1.json
                                                             ↓
player1.json → AvatarDataReader → Player 2 Avatar

Troubleshooting

Connection Issues

1. Check server is running: Visit http://server-ip:8080 in browser
2. Verify IP address is correct
3. Check firewall settings
4. Enable debug mode in Unity clients for detailed logs

Sync Issues

1. Check file paths in Sync-Files directory
2. Verify JSON file formats are valid
3. Ensure avatar bone structures match
4. Enable debug mode on writer/reader components

Performance

• Reduce sync intervals if network is slow
• Enable smooth transitions for better visual quality
• Monitor Unity console for error messages

Advanced Usage

Multiple Players

• The server supports any number of players
• Add more endpoints by modifying the Python server
• Use different player IDs in Unity clients

Custom Data

• Extend AvatarSyncData class to include more data
• Modify server to handle additional fields
• Update client/reader scripts accordingly

Security

• Add authentication to the Python server
• Use HTTPS for encrypted communication
• Implement rate limiting for production use

File Structure

Assets/
├── Scripts/
│   ├── AvatarDataWriter.cs      # Captures avatar data
│   ├── AvatarDataUploader.cs    # Uploads data to server
│   ├── AvatarDataDownloader.cs  # Downloads data from server
│   └── AvatarDataReader.cs      # Applies avatar data  
├── Sync-Files/
│   ├── avatar_sync_data.json    # Local avatar data
│   ├── player1.json            # Remote player 1 data
│   └── player2.json            # Remote player 2 data
└── avatar_sync_server.py        # Python server

Component Workflow

For Players Sending Data:

1. AvatarDataWriter → Captures avatar data every frame
2. AvatarDataUploader → Reads the JSON file and uploads to server

For Players Receiving Data:

1. AvatarDataDownloader → Downloads remote player data from server
2. AvatarDataReader → Reads the downloaded JSON and applies to avatar

Tips

1. Start Simple: Begin with local testing before network setup
2. Use Debug Mode: Enable debug logging to understand data flow
3. Check File Timestamps: Verify files are being updated
4. Monitor Server Logs: Watch Python server console for activity
5. Test Connection: Use browser to verify server endpoints work
6. Separate Concerns: Use uploader for sending, downloader for receiving

Common Use Cases

Two-Player Avatar Sync

• Player 1: Uses AvatarDataWriter + AvatarDataUploader (upload as player1) + AvatarDataDownloader (fetch player2)
• Player 2: Uses AvatarDataWriter + AvatarDataUploader (upload as player2) + AvatarDataDownloader (fetch player1)

Spectator Mode

• Players: Use AvatarDataWriter + AvatarDataUploader only
• Spectators: Use AvatarDataDownloader + AvatarDataReader only

Recording/Playback

• Recording: Use AvatarDataUploader to save avatar data to server
• Playback: Use AvatarDataDownloader to fetch and replay stored data

Benefits of Separated Scripts

✅ Cleaner Architecture: Each script has a single responsibility
✅ Easier Configuration: Set up only what you need per client
✅ Better Performance: No unnecessary network calls
✅ Flexible Deployment: Mix and match upload/download as needed
✅ Simpler Debugging: Isolate issues to specific functionality