Create a WebView
Package the page
Section titled “Package the page”Place the interface files inside the folder selected by resources.pack.path.
With the example project layout, this is
the mod’s client/ folder:
client/ scripts/ client.js ui/ hud.html hud.jsresources://ui/hud.html loads ui/hud.html from that bundle. Relative URLs
inside the page work normally, so ./hud.js loads the adjacent file.
For a frontend framework, put its built HTML, JavaScript, CSS and assets in
client/ui/. Configure its asset paths for that location. With a
resources://ui/… URL, /assets/… resolves inside ui/assets/…. Build before
the server packages the files.
Show a HUD
Section titled “Show a HUD”The example displays a message over the game. Create ui/hud.html:
<!doctype html><html lang="en"> <head> <meta charset="utf-8"> <title>HUD</title> <style> html, body { margin: 0; background: transparent; }
body { color: white; font: 16px system-ui; }
#message { position: absolute; top: 24px; left: 24px; width: 360px; max-width: calc(100vw - 48px); box-sizing: border-box; margin: 0; padding: 12px 16px; border-radius: 8px; background: rgb(15 18 24 / 85%); } </style> </head> <body> <p id="message"></p> <script type="module" src="./hud.js"></script> </body></html>In ui/hud.js, register the event handler and notify the client that the page
is ready:
// @ts-check/// <reference types="@revomp/types-webview" />
const message = document.querySelector('#message');if (!message) throw new Error('HUD message element is missing');
revo.on('hud:message', (/** @type {string} */ text) => { message.textContent = text;});
revo.emit('hud:ready');The browser exposes revo as a global. For editor types, install
@revomp/types-webview as a development dependency in your frontend project.
Run this from the client entry script or import it from there:
// @ts-check/// <reference types="@revomp/types-client" />import * as revo from 'revo-client';
const view = new revo.WebView('resources://ui/hud.html');view.visible = false;
view.on('hud:ready', () => { view.emit('hud:message', 'Welcome to the server'); view.visible = true;});
view.on('loadFailed', (url, code, message) => { revo.log('HUD failed to load:', url, code, message);});view.emit() sends an event to the page. The page’s revo.emit() sends an event
back to that WebView’s client-side handlers. Arguments use JSON serialization.
Send plain data such as strings, numbers, arrays and objects. Pass selected
entity properties or IDs when the UI needs game state.
For requests, errors and handler cleanup, see WebView bridge.
For console, network and layout inspection, see Debug WebViews.
Readiness
Section titled “Readiness”view.waitForReady() waits for the main document’s JavaScript bridge and defaults
to a 15-second timeout. Images, fonts, framework mounting and application data
can still be loading when it resolves. The example uses hud:ready after
registering its handler. In a larger interface, send that event once the page has
finished the setup it needs before being shown.
The ready property reports bridge readiness. Calling view.emit() before the
bridge is ready throws. The loadSuccessed event reports document loading with
the URL and HTTP status code. loadFailed reports a load error and the browser
closes. Errors in your page’s JavaScript need their own error handling.
For an interface required during connection, see Loading screen.
Size, transparency and visibility
Section titled “Size, transparency and visibility”Omitting the dimensions in new WebView(url) creates a fullscreen WebView at
(0, 0). It follows changes to the game resolution automatically, including while
hidden. The page keeps its state and receives the browser’s resize event.
Use responsive CSS to adapt its layout.
For a view that occupies part of the screen, pass width and height with
units: 'viewport'. Each dimension is a fraction from 0 to 1, where 1
fills that axis. This example uses half the game viewport’s width and height:
// @ts-check/// <reference types="@revomp/types-client" />import * as revo from 'revo-client';
const panel = new revo.WebView('resources://ui/hud.html', { width: 0.5, height: 0.5, units: 'viewport',});panel.pos = { x: 24, y: 24 };panel.on('hud:ready', () => panel.emit('hud:message', 'Viewport panel'));
const size = revo.getViewportSize();revo.log('Viewport:', size.x, size.y);revo.on('viewportResize', (width, height) => { revo.log('Viewport changed:', width, height);});getViewportSize() returns the current game render dimensions in pixels.
viewportResize(width, height) fires when they change. Read the initial size
with the getter when registering a handler. Before the first valid viewport is
available, the getter returns (0, 0).
Pass both dimensions, such as new WebView(url, 360, 80), for a fixed pixel size.
The object form also supports units: 'pixels', which is the default when
units is omitted. Pixel dimensions must be positive integers.
Use view.setSize({ width: 0.5, height: 1, units: 'viewport' }) to change the
sizing rule later. view.size returns the resolved pixel size. Assigning to it
switches to fixed pixels. Viewport fractions round to the nearest pixel, with a
minimum of one pixel for positive values. A zero dimension hides the surface
and disables its input while keeping the page loaded.
view.pos sets the position in pixels and preserves the sizing rule.
view.zIndex controls stacking, with higher values drawn above lower ones.
Setting view.fullscreen = true fills the viewport and resets the position to
(0, 0). Setting it to false keeps the current position and fixes the size in
pixels.
CSS viewport units such as vw and vh refer to the WebView’s dimensions.
Use the browser’s resize event when the page itself needs to respond to a
change in its dimensions.
The browser surface supports transparency. Keep the page background transparent
where the game should remain visible. An opaque body or fullscreen container
covers the scene beneath it.
New WebViews are visible by default. visible = false hides the surface while
keeping the page loaded. Showing it again preserves the document’s state.
For an interactive menu, follow
Cursor and UI focus. To hide a private
panel while OBS is open, see OBS detection.
Navigation and cleanup
Section titled “Navigation and cleanup”Assigning view.url loads another document and resets bridge readiness. Register
the new page’s handlers and repeat its ready notification before sending data.
Pending bridge requests are rejected when their document closes.
The URL can also point to a hosted HTTP(S) page. Use a URL you control. Bridge access is restricted to the origin selected by the client script, so a redirect to another origin can leave the page without bridge access.
Call view.destroy() when the interface is no longer needed. This closes the
browser and releases its resources. WebViews are also destroyed when their
owning script resource stops.
For frame-rate settings and choosing when to reuse or close an interface, see WebView performance and lifetime.