View source for Mod Creation/Mod Context API Reference

== Accessing the Mod Context Object ==

All examples in this guide will assume a mod context object ctx is in the current scope.

=== From a Module ===

If the module is defined as the <code>"setup"</code> for your mod in <code>manifest.json</code>, the exported <code>setup</code> function will receive the context object as a sole parameter:

 <nowiki>export function setup(ctx) {
  // ...
}</nowiki>

Otherwise, use the global <code>mod.getContext</code> method, passing in your module's meta object:

 <nowiki>const ctx = mod.getContext(import.meta);</nowiki>

=== From a Script ===

The recommended approach for scripts is to use the global <code>mod.register</code> method. This only works in scripts injected via the <code>"load"</code> property of <code>manifest.json</code> or the <code>loadScript</code> method of the context object.

 <nowiki>mod.register(ctx => {
  // ...
});</nowiki>

=== From a Lifecycle Method ===

All game lifecycle method callbacks will also receive their respective mod's context object as a sole parameter.

 <nowiki>onCharacterLoaded(ctx => {
  // ...
});</nowiki>

=== From the Dev Context ===

For easier prototyping, you can use the global <code>mod.getDevContext</code> method to get a special dev mod context object. This should not be used in a mod, but only for development purposes (via the console). Any APIs that require resources will not work as the dev "mod" does not contain any resources.

 <nowiki>const devCtx = mod.getDevContext();</nowiki>

== Loading Resources ==

🚨 '''All resource file paths must be relative to the root of your mod''' 🚨

=== getResourceUrl(path: string): string ===

Retrieves a usable URL for any resource packaged in your mod.

'''Parameters'''

<code>path: string</code> The relative path to the resource to generate a URL for

'''Returns'''

<code>string</code> The URL to the requested resource

'''Example'''

 <nowiki>const url = ctx.getResourceUrl('sea-shanty-2.ogg');
const song = new Audio(url);
song.loop = true;
song.play();</nowiki>

=== loadModule(path: string): Promise<any> ===

Dynamically imports a JavaScript module.

'''Parameters'''

<code>path: string</code> The relative path to the module resource

'''Returns'''

<code>Promise<any></code> A promise that resolves to an object containing all exported features from the module

'''Example'''

 <nowiki>// my-module.mjs
export function greet(name) {
  console.log(`Hello, ${name}!`);
}</nowiki>

 <nowiki>const myModule = await ctx.loadModule('my-module.mjs');
myModule.greet('Melvor'); // Hello, Melvor!</nowiki>

=== loadScript(path: string): Promise<void> ===

Injects a JavaScript file into the page.

'''Parameters'''

<code>path: string</code> The relative path to the script resource

'''Returns'''

<code>Promise<void></code> A promise that resolves when the injected script has finished running

'''Example'''

 <nowiki>// Await call if wanting the script to run before continuing
await ctx.loadScript('my-script.js');
// my-script.js has run

// Don't await if no dependency on script
ctx.loadScript('my-independednt-script.js');
// my-independent-script.js has NOT run yet</nowiki>

=== loadTemplates(path: string): void ===

Inject all <template> elements contained in a given HTML file into the document body.

'''Parameters'''

<code>path: string</code> The relative path to the HTML resource

'''Example'''

 <nowiki>ctx.loadTemplates('my-templates.html');</nowiki>

=== loadStylesheet(path: string): void ===

Injects a CSS stylesheet into the page.

'''Parameters'''

<code>path: string</code> The relative path to the stylesheet resource

'''Example'''

 <nowiki>ctx.loadStylesheet('my-styles.css');</nowiki>

=== loadData(path: string): Promise<any> ===

Loads data from a JSON resource.

'''Parameters'''

<code>path: string</code> The relative path to the JSON resource

'''Returns'''

<code>Promise<any></code> A promise that resolves to the parsed JSON object

'''Example'''

 <nowiki>// my-data.json
{
  "coolThings": [
    "rocks"
  ]
}</nowiki>

 <nowiki>// in JavaScript
const myData = await ctx.loadData('my-data.json');
console.log(myData.coolThings); // ['rocks']</nowiki>

