Skip to content

⚙️ Optimization Guide

Optimizing your StorySplat scenes ensures they load quickly and run smoothly across various devices, especially on the web and mobile platforms. This guide covers key techniques for optimizing both Gaussian Splat data and scene configuration.

1. Gaussian Splat Data Optimization

The size and complexity of your core Gaussian Splat data (.ply, .splat, .spz) are the biggest factors influencing performance and load times.

  • Convert to Optimized Formats:
    • .spz (Recommended): Use the File Menu -> Convert PLY to SPZ tool or enable Auto-convert PLY to SPZ on load. This format offers good compression while preserving Spherical Harmonics (lighting detail). It's generally the best balance for web delivery.
    • .splat: Use File Menu -> Convert PLY to SPLAT. This format is uncompressed but can sometimes be more compatible with simpler viewers. Warning: This conversion removes Spherical Harmonics data.
  • Reduce Point Count (External Tools): Before importing into StorySplat, consider using external tools (like PlayCanvas SuperSplat or other point cloud software) to:
    • Downsample: Reduce the total number of Gaussian points if the scene is excessively dense.
    • Clean Up: Remove unnecessary points (floaters, noise) that don't contribute significantly to the visual result.
  • Optimize During Capture: If you're creating splats from photogrammetry, follow best practices for clean captures to minimize noise and unnecessary data from the start.

2. Scene Configuration Optimization

Within the StorySplat editor, optimize the elements you add to your scene:

  • Waypoints:
    • Use a reasonable number of waypoints. Too many closely spaced waypoints can slightly increase path calculation overhead, though the impact is usually minimal.
    • Optimize audio files associated with waypoints (see below).
  • Hotspots:
    • Media Files: Use optimized image (e.g., WebP, compressed JPG/PNG) and video (e.g., compressed MP4/WebM) files for image/video plane hotspots and info popups. Large media files significantly impact load times.
    • GIFs: Animated GIFs can be large. Consider using short video loops (MP4/WebM) instead for better performance and quality.
    • Complexity: Limit the number of complex hotspots (especially those with video or large images) visible simultaneously. Use Visibility Ranges to load/unload hotspots as needed.
  • Collision Meshes:
    • Use the simplest possible shapes (Plane, Cube, Sphere) that effectively define your boundaries.
    • Avoid overly complex custom meshes for collision if simple primitives suffice.
    • Use the minimum number of colliders necessary. Fewer colliders mean better performance in Walk/VR modes.
  • Custom 3D Models:
    • Polygon Count: Use low-polygon models where possible. High-poly models increase load time and rendering cost.
    • Textures: Optimize texture sizes. Use formats like JPG or PNG with appropriate compression. Consider texture atlases for multiple small objects.
    • Materials: Simple materials perform better than complex PBR materials with many layers, although StorySplat generally handles standard materials well.
  • Lighting:
    • Remember lights only affect meshes/hotspots, not splats.
    • Limit the number of active lights, especially those casting shadows (shadows are computationally expensive).
    • Use light Range properties (for Point/Spot lights) effectively to limit their influence.
  • Particle Systems:
    • Emit Rate & Lifetime: Lower emit rates and shorter particle lifetimes reduce the number of active particles.
    • Particle Count: Keep the maximum number of particles (maxParticles in the underlying system, often around 2000 by default in the editor) reasonable.
    • Texture Size: Use small, optimized textures for particles.
    • Complexity: Avoid overly complex particle behaviors or numerous emitters if performance is critical.
  • Skybox:
    • Use reasonably sized equirectangular images (e.g., 4096x2048). Very large skybox textures consume significant VRAM. Consider JPEG for smaller file size if maximum quality isn't essential.

3. Export Settings Optimization

When exporting your scene (HTML or saving):

  • Spherical Harmonics (SH Bands): In the export settings (via File -> Export -> Viewer App or during Upload/Update), you can choose the number of SH bands (0-3) to include.
    • 3 Bands (Default): Highest quality lighting and reflections.
    • 2 or 1 Band: Reduces data size and rendering cost at the expense of some lighting detail.
    • 0 Bands: Smallest size, removes all SH data, resulting in flat lighting (similar to .splat format).
    • Recommendation: Start with 3 bands and reduce only if necessary for performance or file size targets.
  • Keep Meshes In Memory (SplatSwap): If using the SplatSwap feature:
    • Enabled: Smoother transitions between splats, but higher memory usage as all loaded splats are kept in VRAM.
    • Disabled (Default): Lower memory usage, but transitions might involve brief loading/unloading, potentially causing a slight hitch.

4. Testing and Iteration

  • Test on Target Devices: Performance can vary greatly. Test your exported scenes on the types of devices (desktop, mobile, low-end, high-end) your audience will use.
  • Check Network Loading: Use browser developer tools (Network tab) to analyze load times and identify large assets.
  • Iterate: If performance is poor, revisit the optimization steps above, focusing on the largest or most complex elements first.

By applying these optimization techniques, you can create StorySplat experiences that are both visually stunning and performant across a wide range of devices.

Previous: Lighting | Next: Scroll Post Message Functionality