The Module API

Michael Barrett edited this page Jun 1, 2018 · 10 revisions

Jankbot is designed to be extended by modules. These modules are written in NodeJS and use a simple API to interact with the core of Jankbot. Modules can interact directly with the bot, friends list, and any functionality you can think of within the world of NodeJS. Think of Jankbot as a front-end to your module.

Square 1

Create a directory for your module and add a module.json file that looks like this:

{
  "name": "Module Name",
  "author": "Author Name",
  "main": "module-file.js",
  "license": "MIT",
  "description": "Description of the module",
  "compatibility": "4.0.0" // The version of Jankbot supported by this module (semver)
}

Edit module.json to your liking. This is the file Jankbot will use to identify your module when it is loading. After that, make your module file (with the same file name as you put in module.json as "main") and begin writing your module.

The API

exports.handle(input, source)

is the hook into Jankbot's message handling system. Jankbot will pass the raw text and the ID of the user who sent the command to this function (input and source respectively). This function should parse the user input and decide if your module is capable of handling the input, and if so, act upon the input. This function should return true if it handles the input, and false (or no return) otherwise. Returning true will stop other modules from checking the input. If for some reason you want to handle the input but still allow other modules to execute, do your work here and do not return anything.

exports.onExit()

runs when Jankbot is shutting down. Useful for ensuring proper saves.

exports.onBotLogin(bot)

Runs when Jankbot successfully logs in to steam. This function is passed the node-steam bot instance as the first parameter.

exports.getHelp(isAdmin)

should return the help string for your module for when the a user says 'help' to Jankbot. isAdmin is true if the requesting user is an administrator for this Jankbot. Use this flag to optionally return any admin-only command help for your module.

Jankbot will call getHelp on every module when a user sends the message "help", and combine them into a response to that user.

exports.setDictionary(dictionaryFileName)

If Jankbot sees this function exported in your module, it will pass in the file name of the dictionary being used in the main Jankbot modules. You can in turn use this to load your own dictionary and localize your module.

For example, if this Jankbot instance is using english.json as its core dictionary, it will pass 'english.json' to this function, prompting your module to use its own english.json dictionary file. This is more advanced, but allows you to add localization to your module in tandem with Jankbot's localization.

Core Modules

Jankbot has 3 core modules to give functionality to modules. To use these modules, require them to your file with:

var modulename = require('../../core/modulename');

Replacing modulename with the module you need.

The 3 core modules are:

  1. friends.js for managing friend data and sending messages
  2. logger.js for logging data and errors to the console and log file
  3. dota2.js for doing in-game functionality

Publish your module

Just like any other Node.js package, you can publish your Jankbot module to npm with npm publish. This allows you to specify dependencies in a package.json file. If you publish your Jankbot module to npm, we recommend prefixing your package name with jankbot- to ensure that Jankbot modules are easily found and identified. For example, if you were writing a message of the day module, you could title it jankbot-motd.

NPM development tip

When designing your Jankbot package to publish to npm, you can simulate an npm installation using your local directory. If you have a Jankbot install at /home/jankbot and you are developing your module at /home/mymodule, you can go to your Jankbot folder and run npm install ../mymodule to have npm install it as if it were installing from the npm registry.