Skip to content

🛠️ Troubleshooting Guide

Encountering issues while using StorySplat? This guide covers common problems and potential solutions.

Loading Issues

Scene / Splat Won't Load

  • Symptom: The editor remains blank, shows a loading indicator indefinitely, or displays an error message upon trying to load a file or URL.
  • Possible Causes & Solutions:
    • Unsupported File Format: Ensure you are loading a supported Gaussian Splat format (.ply, .splat, .spz). Traditional mesh formats (.glb, .gltf, .obj) should be loaded via the "3D Models" menu, not as the primary scene splat. See File Format Compatibility.
    • Invalid File Content: The file might be corrupted or might not contain valid Gaussian Splat data (e.g., a standard mesh saved as .ply). Try opening the file in another viewer (like PlayCanvas SuperSplat) to verify its contents.
    • Large File Size: Very large splat files can exceed browser memory limits or take a very long time to load. Consider optimizing the splat externally before importing (See Optimization Guide).
    • Network Issues: Check your internet connection. Slow or unstable connections can interrupt loading from URLs.
    • CORS Errors (URL Loading): If loading from a URL, the hosting server might be blocking access due to CORS (Cross-Origin Resource Sharing) restrictions.
      • Solution 1: Ensure the server hosting the file sends the correct CORS headers (e.g., Access-Control-Allow-Origin: * or your specific domain).
      • Solution 2: Enable the "Use CORS Proxy" option in the Settings Menu (⚙️ icon) within the StorySplat editor.
    • Browser Cache: Sometimes stale cache data can interfere. Try clearing your browser's cache and reloading the editor.
    • Temporary Glitch: Occasionally, a simple page refresh (Ctrl+R or Cmd+R) can resolve temporary loading hiccups.

Assets (Images, Audio, Custom Models) Not Loading

  • Symptom: Hotspots display incorrectly (missing images/videos), audio doesn't play, or custom 3D models don't appear.
  • Possible Causes & Solutions:
    • Incorrect URL: Double-check the URLs provided for images, videos, audio files, or custom models in the respective editor panels (Hotspots, Waypoints, 3D Models). Ensure they are correct and publicly accessible.
    • CORS Errors: Similar to splat loading, assets loaded from external URLs might be blocked by CORS. Enable the "Use CORS Proxy" setting or ensure the hosting server has correct CORS headers.
    • File Deletion (Cloud Storage): If the assets were uploaded via StorySplat, ensure they haven't been accidentally deleted from your cloud storage. Check your User Dashboard or Firebase console if applicable.
    • Network Issues: Verify your internet connection.

Performance Issues

Slow Rendering / Low FPS (Frames Per Second)

  • Symptom: The scene view is sluggish, camera movement feels choppy, interactions are delayed.
  • Possible Causes & Solutions:
    • High Splat Count: The primary Gaussian Splat file has too many points for the device to handle smoothly. Optimize the splat externally (See Optimization Guide).
    • Complex Scene Elements: Too many active custom meshes, complex particle systems, or numerous high-resolution media hotspots can strain resources. Simplify these elements or use Visibility Ranges to manage when they are active.
    • Inefficient Lighting: While lights don't affect splats, numerous complex lights can impact performance if you also have meshes in the scene. Simplify your lighting setup if necessary.
    • Hardware Limitations: The viewing device (especially older mobiles or laptops with integrated graphics) may not have sufficient GPU power. Test on different devices.
    • Browser Issues: Try a different web browser (Chrome, Firefox, Edge often have good WebGL/WebGPU performance). Ensure your browser and graphics drivers are up-to-date. Clear browser cache.
    • "Keep Meshes In Memory" (SplatSwap): If using SplatSwap, having this option enabled with many large splats can consume excessive memory. Try disabling it.

Long Load Times

  • Symptom: The initial loading screen takes a very long time to disappear.
  • Possible Causes & Solutions:
    • Large Splat File: Optimize the source splat file (convert to .spz, reduce points externally).
    • Large Assets: Optimize images, videos, audio files, and custom 3D models used in hotspots, waypoints, etc.
    • Slow Network: Test with a faster internet connection.
    • Server Issues (URL Loading): If loading from a URL, the host server might be slow.

