Mod Creation/Mod Context API Reference: Difference between revisions
Buttchouda (talk | contribs) |
(→MethodPatch.after(hook: (returnValue: any, ...args: any) => any | void): void: Make it more obvious that the after function has one more argument than the original call (the return type)) |
||
(11 intermediate revisions by 2 users not shown) | |||
Line 36: | Line 36: | ||
<syntaxhighlight lang="js" line>const devCtx = mod.getDevContext();</syntaxhighlight> | <syntaxhighlight lang="js" line>const devCtx = mod.getDevContext();</syntaxhighlight> | ||
== Getter Properties == | |||
=== name: string === | |||
The name of the mod. | |||
=== namespace: string | undefined === | |||
The defined namespace of the mod, if provided. | |||
=== version: string === | |||
The currently loaded version of the mod. | |||
== Loading Resources == | == Loading Resources == | ||
Line 104: | Line 118: | ||
// my-independent-script.js has NOT run yet</syntaxhighlight> | // my-independent-script.js has NOT run yet</syntaxhighlight> | ||
=== loadTemplates(path: string): void === | === loadTemplates(path: string): Promise<void> === | ||
Inject all <template> elements contained in a given HTML file into the document body. | Inject all <template> elements contained in a given HTML file into the document body. | ||
Line 111: | Line 125: | ||
<code>path: string</code> The relative path to the HTML resource | <code>path: string</code> The relative path to the HTML resource | ||
'''Returns''' | |||
<code>Promise<void></code> A promise that is resolved once all templates have been injected into the document body. | |||
'''Example''' | '''Example''' | ||
Line 203: | Line 221: | ||
=== onCharacterSelectionLoaded(callback: (ctx: ModContext) => void | Promise<void>): void === | === onCharacterSelectionLoaded(callback: (ctx: ModContext) => void | Promise<void>): void === | ||
Execute code after | Execute code after the character selection screen has fully loaded. | ||
'''Parameters''' | '''Parameters''' | ||
Line 315: | Line 333: | ||
== Mod Settings == | == Mod Settings == | ||
{{Disclaimer|When loading your mod as a Local Mod via the Creator Toolkit, the mod must be linked to mod.io and you must have subscribed to and installed the mod via mod.io in order for this data to persist.}} | |||
The mod settings API can be accessed through the <code>settings</code> property on the root context object. | The mod settings API can be accessed through the <code>settings</code> property on the root context object. | ||
Line 455: | Line 475: | ||
input.type = 'text'; | input.type = 'text'; | ||
input.name = name; | input.name = name; | ||
input.addEventListener('change', () => onChange()); | |||
const label = document.createElement('label'); | const label = document.createElement('label'); | ||
Line 625: | Line 646: | ||
== Character Data Storage == | == Character Data Storage == | ||
{{Disclaimer|When loading your mod as a Local Mod via the Creator Toolkit, the mod must be linked to mod.io and you must have subscribed to and installed the mod via mod.io in order for this data to persist.}} | |||
The character storage API can be accessed through the <code>characterStorage</code> property on the root context object. | The character storage API can be accessed through the <code>characterStorage</code> property on the root context object. | ||
Line 686: | Line 709: | ||
== Account Data Storage == | == Account Data Storage == | ||
{{Disclaimer|When loading your mod as a Local Mod via the Creator Toolkit, the mod must be linked to mod.io and you must have subscribed to and installed the mod via mod.io in order for this data to persist.}} | |||
The account storage API can be accessed through the <code>accountStorage</code> property on the root context object. | The account storage API can be accessed through the <code>accountStorage</code> property on the root context object. | ||
Line 747: | Line 772: | ||
== Game Object Patching/Hooking == | == Game Object Patching/Hooking == | ||
=== A Quick Note on Function Syntax === | |||
When patching methods, for most scenarios you'll want to use a traditional function expression, rather than the arrow expression syntax. This will ensure <code>this</code> is bound to the class instance that is calling the method, rather than the context where the patch was defined. | |||
For example, | |||
<syntaxhighlight lang="js" line="1">export function setup({ patch }) { | |||
const methodPatch = patch(Class, 'method'); | |||
// Do this | |||
methodPatch.before(function () { }); | |||
// Or this | |||
function beforePatch () { } | |||
methodPatch.before(beforePatch); | |||
// Not this, unless you understand the implications of doing so | |||
methodPatch.before(() => { }); | |||
}</syntaxhighlight> | |||
=== patch(className: class, methodOrPropertyName: string): MethodPatch | PropertyPatch === | === patch(className: class, methodOrPropertyName: string): MethodPatch | PropertyPatch === | ||
Line 778: | Line 821: | ||
<syntaxhighlight lang="js" line>// Double all XP gains | <syntaxhighlight lang="js" line>// Double all XP gains | ||
ctx.patch(Skill, 'addXP').before((amount, masteryAction) | ctx.patch(Skill, 'addXP').before(function (amount, masteryAction) { | ||
return [amount * 2, masteryAction]; | |||
});</syntaxhighlight> | |||
==== MethodPatch.after(hook: (returnValue: any, ...args: any) => any | void): void ==== | ==== MethodPatch.after(hook: (returnValue: any, ...args: any) => any | void): void ==== | ||
Line 791: | Line 836: | ||
<syntaxhighlight lang="js" line>// The player never misses an attack | <syntaxhighlight lang="js" line>// The player never misses an attack | ||
ctx.patch(Player, 'rollToHit').after(willHit | // Patching: rollToHit(target: Character, attack: SpecialAttack): boolean; | ||
if (!willHit) console.log( | ctx.patch(Player, 'rollToHit').after(function(willHit, target, attack) { | ||
if (!willHit) { | |||
console.log(`A miss? With ${attack.name}? Against ${target.noun.plain}? I think not!`); | |||
} | |||
return true; | return true; | ||
}) | })</syntaxhighlight> | ||
==== MethodPatch.replace(replacement: (replacedMethod: (...args: any) => any, ...args: any) => any): void ==== | ==== MethodPatch.replace(replacement: (replacedMethod: (...args: any) => any, ...args: any) => any): void ==== | ||
Line 806: | Line 854: | ||
'''Example''' | '''Example''' | ||
<syntaxhighlight lang="js" line>ctx.patch(Skill, 'addXP').replace(function(o, amount, masteryAction) { | <syntaxhighlight lang="js" line>ctx.patch(Skill, 'addXP').replace(function (o, amount, masteryAction) { | ||
// Prevent any woodcutting XP | // Prevent any woodcutting XP | ||
if (this.id === 'melvorD:Woodcutting') return; | if (this.id === 'melvorD:Woodcutting') return; | ||
Line 821: | Line 869: | ||
<syntaxhighlight lang="js" line>const xpPatch = ctx.patch(Skill, 'addXP'); | <syntaxhighlight lang="js" line>const xpPatch = ctx.patch(Skill, 'addXP'); | ||
xpPatch.replace((o, amount, masteryAction) | xpPatch.replace(function (o, amount, masteryAction) { | ||
console.log('Replacement #1'); | console.log('Replacement #1'); | ||
return o(amount, masteryAction); | return o(amount, masteryAction); | ||
}); | }); | ||
xpPatch.replace( | xpPatch.replace(function (o, amount, masteryAction) { | ||
console.log('Replacement #2'); | console.log('Replacement #2'); | ||
return o(amount, masteryAction); | return o(amount, masteryAction); | ||
Line 847: | Line 895: | ||
<syntaxhighlight lang="js" line>// Effectively double available Township resources | <syntaxhighlight lang="js" line>// Effectively double available Township resources | ||
ctx.patch(TownshipResource, 'amount').get((o) | ctx.patch(TownshipResource, 'amount').get(function (o) { | ||
return o() * 2; | |||
}); | |||
// Or more practically, make resources unlimited | // Or more practically, make resources unlimited | ||
ctx.patch(TownshipResource, 'amount').get(() | ctx.patch(TownshipResource, 'amount').get(function () { | ||
return 999999; | |||
});</syntaxhighlight> | |||
==== PropertyPatch.set(setter: (o: (value: any) => void, value: any) => void): void ==== | ==== PropertyPatch.set(setter: (o: (value: any) => void, value: any) => void): void ==== | ||
Line 863: | Line 915: | ||
<syntaxhighlight lang="js" line>// Sorry, there aren't many setters in the game to use for a practical example | <syntaxhighlight lang="js" line>// Sorry, there aren't many setters in the game to use for a practical example | ||
// Doubles whatever resource amount is being set | // Doubles whatever resource amount is being set | ||
ctx.patch(TownshipResource, 'amount').set((o, amount) | ctx.patch(TownshipResource, 'amount').set(function (o, amount) { | ||
return o(amount * 2); | |||
}); | |||
// While in-game | // While in-game | ||
game.township.resources.getObjectByID('melvorF:Wood').amount = 1000; | game.township.resources.getObjectByID('melvorF:Wood').amount = 1000; | ||
Line 926: | Line 980: | ||
"setup": "setup.mjs" | "setup": "setup.mjs" | ||
}</syntaxhighlight> | }</syntaxhighlight> | ||
<small>''Comments in JSON are purely illustrative and not valid markup''</small> | |||
<syntaxhighlight lang="js" line>// setup.mjs | <syntaxhighlight lang="js" line>// setup.mjs |
Latest revision as of 18:36, 10 June 2024
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();
Getter Properties
name: string
The name of the mod.
namespace: string | undefined
The defined namespace of the mod, if provided.
version: string
The currently loaded version of the mod.
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): Promise<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
Returns
Promise<void>
A promise that is resolved once all templates have been injected into the document body.
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
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();
Lifecycle Hooks
onModsLoaded(callback: (ctx: ModContext) => void | Promise<void>): void
Execute code after all mods have been loaded (character select screen).
Parameters
callback: (ctx: ModContext) => void | Promise<void>
A callback function that receives the mod's context object as a parameter. Can be synchronous or asynchronous.
Example
ctx.onModsLoaded(async (ctx) => {
// ...
});
onCharacterSelectionLoaded(callback: (ctx: ModContext) => void | Promise<void>): void
Execute code after the character selection screen has fully loaded.
Parameters
callback: (ctx: ModContext) => void | Promise<void>
A callback function that receives the mod's context object as a parameter. Can be synchronous or asynchronous.
Example
ctx.onCharacterSelectionLoaded(async (ctx) => {
// ...
});
onInterfaceAvailable(callback: (ctx: ModContext) => void | Promise<void>): void
Execute code before the character is loaded but after the game interface is initially injected into the page (but not initialized). Mostly useful for adding interface elements for custom skills that need to be present before onCharacterLoaded
.
Parameters
callback: (ctx: ModContext) => void | Promise<void>
A callback function that receives the mod's context object as a parameter. Can be synchronous or asynchronous.
Example
ctx.onInterfaceAvailable(async (ctx) => {
// ...
});
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
callback: (ctx: ModContext) => void | Promise<void>
A callback function that receives the mod's context object as a parameter. Can be synchronous or asynchronous.
Example
ctx.onCharacterLoaded(async (ctx) => {
// ...
});
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
callback: (ctx: ModContext) => void | Promise<void>
A callback function that receives the mod's context object as a parameter. Can be synchronous or asynchronous.
Example
ctx.onInterfaceReady(async (ctx) => {
// ...
});
Game Object Registration
The game object registration API can be accessed through the gameData
property on the root context object.
addPackage(data: string | GameDataPackage): Promise<void>
Registers a game data package.
Parameters
data: string | GameDataPackage
The resource path to your game data package .json
file or a valid JavaScript GameDataPackage object.
Example
// data.json
{
"$schema": "https://melvoridle.com/assets/schema/gameData.json",
"data": {
// data objects here
}
}
Comments in JSON are purely illustrative and not valid markup
await ctx.gameData.addPackage('data.json');
buildPackage(builder: (packageBuilder: GameDataPackageBuilder) => void): BuiltGameDataPackage
Builds a GameDataPackage object using the GameDataPackageBuilder
API.
Parameters
builder: (packageBuilder: GameDataPackageBuilder) => void
The builder to be used to add individual game objects to the data package.
Returns
BuiltGameDataPackage
A wrapper for the game data package. See information below.
Example
ctx.gameData.buildPackage((p) => {
// data registration here
});
BuiltGameDataPackage.package: GameDataPackage
(Property) The actual built GameDataPackage
object.
BuiltGameDataPackage.add(): void
Registers the built game data package.
Example
const pkg = ctx.gameData.buildPackage((p) => { /* ... */ });
pkg.add();
Mod Settings
The mod settings API can be accessed through the settings
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
name: string
The name of the section. This will be displayed as a header of the section in the settings window.
Returns
Section
The section's object, used to perform add, set, or get settings.
Example
ctx.settings.section('General');
ctx.settings.section('Other');
// Sections will be displayed in the settings window in this order
// 1. General
// 2. Other
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
config: SettingConfig | SettingConfig[]
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
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'
}]);
Section.get(name: string): any
Gets the current value of a setting by its name property.
Parameters
name: string
The name of the setting to get the value of
Returns
any
The current value of the setting
Example
// Assuming the player has typed "1" into the setting
ctx.settings.section('Other').get('pick-a-number'); // 1
Section.set(name: string, value: any): void
Programmatically sets the value of a setting by its name property.
Parameters
name: string
The name of the setting to set the value of
value: any
The value to set the setting to
Example
ctx.settings.section('Other').set('pick-a-number', 5);
type(name: string, config: SettingTypeConfig): void
Registers a setting type that can then be used by by any mod when adding a setting.
Parameters
name: string
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.
config: SettingTypeConfig
An object defining the setting type's behavior. See definition below.
Example
// manifest.json
{
"namespace": "my_mod",
// ...
}
Comments in JSON are purely illustrative and not valid markup
ctx.settings.type('customText', {
// See example config in SettingTypeConfig section below
});
ctx.settings.section('General').add({
type: 'customText',
// ...
});
Other mods will have to add your namespace to use your custom type:
ctx.settings.section('Other').add({
type: 'my_mod:customText',
// ...
});
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 name
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 <input>
's name
and id
attributes to this value, and then setting a <label>
's for
attribute to this value as well.
The onChange
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 <input>
element's change
event.
The config
parameter holds all values passed in the config object when this setting is being added. For example, the label
, hint
, default
, etc. properties.
Individual settings can opt to return validation errors in their onChange
method. You can give a place to display this validation error in an element with a class of validation-message
.
// 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;
input.addEventListener('change', () => onChange());
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.appendChild(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;
}
get(root: HTMLElement): any
The get
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.
// get function for simple text input defined by above render
function get(root) {
return root.querySelector('input').value;
}
set(root: HTMLElement, value: any): void
The set
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.
// set function for simple text setting defined above
function set(root, value) {
root.querySelector('input').value = value;
}
Example
// Use functions defined in above examples as reference
ctx.settings.type('simpleText', {
render: render,
get: get,
set: set
});
Built-In Types
Base Setting Configuration
All individual settings inherit this base setting config object.
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
}
The onChange
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 /
undefined
/true
/ truth-y (non-string) value: Validates successfully and allows the value to be changed false
/ false-y value: Validation fails and setting value is restored to previousstring
value: Validation fails, setting value is restored to previous, and the string contents are displayed in a.validation-message
element, if available (see custom render above)
Text
A simple textbox that accepts any character by default. Value is of type string
.
interface TextConfig implements SettingConfig {
type: 'text';
maxLength: number; // Max length attribute for the textbox
}
Number
A simple textbox that only accepts numbers. Value is of type number
.
interface NumberConfig implements SettingConfig {
type: 'number';
min: number; // Minimum value to be entered
max: number; // Maximum value to be entered
}
Switch
An on/off toggle switch. Value is of type boolean
.
interface SwitchConfig implements SettingConfig {
type: 'switch'
}
Dropdown
A dropdown button. Example: "Default Page on Load" game setting. Value is of type any
.
DropdownConfig implements SettingConfig {
type: 'dropdown';
color: string; // see Button config
options: DropdownOption[]; // see note
}
The options
option defines the dropdown options available to be selected. Dropdown option schema is:
interface DropdownOption {
value: any; // value that is used by the setting
display: string | HTMLElement; // display text or element on the option
}
Button
A button. Value is undefined
.
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
}
The color
option is appended to a CSS class starting with btn-
and defaults to primary
(btn-primary
) 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 any[]
.
interface CheckboxGroupConfig implements SettingConfig {
type: 'checkbox-group';
options: CheckboxOption[]; // see note
}
The options
option defines the checkboxes that are available to be selected. Checkbox option schema is:
interface CheckboxOption {
value: any; // value to be added to array that is set as setting value
label: string | HTMLElement;
hint: string | HTMLElement;
}
Radio Group
A group of radio buttons. Value is of type any
.
interface RadioGroupConfig implements SettingConfig {
type: 'radio-group';
options: CheckboxOption[]; // see checkbox group's options schema
}
Label
A simple label. Value is undefined
.
interface LabelConfig implements SettingConfig {
type: 'label';
}
Custom
A custom-rendered setting. See 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 any
.
interface CustomConfig implements SettingConfig, SettingTypeConfig {
type: 'custom';
}
Character Data Storage
The character storage API can be accessed through the characterStorage
property on the root context object.
Limitations
The character storage can only be used once a character has been loaded (after lifecycle hook onCharacterLoaded
).
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 (string
, number
, boolean
) and objects and arrays that contain only primitive types or other objects or arrays that fit this description. This serialization/deserialization is handled automatically.
setItem(key: string, data: any): void
Sets a key/value pair in character storage.
Parameters
key: string
The key to identify the data being stored. Used in calls to getItem
and removeItem
.
data: any
The data to be stored. See limitations above.
Example
ctx.characterStorage.setItem('coolThings', ['rocks']);
getItem(key: string): any
Gets a value by its key from character storage.
Parameters
key: string The key of the data to retrieve
Returns
any
The data retrieved. Returns undefined
if no such key is stored.
Example
ctx.characterStorage.getItem('coolThings'); // returns ['rocks']
removeItem(key: string): void
Removes a key/value pair by key from character storage.
Parameters
key: string
The key of the key/value pair to remove
Example
ctx.characterStorage.removeItem('coolThings');
ctx.characterStorage.getItem('coolThings'); // returns undefined
clear(): void
Removes all key/value pairs from character storage.
Example
ctx.characterStorage.clear();
Account Data Storage
The account storage API can be accessed through the accountStorage
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 (string
, number
, boolean
) and objects and arrays that contain only primitive types or other objects or arrays that fit this description. This serialization/deserialization is handled automatically.
setItem(key: string, data: any): void
Sets a key/value pair in account storage.
Parameters
key: string
The key to identify the data being stored. Used in calls to getItem
and removeItem
.
data: any
The data to be stored. See limitations above.
Example
ctx.accountStorage.setItem('coolThings', ['rocks']);
getItem(key: string): any
Gets a value by its key from account storage.
Parameters
key: string
The key of the data to retrieve
Returns
any
The data retrieved. Returns undefined
if no such key is stored.
Example
ctx.accountStorage.getItem('coolThings'); // returns ['rocks']
removeItem(key: string): void
Removes a key/value pair by key from account storage.
Parameters
key: string
The key of the key/value pair to remove
Example
ctx.accountStorage.removeItem('coolThings');
ctx.accountStorage.getItem('coolThings'); // returns undefined
clear(): void
Removes all key/value pairs from account storage.
Example
ctx.accountStorage.clear();
Game Object Patching/Hooking
A Quick Note on Function Syntax
When patching methods, for most scenarios you'll want to use a traditional function expression, rather than the arrow expression syntax. This will ensure this
is bound to the class instance that is calling the method, rather than the context where the patch was defined.
For example,
export function setup({ patch }) {
const methodPatch = patch(Class, 'method');
// Do this
methodPatch.before(function () { });
// Or this
function beforePatch () { }
methodPatch.before(beforePatch);
// Not this, unless you understand the implications of doing so
methodPatch.before(() => { });
}
patch(className: class, methodOrPropertyName: string): MethodPatch | PropertyPatch
This is the entry-point to the method and getter/setter patching API. Depending on if the second parameter is a method or getter/setter property, a MethodPatch
or PropertyPatch
object will be returned, respectively. The MethodPatch/PropertyPatch object should then be used to perform further actions with the specified class and method/property.
Parameters
className: class
Class containing the method or getter/setter you want to patch. Should be the actual class reference, not a string, e.g. Skill
, not 'Skill'
.
methodOrPropertyName: string
Name of the method or getter/setter property to patch.
Returns
MethodPatch | PropertyPatcch
A patch object for the specified class and method or getter/setter property. See below for usage.
Example
ctx.patch(Skill, 'addXP'); // Returns a MethodPatch
ctx.patch(Skill, 'level'); // Returns a PropertyPatch
MethodPatch.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 undefined
), the arguments are left as-is.
Parameters
hook: (...args: any) => any[] | void
The callback hook to be executed.
Example
// Double all XP gains
ctx.patch(Skill, 'addXP').before(function (amount, masteryAction) {
return [amount * 2, masteryAction];
});
MethodPatch.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 undefined
), the return value is left as-is.
Parameters
hook: (returnValue: any, ...args: any) => any | void
The callback hook to be executed.
Example
// The player never misses an attack
// Patching: rollToHit(target: Character, attack: SpecialAttack): boolean;
ctx.patch(Player, 'rollToHit').after(function(willHit, target, attack) {
if (!willHit) {
console.log(`A miss? With ${attack.name}? Against ${target.noun.plain}? I think not!`);
}
return true;
})
MethodPatch.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 before
and after
hooks, respectively.
Parameters
replacement: (replacedMethod: (...args: any) => any, ...args: any) => any
The callback function to replace the method body.
Example
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);
});
It's important to note that using the replace
method replaces the current method body, meaning multiple calls of the replace
method get executed in the reverse order that they were declared:
const xpPatch = ctx.patch(Skill, 'addXP');
xpPatch.replace(function (o, amount, masteryAction) {
console.log('Replacement #1');
return o(amount, masteryAction);
});
xpPatch.replace(function (o, amount, masteryAction) {
console.log('Replacement #2');
return o(amount, masteryAction);
});
game.woodcutting.addXP(100);
// Logs:
// Replacement #2
// Replacement #1
PropertyPatch.get(getter: (o: () => any) => any): void
Execute the provided function and return the return value when a getter property is accessed.
Parameters
getter: (o: () => any) => any
The getter function to be executed. The parameter o
is a reference to the getter method being replaced, which is either a previous getter patch or the original getter method.
Example
// Effectively double available Township resources
ctx.patch(TownshipResource, 'amount').get(function (o) {
return o() * 2;
});
// Or more practically, make resources unlimited
ctx.patch(TownshipResource, 'amount').get(function () {
return 999999;
});
PropertyPatch.set(setter: (o: (value: any) => void, value: any) => void): void
Execute the provided function when a setter property is accessed.
Parameters
setter: (o: (value: any) => void, value: any) => void
The setter function to be executed. The first parameter, o
, is a reference to the setter method being replaced, which is either a previous setter patch or the original setter method. The second parameter, value
, contains the value being set.
Example
// Sorry, there aren't many setters in the game to use for a practical example
// Doubles whatever resource amount is being set
ctx.patch(TownshipResource, 'amount').set(function (o, amount) {
return o(amount * 2);
});
// While in-game
game.township.resources.getObjectByID('melvorF:Wood').amount = 1000;
game.township.renderQueue.resourceAmounts = true;
// 2000 wood is available
PropertyPatch.replace(getter?: (o: () => any) => any, setter?: (o: (value: any) => void, value: any) => void): void
Alias for calling get
and set
at the same time.
Parameters
getter: (o: () => any) => any
See above Parameters for get
.
setter: (o: (value: any) => void, value: any) => void
See above Parameters for set
.
Example
See above examples for get
and set
.
isPatched(className: class, methodOrPropertyName: string): boolean
Checks whether or not a method or getter/setter property has been patched.
Parameters
className: class
Class containing the method or property to check for having been patched. Should be the actual class reference, not a string, e.g. Skill
, not 'Skill'
.
methodOrPropertyName: string
Name of the method or property to check.
Returns
boolean
Whether or not the given class method or property is patched.
Example
ctx.isPatched(Skill, 'addXP'); // false
ctx.patch(Skill, 'addXP');
ctx.isPatched(Skill, 'addXP'); // true
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 api
method on the context object. After defining an API using the method below, other mods can access it through the global mod.api['your_mods_namespace']
object.
api(endpoints?: object): object
Specify properties and methods to expose on the global mod.api['your_mods_namespace']
object. Can be called multiple times to append more endpoints.
Parameters
endpoint: object
An object containing any properties or methods you want to expose. Can be omitted to just retrieve your mod's current API object.
Returns
object
The mod's API object
Example
// manifest.json
{
"namespace": "helloWorld",
"setup": "setup.mjs"
}
Comments in JSON are purely illustrative and not valid markup
// setup.mjs
export function setup({ api }) {
api({
greet: name => console.log(`Hello, ${name!}`);
});
}
Other mods would then be able to interact with your API:
// some other mod
mod.api.helloWorld.greet('Melvor'); // Hello, Melvor!
Melvor Idle version v1.3.1 (Released: 30th October 2024) |
---|
Error creating thumbnail: File missing Combat: Error creating thumbnail: File missing Attack • Error creating thumbnail: File missing Strength • Error creating thumbnail: File missing Defence • Error creating thumbnail: File missing Hitpoints • Error creating thumbnail: File missing Ranged • Error creating thumbnail: File missing Magic • Error creating thumbnail: File missing Prayer • Error creating thumbnail: File missing Slayer • Error creating thumbnail: File missing Corruption
|
Skills: Error creating thumbnail: File missing Farming • Error creating thumbnail: File missing Township • Error creating thumbnail: File missing Woodcutting • Error creating thumbnail: File missing Fishing • Error creating thumbnail: File missing Firemaking • Error creating thumbnail: File missing Cooking • Error creating thumbnail: File missing Mining • Error creating thumbnail: File missing Smithing • Error creating thumbnail: File missing Thieving • Error creating thumbnail: File missing Fletching • Error creating thumbnail: File missing Crafting • Error creating thumbnail: File missing Runecrafting • Error creating thumbnail: File missing Herblore • Error creating thumbnail: File missing Agility • Error creating thumbnail: File missing Summoning • Error creating thumbnail: File missing Astrology • Error creating thumbnail: File missing Alternative Magic • Error creating thumbnail: File missing Cartography • Error creating thumbnail: File missing Archaeology • Error creating thumbnail: File missing Harvesting
|
Other: Error creating thumbnail: File missing Beginners Guide • Guides • Error creating thumbnail: File missing Bank • Error creating thumbnail: File missing Combat • Error creating thumbnail: File missing Mastery • Error creating thumbnail: File missing Money Making • Error creating thumbnail: File missing Shop • Easter Eggs • Pets • Error creating thumbnail: File missing Golbin Raid • Error creating thumbnail: File missing Full Version • Throne of the Herald • Atlas of Discovery • Error creating thumbnail: File missing Into the Abyss
|
Reference Tables: Items, Equipment, Experience Table, Upgrading Items, Combat Areas, Slayer Areas, Dungeons, Strongholds, The Abyss, Monsters |