Skip to content

Make a web interface

A web interface is a set of pages - HTML, CSS and JavaScript - that every player’s game draws over the game while they are on your server: a menu, a shop window, a login screen, a map, a chat of your own. KCD:MP carries the browser engine that draws them (Chromium, through CEF) and starts it only on a server that has a web interface. A server without one looks exactly as it always did, and a player whose game cannot draw a page keeps the standard interface.

The interface is a folder of files next to the game mode. Each page in it is a frame: a layer of its own over the game, named in the folder’s ui.toml, which also says what the frame may do. The game mode shows and hides the frames, sends them data and hears what they send back. A page talks to the game through one object, KcdMp, that the game gives every page; the web interface SDK documents it.

This guide builds one frame from start to finish, then covers the keyboard and the mouse, replacing a piece of KCD:MP’s own interface, the look, big files and the players who have no web layer.

The interface lives in a folder called ui, next to the game mode’s client folder:

gamemodes/
mymode.lua the game mode
mymode/
client/ its client scripts, if it has any
ui/
ui.toml what the interface holds and what each frame may do
panel/
index.html
panel.css
panel.js

[client] ui in server.toml points somewhere else: another folder, or a .zip of one, which panel file managers handle better than the hundreds of files a build tool writes (server configuration).

At start the server checks the folder and prints what it found, with every mistake in ui.toml named by its key. An interface with errors is not sent, and players keep the standard interface. A player’s game downloads the interface when they join and keeps it, so a later join fetches only the files that changed.

api = 1
name = "My server's interface"
version = "1"
[frames.panel]
page = "panel/index.html"
focus = "input"
events_in = ["panel.*"]
events_out = ["panel.*"]
feeds = ["session"]

One [frames.<name>] section per frame. This one shows panel/index.html, may receive and send events whose names start with panel., reads the session feed (the server’s name, the player’s name, the ping) and may ask for the keyboard and the mouse cursor (below).

panel/index.html:

<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<link rel="stylesheet" href="panel.css">
</head>
<body>
<div id="box">
<p id="hello">Welcome</p>
<button id="buy">Buy bread</button>
</div>
<script src="panel.js"></script>
</body>
</html>

panel/panel.js:

// the game mode's "panel.hello" event: the value is the table it sent, as JSON parsed
KcdMp.onServer("panel.hello", (value) => {
document.getElementById("hello").textContent = "Welcome, " + value.name;
});
// a click sends the game mode an event of the page's own
document.getElementById("buy").addEventListener("click", () => {
KcdMp.emitServer("panel.buy", { item: "bread" });
});

panel.css is any stylesheet. A page is transparent where it draws nothing, so the game shows through around the box.

-- the player's web layer is up (also called once right after OnPlayerConnect with the state their game reported)
function OnPlayerWebStatus(pid, status, reason)
if status == "ready" then
ShowPlayerWebFrame(pid, "panel")
end
end
-- the panel's page has loaded and listens
function OnPlayerWebReady(pid, frame)
if frame == "panel" then
SendClientEvent(pid, "panel.hello", { name = GetPlayerName(pid) })
end
end
-- what a page sends: the frame's name comes as the source
function OnClientEvent(pid, name, payload, source)
if source == "panel" and name == "panel.buy" then
local order = JsonDecode(payload)
if type(order) == "table" and order.item == "bread" then
-- check it as any other input from a player, then sell the bread
end
end
end

ShowPlayerWebFrame and the other calls answer true when the request was handed to the player’s game, or false and the reason in words: "no such player", "no web interface", "the player has no web layer", "no such frame". HidePlayerWebFrame hides a frame and keeps its page alive, so showing it again finds it as it was. DestroyPlayerWebFrame closes it instead and frees the memory its page used - for a screen the player opens once, like a login or a character creator; showing it again loads the page from the start.

