Skip to main content

WebUI

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

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’s 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 Lua to JavaScript:

  1. In your JavaScript file, subscribe to an event:
Events.Subscribe("myJSEvent", function(arg1, arg2) {
    console.log("myJSEvent called!", arg1, arg2);
});
  1. From Lua, 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 JavaScript to Lua:

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

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) don’t require input.

Performance Tips​

  • The maximum WebUI size is currently 1080p (1920 × 1080).
  • For best performance:
    • Limit the WebUI size to the actual element you need.
    • Use SetRect to position it precisely on the screen.