Skip to main content

Loading Scenes

DDDBrowser loads 3D scenes from web URLs. This guide explains how scene loading works and how to use it effectively.

Using the URL Input​

The URL input field is located in the top bar of DDDBrowser. To load a scene:

  1. Enter a URL in the input field

    • Prefer a valid HTTPS URL (HTTP requires an Allow HTTP confirmation)
    • Should point to an HTML page that embeds or references the scene definition
    • Example: https://blazium-engine.github.io/DDDBrowserExamples/index.html

  2. Click Load or press Enter

  3. Wait for loading - The progress indicator shows:

    • Finding the scene definition in the page/response
    • Asset downloads
    • Scene processing

How DDDBrowser finds the scene definition​

DDDBrowser locates scene JSON in the loaded page/response using a priority order (not an in-app catalog or browse library):

1. HTML <script> Tag (Highest Priority)​

DDDBrowser first looks for a <script> tag with the scene JSON:

<script id="blazium-scene" type="application/vnd.blazium.scene+json">
{
  "name": "My Scene",
  "version": "1.0",
  "schemaVersion": "1.0",
  "assets": [],
  "instances": []
}
</script>

This is the recommended method as it provides the full scene definition inline.

2. HTML <meta> Tag​

If no script tag is found, DDDBrowser checks for a meta tag:

<meta name="x-blazium-scene" content='{"name":"My Scene",...}'>

The content attribute should contain a JSON-encoded scene definition.

3. HTTP Header (Lowest Priority)​

Finally, DDDBrowser checks for an HTTP header:

X-Blazium-Scene: {"name":"My Scene",...}

This is useful for server-side scene generation.

Loading Process​

When you load a scene, DDDBrowser:

  1. Downloads the HTML page from the URL
  2. Locates the scene definition using the priority order above
  3. Validates the scene JSON against the schema
  4. Downloads all assets:
    • Models (OBJ/MTL files)
    • Textures (PNG, JPG, JPEG, TGA)
    • Scripts (Luau files)
    • Fonts (TTF files)
    • Audio (WAV files)
  5. Processes the scene:
    • Creates 3D instances
    • Sets up lighting
    • Loads scripts
    • Initializes physics
  6. Renders the scene and makes it interactive

Loading Progress​

The progress indicator in the top bar shows:

  • Scene definition: Finding scene JSON in the page/response
  • Validation: Checking scene JSON validity
  • Asset downloads: Downloading required files
  • Processing: Creating 3D objects and initializing systems

Error Handling​

If loading fails, DDDBrowser will:

  • Show an error message explaining what went wrong
  • Provide a retry option to try loading again
  • Common errors:
    • Invalid URL or network error
    • Scene JSON validation failure
    • Missing required assets
    • Unsupported file formats

Cache Behavior​

DDDBrowser caches downloaded assets to speed up subsequent loads:

  • Cache location: %LOCALAPPDATA%\DDDBrowser\cache\<md5-hash>\
  • Cache key: MD5 hash of the base URL (scheme://host[:port])
  • Benefits: Faster loading when revisiting scenes
  • Automatic: No configuration needed

The cache is organized by base URL, so assets from the same domain are shared across scenes.

HTTPS default and Allow HTTP​

HTTPS is the default and recommended for scene and asset URLs:

  • ✅ https://example.com/scene.html — Allowed
  • ⚠️ http://example.com/scene.html — Allowed only after an explicit Allow HTTP confirmation
  • ❌ file:///path/to/scene.html — Not supported

Script Engine.httpRequest does not inherit travel Allow HTTP; it stays HTTPS-only under Network Policy.

Leaving a Scene​

To unload the current scene and return to the idle state:

  • Click the Leave Instance button in the top bar
  • Or use Esc leave/quit controls when appropriate

This will:

  • Unload all scene assets
  • Stop all scripts
  • Return to the default grid view
  • Clear the scene state

Best Practices​

  • Prefer HTTPS: Serve scenes over HTTPS; use Allow HTTP only when you intentionally need plain HTTP
  • Optimize assets: Compress textures and models for faster loading
  • Provide metadata: Include scene metadata for travel/portal confirmation previews
  • Test loading: Verify your scene loads correctly before sharing
  • Handle errors: Provide fallbacks for missing assets

Next Steps​