== Lifecycle Hooks ==

=== onModsLoaded(callback: (ctx: ModContext) => void | Promise<void>): void ===

Execute code after all mods have been loaded (character select screen).

'''Parameters'''

<code>callback: (ctx: ModContext) => void | Promise<void></code> A callback function that receives the mod's context object as a parameter. Can be synchronous or asynchronous.

'''Example'''

 <nowiki>ctx.onModsLoaded(async (ctx) => {
  // ...
});</nowiki>

=== onCharacterSelectionLoaded(callback: (ctx: ModContext) => void | Promise<void>): void ===

Execute code after the the character selection screen has fully loaded.

'''Parameters'''

<code>callback: (ctx: ModContext) => void | Promise<void></code> A callback function that receives the mod's context object as a parameter. Can be synchronous or asynchronous.

'''Example'''

 <nowiki>ctx.onCharacterSelectionLoaded(async (ctx) => {
  // ...
});</nowiki>

=== onCharacterLoaded(callback: (ctx: ModContext) => void | Promise<void>): void ===

Execute code after the player's chosen character has loaded and all game objects are created, but before offline progress calculations.

'''Parameters'''

<code>callback: (ctx: ModContext) => void | Promise<void></code> A callback function that receives the mod's context object as a parameter. Can be synchronous or asynchronous.

'''Example'''

 <nowiki>ctx.onCharacterLoaded(async (ctx) => {
  // ...
});</nowiki>

=== onInterfaceReady(callback: (ctx: ModContext) => void | Promise<void>): void ===

Execute code after offline progress has been calculated and all in-game user interface elements have been created.

'''Parameters'''

<code>callback: (ctx: ModContext) => void | Promise<void></code> A callback function that receives the mod's context object as a parameter. Can be synchronous or asynchronous.

'''Example'''

 <nowiki>ctx.onInterfaceReady(async (ctx) => {
  // ...
});</nowiki>

== Adding and Modifying Game Data ==

✔️ '''Not documented yet, but it is available''' ✔️

== Mod Settings ==

The mod settings API can be accessed through the <code>settings</code> property on the root context object.

=== section(name: string): Section ===

Gets or creates a settings section. The order that sections are created are the order they will display in a mod's settings window.

'''Parameters'''

<code>name: string</code> The name of the section. This will be displayed as a header of the section in the settings window.

'''Returns'''

<code>Section</code> The section's object, used to perform add, set, or get settings.

'''Example'''

 <nowiki>ctx.settings.section('General');
ctx.settings.section('Other');
// Sections will be displayed in the settings window in this order
// 1. General
// 2. Other</nowiki>

==== Section.add(config: SettingConfig | SettingConfig[]): void ====

Adds a setting to the section. The order that settings are added to a section are the order they will display in a mod's settings window.

'''Parameters'''

<code>config: SettingConfig | SettingConfig[]</code> The setting's configuration object or an array of configuration objects to add multiple settings at once. See Settings Types section below for setting configuration options.

'''Example'''

 <nowiki>ctx.settings.section('General').add({
  type: 'switch',
  name: 'awesomeness-detection',
  label: 'Awesomeness Detection',
  hint: 'Determines if you are awesome or not.',
  default: false
});

ctx.settings.section('Other').add([{
    type: 'label',
    label: 'I am just a label though my story seldom told...'
  }, {
    type: 'number',
    name: 'pick-a-number',
    label: 'Pick a Number',
    hint: '1 through 10'
}]);</nowiki>

==== Section.get(name: string): any ====

Gets the current value of a setting by its name property.

'''Parameters'''

<code>name: string</code> The name of the setting to get the value of

'''Returns'''

<code>any</code> The current value of the setting

'''Example'''

 <nowiki>// Assuming the player has typed "1" into the setting
ctx.settings.section('Other').get('pick-a-number'); // 1</nowiki>

==== Section.set(name: string, value: any): void ====

Programmatically sets the value of a setting by its name property.

'''Parameters'''

<code>name: string</code> The name of the setting to set the value of

<code>value: any</code> The value to set the setting to

'''Example'''

 <nowiki>ctx.settings.section('Other').set('pick-a-number', 5);</nowiki>

