@discordia/action

Note: Some of the links in this README file work better on the documentation site

• Installation
• Basic Example
• Usage
  • Accessor
  • Response
  • Description
• Examples
  • String Accessor and String Response
  • Array Accessor
  • Function Accessor
  • Function Response
• Testing

Installation

# install the module using npm
npm install @discordia/action

# install the module using yarn
yarn add @discordia/action

Discordia actions are designed to be used with a Discordia framework instance. See the section on testing below for details on how to validate your actions.

Basic Example

const DiscordiaAction = require('@discordia/action');

const pingAction = new DiscordiaAction('ping', 'pong');

# Conversation Example(s)

User: @BotName ping
BotName: @User, pong

Usage

Every Discordia action is made of three pieces: an accessor, a response, and an optional description.

Accessor

The accessor is how the Discordia framework determines whether or not this action should give its response. The Discordia framework calls the action's checkAccessor method which in turn determines whether or not to call the action's handleAction method based on the type of the accessor. The checkAccessor method is given three parameters:

Parameter	Description
msgContent	The exact content of the message that triggered this action
msg	The full Message object that triggered this action
framework	The full Discordia Framework instance - USE WITH CAUTION

String

If the accessor is a string and it is the first string after the name of the bot then handleAction for this action will be called.

Array

If the accessor is an array and any of its entries is the first string after the name of the bot then handleAction for this action will be called.

Function

If the accessor is a function that returns true when provided with msgContent, msg, and framework then handleAction for this action will be called.

Response

The response is how the Discordia framework responds to a user that tries to interact with the bot it creates. Once handleAction is called it will determine how to respond to the user based on the type of the response. The handleAction method is given four parameters:

Parameter	Description
msgContent	The exact content of the message that triggered this action
msg	The full Message object that triggered this action
framework	The full Discordia Framework instance - USE WITH CAUTION
userArgs	Everything in the user's message after the accessor that triggered this action

String

If the response is a string then msg.reply is called with response as the content parameter.

Function

If the response is a function then that function will be called with msgContent, msg, framework, and userArgs as parameters. If the function returns a string then msg.reply is called with the result of that function as the content parameter. Otherwise you are encouraged to use the msg object to handle sending the response yourself.

Description

Description is an optional parameter that must be a string used to enable a help (or h) action on the Discordia framework. By default the discordia framework will attempt to supply usage information to server members who ask the bot created by the Discordia framework for help.

// Default Behavior
`-------------------------
**Command**: \`${accessor}\`

${description}`

Accessor is formatted based on its type to show the available options (with "{Dynamic Accessor}" sent if the accessor is a function). The description is the exact contents of the description parameter given to the Discordia action constructor.

If description is ommitted or set to null then the whole action will be left off when the the help action is triggered.

The behavior of the help command can be overriden - see the Discordia Framework constructor.

Examples

String Accessor and String Response

const DiscordiaAction = require('@discordia/action');

const pingAction = new DiscordiaAction('ping', 'pong');

# Conversation Example(s)

User: @BotName ping
BotName: @User, pong

Array Accessor

const DiscordiaAction = require('@discordia/action');

const ouchAction = new DiscordiaAction(['oof', 'ow', 'ouch'], 'rekt');

# Conversation Example(s)

User: @BotName oof
BotName: @User, rekt
---
User: @BotName ow
BotName: @User, rekt
---
User: @BotName ouch
BotName: @User, rekt

Function Accessor

const DiscordiaAction = require('@discordia/action');

const accessor = (msgContent, msg, framework) => {
  if (msgContent.includes('potato')) {
    return true;
  }
  return false;
};
const potatoAction = new DiscordiaAction(accessor, 'delicious');

# Conversation Example(s)

User: @BotName Do you like potatoes?
BotName: @User, delicious

Function Response

const DiscordiaAction = require('@discordia/action');

const response = (msgContent, msg, framework, userArgs) => {
  return `here is a joke for ${msg.author.username}: ${generateJoke()}`;
};
const jokeAction = new DiscordiaAction('joke', response);

# Conversation Example(s)

User: @BotName joke
BotName: @User, here is a joke for User: {something funny}

Testing

🚧 Coming Soon! 🚧

Changelog

1.4.2 (2020-05-11)

Bug Fixes

• documentation fixes (144a707)