Visual Glitches

Model Orientation Incorrect (Upside Down / Rotated)

  • Symptom: Imported splat appears flipped or rotated incorrectly.
  • Solution: Go to the Settings Menu (⚙️ icon) and toggle the "Invert Y Scale" and/or "Invert X Scale" options until the orientation is correct. Save the scene to persist this setting. See File Format Compatibility.

Flickering or Z-Fighting

  • Symptom: Surfaces appear to flicker or fight for visibility.
  • Possible Causes & Solutions:
    • Overlapping Geometry: Ensure collision meshes or custom 3D models are not perfectly overlapping flat surfaces. Adjust their positions slightly.
    • Clipping Planes: The Near/Far Clipping Distance settings in the Settings Menu might be too extreme. Try adjusting them (e.g., increase Near, decrease Far).

Missing Textures or Colors

  • Symptom: Custom meshes or image/video/gif hotspots appear white, black, or untextured.
  • Possible Causes & Solutions:
    • Incorrect URL/Path: Verify the media URL is correct and accessible.
    • CORS Issues: Enable the CORS Proxy or fix server headers.
    • Unsupported Format: Ensure image/video formats are web-compatible (JPG, PNG, WebP, MP4, WebM, GIF).

Interaction Issues

Hotspots Not Working

  • Symptom: Clicking or hovering over hotspots does nothing.
  • Possible Causes & Solutions:
    • Activation Mode: Check the hotspot's Activation Mode setting (Click, Hover, None). Ensure it's set correctly for the desired interaction.
    • Content Missing: Verify that content (Image URL, iFrame URL, Description, External Link) is actually configured for the hotspot.
    • Visibility Range: Check if the hotspot is currently outside its defined Visibility Range (Percentage or Waypoint).
    • Overlapping Elements: Another invisible element (like a large collision mesh) might be blocking interaction. Check in Collision Edit Mode.

Audio Not Playing

  • Symptom: Waypoint or custom mesh audio fails to play.
  • Possible Causes & Solutions:
    • Browser Autoplay Policy: Browsers often require user interaction (a click) before allowing audio to play automatically. Ensure the user has clicked somewhere in the scene first, or use the "Show Start Experience Button" export option.
    • Incorrect URL/CORS: Verify the audio URL and check for CORS issues.
    • Spatial Audio Settings: If using spatial audio, ensure the Trigger Distance (Waypoints) or position/max distance settings are appropriate for the camera's location.
    • Mute Button: Check if the scene's mute button is active.

Saving/Exporting Issues

Unable to Save/Upload

  • Symptom: Clicking "Save Project" or "Publish Changes" results in an error or does nothing.
  • Possible Causes & Solutions:
    • Not Logged In: You must be logged into a StorySplat account.
    • No Waypoints: At least one waypoint must be created to define the initial camera view.
    • Storage/Scene Limit Reached: Check your account limits (Storage Used, Splats Used) in the User Dashboard. Upgrade your plan if necessary.
    • Invalid Scene Title: Ensure the scene title doesn't contain problematic characters (though this is less common).
    • Network Error: Check your internet connection.
    • Server Error: Temporary StorySplat server issues. Try again later.

Export to HTML Fails

  • Symptom: Clicking "Export Scene to HTML" results in an error or no download.
  • Possible Causes & Solutions:
    • Project Not Saved: You must save the project to your account first before exporting.
    • Pop-up Blocker: Your browser might be blocking the file download pop-up. Check your browser settings.
    • Large Scene Size: Very large scenes might time out during the export generation process. Try optimizing the scene first.

Still Having Trouble?

If your issue isn't covered here or the solutions don't work:

  1. Check the Console: Open your browser's developer console (F12 or Right-Click -> Inspect -> Console) for specific error messages.
  2. Visit the Help Page: Review the full Help Documentation.
  3. Join Discord: Ask the community for help on the StorySplat Discord Server.
  4. Contact Support: Email support@storysplat.com with details about the issue, including steps to reproduce it, your browser/OS information, and any console errors.

Previous: SplatSwap | Next: Understanding Gaussian Splats