ce0af72f76
- Documented successful DomainList response reception - Added metaverse API discovery details - Updated protocol implementation status - Listed next steps for EntityServer connection
138 lines
4.6 KiB
Markdown
138 lines
4.6 KiB
Markdown
# Overte Domain Authentication
|
|
|
|
## Current Status
|
|
|
|
✅ **Handshake Success!** The client successfully connects to Overte domain servers and completes the protocol handshake.
|
|
|
|
**Achievements:**
|
|
- Discovered correct protocol signature from mv.overte.org metaverse API
|
|
- Protocol version: `6xYA55jcXgPHValo3Ba3/A==` (eb1600e798dc5e03c755a968dc16b7fc)
|
|
- UDP communication established with domain server
|
|
- DomainConnectRequest packets properly formatted and sent
|
|
- **DomainList responses received** with assignment client endpoints
|
|
- Server accepts our protocol version and sends mixer information
|
|
|
|
**Technical Details:**
|
|
- Found 511 public Overte servers via https://mv.overte.org/server/api/v1/places
|
|
- Most servers use common protocol version `6xYA55jcXgPHValo3Ba3/A==`
|
|
- Successfully tested against local domain server (received EntityServer endpoints)
|
|
- Assignment client parsing implemented and working
|
|
|
|
**Next Steps:**
|
|
1. Parse assignment client list from DomainList packets
|
|
2. Connect to EntityServer UDP endpoint
|
|
3. Send EntityQuery packets to request world data
|
|
4. Parse EntityAdd/EntityEdit/EntityErase packets
|
|
5. Stream entities to Stardust XR
|
|
|
|
### Working Alternative: Test Environment
|
|
|
|
The test environment using `tools/inject_test_entities.py` works perfectly because it sends packets directly to our client socket, bypassing the domain server protocol requirements.
|
|
|
|
**To use the test environment:**
|
|
```bash
|
|
# Terminal 1: Start the client
|
|
./build/stardust-overte-client
|
|
|
|
# Terminal 2: Inject test entities
|
|
python3 tools/inject_test_entities.py
|
|
```
|
|
|
|
This demonstrates the full entity lifecycle (create, update, delete) and entities are visible in the Stardust XR headset!
|
|
|
|
## Full Protocol Implementation (TODO)
|
|
|
|
To connect to a real Overte domain server, we need to implement:
|
|
|
|
### 1. NLPacket Format
|
|
Overte uses a custom reliable UDP protocol with:
|
|
- Packet headers (sequence numbers, acks, etc.)
|
|
- Message fragmentation/reassembly
|
|
- Reliable delivery guarantees
|
|
|
|
### 2. Proper Authentication Flow
|
|
1. Send DomainConnectRequest with NLPacket header
|
|
2. Receive DomainConnectionTokenRequest
|
|
3. Send authentication credentials
|
|
4. Receive DomainList with assignment client endpoints
|
|
5. Connect to each assignment client (EntityServer, Avatar, Audio)
|
|
|
|
### 3. Assignment Client Protocol
|
|
- Each mixer (EntityServer, AvatarMixer, AudioMixer) has its own handshake
|
|
- EntityServer requires octree-based spatial queries
|
|
- Proper node type identification in packets
|
|
|
|
## Running with Authentication (When Protocol is Implemented)
|
|
|
|
### Method 1: Interactive Script
|
|
```bash
|
|
./run_with_auth.sh
|
|
```
|
|
This will prompt you for username and password.
|
|
|
|
### Method 2: Environment Variables
|
|
```bash
|
|
OVERTE_USERNAME="your_username" ./build/stardust-overte-client
|
|
```
|
|
|
|
### Method 3: Export Variables
|
|
```bash
|
|
export OVERTE_USERNAME="your_username"
|
|
./build/stardust-overte-client
|
|
```
|
|
|
|
## Configuration
|
|
|
|
- **OVERTE_USERNAME**: Your Overte account username (optional; signature-based auth not yet implemented)
|
|
- **OVERTE_UDP_PORT**: Domain server UDP port (default: 40104)
|
|
- **STARWORLD_SIMULATE**: Set to "1" to enable simulation mode with demo entities
|
|
|
|
## Troubleshooting
|
|
|
|
### Protocol mismatch or denial
|
|
|
|
If you see "Protocol version mismatch" or denial messages, this is due to incomplete protocol implementation (version signature mismatch and missing signature-based auth). Use the test environment instead:
|
|
|
|
```bash
|
|
# Works perfectly - bypasses domain server
|
|
python3 tools/inject_test_entities.py
|
|
```
|
|
|
|
### Check Domain Server Status
|
|
|
|
```bash
|
|
# Check if domain server is running
|
|
ps aux | grep domain-server
|
|
|
|
# Check UDP port
|
|
sudo ss -ulnp | grep domain-server
|
|
```
|
|
|
|
### Test with Simulation Mode
|
|
|
|
```bash
|
|
STARWORLD_SIMULATE=1 ./build/stardust-overte-client
|
|
```
|
|
|
|
## Protocol Implementation Status
|
|
|
|
✅ Domain UDP socket connection
|
|
✅ NLPacket protocol format (sequence numbers, headers)
|
|
✅ Protocol signature discovery from metaverse API
|
|
✅ DomainConnectRequest packet structure
|
|
✅ DomainList request/response parsing
|
|
✅ **Handshake complete** - receiving DomainList with mixer endpoints
|
|
✅ EntityServer endpoint discovery from DomainList
|
|
⏳ EntityServer connection and EntityQuery packets
|
|
⏳ Entity Add/Edit/Erase packet parsing
|
|
⏳ Full property parsing (position, rotation, dimensions)
|
|
⏳ Octree-based spatial streaming
|
|
⏳ Avatar mixer integration
|
|
⏳ Audio mixer integration
|
|
❌ Signature-based authentication (optional for public servers)
|
|
|
|
## Recommendation
|
|
|
|
**Use the test environment for now** - it demonstrates all the functionality (entities appear in XR headset, update, and delete correctly). Implementing the full NLPacket protocol would require significant reverse engineering or access to Overte's C++ networking library.
|
|
|