Every page runs under the same strict security policy in every player’s game. Most pages written for a browser work as they are; these are the differences that catch people out:

  • Scripts come from files. <script src="panel.js"></script> runs; an inline <script> block, an onclick="..." attribute (or any other on...= attribute) and a javascript: link do not. Attach handlers from your script instead: button.addEventListener("click", buy).
  • No code from text. eval(), new Function() and setTimeout("...") with a string are refused; setTimeout with a function is fine. Use your build tool’s production build: some development modes rely on eval.
  • Styles are free. <style> blocks, style="..." attributes and stylesheets of your folder all work.
  • Nothing from other sites unless [permissions] in ui.toml names the host, and then over https only: img for pictures, connect for fetch() and WebSockets, embeds for a video. Put your fonts, pictures and sounds in the folder.
  • No browser windows. alert(), confirm(), prompt(), window.open(), file pickers and downloads do nothing: draw your own dialogs. A site the player must see in a real browser - a sign-in with Discord or Google, your forum - opens in their own browser with KcdMp.openInBrowser, once the game has asked them ([permissions] links).
  • Nothing lasts. Cookies are off, and what a page keeps in localStorage is gone when the game closes: keep what matters in the game mode.
  • No selection over the game. A full-screen page whose text gets selected (a drag, Ctrl+A) tints everything it covers; give the page’s body user-select: none (and allow it back on the text fields that need it) and leave its background transparent.

A refused script leaves a line in the page’s console, which UI developer mode shows (below).

Key Default What it is
api - 1, the version of the web interface the folder is written for (required)
name, version "" the interface’s own name and version
[frames.<name>] - one frame; the name is lower-case letters, digits and - (root, ui, engine, kcdmp, theme, native, default, hidden, lab and lua are taken); at most 128 frames. A frame costs nothing until it is first shown
page - the frame’s .html file, a path inside the folder (required)
preload false true loads the page at the join, hidden, so it shows at once when the mode shows it with ShowPlayerWebFrame (a page that must be on screen from the start, such as a HUD, is shown in OnPlayerWebReady); at most 32 frames may preload
z 300 the frame’s layer, 0 to 999: a higher frame is drawn over a lower one
focus "input" what the frame may take when it asks: "never" (nothing), "input" (the cursor at once, the keyboard only just after the player’s own click or key in the frame), "open" (the cursor at any time, and the keyboard at once together with it) - below
events_in [] the names of the mode’s events the page may receive; * at the end matches any rest: "panel.*"
events_out [] the names the page may send with emitServer
feeds [] the live values the page may read: "session" (the server, the level, the player, the ping) and "visibility" (whether the interface is drawn, and why not)
[surfaces.<name>] - a page drawn on boards in the world instead of over the game (below); at most 16
[components.<name>] - a piece of KCD:MP’s interface the folder draws or styles (below)
[theme] - the look of KCD:MP’s own web pieces (below)
[files] include = ["**"] include and exclude, lists of patterns, choose the files that are sent; every frame’s page and the theme’s stylesheet always are
[permissions] nothing what the pages may reach outside the folder: connect and img (hosts), embeds ("youtube"), capabilities ("webgl", "wasm", "audio", "workers"), links (hosts a page may open in the player’s own browser with KcdMp.openInBrowser - a sign-in with Discord or Google; the game asks the player first)

A page can reach nothing outside its folder unless [permissions] names it: no other site, no other frame, nothing of the game but what KcdMp gives it. The files are the kinds a page uses: html, css, js, mjs, json, svg, txt, the images (png, jpg, jpeg, webp, avif, gif), the fonts (woff, woff2, ttf, otf) and the sounds and videos (ogg, opus, webm, wav, mp3, flac). Sounds the game mode plays in the world, at an actor or a place, through the game’s own sound (PlayEntitySound, PlaySoundAt), belong in the mode’s sounds/ folder instead: a player gets one of those only when it plays near them.

From To How Arrives as
the game mode a page SendClientEvent / SendClientEventToAll KcdMp.onServer, in every page whose events_in takes the name (the client scripts get the same event)
the game mode one frame SendPlayerWebMessage KcdMp.onMessage, exactly the value sent
a page the game mode KcdMp.emitServer OnClientEvent, the frame’s name as its source
a client script a frame SendWebMessage KcdMp.onMessage
a page the client scripts KcdMp.post OnWebEvent, whose answer the page awaits

The values travel as JSON: a Lua table becomes an object, and JsonEncode and JsonDecode do it by hand on the server’s side. A message a frame cannot take yet waits until its page is ready. What comes back from a page is the player’s game’s word: a page can be changed on the player’s own PC, so check every request as you would a chat command.

