WebUI

WebUIs utilize CEF (Chromium Embedded Framework) to render HTML pages directly inside the game. This provides an easy and straightforward way to create modern, beautiful user interfaces using standard web technologies (HTML, CSS, JavaScript).

An introduction with URL format, events between page and script, input and debugging is on the WebUI page.

Quick Reference

Name	Type	Description
Create	Client	Creates a WebUI.
Destroy	Client	Destroys a WebUI.
CallEvent	Client	Calls an event on the WebUIs javascript.
GetEventSource	Client	Returns the WebUI whose event is being handled.
SetFocus	Client	Sets focus on a WebUI (mouse & keyboard input).
GetFocus	Client	Returns the focused WebUI.
SetRect	Client	Changes where and how large the WebUI is drawn.
SetSize	Client	Changes the resolution of the page.
GetSize	Client	Returns the resolution of the page.
SetVisible	Client	Shows or hides a WebUI.
IsVisible	Client	Returns whether a WebUI is shown.
SetZIndex	Client	Changes the drawing order of WebUIs.
GetZIndex	Client	Returns the z-index of a WebUI.
LoadURL	Client	Opens another page in a WebUI.
Reload	Client	Loads the current page again.
SetFrameRate	Client	Limits how often the page is rendered.
IsReady	Client	Returns whether the specified WebUI is ready.

Functions that take a webuiID raise a script error if no WebUI with this ID exists, only IsReady returns false instead. A resource can use the WebUIs of other resources as well, as long as it knows their ID.

---

Client Functions

Create

Creates a WebUI.

int webuiID = WebUI.Create(string url, int width, int height, [optional] bool transparent)

Parameter	Description
url	resource://[resource]/[file] (or file://[resource]/[file]) for a file of a resource, or an http:///https:// URL.
width, height	Resolution of the page in pixels, 1 to 8192.
transparent	true lets the game shine through where the page has no background. Default false (white background).

info

A resource file must be listed in the meta file and must exist, otherwise Create raises a script error. See Resource URLs for what the page can do with the files of its resource.

The WebUI belongs to the resource that called Create and is destroyed when that resource stops. At most 10 WebUIs can exist at the same time on a client, including the chat.

Example:

Lua

Events.Subscribe("chatCommand", function(command)
    if command == "/webui" then
        local testWebUI = WebUI.Create("resource://freeroam/webui/index.html", 1920, 1080, true)
    end
end)

JavaScript

Events.Subscribe("chatCommand", (command) => {
    if (command === "/webui") {
        const testWebUI = WebUI.Create("resource://freeroam/webui/index.html", 1920, 1080, true);
    }
});

Squirrel (deprecated)

Events.Subscribe("chatCommand", function(command) {
    if (command == "/webui") {
        local testWebUI = WebUI.Create("resource://freeroam/webui/index.html", 1920, 1080, true);
    }
});

---

Destroy

Destroys a WebUI.

WebUI.Destroy(int webuiID)

If the WebUI has the focus, the focus is released.

---

CallEvent

Calls an event on the WebUIs javascript.

WebUI.CallEvent(int webuiID, string name, [optional] list arguments)

info

Events called before the page is ready (right after Create, LoadURL or Reload) are kept and delivered in order once it has loaded, up to 256 per WebUI. If more are sent before that, the oldest are dropped.

The arguments are converted like all event arguments.

Example:

Lua

-- in client script:
Events.Subscribe("chatCommand", function(command)
    if command == "/webuievent" then
        WebUI.CallEvent(g_webUI, "testEvent", { 3 })
    end
end)

-- in the web page's script:
Events.Subscribe("testEvent", function(testint)
{
    console.log("testEvent was called: " + testint);
});

JavaScript

// in client script:
Events.Subscribe("chatCommand", (command) => {
    if (command === "/webuievent") {
        WebUI.CallEvent(g_webUI, "testEvent", [ 3 ]);
    }
});

// in the web page's script:
Events.Subscribe("testEvent", function(testint)
{
    console.log("testEvent was called: " + testint);
});

Squirrel (deprecated)

// in client script:
Events.Subscribe("chatCommand", function(command) {
    if (command == "/webuievent") {
        WebUI.CallEvent(g_webUI, "testEvent", [ 3 ]);
    }
});

// in the web page's script:
Events.Subscribe("testEvent", function(testint)
{
    console.log("testEvent was called: " + testint);
});

---

GetEventSource

Returns the ID of the WebUI whose event is being handled right now.

int webuiID = WebUI.GetEventSource()

Returns -1 if the event did not come from a WebUI. In a webUIReady handler it returns the WebUI that became ready.

caution

The value is only valid while the handler runs. In a thread started from the handler, or in JavaScript after the first await, it returns -1. Store it in a variable at the start of the handler.

Example:

Lua

Events.Subscribe("buyItem", function(item)
    local webui = WebUI.GetEventSource()
    if webui ~= g_shopWebUI then
        return -- not sent by the shop
    end

    -- ...
end)

JavaScript

Events.Subscribe("buyItem", (item) => {
    const webui = WebUI.GetEventSource();
    if (webui !== g_shopWebUI) {
        return; // not sent by the shop
    }

    // ...
});

Squirrel (deprecated)

Events.Subscribe("buyItem", function(item) {
    local webui = WebUI.GetEventSource();
    if (webui != g_shopWebUI) {
        return; // not sent by the shop
    }

    // ...
});

---

SetFocus

Sets focus on a WebUI (mouse & keyboard input).

WebUI.SetFocus(int webuiID, [optional] bool keepGameInput)

info