=== type(name: string, config: SettingTypeConfig): void ===

Registers a setting type that can then be used by by any mod when adding a setting.

'''Parameters'''

<code>name: string</code> The name of the setting type. This is what should be used for the type property of a setting configuration when adding a new setting. Other mods have to prepend the name with your mod's namespace.

<code>config: SettingTypeConfig</code> An object defining the setting type's behavior. See definition below.

'''Example'''

 <nowiki>// manifest.json
{
  "namespace": "my_mod",
  // ...
}</nowiki>

 <nowiki>ctx.settings.type('customText', {
  // See example config in SettingTypeConfig section below
});

ctx.settings.section('Genera').add({
  type: 'customText',
  // ...
});</nowiki>

Other mods will have to add your namespace to use your custom type:

 <nowiki>ctx.settings.section('Other').add({
  type: 'my_mod:customText',
  // ...
});</nowiki>

==== SettingTypeConfig ====

All functions are required.

===== render(name: string, onChange: () => void, config: SettingConfig): HTMLElement =====

The render function is responsible for using any properties passed into the config to render HTML for the setting.

The <code>name</code> parameter should be used as a form of id in the setting's HTML, if needed. The common use case for this is setting an <code><input></code>'s <code>name</code> and <code>id</code> attributes to this value, and then setting a <code><label></code>'s <code>for</code> attribute to this value as well.

The <code>onChange</code> parameter should be called when this setting's value is changed. The common use case for this is adding this as an event listener to an <code><input></code> element's <code>change</code> event.

The <code>config</code> parameter holds all values passed in the config object when this setting is being added. For example, the <code>label</code>, <code>hint</code>, <code>default</code>, etc. properties.

Individual settings can opt to return validation errors in their <code>onChange</code> method. You can give a place to display this validation error in an element with a class of <code>validation-message</code>.

 <nowiki>// The render function for a simple text box
function render(name, onChange, config) {
  const input = document.createElement('input');
  input.id = name;
  input.type = 'text';
  input.name = name;

  const label = document.createElement('label');
  label.for = name;
  label.textContent = config.label;

  if (config.hint) {
    const hint = document.createElement('small');
    hint.textContent = config.hint;
    label.appendChile(hint);
  }

  const validation = document.createElement('small');
  validation.classList.add('text-danger', 'validation-message');

  const root = document.createElement('div');
  root.appendChild(input);
  root.appendChild(label);
  root.appendChild(validation);

  return root;
}</nowiki>

===== get(root: HTMLElement): any =====

The <code>get</code> function is responsible for retrieving the current value of the setting. It receives just one parameter, the root HTML element returned from the render function, which can be useful for getting the current value.

 <nowiki>// get function for simple text input defined by above render
function get(root) {
  return root.querySelector('input').value;
}</nowiki>

===== set(root: HTMLElement, value: any): void =====

The <code>set</code> function is responsible to keeping the HTML up-to-date with the current value (if updated programmatically). It receives the root HTML element from the render function and the value being set as the two parameters.

 <nowiki>// set function for simple text setting defined above
function set(root, value) {
  root.querySelector('input').value = value;
}</nowiki>

==== Example ====

 <nowiki>// Use functions defined in above examples as reference
ctx.settings.type('simpleText', {
  render: render,
  get: get,
  set: set
});</nowiki>

=== Built-In Types ===

==== Base Setting Configuration ====

All individual settings inherit this base setting config object.

 <nowiki>interface SettingConfig {
  type: string; // Type of the setting
  name: string; // Name of the setting
  label: string | HTMLElement; // Display label for the setting
  hint: string | HTMLElement; // Small help text to display alongside the setting
  default: any; // Default value for the setting
  onChange(value: any, previousValue: any): void | boolean | string // See notes
}</nowiki>

The <code>onChange</code> option is a callback function that receives the new value being set and the previous value of the setting. This function can optionally return a value to serve as a validator:

* No return value / <code>undefined</code> / <code>true</code> / truth-y (non-string) value: Validates successfully and allows the value to be changed
* <code>false</code> / false-y value: Validation fails and setting value is restored to previous
* <code>string</code> value: Validation fails, setting value is restored to previous, and the string contents are displayed in a <code>.validation-message</code> element, if available (see custom render above)