A client script can drive frames too, with ShowWebFrame, HideWebFrame, DestroyWebFrame and SetWebFocus: a mode with client scripts keeps its screen logic there, a mode without any drives everything from the server.

A frame starts without either: the player keeps playing while it is drawn. It gets the cursor, the keyboard or both when the mode asks with SetPlayerWebFocus or the page asks with KcdMp.focus, and gives them back with SetPlayerWebFocus(pid, frame, false, false) or KcdMp.blur. The frame’s focus setting has the last word on the player’s side:

  • "never" - the frame gets no focus at all: an overlay the player only looks at.
  • "input" (the default) - the cursor at once; the keyboard only within five seconds of the player’s own click or key in the frame, so a page can take the keyboard from a click handler but never out of the blue.
  • "open" - the cursor at any time, and the keyboard at once together with it: a menu the server opens gets the keys straight away, Esc included. A keyboard asked for without the cursor still waits for the player’s first click in the frame.

keepInput (the fifth argument of SetPlayerWebFocus) keeps the game’s walking keys working while no text field of the page has the focus: a menu the player can walk with. Esc gives the focus back unless the page handles the key itself (preventDefault() in any of its own keydown listeners - on an element, the document or the window), and asking for the keyboard more than six times a minute without any input from the player is refused. The keys a mode declares with RegisterKeyBinding reach the pages too, through KcdMp.onKeyBinding.

The player also has a cursor of their own: their cursor key (left Alt unless they picked another in the launcher), held for a second, brings the game’s pointer up over the world while they keep walking, and its clicks go to the page under it. A mode brings it up or takes it away with SetPlayerCursor, a client script with SetCursorShown, and a page hears it with KcdMp.onPlayerCursor - a page that wants those clicks for itself takes the cursor with KcdMp.focus({ cursor: true }).

A page can also be drawn in the world - a notice board, a shop sign, a screen on a wall. Declare it under [surfaces.<name>] instead of [frames.<name>], and the game mode places boards that show it with CreateWebSurface. Every player near a board sees the page on it, lit by the world like the game’s own signs, and each player’s game draws its own copy: the mode sends each copy what it should show when it is ready (OnPlayerWebSurfaceReady).

[surfaces.board]
page = "board/index.html"
width = 768 # the page's pixels, 64 to 1024 (512)
height = 512
fps = 2 # pictures a second at most, 1 to 30 (10): a page that changes rarely needs few
range = 30 # how near a player must be, 5 to 100 metres (30)
events_out = ["board.read"] # what its page may send (the surface's own "board.*" unless it says)
local notices = { { title = "Wanted", text = "A smith's apprentice." } }
RegisterCommand("board", function(pid)
local x, y, z = GetPlayerPos(pid)
local yaw = GetPlayerYaw(pid)
local a = math.rad(yaw)
-- 2.5 m ahead, its middle 1.5 m up, facing the player; 1.5 x 1 m - the page's shape
CreateWebSurface("board", x - math.sin(a) * 2.5, y + math.cos(a) * 2.5, z + 1.5, yaw + 180, 1.5, 1.0,
{ prompt = "Read the notices" })
end)
function OnPlayerWebSurfaceReady(pid, id)
SendPlayerWebSurfaceMessage(pid, id, { notices = notices })
end

The page is an ordinary page - KcdMp.onMessage hears the mode, emitServer reaches OnPlayerWebSurfaceEvent - laid out for exactly its width and height, with type large enough to read from a few metres. Nobody clicks or types on it; a board with a prompt hears the player’s use key instead, in OnPlayerUseWebSurface and on that player’s copy in KcdMp.onSurfaceUse. A page is drawn only near the player and for the closest few boards; it starts afresh each time the player comes back, so the mode keeps what it shows. glow makes a board shine by itself at night (a lit sign, a screen). The whole list is the API group Web surfaces; the server folder’s sdk/web/examples/notice-board/ is a working example.

A board looks like part of the place when it hangs flat on a wall, and the player’s own game knows exactly where the wall is: GetLookTarget in a client script gives the point under the crosshair and the way the surface faces there (its normal). Send both to the mode and put the board’s middle a few centimetres out from the point, its face looking the way the wall does:

