initial upload
This commit is contained in:
tom.hempel
213
Unity-Master/Assets/README_AvatarSync.md
Normal file
213
Unity-Master/Assets/README_AvatarSync.md
Normal file
@ -0,0 +1,213 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user