# DDDBrowser - A Browser for 3D Worlds

## Overview
DDDBrowser is a specialized browser application that loads and renders interactive 3D scenes from HTTPS URLs. Think of it as a web browser, but specifically designed for exploring virtual 3D worlds instead of traditional web pages.

## Creator & Attribution
- **Creator**: Randolph William Aarseth II (Bioblaze Payne)
- **Publisher**: Blazium Games
- **Twitter**: @BlaziumGames
- **Website**: https://dddbrowser.blazium.app/

## Core Features

### URL-Based Scene Loading
DDDBrowser discovers and loads 3D scenes from HTTPS URLs using multiple discovery methods:
1. Script tag (highest priority)
2. Meta tag
3. HTTP header (lowest priority)

All assets must be served over HTTPS for security.

### Scene Format
Scenes are defined using JSON with the following structure:
- **Required fields**: name, version, schemaVersion, assets
- **Optional fields**: world, spawn, movementBounds, gameType, skybox, gamemode
- **Asset types**: model (OBJ/MTL), texture (PNG/JPG/TGA), script (Luau), font (TTF), audio (WAV), textbox, picturebox
- **Instance types**: model, lights, portal, textbox, picturebox, audio, autosaveVolume, teleportVolume

### Luau Scripting
DDDBrowser supports sandboxed Luau scripting for interactive behavior:
- **Entity scripts**: Attach to individual objects
- **Gamemode scripts**: Control overall scene behavior and persistence
- **Lifecycle methods**: on_start, on_update, on_interact, on_save, on_load, on_shutdown
- **APIs**: Input actions, scene identity helpers, localStorage, gamemode state

### Portals & World Spaces
- **Portals**: Jump to destination URLs with configurable radius and trigger types (auto/manual/script)
- **Worlds**: Scenes can share a coordinate space using world IDs and positions
- Enables creation of interconnected scene networks

### 3D UI & Media
- **Textboxes**: Script-controlled UI with buttons and checkboxes, ImGui support
- **Pictureboxes**: Display images in 3D space
- **Audio**: Spatial and ambient sound (WAV format)
- **Fonts**: Custom TTF fonts for textboxes
- **URL Modals**: In-world URL displays

### Game Mechanics
- **Movement modes**: FPS (WASD + mouse, interact E/F, jump/sprint) or NONE (view-only)
- **Volumes**: Autosave, teleport, and trigger volumes (LookedAt, Single, Stay, Toggle)
- **Skybox**: Cubemap or equirectangular textures with rotation
- **Save system**: Manual save from gamemode scripts, autosave volumes

## Technical Details

### Supported Formats
- **Models**: OBJ/MTL
- **Textures**: PNG, JPG, TGA
- **Fonts**: TTF
- **Audio**: WAV (spatial and ambient)
- **Scripts**: Luau

### Configuration & Caching
- **Windows paths**:
  - Config: %APPDATA%/DDDBrowser/config.json
  - Keybindings: %APPDATA%/DDDBrowser/keybindings.json
  - Cache: %LOCALAPPDATA%/DDDBrowser/cache/
- Cache is keyed by base URL
- Audio volume model with categories and master multiplier

### Schema Validation
All scenes are validated against a schema to ensure:
- Required fields are present
- Asset references are valid
- Instance configurations are correct
- HTTPS requirement is met

## Example Scenes
DDDBrowser provides several example scenes demonstrating various features:

1. **All Features Scene** - https://blazium-engine.github.io/DDDBrowserExamples/all-features-scene.html
   Demonstrates: textbox, picturebox, audio, fonts, ImGui textbox, URL modal, scripts

2. **UI Features Scene** - https://blazium-engine.github.io/DDDBrowserExamples/ui-features-scene.html
   Comprehensive UI components demonstration

3. **Media Features Scene** - https://blazium-engine.github.io/DDDBrowserExamples/media-features-scene.html
   Audio and visual media examples

4. **Portal Source** - https://blazium-engine.github.io/DDDBrowserExamples/portal-source.html
   Portal connections between scenes

5. **Textbox Scene** - https://blazium-engine.github.io/DDDBrowserExamples/textbox-scene.html
   Interactive textbox with controls

6. **Metadata HTML** - https://blazium-engine.github.io/DDDBrowserExamples/metadata-html.html
   Scene discovery via HTML metadata

## Use Cases
- Virtual world exploration
- 3D game prototyping
- Interactive 3D presentations
- Educational 3D environments
- Networked virtual spaces via portals
- 3D art galleries and exhibitions

## Key Principles
1. **HTTPS-only**: All assets must be served securely
2. **URL-based**: Scenes are loaded from web URLs, not local files
3. **Sandboxed scripting**: Luau scripts run in a secure sandbox
4. **Scene networks**: Portals enable creation of interconnected virtual spaces
5. **Real-time rendering**: Immediate visual feedback as scenes load and run

## FAQ

**Q: What formats are supported?**
A: OBJ/MTL for models, PNG/JPG/TGA for textures, TTF for fonts, WAV for audio, and Luau for scripts.

**Q: How do scenes get discovered from a webpage?**
A: DDDBrowser checks in priority order: script tag > meta tag > HTTP header.

**Q: Does it support movement?**
A: Yes! Scenes can be FPS mode (full movement with WASD) or NONE (view-only) via the gameType setting.

**Q: Why isn't HTTP supported?**
A: Security and consistency. All assets must be served over HTTPS to ensure safe, encrypted delivery.

## Technology Stack
- Platform: Desktop application (Windows, macOS, Linux)
- Rendering: Real-time 3D graphics
- Scripting: Luau (sandboxed)
- Network: HTTPS-only asset loading
- Format: JSON-based scene definition

## Documentation
For detailed documentation, examples, and troubleshooting, visit:
https://dddbrowser.blazium.app/

## License & Attribution
When referencing DDDBrowser, please credit:
- Creator: Randolph William Aarseth II (Bioblaze Payne)
- Organization: Blazium Games
- Twitter: @BlaziumGames