-- client script: the mode asks, the player's game answers with where they look
function OnServerEvent(name, payload)
if name ~= "board.look" then return end
local t = GetLookTarget(8)
if t and t.normal then
SendServerEvent("board.spot", string.format("%.3f %.3f %.3f %.4f %.4f %.4f",
t.x, t.y, t.z, t.normal.x, t.normal.y, t.normal.z))
end
end
-- game mode
RegisterCommand("board", function(pid) SendClientEvent(pid, "board.look") end)
function OnClientEvent(pid, name, payload)
if name ~= "board.spot" then return end
local x, y, z, nx, ny, nz = payload:match("^(%S+) (%S+) (%S+) (%S+) (%S+) (%S+)$")
x, y, z, nx, ny, nz = tonumber(x), tonumber(y), tonumber(z), tonumber(nx), tonumber(ny), tonumber(nz)
if not nz or math.abs(nz) > 0.85 then return end -- a floor or a ceiling: no wall
local yaw = math.deg(math.atan(-nx, ny)) -- a board's yaw is the way its face looks
local pitch = math.deg(math.asin(nz)) -- as far as the wall leans back
CreateWebSurface("board", x + nx * 0.03, y + ny * 0.03, z + nz * 0.03, yaw, 1.5, 1.0, { pitch = pitch })
end

Check the answer like any input from a player (the example also checks that the point is near them). To keep a board for good, place it by eye once and write down the numbers: the notice-board example prints the CreateWebSurface line for the board it just hung, ready to paste into the mode’s OnGameModeInit.

A board is solid unless the mode says otherwise: the page is drawn on white, like in a browser. With transparent = true in CreateWebSurface’s options (or SetWebSurfaceTransparent later) the world shows through every part of the page that is see-through - letters painted on a wall, a sign cut to its own shape, a half-clear panel. The page decides which parts those are:

html, body { background: transparent; } /* nothing behind the letters */
h1 { color: rgba(236, 222, 180, 0.88); } /* worn paint: the wall shows a little through it too */

transparent = true is soft: each pixel as see-through as the page draws it, edges smooth - at its best in the sun or with a little glow: the game lights it with the sun and the lamps but not with the light bounced into shade, so on a wall in deep shade its paint reads darker than the wall. transparent = "cutout" is hard-edged: a pixel shows when it is at least half opaque, else not at all - lit exactly like the wall, crisper from far away, and the board’s shadow takes the page’s outline, but no half-clear parts (a soft text-shadow becomes a hard copy of the letters). A see-through board shows nothing until its page has loaded; a page with a background of its own stays solid either way. The notice-board example’s /paint hangs the tavern’s name painted on the wall you look at.

The chat, the scoreboard, the notices, the party frames, the voice indicator, the emote wheel, the HUD texts, the sleep fade, the death screen, the shop and the dialogs each have two more drawers than native and hidden (Change the interface):

  • default - KCD:MP’s own web version of the piece, which your theme styles: a chat with channel tabs and command suggestions as the player types, a scoreboard with the mode’s own columns (SetScoreboardColumns).
  • the name of one of your frames - your page draws the piece. It receives the piece’s lines, roster or notices, its keys and its settings, and calls the piece’s actions: the piece’s contract (chat@1, scoreboard@1, notices@1 …) is documented under Drawing a component. A frame draws one piece at a time.

[components.<name>] in ui.toml sets what every player starts with:

[components.chat]
drawer = "default"
[components.scoreboard]
drawer = "board" # the frame [frames.board] draws it
contract = "scoreboard@1"
mode = "toggle" # the piece's options, as SetInterfaceOptionsForAll takes them

and the mode changes it for one player or everyone with SetPlayerInterface and SetInterfaceForAll. While a player’s game cannot draw the web drawer - no web layer, a page not ready yet, a page that stopped - the native piece draws instead, and the web one takes over the moment it can; GetPlayerInterface says which draws now.

The loading screen has a web version too, but only ui.toml chooses it: [components.loading] drawer is "default" or a frame’s name, and without the section a frame called loading draws it. It shows while the level loads, before anything the mode sends can arrive, so its data comes from SetPlayerLoadingHandover, and manual_shutdown = true keeps it up until the mode calls ClosePlayerLoadingScreen.

