ModAttachr
Hookups for extensible triggered mod events.
ModAttachr allows host applications to send messages to "mods", or collections of callbacks linked to string event names. Mods may be individually enabled or disabled.
Usage
Events
Each mod may attach callbacks to named calls fired by the host application to act on application events. Event names are shared across mods.
Two event names are defined by default:
-
"onModEnable"
: Called when a mod is enabled, including when a newModAttachr
instance is created. -
"onModDisable"
: Called when a mod is disabled after previously being enabled.
Mods default to disabled unless provided with an enabled: true
.
enableMod
Enables a mod if it wasn't already enabled.
// "Enabled Two!"
const modAttacher = new ModAttachr({
mods: [
{
events: {
onModEnable: () => console.log("Enabled One!"),
onStart: () => console.log("Starting One!"),
},
name: "One",
},
{
enabled: true,
events: {
onModEnable: () => console.log("Enabled Two!"),
},
name: "Two",
},
],
});
// "Enabled One!"
// "Enabled Two!"
modAttacher.fireModEvent("onModEnable");
// "Starting One!"
modAttacher.fireModEvent("onStart");
disableMod
Disables a mod if it was previously enabled.
const modAttacher = new ModAttachr({
mods: [
{
events: {
onModDisable: () => console.log("Disabled One!"),
onStart: () => console.log("Starting One!"),
},
name: "One",
},
{
enabled: true,
events: {
onModDisable: () => console.log("Disabled Two!"),
},
name: "Two",
},
],
});
// "Disabled Two!"
modAttacher.fireModEvent("onModDisable");
modAttacher.fireModEvent("onStart");
fireEvent
Fires a named event to be received by any enabled subscribing mod. Any parameters passed to the event are directly passed to mods.
const modAttacher = new ModAttachr({
mods: [
{
events: {
onPoints: (player, points) => console.log(`${player} scored ${points}!`),
},
name: "Sample",
},
],
});
// "You scored 7!"
modAttacher.fireModEvent("onPoints", "You", 7);
eventNames
It's common to use a class extending from the module's exported ModEventNames
to store common event names.
Pass it as a eventNames
to the ModAttachr
constructor and use it instead of string literals for event names:
import { ModAttachr, ModEventNames } from "modattachr";
class SampleModEventNames extends ModEventNames {
onStart = "onStart",
}
const modEventNames = new SampleModEventNames();
// "Starting!"
const modAttacher = new ModAttachr({
mods: [
{
enabled: true,
eventNames: modEventNames,
events: {
[modEventNames.onModEnable]: () => console.log("Enabled!"),
[modEventNames.onStart]: () => console.log("Starting!"),
},
name: "Sample",
},
],
});
// "Starting!"
modAttacher.fireEvent(modEventNames.onStart);
ItemsHoldr
It's common in persistent applications to store whether mods are enabled or disabled in a cache such as localStorage
.
Pass an ItemsHoldr
as itemsHolder
to a ModAttachr
to have it store whether each mod is enabled there.
new ModAttachr({
itemsHolder: new ItemsHoldr(),
mods: [],
});
Mod toggle booleans are stored directly under mod names by default.
const itemsHolder = new ItemsHoldr();
itemsHolder.setItem("One", true);
// "Enabled One!"
const modAttacher = new ModAttachr({
itemsHolder,
mods: [
{
events: {
onModEnable: () => console.log("Enabled One!"),
},
name: "One",
},
],
});
transformModName
Pass a lambda that converts a string name to another string if you need to customize which keys are used for mods in storage.
const itemsHolder = new ItemsHoldr();
itemsHolder.setItem("MyMods::One", true);
// "Enabled One!"
const modAttacher = new ModAttachr({
itemsHolder,
mods: [
{
events: {
onModEnable: () => console.log("Enabled One!"),
},
name: "One",
},
],
transformModName: (modName) => `MyMods::${modName}`,
});
Development
This repository is a portion of the EightBittr monorepo.
See its docs/Development.md for details on how to get started.
Running Tests
yarn run test
Tests are written in Mocha and Chai.
Their files are written using alongside source files under src/
and named *.test.ts?
.
Whenever you add, remove, or rename a *.test.t*
file under src/
, watch
will re-run yarn run test:setup
to regenerate the list of static test files in test/index.html
.
You can open that file in a browser to debug through the tests, or run yarn test:run
to run them in headless Chrome.