From 8fc8ea519592d8a893d3782339a850612af893d1 Mon Sep 17 00:00:00 2001 From: MayaTheShy Date: Sun, 9 Nov 2025 02:53:32 -0500 Subject: [PATCH] docs: add comprehensive developer guide with build, run, test, and debugging commands --- DEVELOPER_GUIDE.md | 319 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 319 insertions(+) create mode 100644 DEVELOPER_GUIDE.md diff --git a/DEVELOPER_GUIDE.md b/DEVELOPER_GUIDE.md new file mode 100644 index 0000000..21897ae --- /dev/null +++ b/DEVELOPER_GUIDE.md @@ -0,0 +1,319 @@ +# Starworld Developer Quick Reference + +## Build Commands + +```bash +# Full clean build +./build_and_test.sh + +# Build Rust bridge only +cd bridge && cargo build --release + +# Build C++ client only +cmake --build build --target starworld -j$(nproc) + +# Rebuild bridge (debug mode) +cd bridge && cargo build + +# Clean everything +rm -rf build bridge/target +``` + +## Run Commands + +```bash +# Simulation mode (no Overte server needed) +STARWORLD_SIMULATE=1 ./build/starworld + +# Connect to local domain +./build/starworld --overte=127.0.0.1:40104 + +# Connect to remote domain +./build/starworld --overte=domain.example.com:40104 + +# Domain discovery +./build/starworld --discover + +# With verbose logging +RUST_LOG=debug ./build/starworld +``` + +## Test Commands + +```bash +# Run all tests +./ci-test.sh + +# Run C++ tests only +./build/starworld-tests + +# Run Rust tests only +cd bridge && cargo test + +# Check code style +cd bridge && cargo fmt --check +cd bridge && cargo clippy +``` + +## Debugging + +### Check Domain Server Status +```bash +# Is domain server running? +ps aux | grep domain-server + +# What ports is it listening on? +sudo ss -ulnp | grep domain-server + +# Check for assignment clients +ps aux | grep assignment-client +``` + +### Check StardustXR Connection +```bash +# Is Stardust server running? +ps aux | grep stardust + +# Find Stardust socket +ss -lx | grep stardust + +# Check Stardust logs +journalctl --user -u stardust -f +``` + +### Debug Overte Connection +```bash +# Test network connectivity +ping 127.0.0.1 +nc -zvu 127.0.0.1 40104 # If nc available + +# Capture Overte packets (requires root) +sudo tcpdump -i lo -n udp port 40104 -X + +# Run with connection logging +./build/starworld --overte=127.0.0.1:40104 2>&1 | tee connection.log +``` + +### Check Model Cache +```bash +# List cached primitive models +ls -lh ~/.cache/starworld/primitives/ + +# List downloaded models +ls -lh ~/.cache/starworld/models/ + +# Check export log +cat ~/.cache/starworld/primitives/export_log.txt + +# Regenerate primitives +python3 tools/blender_export_simple.py +``` + +## Common Issues + +### "Failed to connect to StardustXR compositor" +```bash +# Start StardustXR server first +stardust-xr-server & + +# Or check if it's running +ps aux | grep stardust +``` + +### "Rust bridge present but start() failed" +```bash +# Rebuild bridge +cd bridge && cargo build --release + +# Check library exists +ls -lh bridge/target/release/libstardust_bridge.so + +# Check for missing dependencies +ldd build/starworld +``` + +### "Retrying domain handshake..." +```bash +# Domain server not responding - check if running +ps aux | grep domain-server + +# Try local server first +./build/starworld --overte=127.0.0.1:40104 + +# Check firewall for remote domains +sudo ufw status +``` + +### Nothing renders in XR +```bash +# Check if entities exist +RUST_LOG=debug ./build/starworld 2>&1 | grep -i entity + +# Use simulation mode +STARWORLD_SIMULATE=1 ./build/starworld + +# Check bridge logs +./build/starworld 2>&1 | grep '\[bridge' +``` + +## File Locations + +### Source Code +- `src/main.cpp` - Entry point, argument parsing +- `src/OverteClient.cpp` - Overte protocol implementation +- `src/StardustBridge.cpp` - C++/Rust bridge interface +- `src/SceneSync.cpp` - Entity synchronization +- `src/NLPacketCodec.cpp` - Packet encoding/decoding +- `src/QDataStream.cpp` - Qt serialization +- `bridge/src/lib.rs` - Rust StardustXR client + +### Configuration +- `CMakeLists.txt` - C++ build configuration +- `bridge/Cargo.toml` - Rust build configuration +- `.gitea/workflows/` - CI/CD pipelines + +### Documentation +- `README.md` - Main documentation +- `OVERTE_AUTH.md` - OAuth implementation guide +- `OVERTE_ASSIGNMENT_CLIENT_TASK.md` - Protocol details +- `CHANGELOG.md` - Version history +- `ENTITY_RENDERING_ENHANCEMENTS.md` - Rendering implementation +- `MODELCACHE_IMPLEMENTATION.md` - Asset pipeline + +### Tests +- `tests/TestHarness.cpp` - C++ unit tests +- `bridge/src/lib.rs` - Rust unit tests (inline) + +## Key Environment Variables + +| Variable | Purpose | Example | +|----------|---------|---------| +| `STARWORLD_SIMULATE` | Enable simulation mode | `1` | +| `STARWORLD_BRIDGE_PATH` | Override bridge location | `./bridge/target/release` | +| `OVERTE_UDP_PORT` | Override UDP port | `40104` | +| `OVERTE_DISCOVER` | Enable domain discovery | `1` | +| `RUST_LOG` | Rust logging level | `debug` | +| `STARDUSTXR_SOCKET` | Override Stardust socket | `/run/user/1000/stardust-socket` | + +## Protocol Quick Reference + +### Port Numbers +- **40102**: HTTP/WebSocket (domain server web interface) +- **40104**: UDP (domain server main communication) +- **Dynamic**: Assignment clients (EntityServer, AudioMixer, etc.) + +### Packet Types +- `0x1F` (31): DomainConnectRequest +- `0x02` (2): DomainList reply +- `0x03` (3): DomainListRequest +- `0x05` (5): Ping +- `0x06` (6): PingReply +- `0x10` (16): EntityQuery + +### Connection Flow +``` +1. Client → Domain: DomainConnectRequest (UDP 40104) +2. Domain → Client: DomainList (session UUID, local ID, assignment clients) +3. Client → Domain: Periodic Ping (keep-alive) +4. Client → EntityServer: EntityQuery (or domain as fallback) +5. EntityServer → Client: EntityData (not yet implemented) +``` + +## Architecture Diagram + +``` +┌─────────────────┐ +│ StardustXR │ +│ Compositor │ +└────────┬────────┘ + │ Unix Socket +┌────────▼────────┐ +│ Rust Bridge │ +│ (stardust-xr- │ +│ fusion) │ +└────────┬────────┘ + │ C ABI (dlopen) +┌────────▼────────┐ +│ StardustBridge │ +│ (C++) │ +└────────┬────────┘ + │ +┌────────▼────────┐ +│ OverteClient │ +│ (C++) │ +└────────┬────────┘ + │ UDP (NLPacket) +┌────────▼────────┐ +│ Overte Domain │ +│ Server │ +└─────────────────┘ +``` + +## Useful Commands + +```bash +# Find all TODO comments +grep -rn "TODO\|FIXME" src/ bridge/src/ + +# Count lines of code +cloc src/ bridge/src/ + +# Generate compile_commands.json +cmake -DCMAKE_EXPORT_COMPILE_COMMANDS=ON build + +# Format Rust code +cd bridge && cargo fmt + +# Update dependencies +cd bridge && cargo update + +# Check for security vulnerabilities +cd bridge && cargo audit + +# Build documentation +cd bridge && cargo doc --open +``` + +## Performance Profiling + +```bash +# Build with debug symbols +cmake -DCMAKE_BUILD_TYPE=RelWithDebInfo build +make -j$(nproc) + +# Run with perf +perf record -g ./build/starworld +perf report + +# Memory profiling with valgrind +valgrind --leak-check=full ./build/starworld + +# Rust flamegraph (requires cargo-flamegraph) +cd bridge && cargo flamegraph +``` + +## Git Workflow + +```bash +# Start new feature +git checkout -b feature/my-feature + +# Make changes, commit +git add src/OverteClient.cpp +git commit -m "Add entity color support" + +# Push and create PR +git push origin feature/my-feature +# Then create PR in Gitea web UI + +# Update from main +git fetch origin +git rebase origin/main +``` + +## Resources + +- [Overte Source](https://github.com/overte-org/overte) +- [StardustXR Docs](https://stardustxr.org) +- [Overte Protocol](https://github.com/overte-org/overte/tree/master/libraries/networking/src) +- [Issue Tracker](https://git.spatulaa.com/MayaTheShy/Starworld/issues)