==== Text ====

A simple textbox that accepts any character by default. Value is of type <code>string</code>.

 <nowiki>interface TextConfig implements SettingConfig {
  type: 'text';
  maxLength: number; // Max length attribute for the textbox
}</nowiki>

==== Number ====

A simple textbox that only accepts numbers. Value is of type <code>number</code>.

 <nowiki>interface NumberConfig implements SettingConfig {
  type: 'number';
  min: number; // Minimum value to be entered
  max: number; // Maximum value to be entered
}</nowiki>

==== Switch ====

An on/off toggle switch. Value is of type <code>boolean</code>.

 <nowiki>interface SwitchConfig implements SettingConfig {
  type: 'switch'
}</nowiki>

==== Dropdown ====

A dropdown button. Example: "Default Page on Load" game setting. Value is of type <code>any</code>.

 <nowiki>DropdownConfig implements SettingConfig {
  type: 'dropdown';
  color: string; // see Button config
  options: DropdownOption[]; // see note
}</nowiki>

The <code>options</code> option defines the dropdown options available to be selected. Dropdown option schema is:

 <nowiki>interface DropdownOption {
  value: any; // value that is used by the setting
  display: string | HTMLElement; // display text or element on the option
}</nowiki>

==== Button ====

A button. Value is <code>undefined</code>.

 <nowiki>interface ButtonConfig implements SettingConfig {
  type: 'button';
  display: string | HTMLElement; // displayed text or element inside the button
  color: string; // see note
  onClick(): void; // triggered on click of the button
}</nowiki>

The <code>color</code> option is appended to a CSS class starting with <code>btn-</code> and defaults to <code>primary</code> (<code>btn-primary</code>) if not defined. Default colors available:

* primary: blue
* secondary: grey
* success: green
* info: light blue
* warning: yellow
* danger: red
* dark: dark grey

==== Checkbox Group ====
A group of checkboxes. Value is of type <code>any[]</code>.
 <nowiki>interface CheckboxGroupConfig implements SettingConfig {
  type: 'checkbox-group';
  options: CheckboxOption[]; // see note
}</nowiki>

The <code>options</code> option defines the checkboxes that are available to be selected. Checkbox option schema is:

 <nowiki>interface CheckboxOption {
  value: any; // value to be added to array that is set as setting value
  label: string | HTMLElement;
  hint: string | HTMLElement;
}</nowiki>

==== Radio Group ====
A group of radio buttons. Value is of type <code>any</code>.
 <nowiki>interface RadioGroupConfig implements SettingConfig {
  type: 'radio-group';
  options: CheckboxOption[]; // see checkbox group's options schema
}</nowiki>

==== Label ====
A simple label. Value is <code>undefined</code>.
 <nowiki>interface LabelConfig implements SettingConfig {
  type: 'label';
}</nowiki>

