nui

Client

Browser pages over the game, the cursor and notifications. Read the NUI guide first, it has a complete example.

Pages are drawn by an off-screen Chromium browser into a transparent window above the game.

modkit.browser.add

modkit.browser.add(url)

Opens a page and returns a browser object. The page covers the whole screen. It is click-through until you give it focus.

Parameter	Type	Description
url	string	path inside your own resource, for example `"ui/index.html"`. With a leading slash it is `"/<resource>/<path>"` of any delivered resource.

Returns: a browser object, or nil when the browser could not be created, for example because the game's CEF library is not loaded yet.

local ui = modkit.browser.add("ui/index.html")
if not ui then print("no browser") end

Browser object

Member	Description
`browser.id`	integer id of this browser
`browser:call(name, ...)`	fire `modkit.events.add(name, fn)` handlers in the page. Strings, numbers, booleans and `nil` keep their type.
`browser:on(name, fn)`	handle `modkit.trigger(name, ...)` from the page. Only the resource that opened the browser receives its events.
`browser:execute(js)`	run JavaScript in the page
`browser:setActive(active)`	ask for mouse and keyboard input. It only takes effect while the cursor is on.
`browser:isActive()`	`true` when input was requested with `setActive(true)`
`browser:getUrl()`	full URL of the page
`browser:reload([ignoreCache])`	reload the page
`browser:destroy()`	close the browser

ui:on("formSubmitted", function(name, amount)
  modkit.events.callRemote("shop:buy", name, amount)
  ui:setActive(false)
  modkit.gui.cursor.show(false, false)
end)

ui:call("showShop", "Meat", 25)
ui:execute("document.body.style.opacity = 0.9")

Objects and arrays from the page arrive as JSON text. Decode them with modkit.json.decode.

Page API

Inside the page, window.modkit is created by the client mod.

Member	Description
`modkit.id`	id of this browser
`modkit.events.add(name, fn)`	handle `browser:call(name, ...)`
`modkit.events.remove(name [, fn])`	remove one handler, or all handlers of `name`
`modkit.events.reset()`	remove every handler
`modkit.events.call(name, ...)`	send an event to the client script
`modkit.trigger(name, ...)`	same as `modkit.events.call`

<script>
  modkit.events.add("showShop", (item, price) => {
    document.getElementById("title").textContent = item + " for " + price;
  });
  document.getElementById("buy").onclick = () => modkit.trigger("formSubmitted", "meat", 2);
</script>

modkit.gui.cursor.show

modkit.gui.cursor.show(freeze [, visible])

Turns the mouse cursor on or off. Pages only receive input while the cursor is on.

Parameter	Type	Description
freeze	boolean	`true` turns the game controls off while the cursor is visible (UI only). `false` lets game and page share the input.
visible	boolean	show or hide the cursor, default `true`

Returns: nothing.

Always turn the cursor off again when the player is done. A focused full screen page swallows every click.

modkit.gui.cursor.show(true, true)
modkit.gui.cursor.show(false, false)

modkit.gui.cursor.visible

modkit.gui.cursor.visible()

Returns: true while the cursor is on.

if not modkit.gui.cursor.visible() then modkit.gui.cursor.show(true, true) end

modkit.gui.notify

modkit.gui.notify(text)

Shows the game's own notification on this client. It calls ClientShowNotification on the local player controller, the same function the server uses for player:notify.

Parameter	Type	Description
text	string	the message

Returns: true when the local player controller was found and the call was made.

modkit.gui.notify("Press F5 to open the shop.")