Skip to content

Create a WebView

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.js

resources://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.

The example displays a message over the game. Create ui/hud.html:

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:

WebView · ui/hud.js
// @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:

Client
// @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.

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.

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:

Client
// @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.

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.