Installing

$ npm install @jiman24/discord-rpg

Setup

discord-rpg extends node's discord commando framework. So if you feel the documentation here is incomplete, you can refer to their documentation.

const DiscordRPG = require('@jiman24/discord-rpg');

const client = new DiscordRPG({ 
  commandPrefix: "sb!", // setup default command prefix
  owner: ["264010327023288323"], // add your discord id here
});

//... rest of the code goes here

// make sure to put this last
client.login("secret-token-here");

Setup database

To setup a sqlite database, you need to give a filename as sqlite works as a file. The setup has been abstracted so that you can start away use the database. client.db returns sqlite3's Database which you can run custom sql statement. client.db? has ? at the end is javascript's optional chaining which means if this member of an object exists return it, if not return early undefined.

client.setDBFile("data.db").then(() => {

    // define custom schema
    client.db?.run(`
      CREATE TABLE IF NOT EXISTS player (
       player_id TEXT UNIQUE PRIMARY KEY,
       gold      DEFAULT 0,
       xp        DEFAULT 0
      )
    `)

  })

Changing command prefix

Changing command prefix has been implemented by default by commando. By default, only guild owner and admins can use this command.

Adding command

discord-rpg also provide simpler way to add command. Unlike commando where you have to extend Command class in order to add a command, you can just use client.registerCommand. The first parameter is command information where you can pass additional info about the command for example adding alias or add description about a command.

// normal command
client.registerCommand({ name: "name" }, (msg, args) => {
  msg.say(`My name is ${client.user?.username}`);
  const guild = msg.guild.name; // to access which guild the command is run
  const channel = msg.channel.name; // access which channel the command run
  msg.say(`Im in ${guild} on channel ${channel}`); // send message
})


// adding alias to a command. aliases expects an array of strings where you add
// multiple aliases for a command
client.registerCommand({ name: "sample", aliases: ["s"] }, (msg, args) => {
  msg.say("I'm sample command");
})

Embed message

Embed message is already provided by discord.js and it's already simple and powerful. To read further, you can read the documentation here.

const {MessageEmbed} = require("discord.js");

// embed message with image
client.registerCommand({ name: "profile" }, async (msg, args) => {
  const player = await client.db?.get(
    `SELECT * FROM player WHERE player_id = ?`, msg.author.id
  )!;

  const embed = new MessageEmbed()
    .setThumbnail(msg.author.displayAvatarURL())
    .setColor("#ccc")
    .addField("Name", msg.member?.displayName)
    .addField("Gold", player.gold, true)
    .addField("XP", player.xp, true);

  msg.embed(embed); // finally send the embed message
})

Implement ban command

You can access the arguments passed to a command by indexing second argument args.

// ban command
client.registerCommand({ name: "ban", ownerOnly: true }, (msg, args) => {
  const [mention] = args; // array destructuring to get first element in the array
  client.provider.set(msg.guild, `ban-${mention}`, true); // simple key value db
  msg.say(`${mention} has been banned`);
})

Set a channel

Sometimes you want your bot to only be accessible in a particular channel. client.dispatcher.addInhibitor adds functions to run before the actual command is executed, this is necessary for us to prevent user from using our bot outside the selected channel. To read more, you can follow this link.

// set channel
client.registerCommand({ name: "setchannel", ownerOnly: true }, (msg, args) => {
  const channel = msg.channel;
  client.provider.set(msg.guild, "channel", channel.toString());
  msg.say(`Successfully set channel ${channel}`);
})

// only allow command to be run on selected channel only (which was set by
// sb!setchannel command)
client.dispatcher.addInhibitor(msg => {
  const channel = client.provider.get(msg.guild, "channel"); // get selected channel

  if (channel && msg.channel.toString() !== channel) {
    const response = msg.reply(
      `Commands on this channel is disabled. Please use ${channel}.`
    )

    // returning this object prevents the actual command to be run
    return {
      reason: "invalid channel",
      response,
    }
  }

  return false;
})

Throttled command

Throttled command prevents user from executing command excessively. You can set how many usage per time.

// throttled command
client.registerCommand({ 
  name: "fish", 
  throttling: { usages: 1, duration: 5 } },  // set throttle
  (msg, args) => {
    const random = (min, max) => Math.floor(Math.random() * max) + min;
    const gold = random(1, 10);
    const xp = random(1, 10);
    const playerID = msg.author.id;

    // update user profile in the database
    client.db?.run(`
      UPDATE player 
      SET xp = xp + ?, gold = gold + ?
      WHERE player_id = ?
    `, xp, gold, playerID);
    
    msg.say(`Caught a fish and earned ${gold} gold and ${xp} xp`);
  })

Register player upon using any command

This can be implemented by adding inhibitor.

