Troubleshooting Realm VTT Issues

This guide is designed to help troubleshoot various issues that can come up.

Mobile Devices

While Realm VTT can work on most tablets and mobile devices, mobile devices tend to have much higher memory constraints. As a result, you might have trouble loading or viewing larger Scenes. If you experience frequent crashes or refreshes on a mobile or tablet device, try either disabling the Dynamic Lighting on that scene, or re-uploading the image used for the Scene at a much lower resolution.

Common Error Messages

If you see any of these errors in your browser console:

• THREE.WebGLRenderer: Error creating WebGL context with your selected attributes

• WebGL creation failed: tryNativeGL (FEATURE_FAILURE_CGL_FBO)

• Exhausted GL driver options. (FEATURE_FAILURE_WEBGL_EXHAUSTED_DRIVERS)

• Failed to initialize dice box

These indicate that your browser cannot create a WebGL rendering context needed for 3D dice. This is a common issue in Firefox.

Firefox - Hardware Acceleration Fix

This is the most common solution for Firefox users.

Steps to Enable Hardware Acceleration:

1. Open Firefox Settings

   • Click the menu button (...) in the top-right corner

   • Select "Settings"

2. Navigate to Performance Settings

   • In the Settings search bar, type "performance"

   • Or scroll down to the "General" section and find "Performance"

3. Disable Recommended Settings

   • Uncheck "Use recommended performance settings"

   • This will reveal additional options

4. Enable Hardware Acceleration

   • Make sure "Use hardware acceleration when available" is checked

5. Restart Firefox

   • Completely close Firefox (all windows)

   • Reopen Firefox and reload the application

Why This Works

Firefox's "recommended performance settings" may disable hardware acceleration on some systems, which prevents WebGL from working properly. By manually enabling hardware acceleration, you allow Firefox to use your GPU for 3D rendering.

Chrome/Edge - Hardware Acceleration

If you experience similar issues in Chrome or Edge:

1. Open Settings → System

2. Enable "Use hardware acceleration when available"

3. Restart the browser

Advanced Firefox Troubleshooting

If the above steps don't work, try these additional fixes:

Enable WebGL Force Mode

1. Type about:config in the Firefox address bar

2. Click "Accept the Risk and Continue"

3. Search for webgl.force-enabled

4. Double-click to set it to true

5. Search for webgl.disabled

6. Make sure it's set to false

7. Restart Firefox

Check WebGL Support

Visit https://get.webgl.org/ to verify WebGL is working in your browser.

If you see a spinning cube, WebGL is working. If not, there may be a deeper issue with your system or drivers.

Update Graphics Drivers

Outdated GPU drivers can cause Firefox to blacklist WebGL support:

• Windows: Visit your GPU manufacturer's website (NVIDIA, AMD, or Intel)

• macOS: Update to the latest macOS version via System Preferences → Software Update

• Linux: Update via your package manager or GPU manufacturer's drivers

Browser-Specific Notes

Firefox

• Most common issue: Hardware acceleration disabled

• Solution: Follow the "Firefox - Hardware Acceleration Fix" steps above

Safari

• WebGL should work by default on modern macOS versions

• If issues persist, check macOS system updates

Chrome/Edge

• Hardware acceleration disabled in settings

• Too many WebGL contexts from other tabs (close some tabs)

Too Many WebGL Contexts

If you have many tabs open with 3D content:

1. Close unused tabs - Browsers limit the number of WebGL contexts

2. Reload the page after closing tabs

3. Use a separate browser window for the VTT if needed

Fallback Option

If you cannot get WebGL working:

• The application will display error messages with retry options

• Close other tabs that might be using WebGL

• Try a different browser (Chrome, Edge, or Firefox)

Still Not Working?

If you've tried all the above steps:

1. Check your browser console (F12) for specific error messages

2. Try a different browser to isolate the issue

3. Update your operating system and GPU drivers

4. Contact support with:

   • Browser version

   • Operating system

   • GPU model

   • Console error messages

Technical Details

The 3D dice system uses:

• THREE.js for WebGL rendering

• Phaser for the main game canvas (separate WebGL context)

If Phaser loads but dice don't, the issue is likely related to:

• Multiple WebGL contexts

• Firefox's hardware acceleration settings

• GPU driver compatibility

If the Scene or page refreshes constantly:

• This could be due to low memory. While Realm VTT does work on Mobile devices, large scenes or maps may cause memory related issues on some mobile devices.