Runtime host interface

WFramework's server logic is JavaScript (like ox_core, which is TypeScript): SQLite access, money and inventory rules, all covered by node --test. Lua resources reach it through exports. This page describes what WFramework expects from the WildM scripting runtime. It is a proposal being agreed with the runtime; names may still change.

server_host

{
  "name": "wf_inventory",
  "dependencies": ["wf_core"],
  "server_host": "server/index.js",
  "server_files": ["server/**", "data/**", "config.json"],
  "client_scripts": ["client/main.lua"]
}

server_files, client_scripts and dependencies are the runtime's existing manifest keys: server files are never sent to players. server_host is the addition WFramework needs: the runtime calls require(server_host).start(ctx) when the resource starts (after its dependencies) and stop() when it stops.

On the client, wf_inventory reuses the UI layer of wf_core through client exports (exports.wf_core:UI(), exports.wf_core:ErrorText(code)): all client scripts share one Lua machine, so tables and functions pass as they are.

ctx

Member	Meaning
resourceName, resourceDir	the resource
log(level, msg)	info, warn, error
onNet(name, fn(source, ...args))	network event from a client
on(name, fn(...args))	local server event, including playerJoining(source) and playerDropped(source, reason)
emitClient(name, target, ...args)	TriggerClientEvent (-1 = everyone)
emit(name, ...args)	TriggerEvent to server Lua scripts
exports(name, fn)	exports.<resource>:<name>(...) for Lua. A returned JS array becomes several Lua values; Lua functions passed as arguments are callable
registerCommand(name, fn(source, args, raw))	source 0 = console
getPlayers()	connected player ids
getIdentity(source)	{ name, identifiers }, identifiers already verified by the host ("wfx:<username>")
getCoords(source)	{ x, y, z, h } from the server's player sync, or nil
dropPlayer(source, reason)	disconnect with a message
ace (optional)	{ isPlayerAllowed(source, object), addPrincipal(child, parent), removePrincipal(child, parent) } — the server ACE (game-server/core/ace.js)

game-server/tests/wframework/bind.test.js contains a fake ctx implementing exactly this. client-lua.test.js runs the client scripts inside the runtime's real Lua core (runtime/lua/wildm_core.lua) with fake UI natives.

Client natives used by the v1 interface

Only wf_core/client/ui.lua depends on them; it degrades to log lines when they are missing. They wrap the client's native UI (ShUi*, see the ScriptHook API):

UiReady, UiSceneCreate(name, order), UiSceneShow, UiFocus, UiCreate(scene, parent, kind, x, y, w, h), UiSetText, UiSetColour, UiSetAlpha, UiSetPosition, UiShow, UiDestroy and the local event wildm:uiKey(scene, vk, down). Already available and used: ShowNotification(text), SetPlayerCoords(x, y, z).

The RP character also needs weapon and outfit natives: see The RP character in game.