Client Plugins

Client plugins are JavaScript files that run in the player's browser. They can create HUD widgets, register local chat commands, and communicate with server plugins.

How They Work#

1. Create a .js file in the Plugin editor (Client tab) or the client-plugins/ folder
2. When a player connects, the server sends all client plugins to their browser
3. Each plugin runs with a ctx object and interacts with the game only through it

Important: Client plugins must be plain JavaScript (.js).

Sandbox: by default (sandboxedClientPlugins, on), a client plugin runs inside a QuickJS-WASM isolate with no DOM, window, or globals — it reaches the page only through ctx. In this mode import lines are stripped and modern (ES2020) syntax is fine. If the sandbox flag is turned off, a legacy path runs the code with new Function and full DOM access — only there does ES5-only advice apply. Write for the sandbox: use ctx, not the DOM. Unlike server plugins, the client ctx is not capability-gated today.

Game State#

var state = ctx.getState();
// Returns: selfId, selfName, selfPosition, selfHp, selfMaxHp,
// selfMp, selfMaxMp, selfSilver, accountGold, currentZoneId,
// currentZoneName, connected, isDead, isMounted, playerLevel,
// inventory, equipment, skills, activeEffects, activeQuests,
// party, guild, chatMessages, entities, survival, environment

ctx.onStateChange(function() {
  var state = ctx.getState();
  // Update your widgets here...
});

HUD Widgets#

Create floating UI elements on screen:

var widgetId = ctx.createWidget({
  html: "<div>My Widget</div>",
  anchor: "top-right",
  position: { x: 16, y: 80 },
  width: 200,
  height: 100,
  visible: true,
  draggable: true,
  zIndex: 100,
  css: "background:rgba(0,0,0,0.8);color:white;" +
       "padding:10px;border-radius:8px;",
  onClick: function() {
    ctx.addLocalChatMessage("Widget clicked!");
  },
});

ctx.updateWidget(widgetId, { html: "<div>Updated!</div>" });
ctx.removeWidget(widgetId);

Widget Options:

Chat Commands#

ctx.addChatCommand("pos", function(args) {
  var state = ctx.getState();
  ctx.addLocalChatMessage(
    "[Plugin] X=" + Math.round(state.selfPosition.x) +
    " Y=" + Math.round(state.selfPosition.y)
  );
});

Server Communication#

Send and receive data from server plugins:

// Send to server
ctx.send("my-channel", { action: "request-data" });

// Receive from server
ctx.on("my-channel", function(data) {
  ctx.addLocalChatMessage("Server says: " + data.message);
});

Timers#

var cancel = ctx.setInterval(function() {
  // runs every second
}, 1000);

ctx.setTimeout(function() {
  ctx.addLocalChatMessage("Timer fired!");
}, 5000);

More client APIs#

Beyond the above, the client ctx also gives you:

ctx.pluginName;                       // this plugin's name (read-only)

ctx.log.info("loaded");               // client logger: info / warn / error (no debug)

// Listen to raw server messages by type (not just plugin channels):
var off = ctx.onServerMessage("EntityUpdate", function (msg) { /* ... */ });
off();                                // every subscribe returns an unsubscribe fn

ctx.on, ctx.onStateChange, ctx.addChatCommand, ctx.setInterval, and ctx.setTimeout all return a teardown function too — call it to stop listening.

Restrictions#

• No direct DOM access — build UI only through createWidget. Widget HTML is sanitized: <script>, inline on* handlers, javascript: URLs, and <iframe>/<object>/<embed>/<form>/<meta>/<link>/<base> are stripped. Use the onClick option for interactivity, not inline handlers.
• No access to game engine internals — only the ctx API.
• Server communication is named channels carrying arbitrary JSON — not schema-validated, so validate payloads on the server.
• In the sandboxed path, a widget's onClick receives no arguments (the MouseEvent is only available on the legacy non-sandboxed path).