Creating Configurable Options

The config package allows you to use write-on-exit config options (it's blazingly fast 🚀), it also comes with a clickable text interface at /config for users to easily change options.

Add Dependencies

Include config as dependency in package.json.

// package.json
{
  // ...
  dependencies: {
    "config": "0.1.0",
    // ...
  }
}

If config is not installed, you can run /pully install to install any missing dependencies.

Basic Read-Write

Reading an Entry

config.load(label) returns the value of an existing config entry.

let config = require("config");

let options1 = config.load("myPackage.options1");
let options2 = config.load("myPackage.options2");

Each config entry holds a JS object, and is identified by a period separated string. Each entry should only store pure JavaScript objects without any Java objects.

If you hold a Java variant of the value, such as java.lang.String instead of string, the value will be shown in purple and some features, such as inferred typing will not work.

If the entry does not exist, undefined will be returned.

Writing Changes

config.save(label, value) writes value to an entry, creating an entry if it doesn't exist.

let config = require("config");

// writes to entry
let options1 = config.load("myPackage.options1");
config.save("myPackage.options1", { hello: 1 });

// modify an existing entry
let options2 = config.load("myPackage.options2");
options2.hello = 1;
config.save("myPackage.options2", options2);

The changes will be written to disk when the game is closed, or JSCore restarts, and loaded entries are cached for the duration of the running of the game. Config entries should only be modified using the config package.

Fields are displayed in alphabetical order when viewed in the /config menu, if you wish to group entries, put them under the same subfield. E.g. options.myGroup.field1 and options.myGroup.field2.

Removing Entries

config.remove(label) removes a config entry.

let config = require("config");

config.remove("myPackage.options2");

Adding Missing Fields

New fields in config may be added as your package updates, you will need to add them to existing config entries for the user to change them.

You can write a getOptions function, see how the translate use it.

// translate/init.js
let command = require("command");
let config = require("config");

function getOptions() {
  let options = config.load("translate");
  options ??= {}; // if the entry does not exist, make it an empty object
  options.instance ??= "translate.siri.ws"; // default value for `instance`
  options.source ??= "auto";
  options.target ??= "en";

  config.save("translate", options);
  return options;
}

getOptions();

// ...

command.register({
  name: "translate",
  args: {
    phrase: {
      type: "greedy",
      execute: (phrase) => {
        let options = getOptions();
        translate(options, phrase);
      },
    },
  },
});

First of all, because config.save doesn't actually write to disk, the getOptions function is not an expensive operation.
The script runs getOptions on start so that the entry can be edited in the /config menu.

Creating Configurable Options ​

Add Dependencies ​

Basic Read-Write ​

Reading an Entry ​

Writing Changes ​

Removing Entries ​