Neptune: Planet or Myth?

    @tmware/status-rotate
    TypeScript icon, indicating that this package has built-in type declarations

    1.2.10 • Public • Published

    Status Rotate

    Status Rotate lets you manage the presence status of your Discord Bot easily. Supports any discord.js based bots, including discord-akairo or discord.js-commando.

    Features

    • [x] Customize selection of status messages/activities (details)
    • [x] Variable support (i.e. show how many servers your bot has) (details)
    • [x] Web-based status message lists (details)
    • [x] Periodically update the status (details)

    Table of Contents

    Getting Started

    Installation

    With npm: npm install --save @tmware/status-rotate

    With yarn: yarn add @tmware/status-rotate

    Usage

    Q: Help, I don't want to read all this, can you show me how this looks in code?

    A: Yes. See lines 81 and 82, 141

    Creating an instance of the status rotator:

    const { Client } = require('discord.js')
    
    const StatusUpdater = require('@tmware/status-rotate')
    
    const bot = new Client({
      /* client options... */
    })
    
    const Updater = new StatusUpdater(bot)

    You can of course attach the rotator to your Discord client

    bot.statusUpdater = new StatusUpdater(bot)

    Passing status messages

    You can pass an array of possible status messages when creating the rotator,

    const statusMessages = [
      { type: 'PLAYING', name: 'with my banhammer' },
      { type: 'LISTENING', name: 'you' }
    ]
    
    const Updater = new StatusUpdater(bot, statusMessages)

    or you can add single messages afterwards

    Updater.addStatus({ type: 'PLAYING', name: 'in the sandbox' })

    Actually using the Rotator

    You now know a bit about adding status messages (more on custom variables and online status files later), here's how to actually use them.

    Updater.updateStatus()

    Will choose, at random, one of the statuses that are available (the ones you added on initializing and with .addStatus()) and apply it.

    If you want to set a specific status that isn't random, you can use

    Updater.updateStatus({
      type: 'WATCHING',
      name: 'a sports game.'
    }) /* optionally, you can append a shard id */

    More advanced examples

    The section above only featured some very basic things status rotate can do. In the following you will learn how to automate status updates (update every n minutes) and how you can use values like your bot's guild count in these status messages.

    Automating Status Updates

    If you want to have such an update done every once in a while, for example every 10 minutes, use the .start() method

    Updater.start(10 * 60 * 1000) // Delay of 10 minutes in milliseconds

    This will set up an interval of the given delay (ten minutes in this case).

    Use .stop() to stop the automatic updates:

    Updater.stop()

    This will clear the interval.

    If you aren't satisfied with the level of control this gives you, you can adapt the behaviour below to your needs

    bot.setInterval(
      () => Updater.updateStatus(),
      10 * 60 * 1000
    ) /* the second argument is the time in milliseconds */

    This can be combined with the event emitter

    // Listen for an event 'updateStatus', update the status when it occurs
    bot.on('updateStatus', () => Updater.updateStatus())
    
    // Every 10 minutes, emit such an event
    bot.setInterval(() => bot.emit('updateStatus'), 10 * 60000)

    Note: This technique can be used to execute a status update when the bot becomes ready.

    bot.once('ready', () => {
      /* your other code ... */
      bot.emit('updateStatus')
    })

    Using Variables

    For now, you've only seen static status messages (i.e. they don't depend on some variable, like your bot's guild count), but this is the advanced section so we'll learn how to do that as well.

    First, let's make a new Updater, that has only messages that depend on variables

    const statusMessages = [
      { type: 'PLAYING', name: 'with {users} users' },
      { type: 'LISTENING', name: '{users} users' },
      { type: 'WATCHING', name: 'over {users} users' },
      { type: 'PLAYING', name: 'in {guilds} servers' },
      { type: 'PLAYING', name: '{prefix}help for help' },
      { type: 'WATCHING', name: '{guilds} servers' }
    ]
    
    const Updater = new StatusUpdater(bot, statusMessages)

    For more information on the under-the-hood workings of variables, see @tmware/variable-parser.

    What you need to know

    • Variables are identified (by default, yes you can change that), by strings in singular curly braces: {someString}
    • Before a variable can be parsed (replaced by it's value), you must define that variable.

    Defining and updating variables:

    Updating and defining variables works exactly the same way. Using the .updateParserData() method, you pass an Object containing keys (which are the variable names) and values. This will merge the existing data (by default no data), with the Object you passed, keeping all existing data and only adding or overwriting key-value pairs you defined.

    Updater.updateParserData({ key: 'value' })

    Actually useful example: adding current data to your Updater

    Updater.updateParserData({
      users: bot.users.cache.size,
      guilds: bot.guilds.cache.size,
      channels: bot.channels.cache.size
    })

    Since these values are not updated automatically, you should implement such a routine (see Automating)

    Web-based status messages

    If you want to keep your status messages out of your code, maybe you want to keep your code cleaner, or not produce so many changes just because you want to update your status messages, you can upload a JSON formatted file to the internet and have status rotate take care of the rest.

    I recommend creating a GitHub Gist, but a file on Pastebin or similar will do just as well.

    Example file, so you can see how to format this.

    Using this in your code: instead of an array of statuses, pass a url to the file when initializing the Updater

    const Updater = new StatusUpdater(
      bot,
      'https://gist.githubusercontent.com/TMUniversal/253bd3172c3002be3e15e1152dd31bd4/raw/exampleFile.json'
    )

    You may also pass a url after the StatusUpdater has been initialized

    Updater.setStatusFileUrl(
      'https://gist.githubusercontent.com/TMUniversal/253bd3172c3002be3e15e1152dd31bd4/raw/3c9a2eeb9a79c0b999942e761b11838acb71d89f/exampleFile.json'
    )

    Note that this will not fetch any data. The .refetchOnlineData() method is used to do this:

    Updater.refetchOnlineData()

    Will (re-)fetch the previously given file, overriding the old data.

    If you want the new data to be added to the old instead, supply a truthy additive argument (defaults to false)

    Updater.refetchOnlineData(true)

    Lastly, .setStatusFileUrl() and .refetchOnlineData() can be chained together:

    Updater.setStatusFileUrl(
      'https://gist.githubusercontent.com/TMUniversal/253bd3172c3002be3e15e1152dd31bd4/raw/3c9a2eeb9a79c0b999942e761b11838acb71d89f/exampleFile.json'
    ).refetchOnlineData()

    Author

    👤 TMUniversal

    Contributing

    Contributions, issues and feature requests are welcome!
    Feel free to check issues page. You can also take a look at the contributing guide.

    Show your support

    Give a ⭐️ if this project helped you!

    License

    Copyright © 2020 - 2021 TMUniversal.
    This project is MIT licensed.

    Install

    npm i @tmware/status-rotate

    DownloadsWeekly Downloads

    96

    Version

    1.2.10

    License

    MIT

    Unpacked Size

    32.7 kB

    Total Files

    7

    Last publish

    Collaborators

    • tmuniversal