# 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

```bash
# 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