# Avatar Sync Servers

This repository contains two functionally identical avatar synchronization servers optimized for different use cases:

## 1. Python Server (`avatar_sync_server.py`)
- **Data Format**: JSON
- **Language**: Python 3
- **Use Case**: Quick setup, easy debugging, human-readable data

## 2. Go Server (`avatar_sync_server.go`)
- **Data Format**: Raw Binary (Little Endian)
- **Language**: Go
- **Use Case**: High performance, reduced bandwidth, production deployment

## Features

Both servers provide:
- **REST API** for avatar data synchronization
- **CORS support** for web applications
- **Two player slots** (player1, player2)
- **Real-time data exchange**
- **Status monitoring**

## Endpoints

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/` | GET | Status page (HTML) |
| `/status` | GET | Server status information |
| `/player1` | GET | Retrieve Player 1 avatar data |
| `/player1` | POST | Update Player 1 avatar data |
| `/player2` | GET | Retrieve Player 2 avatar data |
| `/player2` | POST | Update Player 2 avatar data |

## Installation & Usage

### Python Server

**Requirements**: Python 3.6+

```bash
# Run the server
python avatar_sync_server.py

# With custom host/port
python avatar_sync_server.py --host 0.0.0.0 --port 8080
```

### Go Server

**Requirements**: Go 1.16+

```bash
# Install Go from https://golang.org/dl/

# Run the server
go run avatar_sync_server.go

# Or build and run
go build avatar_sync_server.go
./avatar_sync_server    # Linux/macOS
avatar_sync_server.exe  # Windows
```

## Performance Comparison

| Aspect | Python (JSON) | Go (Binary) |
|--------|---------------|-------------|
| Data Size | ~100% | ~60-70% |
| Parse Speed | Baseline | 3-5x faster |
| Memory Usage | Higher | Lower |
| CPU Usage | Higher | Lower |
| Setup Complexity | Simple | Moderate |

## Data Format

### Python Server (JSON)
```json
{
  "rootTransform": {
    "worldPosition": {"x": 0.0, "y": 0.0, "z": 0.0},
    "worldRotation": {"x": 0.0, "y": 0.0, "z": 0.0, "w": 1.0},
    "localScale": {"x": 1.0, "y": 1.0, "z": 1.0}
  },
  "bones": [],
  "blendShapes": [],
  "timestamp": 1234567890.123,
  "server_timestamp": 1234567890.456
}
```

### Go Server (Binary)
- **Fixed-size structures** for efficient memory layout
- **Little Endian encoding** for cross-platform compatibility
- **Compact representation** with no text overhead

## Binary Protocol Specification

| Field | Type | Size (bytes) | Description |
|-------|------|-------------|-------------|
| Root Transform | struct | 40 | Position(12) + Rotation(16) + Scale(12) |
| Timestamp | float64 | 8 | Client timestamp |
| Server Time | float64 | 8 | Server timestamp |
| Bone Count | int32 | 4 | Number of bones |
| Bones | []BoneData | Variable | Bone transformations |
| Blend Count | int32 | 4 | Number of blend shapes |
| Blend Shapes | []BlendShapeData | Variable | Facial animation data |

## When to Use Which Server

### Choose Python Server when:
- Rapid prototyping
- Easy debugging needed
- Human-readable data preferred
- Python ecosystem integration
- Small scale deployments

### Choose Go Server when:
- High performance required
- Network bandwidth is limited
- Large scale deployments
- Binary data handling preferred
- Production environments

## Example Client Code

### Python Client (for JSON server)
```python
import requests
import json

# Send avatar data
data = {
    "rootTransform": {
        "worldPosition": {"x": 1.0, "y": 2.0, "z": 3.0},
        "worldRotation": {"x": 0.0, "y": 0.0, "z": 0.0, "w": 1.0},
        "localScale": {"x": 1.0, "y": 1.0, "z": 1.0}
    },
    "bones": [],
    "blendShapes": [],
    "timestamp": time.time()
}

response = requests.post('http://localhost:8080/player1', json=data)
print(response.json())

# Get avatar data
response = requests.get('http://localhost:8080/player1')
avatar_data = response.json()
```

### Go Client (for binary server)
```go
import (
    "bytes"
    "encoding/binary"
    "net/http"
)

// Serialize and send binary data
avatarData := AvatarData{/* ... */}
data, _ := avatarData.SerializeAvatarData()

resp, err := http.Post("http://localhost:8080/player1", 
                      "application/octet-stream", 
                      bytes.NewBuffer(data))

// Receive and deserialize binary data
resp, err := http.Get("http://localhost:8080/player1")
buf := new(bytes.Buffer)
buf.ReadFrom(resp.Body)
avatarData, err := DeserializeAvatarData(buf.Bytes())
```

## Network Information

Both servers will display network information on startup:
- **Local**: `http://127.0.0.1:8080`
- **Network**: `http://[YOUR_IP]:8080`
- **External**: `http://0.0.0.0:8080`

Access the status page in your browser to verify the server is running correctly.