The default pieces take a theme from ui.toml:

[theme]
css = "theme.css" # a stylesheet of the folder, applied to KCD:MP's web pieces
[theme.vars]
"--kcdmp-accent" = "#F6E890"
"--kcdmp-text" = "#F3EEDF"
"--kcdmp-backing" = "rgba(20, 16, 12, 0.6)"
[theme.chat.templates] # chat lines laid out by the mode's templates
me = "<i>* {0} {1}</i>"

The variables are --kcdmp- names: accent, text, text-dim, backing, font, radius and the pieces’ own. A chat line sent with SendChatMessage and a template name fills the template’s {0} to {15} with its values, always as text. The game’s own typefaces are there for every page: "KcdMp Regular", "KcdMp Light", "KcdMp Display" and "KcdMp Manuscript" in a font-family. So are the game’s item pictures: KcdMp.itemIcon("longSwordDuel") is the address of an item’s inventory icon for an <img> or a CSS background, made by each player’s game from its own files. And so is the world map the M key opens: KcdMp.mapImage() gives it as one picture, KcdMp.mapTiles() as tiles for a zoomable map, and KcdMp.worldToMap places a player on it - no host of your own needed (The game’s pictures and typefaces).

A player downloads the interface over the game’s connection when they first join, so keep it small: [client] ui_max_mb caps it (8 MB by default, 64 at most) and the server log warns from 4 MB up. Pictures, fonts, sounds and videos over 1 MB come from a host of your own instead: set [client] ui_cdn to its address, run the server once with --pack-ui <folder> to write the files to upload there, and list the host in [permissions] connect. Without ui_cdn a file that big is an error.

OnPlayerWebStatus says how a player’s web layer stands: "starting", "ready", "failed" (with the reason) or "off" - an older game, or a player who turned Server interfaces off in the launcher. Those players keep the standard interface, and IsPlayerWebReady answers false for them. A mode whose screens matter has a second way for them: RegisterUiFallback sends a frame’s events to a client script’s box instead, player by player.

A reload of the mode leaves the frames on the players’ screens, and the new mode hears OnPlayerWebStatus and OnPlayerWebReady again.

  • Start from an example. The server folder’s sdk/web/ has four that run as they are - point [gamemode] script at one:

    • examples/replace-chat/ - a chat of your own, with channel tabs and command suggestions;
    • examples/scoreboard/ - a scoreboard of your own with the mode’s columns (kills, deaths, time played);
    • examples/inventory/ - a window a key opens, showing what the player carries with the game’s item pictures;
    • examples/theme/ - no page at all: KCD:MP’s own chat and scoreboard moved and restyled.

    sdk/web/react-template/ is a React + TypeScript starter (Vite): npm install, npm run dev to work on it in a browser or in the game, npm run build for the files your interface ships. Its README has the steps.

  • Any build tool works - the folder only needs the files it writes. Vite needs base: './'. Source maps, node_modules and the sources stay out with [files] exclude.

  • In a browser. A page opened outside the game runs in mock mode: copy sdk/web/sdk.js from the server folder (or web/sdk.js from your KCD:MP folder) next to your pages and load it first with <script src="sdk.js"></script> (in the game the copy steps aside for the game’s own). Then KcdMp.mock plays the game’s part: events, messages, feeds and keys.

  • In the game. Turn on UI developer mode in the launcher’s settings: the F9 window gets a Web tab with every frame’s state, the pages’ console, a line to run JavaScript in a frame and a reload button, and the game argument -KcdMp_web_dev_url <frame>=http://127.0.0.1:<port>/ (the launcher’s Game arguments) loads a frame from a development server on your own PC. In this mode the launcher joins only servers on your own list (a favourite, a line of your server list, this PC).

  • Script errors stay in the player’s own log unless [client] ui_report_errors = true: then the mode hears each one in OnPlayerWebError.

  • The types of the whole KcdMp object are in KcdMp-web.d.ts, for TypeScript and for editors that read it.

A C# mode has every call above on IServerApi and every callback on IGameMode, with the same names and the same rules: ShowPlayerWebFrame(player, "panel", out var reason), OnPlayerWebStatus(IPlayer, string status, string reason) and the rest - the C# page lists them under Web interface.