Shire Plugin API Reference

Generated from sdk/contract/api.json. Do not edit by hand; run python tools/shire-plugin/gen_docs.py after changing the contract.

API version: 1.0
Transport: named-pipe
Framing: newline-delimited JSON-RPC 2.0
Max line: 1048576 bytes

Handshake

Every SDK sends plugin.hello first. The Host returns the capability list, the plugin's declared permissions and the granted subset.

Permissions

Events

Events arrive as JSON-RPC notifications with method shire.event.

UI component types

text, button, toggle, slider, input, select, progress, separator, section

Methods

api.info

Return the Host API version, capabilities, permissions, events and UI component types.

Permission: none

Params:

{}

Result:

"object"

plugin.hello

Bind this connection to a plugin process. Sent automatically by every SDK.

Permission: none

Params:

{
  "plugin_id": "string",
  "token": "string",
  "api_version": "string",
  "sdk": "string?"
}

Result:

{
  "api_version": "string",
  "host": "string",
  "plugin_id": "string",
  "capabilities": "string[]",
  "permissions": "string[]",
  "granted": "string[]",
  "events": "string[]",
  "ui_types": "string[]"
}

plugin.ping

Liveness probe. Returns the Host millisecond clock.

Permission: none

Params:

{}

Result:

{
  "time": "number"
}

player.getPosition

Read the local player's public position.

Permission: player.read

Params:

{}

Result:

{
  "x": "number",
  "y": "number",
  "z": "number",
  "scene": "number"
}

world.getScene

Read the current scene id.

Permission: world.read

Params:

{}

Result:

{
  "scene": "number"
}

entities.list

Read public entities around the local player.

Permission: entities.read

Params:

{
  "limit": "number? (1..256, default 64)"
}

Result:

{
  "entities": [
    {
      "id": "hex string",
      "config": "number",
      "type": "number",
      "x": "number",
      "y": "number",
      "z": "number",
      "distance": "number"
    }
  ]
}

map.getMarkers

Read public markers from the embedded area catalogue.

Permission: map.read

Params:

{
  "limit": "number? (1..512, default 128)"
}

Result:

{
  "markers": [
    {
      "name": "string",
      "category": "string",
      "x": "number",
      "y": "number",
      "z": "number",
      "distance": "number"
    }
  ]
}

teleport.to

Ask the Core to move the local player. The Host validates coordinates and method.

Permission: teleport.write

Params:

{
  "x": "number",
  "y": "number",
  "z": "number",
  "method": "number? (0 direct, 1 waypoints, 2 conditional)"
}

Result:

{
  "queued": "boolean"
}

ui.setLayout

Replace this plugin's declarative UI layout.

Permission: ui.create

Params:

{
  "layout": "array of components"
}

Result:

{
  "components": "number"
}

ui.update

Update one component without replacing the layout.

Permission: ui.create

Params:

{
  "id": "string",
  "value": "string|number|boolean?",
  "label": "string?",
  "text": "string?"
}

Result:

{
  "updated": "boolean"
}

notifications.show

Show a toast in the Shire overlay.

Permission: notifications.show

Params:

{
  "title": "string",
  "text": "string",
  "level": "number? (0 info, 1 warning, 2 error)"
}

Result:

{
  "shown": "boolean"
}

storage.get

Read a key from this plugin's private storage.

Permission: storage.read

Params:

{
  "key": "string"
}

Result:

"any JSON value (null when absent)"

storage.set

Write a JSON value to this plugin's private storage (256 KiB total).

Permission: storage.write

Params:

{
  "key": "string",
  "value": "any JSON value"
}

Result:

{
  "stored": "boolean"
}

storage.remove

Remove a key from this plugin's private storage.

Permission: storage.write

Params:

{
  "key": "string"
}

Result:

"boolean"

storage.keys

List this plugin's storage keys.

Permission: storage.read

Params:

{}

Result:

"string[]"

events.subscribe

Subscribe to one or more Host events. Events arrive as shire.event notifications.

Permission: events.subscribe

Params:

{
  "events": "string[]"
}

Result:

"string[] (accepted events)"

events.unsubscribe

Remove event subscriptions.

Permission: events.subscribe

Params:

{
  "events": "string[]"
}

Result:

"boolean"

logging.log

Append a line to this plugin's log (shown in the Plugin Manager).

Permission: none

Params:

{
  "level": "string? (info|warn|error|debug)",
  "message": "string"
}

Result:

"boolean"

game.functions

List the named game functions the Host exposes (no addresses or offsets).

Permission: game.invoke

Params:

{}

Result:

{
  "functions": [
    {
      "name": "string",
      "args": "string",
      "returns": "string",
      "summary": "string"
    }
  ]
}

game.invoke

Call a named game function with typed arguments.

Permission: game.invoke

Params:

{
  "name": "string",
  "args": "object?"
}

Result:

{
  "name": "string",
  "result": "any"
}

Errors

The SDKs raise ShireError (Python), ShireError (C#), ShireError (Node), ShireException (C#) or a Result error string (C++/Rust) for these codes.