// register player
client.dispatcher.addInhibitor(msg => {

  const id = msg.author.id;
  const sql1 = `
    SELECT player_id
    FROM player
    WHERE player_id = ?
  `;
  const sql2 = `
    INSERT INTO player (player_id)
    VALUES (?)
  `;

  client.db?.get(sql1, id)
    .then(player => {
      // if user is not in the database
      if (!player) {
        // add user to the db
        client.db?.run(sql2, id);
      }
    })

  return false;
})

Full source code

const { MessageEmbed, TextChannel } = require("discord.js");
const DiscordRPG = require("@jiman24/discord-rpg");

const client = new DiscordRPG({ 
  commandPrefix: "sb!",
  owner: ["264010327023288323"],
});

client.setDBFile("data.db")
  .then(() => {

    // define custom schema
    client.db?.run(`
      CREATE TABLE IF NOT EXISTS player (
       player_id TEXT UNIQUE PRIMARY KEY,
       gold      DEFAULT 0,
       xp        DEFAULT 0
      )
    `)

  })


client.once("ready", () => {
  console.log(`${client.user?.username} is ready`);
})

// normal command
client.registerCommand({ name: "name" }, (msg, args) => {
  msg.say(`My name is ${client.user?.username}`);
  const guild = msg.guild.name;
  const channel = msg.channel.name;
  msg.say(`Im in ${guild} on channel ${channel}`);
})

// embed message with image
client.registerCommand({ name: "profile" }, async (msg, args) => {
  const player = await client.db?.get(
    `SELECT * FROM player WHERE player_id = ?`, msg.author.id
  )!;

  const embed = new MessageEmbed()
    .setThumbnail(msg.author.displayAvatarURL())
    .setColor("#ccc")
    .addField("Name", msg.member?.displayName)
    .addField("Gold", player.gold, true)
    .addField("XP", player.xp, true);

  msg.embed(embed);
})

// ban command
client.registerCommand({ name: "ban", ownerOnly: true }, (msg, args) => {
  const [mention] = args;
  client.provider.set(msg.guild, `ban-${mention}`, true);
  msg.say(`${mention} has been banned`);
})

// set channel
client.registerCommand({ name: "setchannel", ownerOnly: true }, (msg, args) => {
  const channel = msg.channel;
  client.provider.set(msg.guild, "channel", channel.toString());
  msg.say(`Successfully set channel ${channel}`);
})

// throttled command
client.registerCommand({ 
  name: "fish", 
  throttling: { usages: 1, duration: 5 } }, 
  (msg, args) => {
    const random = (min, max) => Math.floor(Math.random() * max) + min;
    const gold = random(1, 10);
    const xp = random(1, 10);
    const playerID = msg.author.id;
    client.db?.run(`
      UPDATE player 
      SET xp = xp + ?, gold = gold + ?
      WHERE player_id = ?
    `, xp, gold, playerID);
    
    msg.say(`Caught a fish and earned ${gold} gold and ${xp} xp`);
  })

// register player
client.dispatcher.addInhibitor(msg => {

  const id = msg.author.id;
  const sql1 = `
    SELECT player_id
    FROM player
    WHERE player_id = ?
  `;
  const sql2 = `
    INSERT INTO player (player_id)
    VALUES (?)
  `;

  client.db?.get(sql1, id)
    .then(player => {
      // if user is not in the database
      if (!player) {
        // add user to the db
        client.db?.run(sql2, id);
      }
    })


  return false;
})

// prevent banned members to use the bot
client.dispatcher.addInhibitor(msg => {
  const author = msg.author.id;
  const isBanned = client.provider.get(msg.guild, `ban-${author}`);
  if (isBanned) {
    return {
      reason: "blacklisted",
      response: msg.reply("You are banned"),
    }
  }

  return false;
})

// only allow command to be run on selected channel only (which was run by
// sb!setchannel command)
client.dispatcher.addInhibitor(msg => {
  const channel = client.provider.get(msg.guild, "channel");

  if (channel && msg.channel.toString() !== channel) {
    const response = msg.reply(
      `Commands on this channel is disabled. Please use ${channel}.`
    )

    return {
      reason: "invalid channel",
      response,
    }
  }

  return false;
})

client.login("your-bot-token");

API

DiscordRPG extends Client from commando.js.

DiscordRPG#db

Returns Database instance from node-sqlite3 which you can use to execute SQL statements.

DiscordRPG#setDBFile(filename)

Creates db file if not exists, and read from the specificied file name if exists. This method returns promise which you can use to create table after connection between db and js runtime has been made.

DiscordRPG#registerCommand(commandInfo, command)

Command info is details about your command such as name. You can read more regarding commandInfo here.

Command is a function that accepts two arguments. First argument msg is an instance of Message that triggers the command- from there, you can access both Guild and Channel of where the command was executed.

DiscordRPG#registerCommand has been simplified so you can add commands without having to specify command groups and having to create a whole class.

Documentation

Finally, if you think there are missing documentation here and there you can checkout the following links:

• discord.js
• commando
• node-sqlite3