Starworld/RENDERING_FIX_SUMMARY.md

Starworld Rendering Pipeline Fix Summary

Problem Diagnosis

The Starworld project stopped rendering entities after attempting to implement 3D model and texture support. The root cause was using incorrect Stardust API patterns that don't exist in the current version:

Issues Found:

1. Incorrect Model API Usage

   • Used Model::namespaced("fusion", "tex_cube") which doesn't exist
   • Attempted to use ModelPart::new() and .mat_param() which are server-side APIs, not available in the client asteroids library

2. API Mismatch

   • Confused server-side Model implementation with client-side asteroids Elements
   • The Model element in asteroids requires a file path via Model::direct(PathBuf)
   • Material parameters are not directly accessible from client code

3. Asset Pipeline Missing

   • Overte provides model URLs (HTTP), but Stardust's Model::direct() expects local file paths
   • No asset download/caching mechanism was implemented

Solution Implemented

1. Switched to Wireframe Rendering

Instead of trying to use non-existent model APIs, the fix implements proper wireframe visualizations using the Stardust Lines element, which is well-supported and documented:

// Box entities - 12-edge cube wireframe
let cube_lines = create_wireframe_cube(node_color, 0.005);
Spatial::default()
    .transform(transform)
    .build()
    .child(Lines::new(cube_lines).build())

// Sphere entities - 3 orthogonal circles
let sphere_lines = create_wireframe_sphere(node_color, 0.005);
Spatial::default()
    .transform(transform)
    .build()
    .child(Lines::new(sphere_lines).build())

// Model entities - octahedron placeholder
let oct_lines = create_octahedron_wireframe(node_color, 0.005);
Spatial::default()
    .transform(transform)
    .build()
    .child(Lines::new(oct_lines).build())

2. Cleaned Up Dependencies

Removed unused imports:

• Model and ModelPart from asteroids (not needed for wireframe approach)
• Transform (already using fully qualified path)
• MaterialParameter (not available in client API)
• ResourceID (not needed for current implementation)

3. Updated Cargo Configuration

Changed from path-based dependency (non-existent local asteroids) to git-based:

[dependencies.stardust-xr-asteroids]
git = "https://github.com/StardustXR/asteroids.git"
branch = "dev"

Current Rendering Capabilities

✅ Working:

• Box entities render as colored wireframe cubes
• Sphere entities render as 3-circle wireframe spheres
• Model entities render as octahedron wireframes (distinct placeholder)
• All entities respect:
  • Position, rotation, scale (transform)
  • RGB color with alpha
  • Dimensions (xyz size)
  • Entity type differentiation

❌ Not Yet Implemented:

• Loading actual 3D models from Overte URLs
• Applying textures to surfaces
• Solid surface rendering

Build Status

✅ Bridge compiles successfully (warnings resolved)

cd bridge
cargo build
# Output: Finished `dev` profile [unoptimized + debuginfo] target(s) in 2.01s

How to Test

1. Build the Bridge

cd /home/mayatheshy/stardust/Starworld
cd bridge
cargo build --release

2. Build the C++ Client

cd /home/mayatheshy/stardust/Starworld
mkdir -p build && cd build
cmake ..
make

3. Run with Simulation Mode

export STARWORLD_SIMULATE=1
export STARWORLD_BRIDGE_PATH=/home/mayatheshy/stardust/Starworld/bridge/target/debug
./stardust-overte-client

This will create three demo entities:

• CubeA: Red wireframe cube (20cm)
• SphereB: Green wireframe sphere (15cm)
• ModelC: Blue octahedron (25cm)

4. Connect to Real Overte Server

export STARWORLD_BRIDGE_PATH=/home/mayatheshy/stardust/Starworld/bridge/target/debug
./stardust-overte-client ws://domain.example.com:40102

Path to Full 3D Model Support

To implement true 3D model rendering, you would need:

Phase 1: Asset Management

1. Model Downloader Service

   • Background thread/async task to download models from Overte URLs
   • Cache to local filesystem (e.g., ~/.cache/starworld/models/)
   • Track download progress and completion

2. URL to Path Mapping

   • Hash Overte URLs to generate cache filenames
   • Maintain a registry: HashMap<String, PathBuf> (URL -> local path)
   • Handle re-downloads on cache miss

Phase 2: Dynamic Scene Updates

3. Placeholder → Model Replacement

   • Initially render wireframe placeholder
   • When model download completes, update the scene:

   if let Some(local_path) = model_cache.get(&node.model_url) {
       Model::direct(local_path)
           .transform(transform)
           .build()
   } else {
       // Wireframe placeholder while downloading
       Lines::new(octahedron_lines).build()
   }
   

4. Texture Application

   • Download textures to cache similarly
   • Use model part API to apply materials (requires deeper asteroids integration)

Phase 3: Format Conversion (if needed)

5. Overte → GLTF Conversion
   • If Overte uses proprietary formats, implement converter
   • Or use Overte's existing export capabilities

Example: Working Model Loading Pattern

From the Armillary project (reference implementation):

match Model::direct(&self.model_path) {
    Ok(model_elem) => {
        model = Some(
            model_elem
                .pos([0.0, model_info.height_offset, 0.0])
                .build()
                .identify(&model_info.uuid),
        )
    }
    Err(e) => {
        // Fallback to error text display
        model_error = Some(
            Text::new(format!("Model Error:\n{e}"))
                .character_height(0.025)
                .build(),
        )
    }
};

Key takeaway: Model::direct() requires a valid local PathBuf, not a URL.

Conclusion

The rendering pipeline is now functional and stable with wireframe visualizations. This provides:

• Immediate feedback during development
• Low overhead for debugging entity positions/transforms
• Clear visual distinction between entity types
• Foundation for future 3D model integration

To enable full 3D models, implement the asset pipeline described above. The wireframe approach will continue to work as a fallback for failed downloads or unsupported model formats.

Files Modified

1. bridge/src/lib.rs - Fixed reify() implementation to use Lines instead of non-existent Model APIs
2. bridge/Cargo.toml - Changed asteroids dependency from path to git
3. ENTITY_RENDERING_ENHANCEMENTS.md - Updated documentation to reflect wireframe approach

Build Artifacts

After building, the bridge library will be at:

• Debug: bridge/target/debug/libstardust_bridge.so
• Release: bridge/target/release/libstardust_bridge.so

The C++ client will dynamically load this at runtime.