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 "setup" for your mod in manifest.json, the exported setup function will receive the context object as a sole parameter:

export function setup(ctx) {
  // ...
}

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

const ctx = mod.getContext(import.meta);

From a Script

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

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

From a Lifecycle Method

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

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

From the Dev Context

For easier prototyping, you can use the global mod.getDevContext 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.

const devCtx = mod.getDevContext();

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

path: string The relative path to the resource to generate a URL for

Returns

string The URL to the requested resource

Example

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

loadModule(path: string): Promise<any>

Dynamically imports a JavaScript module.

Parameters

path: string The relative path to the module resource

Returns

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

Example

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

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

loadScript(path: string): Promise<void>

Injects a JavaScript file into the page.

Parameters

path: string The relative path to the script resource

Returns

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

Example

// 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

loadTemplates(path: string): void

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

Parameters

path: string The relative path to the HTML resource

Example

ctx.loadTemplates('my-templates.html');

loadStylesheet(path: string): void

Injects a CSS stylesheet into the page.

Parameters

path: string The relative path to the stylesheet resource

Example

ctx.loadStylesheet('my-styles.css');

loadData(path: string): Promise<any>

Loads data from a JSON resource.

Parameters

path: string The relative path to the JSON resource

Returns

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

Example

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

Comments in JSON are purely illustrative and not valid markup

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

Sharing Resources

share(resourcePath: string): void

Shares a packed mod resource for other mods to use.

Parameters

resourcePath: string The resource path to be shared.

Example

// manifest.json
{
  "namespace": "helloMelvor"
}

Comments in JSON are purely illustrative and not valid markup

// in JavaScript
ctx.share('my_cool_image.png');
ctx.share('Greeter.mjs');

Then another mod can use the resource anywhere that accepts a mod resource path.

ctx.getResourceUrl('helloMelvor:my_cool_image.png');
const { Greeter } = await loadModule('helloMelvor:Greeter.mjs');
const greeter = new Greeter();