==== Custom ====
A custom-rendered setting. See [[#SettingTypeConfig|SettingTypeConfig]] section above. This is different from registering a custom setting type as this is a one-off and will not register the type for reuse. Value is of type <code>any</code>.
 <nowiki>interface CustomConfig implements SettingConfig, SettingTypeConfig {
  type: 'custom';
}</nowiki>

== Character Data Storage ==
The character storage API can be accessed through the <code>characterStorage</code> property on the root context object.

=== Limitations ===
The character storage can only be used once a character has been loaded (after lifecycle hook <code>onCharacterLoaded</code>).

Each character can store up to 8,192 bytes (8kb) of data per mod, including keys. Only JSON-serializable data can be stored. This includes primitive types (<code>string</code>, <code>number</code>, <code>boolean</code>) and objects and arrays that contain only primitive types or other objects or arrays that fit this description. This serialization/deserialization is handled automatically.

=== <code>setItem(key: string, data: any): void</code> ===
Sets a key/value pair in character storage.

'''Parameters'''

<code>key: string</code> The key to identify the data being stored. Used in calls to <code>getItem</code> and <code>removeItem</code>.

<code>data: any</code> The data to be stored. See limitations above.

'''Example'''
 <nowiki>ctx.characterStorage.setItem('coolThings', ['rocks']);</nowiki>

=== <code>getItem(key: string): any</code> ===
Gets a value by its key from character storage.

'''Parameters'''

key: string The key of the data to retrieve

'''Returns'''

<code>any</code> The data retrieved. Returns <code>undefined</code> if no such key is stored.

'''Example'''
 <nowiki>ctx.characterStorage.getItem('coolThings'); // returns ['rocks']</nowiki>

=== <code>removeItem(key: string): void</code> ===
Removes a key/value pair by key from character storage.

'''Parameters'''

<code>key: string</code> The key of the key/value pair to remove

'''Example'''
 <nowiki>ctx.characterStorage.removeItem('coolThings');
ctx.characterStorage.getItem('coolThings'); // returns undefined</nowiki>

=== <code>clear(): void</code> ===
Removes all key/value pairs from character storage.

'''Example'''
 <nowiki>ctx.characterStorage.clear();</nowiki>

== Account Data Storage ==
The account storage API can be accessed through the <code>accountStorage</code> property on the root context object.

=== Limitations ===
Due to the cloud-based nature of how account data is stored and potential network issues the player may experience, data integrity is not 100% guaranteed in the account storage. Account storage is advised to be used sparingly.

An account can store up to 8,192 bytes (8kb) of data per mod, including keys. Only JSON-serializable data can be stored. This includes primitive types (<code>string</code>, <code>number</code>, <code>boolean</code>) and objects and arrays that contain only primitive types or other objects or arrays that fit this description. This serialization/deserialization is handled automatically.

=== <code>setItem(key: string, data: any): void</code> ===
Sets a key/value pair in account storage.

'''Parameters'''

<code>key: string</code> The key to identify the data being stored. Used in calls to <code>getItem</code> and <code>removeItem</code>.

<code>data: any</code> The data to be stored. See limitations above.

'''Example'''
 <nowiki>ctx.accountStorage.setItem('coolThings', ['rocks']);</nowiki>

=== <code>getItem(key: string): any</code> ===
Gets a value by its key from account storage.

'''Parameters'''

<code>key: string</code> The key of the data to retrieve

'''Returns'''

<code>any</code> The data retrieved. Returns <code>undefined</code> if no such key is stored.

'''Example'''
 <nowiki>ctx.accountStorage.getItem('coolThings'); // returns ['rocks']</nowiki>

=== <code>removeItem(key: string): void</code> ===
Removes a key/value pair by key from account storage.

'''Parameters'''

<code>key: string</code> The key of the key/value pair to remove

'''Example'''
 <nowiki>ctx.accountStorage.removeItem('coolThings');
ctx.accountStorage.getItem('coolThings'); // returns undefined</nowiki>

=== <code>clear(): void</code> ===
Removes all key/value pairs from account storage.

'''Example'''
 <nowiki>ctx.accountStorage.clear();</nowiki>

== Game Object Patching/Hooking ==

=== patch(className: class, methodName: string): Patch ===

This is the entry-point to the method patching API. The Patch object returned by this method can perform further actions with the specified class and method.

'''Parameters'''

<code>className: class</code> Class containing the method you want to patch. Should be the actual class reference, not a string, e.g. <code>Skill</code>, not <code>'Skill'</code>.

<code>methodName: string</code> Name of the method to patch.

'''Returns'''

<code>Patch</code> A patch object for the specified class and method. See below for usage.

'''Example'''

 <nowiki>ctx.patch(Skill, 'addXP');</nowiki>

==== Patch.before(hook: (...args: any) => any[] | void): void ====

Execute a callback function immediately before the method body is called. The callback function's parameters are the arguments being passed into the method call. Optionally the callback function can return an array of values to override the arguments being passed to the method body. If no return value is specified (returns <code>undefined</code>), the arguments are left as-is.

'''Parameters'''

<code>hook: (...args: any) => any[] | void</code> The callback hook to be executed.

'''Example'''

 <nowiki>// Double all XP gains
ctx.patch(Skill, 'addXP').before((amount, masteryAction) => [amount * 2, masteryAction]);</nowiki>

==== Patch.after(hook: (returnValue: any, ...args: any) => any | void): void ====

Execute a callback function immediate after the method body is finished executing. The callback function's first parameter is the value returned from the method body. The rest of the parameters are the arguments that were passed into the method body. Optionally the callback function can return a new value to override the method's return value. If no return value is specified (returns <code>undefined</code>), the return value is left as-is.

'''Parameters'''

<code>hook: (returnValue: any, ...args: any) => any | void</code> The callback hook to be executed.

'''Example'''

 <nowiki>// The player never misses an attack
ctx.patch(Player, 'rollToHit').after(willHit => {
  if (!willHit) console.log('A miss? I think not!');
  return true;
});</nowiki>

==== Patch.replace(replacement: (replacedMethod: (...args: any) => any, ...args: any) => any): void ====

Execute a callback function instead of the method's current body. The callback function's first parameter is the replaced method body. The rest of the parameters are the arguments that were to be passed to the method. The callback function's return value is the return value for the method. The replacement function is still subject to argument/return value modifications made in <code>before</code> and <code>after</code> hooks, respectively.

'''Parameters'''

<code>replacement: (replacedMethod: (...args: any) => any, ...args: any) => any</code> The callback function to replace the method body.

'''Example'''

 <nowiki>ctx.patch(Skill, 'addXP').replace(function(o, amount, masteryAction) {
  // Prevent any woodcutting XP
  if (this.id === 'melvorD:Woodcutting') return;

  // Double any mining XP
  if (this.id === 'melvorD:Mining') return o(amount * 2, masteryAction);

  // Grant all other XP as normal
  return o(amount, masteryAction);
});</nowiki>

It's important to note that using the <code>replace</code> method replaces the current method body, meaning multiple calls of the <code>replace</code> method get executed in the reverse order that they were declared:

 <nowiki>const xpPatch = ctx.patch(Skill, 'addXP');

xpPatch.replace((o, amount, masteryAction) => {
  console.log('Replacement #1');
  return o(amount, masteryAction);
});

xpPatch.replace({o, amount, masteryAction) => {
  console.log('Replacement #2');
  return o(amount, masteryAction);
});

game.woodcutting.addXP(100);
// Logs:
// Replacement #2
// Replacement #1</nowiki>

=== isPatched(className: class, methodName: string): boolean ===

Checks whether or not a method has been patched.

'''Parameters'''

<code>className: class</code> Class containing the method to check for having been patched. Should be the actual class reference, not a string, e.g. <code>Skill</code>, not <code>'Skill'</code>.

<code>methodName: string</code> Name of the method to check.

'''Returns'''

<code>boolean</code> Whether or not the given class method is patched.

'''Example'''

 <nowiki>ctx.isPatched(Skill, 'addXP'); // false
ctx.patch(Skill, 'addXP');
ctx.isPatched(Skill, 'addXP'); // true</nowiki>

== Exposing Properties and Methods (Mod API) ==
You may want to allow other mods to be able to interact or integrate with your mod through an API you define. To do so, the recommended approach is through the <code>api</code> method on the context object. After defining an API using the method below, other mods can access it through the global <code>mod.api['your_mods_namespace']</code> object.

=== <code>api(endpoints?: object): object</code> ===
Specify properties and methods to expose on the global <code>mod.api['your_mods_namespace']</code> object. Can be called multiple times to append more endpoints.

'''Parameters'''

<code>endpoint: object</code> An object containing any properties or methods you want to expose. Can be omitted to just retrieve your mod's current API object.

'''Returns'''

<code>object</code> The mod's API object

'''Example'''
 <nowiki>// manifest.json
{
  "namespace": "helloWorld",
  "setup": "setup.mjs"
}</nowiki>

 <nowiki>// setup.mjs
export function setup({ api }) {
  api({
    greet: name => console.log(`Hello, ${name!}`);
  });
}</nowiki>

Other mods would then be able to interact with your API: 
 <nowiki>// some other mod
mod.api.helloWorld.greet('Melvor'); // Hello, Melvor!</nowiki>