Niantic Studio - HTML Loader

General HTML/CSS/JS loader to overlay niantic studio projects with html UI.

HTML Loader Components Documentation

Core Components

HTML Loader (html-loader.ts)

Main component for loading HTML content into the scene.

Schema

• htmlFile: String (asset) - HTML file to load
• htmlEventName: String - Custom event name for HTML loaded notification (default: 'html:loaded')
• zIndex: Integer - CSS z-index for the container
• disablePointerEvents: Boolean - Whether to disable pointer events

Functions

• Creates a container div with full viewport dimensions
• Loads and injects HTML content from asset file
• Dispatches events to child entities when HTML is loaded
• Handles error cases for asset loading

HTML CSS (html-css.ts)

Loads CSS files into the document.

Schema

• cssFile: String (asset) - CSS file to load

Functions

• Loads CSS files asynchronously
• Injects CSS into document head
• Handles loading errors

HTML JS (html-js.ts)

Loads JavaScript files into the document.

Schema

• jsFile: String (asset) - JavaScript file to load
• waitForHtml: Boolean - Whether to wait for HTML loading before loading JS

Functions

• Loads and injects JavaScript files
• Optional waiting for HTML load completion
• Promise-based loading mechanism
• Error handling for failed loads

Helper Components (/helper)

HTML Button Event (html-button-event.ts)

Handles button click events in HTML.

Schema

• htmlId: String - ID of the HTML button element
• target: Entity ID - Target entity to receive events (optional)
• event: String - Event name to dispatch (default: 'button:clicked')

Functions

• Adds click event listeners to specified buttons
• Dispatches events to specified target or globally
• Initializes on HTML load

HTML Dynamic Text (html-dynamic-text.ts)

Manages dynamic text content in HTML elements.

Schema

• htmlId: String - ID of the HTML text element
• initial: String - Initial text content

Functions

• addText: Sets initial text content
• changeText: Updates text content on 'text:change' events
• Listens for HTML load and text change events

HTML Hide (html-hide.ts)

Controls visibility of HTML elements.

Schema

• htmlId: String - ID of element to hide
• parent: Boolean - Whether to hide parent element instead
• eventTarget: Entity ID - Entity to listen for events on
• event: String - Event that triggers hiding

Functions

• Hides elements by setting display: none
• Responds to specified events for visibility control

HTML Image (html-img.ts)

Handles image loading and display.

Schema

• imgId: String - ID of the image element
• imgSrc: String (asset) - Image source file
• backgroundImage: Boolean - Whether to use as background image
• imageEvent: String - Event that triggers image loading (default: 'html:loaded')

Functions

• Loads images asynchronously with cross-origin support
• Can set as either src or background-image
• Uses state machine pattern for lifecycle management
• Handles loading errors

Common Features

1. All components utilize @8thwall/ecs system
2. Asset handling for external files
3. Event-driven architecture
4. Cross-component communication through events
5. Error handling for asset loading
6. Clean separation of concerns

Usage Notes

• All HTML, CSS, and JS files must be uploaded as asset bundles
• Best practice to put assets into folders, otherwise reupload will destroy component assignments
• Components can be used independently or together
• Event system enables modular communication between components