The current implementation only allows you to focus on one WebUI at a time. Use -1 as webuiID to reset the focus.

With keepGameInput set to true, the game keeps receiving keyboard input while the WebUI has the focus (for example to keep driving while a UI is open).

A hidden WebUI cannot be focused, SetFocus raises a script error for it. SetFocus(-1) does not close the chat input if the player has it open.

---

GetFocus

Returns the ID of the focused WebUI.

int webuiID = WebUI.GetFocus()

Returns -1 if no WebUI has the focus. While the player types in the chat, it returns -1 as well.

---

SetRect

Changes the size and screen placement of the WebUI sprite.

WebUI.SetRect(int webuiID, int left, int top, int right, int bottom)

info

While Create defines the internal rendering resolution of the browser, SetRect defines where and how large the WebUI is actually drawn on the player's screen using bounding box coordinates.

The page does not notice SetRect; mouse input is mapped to the page's own coordinates. To change the resolution the page works with, use SetSize.

---

SetSize

Changes the resolution of the page.

WebUI.SetSize(int webuiID, int width, int height)

width and height can be 1 to 8192, like in Create. The page gets a resize event and lays itself out again. Until its first frame in the new size is ready, the WebUI keeps showing the last one.

As long as SetRect was never called for the WebUI, the screen area follows the new size. After a SetRect the screen area stays where it is and the page is scaled into it.

Example:

Lua

-- Follow a change of the game resolution.
local width, height = Game.GetScreenResolution()
local uiWidth, uiHeight = WebUI.GetSize(g_hud)

if width ~= uiWidth or height ~= uiHeight then
    WebUI.SetSize(g_hud, width, height)
end

JavaScript

// Follow a change of the game resolution.
const [width, height] = Game.GetScreenResolution();
const [uiWidth, uiHeight] = WebUI.GetSize(g_hud);

if (width !== uiWidth || height !== uiHeight) {
    WebUI.SetSize(g_hud, width, height);
}

Squirrel (deprecated)

// Follow a change of the game resolution.
local width, height = Game.GetScreenResolution();
local uiWidth, uiHeight = WebUI.GetSize(g_hud);

if (width != uiWidth || height != uiHeight) {
    WebUI.SetSize(g_hud, width, height);
}

---

GetSize

Returns the resolution of the page.

int width, int height = WebUI.GetSize(int webuiID)

---

SetVisible

Shows or hides a WebUI.

WebUI.SetVisible(int webuiID, bool visible)

A hidden WebUI is not drawn and its page stops rendering, which saves performance. The page keeps running and still receives events, but timers and animations run much slower and requestAnimationFrame pauses. In the page, document.visibilityState is "hidden".

Hiding the focused WebUI releases the focus.

Example:

Lua

Events.Subscribe("chatCommand", function(command)
    if command == "/hud" then
        WebUI.SetVisible(g_hud, not WebUI.IsVisible(g_hud))
    end
end)

JavaScript

Events.Subscribe("chatCommand", (command) => {
    if (command === "/hud") {
        WebUI.SetVisible(g_hud, !WebUI.IsVisible(g_hud));
    }
});

Squirrel (deprecated)

Events.Subscribe("chatCommand", function(command) {
    if (command == "/hud") {
        WebUI.SetVisible(g_hud, !WebUI.IsVisible(g_hud));
    }
});

---

IsVisible

Returns whether a WebUI is shown.

bool visible = WebUI.IsVisible(int webuiID)

---

SetZIndex

Changes the drawing order of WebUIs.

WebUI.SetZIndex(int webuiID, int zIndex)

WebUIs with a higher z-index are drawn on top. All WebUIs start with 0, and among WebUIs with the same z-index the newer one is on top. The chat has 0 too, so a negative value puts a WebUI behind the chat.

The z-index only affects drawing. Mouse and keyboard input always go to the focused WebUI.

---

GetZIndex

Returns the z-index of a WebUI.

int zIndex = WebUI.GetZIndex(int webuiID)

---

LoadURL

Opens another page in a WebUI.

WebUI.LoadURL(int webuiID, string url)

The URL follows the same rules as in Create and raises a script error in the same cases. webUIReady is triggered again once the new page has loaded, and IsReady returns false until then.

Example:

Lua

Events.Subscribe("openTab", function(tab)
    local webui = WebUI.GetEventSource()
    WebUI.LoadURL(webui, "resource://myresource/UI/" .. tab .. ".html")
end)

JavaScript

Events.Subscribe("openTab", (tab) => {
    const webui = WebUI.GetEventSource();
    WebUI.LoadURL(webui, "resource://myresource/UI/" + tab + ".html");
});

Squirrel (deprecated)

Events.Subscribe("openTab", function(tab) {
    local webui = WebUI.GetEventSource();
    WebUI.LoadURL(webui, "resource://myresource/UI/" + tab + ".html");
});

---

Reload

Loads the current page again.

WebUI.Reload(int webuiID, [optional] bool ignoreCache)

webUIReady is triggered again once the page has loaded. ignoreCache only matters for http:// and https:// pages; files of a resource are always loaded fresh.

---

SetFrameRate

Limits how often the page is rendered.

WebUI.SetFrameRate(int webuiID, int frameRate)

frameRate can be 1 to 60 frames per second, the default is 60. Animations of the page run at this rate. A UI that rarely changes (a scoreboard, a clock) saves performance with a lower value.

---

IsReady

Returns whether the specified WebUI is ready.

bool ready = WebUI.IsReady(int webuiID)

Returns false while a page is loading after LoadURL or Reload, and for IDs that do not exist.