Skip to main content

WebUI

A WebUI is essentially an in-game browser that can display a custom website you have built using HTML, CSS, and JavaScript. It is a powerful way to create GUI elements for your server quickly and flexibly.

note

The JavaScript on a web page and a JavaScript resource are two different things. The page runs in the browser with the browser's API and talks to your resource through the events below; it has no access to the script functions or the game.

Preparing Your WebUI​

The easiest workflow is:

  1. Fully build and test your HTML page in your regular system browser.
  2. Leave only the interfaces (functions, event hooks, etc.) open that will later communicate with your scripts or receive data.

Adding the WebUI to Your Resource​

For players to see your WebUI, they must download all required files when connecting to the server.

  1. Place all your WebUI files in a dedicated folder inside your resource (e.g., UI).
  2. Define these files in your meta file so the client knows to download them:
<meta type="lua">
    <file src="UI/index.html" />
    <file src="UI/style.css" />
    <file src="UI/script.js" />
</meta>

Creating the WebUI​

Once the player has all the necessary files, you can create the WebUI at any time:

local l_webui = nil

Events.Subscribe("scriptInit", function()
    l_webui = WebUI.Create("file://myresource/UI/index.html", 1920, 1080, true)
end)
info

When a WebUI is created, it is displayed immediately.

The WebUI API is designed for on-demand creation: you create it when you want to show it, and destroy it when it is no longer needed.

caution

Even if your WebUI consists of multiple files, you always create it using the HTML file. CSS and JS files should be loaded in the HTML using standard HTML syntax.

In the example above, the WebUI is created during the scriptInit event, right when the player joins the server. The URL uses a local path, but external URLs are also supported.

Local path format:

file://[RESOURCE_NAME]/[PATH_TO_HTML].html

Communicating with Scripts​

Communication between your script and the WebUI works via events, just like between regular scripts.

From your script to the web page:

  1. In the web page's JavaScript file, subscribe to an event:
Events.Subscribe("myJSEvent", function(arg1, arg2) {
    console.log("myJSEvent called!", arg1, arg2);
});
  1. From your script, trigger the event:
WebUI.CallEvent(l_webui, "myJSEvent", { "test", 11 })
caution

If you want to send an event immediately after creating the WebUI, you must do it inside the webUIReady event. Otherwise, the WebUI cannot receive events yet.

From the web page to your script:

Events.Call("myScriptEvent", [arg1, arg2]);

The event arrives in your resource like any other event, whatever language the resource is written in.

Keyboard & Mouse Input​

If your WebUI requires keyboard or mouse interaction (e.g., clicking buttons, typing text), you must first set focus to it:

WebUI.SetFocus(l_webui)

You can do this right after creation. Focus is not set automatically because some UIs (like a speedometer) do not require input.