Skip to content

Plugins

Jump to bottom
Isaac Hirschfeld edited this page Feb 17, 2021 · 2 revisions

Omegga Plugins

Contents

What is a Plugin?

A plugin is a module that adds functionality to Omegga or a Brickadia Server. An example is the autosaveez plugin, which allows users to create and manage autosaves. More plugins can be found in the #finished-plugins channel in the Omegga Discord.

Omegga and Plugins are not officially supported by Brickadia and may cease to function after any update.

Due to the limits of console commands, plugins can only do so much. At the moment, they can read certain game data, load bricks, save bricks, teleport players, and print chat messages.

Plugins interface with Omegga through JavaScript or child processes over JSON-RPC. Node VM Plugins and RPC Plugins have limited access to Omegga's internals and usually do not crash Omegga when they encounter errors. Unsafe Node Plugins can modify Omegga itself and potentially add extended functionality. If an unsafe plugin crashes, it may crash Omegga!

Plugin Structure

All plugins are located in a plugins directory where you are running Omegga and have the following structure:

  • plugins/myPlugin - plugin folder (required)
  • plugins/myPlugin/doc.json - plugin information (required)
  • plugins/myPlugin/plugin.json - plugin version information, validated with omegga check (optional, for now)
  • plugins/myPlugin/setup.sh - plugin setup script, run after installed by omegga install (optional)
  • plugins/myPlugin/disable.omegga - empty file only present if the plugin should be disabled (optional)

Depending on the plugin type, a plugin may have extra files for code or configuration.

Every plugin requires a doc.json file to document which briefly describes the plugin and its commands.

doc.json (example)

{
  "name": "My Plugin",
  "description": "Example Plugin",
  "author": "cake",
  "config": {
    "example-text": {
      "description": "This is an example text input",
      "default": "default value",
      "type": "string"
    },
    "example-password": {
      "description": "This is example text input hidden as a password",
      "default": "hidden password value",
      "type": "password"
    },
    "example-number": {
      "description": "This is an example numerical input",
      "default": 5,
      "type": "number"
    },
    "example-bool": {
      "description": "This is an example boolean input",
      "default": false,
      "type": "boolean"
    }
  },
  "commands": [
    {
      "name": "!ping",
      "description": "sends a pong to the sender",
      "example": "!ping foo bar",
      "args": [
        {
          "name": "args",
          "description": "random filler arguments",
          "required": false
        }
      ]
    },
    {
      "name": "!pos",
      "description": "announces player position",
      "example": "!pos",
      "args": []
    }
  ]
}

Plugin Config

The web ui provides an interface for editing plugin configs. At the moment, there is no other official way of modifying plugin configs.

Below is an example config section of a doc.json file.

  "config": {
    "example-text": {
      "description": "This is an example text input",
      "default": "default value",
      "type": "string"
    },
    "example-password": {
      "description": "This is example text input hidden as a password",
      "default": "hidden password value",
      "type": "password"
    },
    "example-number": {
      "description": "This is an example numerical input",
      "default": 5,
      "type": "number"
    },
    "example-bool": {
      "description": "This is an example boolean input",
      "default": false,
      "type": "boolean"
    },
    "example-list": {
      "description": "This is an example list input. List type can be string, password, number, or enum",
      "type": "list",
      "itemType": "string",
      "default": ["hello"]
    },
    "example-enum": {
      "description": "This is an example enum/dropdown input",
      "type": "enum",
      "options": [
        "foo", "bar", "baz", 1, 2, 3
      ],
      "default": "foo"
    },
    "example-enum-list": {
      "description": "This is an example list of enums.",
      "type": "list",
      "itemType": "enum",
      "options": [
        "foo", "bar", "baz"
      ],
      "default": ["foo"]
    },
    "example-players-list": {
      "description": "This is an example list of players.",
      "type": "players",
      "default": [{"id":"fa577b9e-f2be-493f-a30a-3789b02ba70b", "name":"Aware"}]
    }
  }

That config section would generate the following default config:

{
  "example-text": "default value",
  "example-password": "hidden password value",
  "example-number": 5,
  "example-bool": false,
  "example-list": ["hello"],
  "example-enum": "foo",
  "example-enum-list": ["foo"],
  "example-players-list": [{"id":"fa577b9e-f2be-493f-a30a-3789b02ba70b", "name":"Aware"}]
}

This is provided to plugins in the constructor or the RPC init function.

Plugin File

This is an example plugin.json, located inside of a plugin folder. The plugin file helps omegga know if the plugin is compatible with the current installation. Plugin files can be validated with the omegga check command.

{
  "formatVersion": 1,
  "omeggaVersion": ">=0.1.32"
}
  • formatVersion - indicates the plugin file format version
  • omeggaVersion - indicates compatible omegga versions (semver cheatsheet)

Plugin Store

All plugins have the capability to get/set values in a very lightweight "database"

The following asynchronous methods are provided:

Method Arguments Description
store.get key (string) Get an object from plugin store
store.set key (string), value (any) Store an object in plugin store
store.delete key (string) Remove an object from plugin store
store.wipe none Remove all objects from plugin store
store.count none Count number of objects in plugin store
store.keys none Get keys for all objects in plugin store

Example usage:

// simple add function
async function add() {
  const a = await store.get('foo');
  const b = await store.get('bar');
  await store.set('baz', a + b);
  await store.delete('foo');
  await store.delete('bar');
}

(async () => {
  // store foo and bar in the plugin store
  await Promise.all([
    store.set('foo', 5),
    store.set('bar', 2),
  ]);

  // add foo and bar
  await add();

  // baz should be equal to 7
  console.log('assert', await store.get('baz') === 7);

  // demo of storing an object
  await store.set('example object', {
    foo: 'you can store objects in the store too',
    bar: 'just don\'t expect it to work with anything recursive (cannot serialize)',
  })
})();

For Node Plugins, the store is the third argument passed into the constructor. For JSONRPC Plugins, the "store.get"/etc methods can be used.

JSONRPC Note: store.set has an array of arguments ([key, value])

Clone this wiki locally