Entity Rendering Implementation for Starworld

Overview

This document describes the entity rendering system in Starworld, which loads and displays Overte entities as 3D GLTF/GLB models in the StardustXR compositor.

Current Implementation

1. Entity Data Structure (`OverteClient.hpp`)

EntityType enum:

enum class EntityType {
    Unknown, Box, Sphere, Model, Shape, Light, Text, 

    ## Current Implementation

    All core entity rendering features are implemented:

    - 3D model rendering (GLTF/GLB) for Box, Sphere, Model, Text, Light, Zone types
    - Parent/child entity hierarchies (scene graph, transform propagation)
    - Entity query/filtering by distance (C++/Rust bridge API)
    - HTTP/HTTPS model and texture download and caching (SHA256-based)
    - Primitive model generation (cube, sphere, suzanne) with Blender
    - Transform, dimension, and color/texture data parsing and propagation
    - Color and texture download infrastructure is complete, but visual application is pending StardustXR API support
    - See [`docs/ENTITY_TROUBLESHOOTING.md`](ENTITY_TROUBLESHOOTING.md) for debug flags and troubleshooting

    ## Testing

    See [`README.md`](../README.md) and [`docs/IMPLEMENTATION_COMPLETE.md`](IMPLEMENTATION_COMPLETE.md) for up-to-date build and test instructions.

    ## Limitations

    - Color tinting and texture application are not yet visually applied (pending StardustXR API extension)
    - Only Box, Sphere, Model entity types are supported
    - atp:// protocol is not yet supported
    - See [`docs/IMPLEMENTATION_COMPLETE.md`](IMPLEMENTATION_COMPLETE.md) for full status

    ## References

    - Overte protocol: `third_party/overte-src/libraries/networking/`
    - Stardust API: https://github.com/StardustXR/core
    - See `docs/` for protocol, troubleshooting, and implementation details

This creates three demo entities:

CubeA - Red cube model (20cm)
SphereB - Green sphere model (15cm)
ModelC - Blue Suzanne model (25cm)

Live Overte Connection

To connect to a real Overte server:

# Optional: Set credentials
export OVERTE_USERNAME=your_username

# Connect to server
./build/starworld ws://domain.example.com:40102

The client will:

Perform domain handshake
Discover entity server via DomainList packets
Send EntityQuery to request all entities
Parse and render entities with full visual properties

Architecture

┌─────────────────┐
│ Overte Server   │
│ (Entity Server) │
└────────┬────────┘
         │ UDP Packets (EntityAdd, EntityEdit)
         │ Contains: type, position, rotation, dimensions,
         │          color, modelUrl, textureUrl
         ▼
┌─────────────────────┐
│  OverteClient.cpp   │
│  - parseEntityPacket│
│  - OverteEntity     │
└────────┬────────────┘
         │ consumeUpdatedEntities()
         ▼
┌─────────────────────┐
│   SceneSync.cpp     │
│  - Maps Overte IDs  │
│    to Stardust IDs  │
└────────┬────────────┘
         │ createNode(), setNodeColor(), 
         │ setNodeModel(), etc.
         ▼
┌─────────────────────┐
│ StardustBridge.cpp  │
│  - C++ wrapper      │
│  - dlopen bridge.so │
└────────┬────────────┘
         │ C-ABI calls: sdxr_set_node_*
         ▼
┌─────────────────────┐
│ bridge/lib.rs       │
│  - Command queue    │
│  - Shared state     │
└────────┬────────────┘
         │ BridgeState::reify()
         ▼
┌─────────────────────┐
│  Stardust Server    │
│  - Model rendering  │
│  - GLTF/GLB loading │
└─────────────────────┘

Implemented Features ✅

3D Model Rendering - Loads GLTF/GLB models using Stardust Model element
Entity Type Support - Box (cube), Sphere, Model (Suzanne placeholder)
Transform Support - Position, rotation, scale from dimensions
HTTP Downloads - ModelCache with SHA256 caching, async libcurl
Primitive Generation - Blender export script for test models
Local Caching - Two-tier cache (primitives + downloaded models)

Future Enhancements

Short Term

Material color application - Apply entity.color to model materials
Texture support - Load and apply entity.textureUrl to models
More entity types - Add support for Light, Text, PolyLine, etc.
ATP protocol - Support atp:// URLs for Overte asset server

Medium Term

Material parameters - PBR materials with metallic/roughness
Animation - Skeletal animation for rigged models
Entity updates - Real-time property changes
Entity deletion - Remove entities from scene

Long Term

Physics sync - Real-time physics state synchronization
Script integration - Execute Overte entity scripts in Stardust context
Avatar rendering - Full avatar mesh and animation support
Audio spatialization - 3D positional audio from Overte

Build Instructions

# Build Rust bridge
cd bridge
cargo build
cd ..

# Build C++ client
cd build
cmake ..
make
cd ..

# Run
./build/starworld

Dependencies

C++17 - Modern C++ features
GLM - Math library for vectors/matrices
OpenSSL - MD5 hashing for protocol signatures
Rust nightly - For Stardust bridge
stardust-xr-asteroids - Declarative UI framework
stardust-xr-fusion - Low-level client API
tokio - Async runtime

References

Overte protocol: third_party/overte-src/libraries/networking/
Entity types: Based on Overte EntityTypes.h
Packet formats: Overte NLPacket specification
Stardust API: https://github.com/StardustXR/core

6.0 KiB Raw Blame History