Custom-Bot v3

Create your own discord bot - Fully customizable and with a lot of features. This bot is for advanced JS-Users, you should only use it if you have some experience with Javascript, discord.js and JSON files.

---

Get your own Custom-Bot completely free and with a modern webinterface and a lot more features!

Go check it out on our website or get started in the dashboard. In addition to the here available features we offer:

• Free hosting
• Custom-Commands
• Easy-to-use Embed-Editor
• Self-Roles
• Send and edit messages in specific channels
• Easy-to-use Configuration-Editor
• Human-Readable Issue Reporting - never look at logs again
• and a modern dashboard
• and a lot more - for free

Get started now - it's free - forever!

Applicable license terms if you use this bot

We really love open-source. It does not make sense financially to publish this Source-Code publicly (as our business model is to host these bots on SCNX, but we still do it. While this project does not fit the definition of Open Source set forward by the Open Source Initiative, we are committed to allowing you as much freedom as possible. Please read the license and follow it.

Here's a summary:

• You may use the bot on your server and change the source code (as long as you follow the license).
• You have to retain a link to the LICENSE and this repository in your bot, most likely in your /help command.
• All changes you make to this codebase are subject to these license terms, you cannot remove the link to the license, even if you change large parts of the bot.
• You may not create a competitor to SCNX or other ScootKit products using this source code.
• You may not use the "ScootKit" brand name or any other trademarks outside of the LICENSE notice.

Please read the full license, as the terms laid out there apply. This is not legal advice.

Failure to abide by these terms might result in deactivation of your bot from Discord or legal action being taken (but we'll act in good faith and usually try to solve the issue before doing anything drastic).

Support development

As mentioned above, our business model is to host these bots for servers - it does not really make sense to publish our product here - but we do it anyway - but we need your support! Feel free to contribute or becoming a GitHub Sponsor. Thank you so much <3

Need help?

Are you stuck? Please do not ask on our Discord (unless you are using our hosted version), instead ask in the discussions-tab.

Need something even more custom?

We are happy to give you a quote for individual requirements. Please email [email protected] with your requirements.

Table of contents

Installation
Features
Configuration
Modules
Add your own module (or API)

Installation

1. Clone this repo
2. Run npm ci
3. Run npm run generate-config
4. Replace your token in the config/config.json file.
5. Start the bot with npm start
6. The bot is now generating a modules.json and a strings.json file inside your config directory. You can change them.

When reading thought the code, you may encounter code "tracking" / "issue reporting" parts of the bot. This part is only enabled in the SCNX-Version and only used to allow users to see (configuration) issues of their bot and to allow our team to detect bugs more easily (users can opt-out of that if they want to; we use the sentry-sdk for that, but don't actually send any data to them, instead to our glitchtip instance - the open-source-version does neither of that). This open-source-version won't contact SCNX, SC Network and won't share any information with us, don't worry. You can verify this by looking at the source code, which you should do before executing any code from the internet.

Features

• Everything is split in different modules - you can enable, configure and disable it how you want
• Highly configurable - The goal with this bot is that you can change everything
• Add your own modules
• Easy configuration - Every config field has a description in an example file

Configuration

You can find all the configuration-files inside your config folder. Every enabled module will have their own folder with config-files inside them. These files are generated automatically. Every module has slightly different configuration options. Every module has example files. Inside these files are more information about every configuration option. Some config values also support embeds. This is the case if allowEmbed is true.
You either input a string (normal Discord message), or an embed object with the following values:

• title: Title of the embed
• message: Message outside the embed (optional)
• description: Description of the embed (optional)
• color: Color of the embed, must be a ColorResolvable (optional)
• url: URL of the embed (optional)
• image: Image of the embed, should be an url (optional)
• thumbnail: Thumbnail-Image of the embed, should be an url (optional)
• author (optional):
  • name: Name of the author
  • img: Image of the author, should be an url
• fields: Fields of the embed, must be an array of EmbedFieldData (optional)
• footer: Footer value (optional, default: global footer value)
• footerImgUrl: URL to image of the footer (optional, default: global footer value)

The footer of the embed is global and is defined in your global strings.json file. The timestamp is set automatically to the current time.

Modules

The bot is split in modules. Each module can register their own commands, events and even database models, so they can do basically anything. Every module can register "example-config-files" witch are files with information about the config file, so the bot can automatically check configs and do all the boring stuff for you.

Add your own modules

As per the License you have to make every of your modules publicly available under the same license. Please read the license for more information.

Before you make a module: Please create an issue with your suggestion and claim that you are working on it so nobody is working on the same thing (;
Also please read the Rules for modules.
Submit a module: Simply create a pull request, and we will check your module and merge it then (;

Rules for modules

Every module should

• Use Slash-Commands wherever possible
• Should provide a file with exported functions which other modules can use to manipulate data or perform actions in your module (eg: an economy module should provide a file with exported functions like User.addToBalance())
• Answer with ephemeral messages wherever it makes sense
• Create as few commands as possible (we have a limit to 100 commands in total), so please try to use Sub-Commands wherever possible (eg: instead of having /ban, /kick, /mute etc, have a /moderate command with sub-commands)
• Use the newest features of the discord api and discord.js (buttons, selects, etc) if possible
• Process and Store only needed user information and data
• Support localization (you don't need to translate everything, you only need to support translations, read more here
• protect sensitive slash-commands with the proper defaultMemberPermissions settings
• must comply with our end-user documentation requirements
• follow our terms of service, Discord's Terms of Service and the Discord Developer Terms of Service. A module should not allow users to bypass or break the mentioned documents. This includes but is not limited to Nitro-Only-Features.

Localization

We'd like to offer SCNX and this bot in as many languages as possible. Because of this, we highly encourage you to use translationable systems in your module.

• Localizations of not-user-editable strings: Use localize(key, string, replace = {}) from src/functions/localize.js to localize strings. Translations of these strings happen on Weblate
  • key: Key of the string (usually your module name, check out any files in locales to get an idea how this works)
  • string: Name of the string
  • replace (optional, object): Will replace %<key> in the source string by <value>
• Localizations of configuration-files and user-editable strings: All localizable configuration fields are an object with values keyed based on language codes. Example: {"description": {"de": "Beschreibung des Feldes", "en": "Description of the field"}. Each field needs to have at least an English value, as every other language will default back to English.

module.json

Every module has to contain a module.json file with the following content:

• name of the module. Should be the same as the name of your dictionary.
• humanReadableName: Localized name of the module, shown to users
• author
  • name: Name of the author
  • link: Link to the author
  • scnxOrgID: SCNX-Organisation-ID of the developer (allows you to accept donations in the dashboard and will show up to users in the dashboard)
• openSourceURL: URL to the Source-Code of the module licensed under an Open-Source-License (will show donation-banners in the SCNX Dashboard (if orgID is set) and qualifies (qualified) developers for financial support from the Open-Source-Pool of SCNX)
• description: Localized short description of the module
• cli (optional): CLI-File of your module
• commands-dir (optional): Directory inside your module folder where all the interaction-command-files are in
• on-load-event (optional): File with exported onLoad function in it. Gets executed when your commands got loaded successfully; at this point the Client is not logged in yet, so you can't communicate with Discord (yet).
• events-dir (optional): Directory inside your module folder where all the event-files are in
• models-dir (optional): Directory inside your module folder where all the models-files are in
• config-example-files (optional, seriously leave this out when you don't have config files): Array of config-files inside your module directory.
• tags (optional): Array of tags.
• fa-icon: Used for matching of icons in our dashboard. We will fill this out for you, please do not set this field.

Interaction-Command

Note: Interaction-Commands get loaded after the configuration got checked.
An interaction-command ("slash command") file has to export the following things:

• run (function; provided arguments: interaction):
  • Without subcommands: Function that gets triggered if the interactions is being used
  • With subcommands: Optional function that gets triggered after the subcommand functions (if specified) got executed
• beforeSubcommand (optional, only if subcommands exit): Function which gets executed before the function in subcommands gets executed
• autoComplete (only required if any of your options use autocomplete): Object of functions, sorted by subcommandgroup, subcommand and option name
• subcommands (only required if subcommands exist): Object of functions, sorted by subcommandgroup and subcommand
• help
• config (both for !help and slash-commands)
  • name: Name of the command (should be the same name as the file name)
  • description: Description of the command
  • restricted: Can this command only be run one of the bot operators (e.g. config reloading, change status or ..., boolean)
  • defaultMemberPermissions: This will determine which users can use your commands by default - leave null (or undefined) to allow usage by @everyone, otherwise, use PermissionsResolvable.
  • options:
    • ApplicationCommandOptionData OR
    • Async function returning ApplicationCommandOptionData ( gets called with client as argument)

Message-Command

Starting V3, message-commands are no longer supported. Please use Interaction-Commands instead. Read more in CHANGELOG.md.

Events

An event file should export the following things:

• run: Function that gets triggered if the event gets executed (provided arguments: client (discord.js Client) and all the arguments that gets past by discord.js for this event)
• allowPartial (optional, default: false): Boolean determining whether the run function should be called if the event has partial structures. When enabling, please make sure you handle partial data correctly.

CLI-Files

A CLI-File should export the following things:

• commands: Array of the following objects:
  • command: Command which should be entered in the CLI
  • description: Description of the command
  • run: Function which should be executed when the command gets executed. The function gets executed with an object of following structure as argument:
    • input: The whole input
    • args: Array of arguments (split by spaces)
    • client: Client
    • cliCommands: Array of all CLICommands

Note: We might allow users to execute CLI-Commands via the Dashboard in the future. This is not supported right now.

Config-Elements

Certain configuration may contain an array of multiple objects with different values - these are called " Config-Elements".

To add a new Config-Element to your configuration use node add-config-element-object.js <Path to example config file> <Path to your config-file>.

Example config-file

An example config file should include the following things:

• filename: Name of the generated config file
• humanname: Localized name of the file, shown to users
• description: Localized description of the file, shown to users
• configElements (boolean, default: false): If enabled the configuration-file will be an array of an object of the content-fields
• elementLimits (optional, if configElements = true): Configuration to limit the amount of configuration elements that guilds with a specific plan
• commandsWarnings: This field is used to indicate, that users need to manually set up the permissions for commands in their discord-server-settings
  • normal: Array of commands which that can be configured without any limitation in the discord-server-settings
  • special: Array of commands that need special configuration in addition to editing the permissions in the server-settings
    • name: Name of the command
    • info: Key by language; Information about the command; used to explain users what exactly they should do
• content: Array of content fields:
  • field_name: Name of the config field
  • default: Localized default value of this field
  • type: Can be channelID, userID, imgURL, select, timezone (treated as string, please check validity before using), roleID , boolean, integer, array, emoji, keyed (codename for an JS-Object) or string
  • description: Localized description of this field
  • humanname: Localized name of this field show to users
  • allowEmbed (if type === array, keyed or string): Allow the usage of an embed (Note: Please use the build-in function in src/functions/helpers.js)
  • content (if type === array): Type (see type above) of every value
  • content (if type === channelID): Array of supported ChannelTypes ( default: ['GUILD_TEXT', 'GUILD_VOICE', 'GUILD_CATEGORY', 'GUILD_NEWS', 'GUILD_STAGE_VOICE']). To improve user experience, we recommend adding information about supported types into description. The bot will verify that the channel is inside the bot's guild.
  • content (if type === select): Array of the possible options
  • content (if type === keyed):
    • key: Type (see type above) of the index of every value
    • value: Type as string (see type above) of the value of every value
  • params: (if type === string, array, optional) Possible parameters
    • name: Name of the parameter (e.g. %mention%)
    • description: Localized Description of the parameter (e.g. Mention of the user)
    • isImage: If true, users will be able to set this parameter as Image, Author-Icon, Footer-Icon or Thumbnail of an embed (only if allowEmbed is enabled)
  • allowNull (default: false, optional): If the value of this field can be empty
  • disableKeyEdits (if type === keyed): If enabled the user can not edit the keys of the object
  • elementToggle (if type === boolean): If this option gets turned off, other fields of the config-element / file will not be rendered in the dashboard
  • dependsOn (a name of any (other) boolean-field): If the referenced boolean field (the value of this option should be equal to the field.field_name of a boolean field) is turned off, the field will be not be rendered in the dashboard
  • links (optional): Array of links displayed below the field description in the SCNX Dashboard
    • label: Localized label of the link displayed to the user
    • url: URL the user will be redirected to on click

botReady-Event and Config-Reload

If you plan to use the ready event of discord.js to run some action when the client is ready, and you need to load some configuration-files you should use the botReady-event instead. Please remember that this event gets re-emitted on configuration reloading. If you set callbacks that get executed later or similar please remember to remove them on configReload. If you set intervals, please push the return value to client.intervals to get them removed on configReload or do it manually.

Helper-Functions

The bot includes a lot of functions to make your live easier. Check out the file src/functions/helpers.js.

Support for developers

As we earn some money with hosting your modules for users, we have decided to give you some (remember, we need to pay for hosting) of this money. Here are the main ways to earn some pocket-cash with developing for SCNX:

• Open-Source-Developer-Pool: We give you a monthly amount for each paying server using your module
• Bounties: We give you a small amount of money for merged pull-requests and contributions We support a lot of payout-methods, learn more here.

© Simon Csaba, 2020-2023

ScootKit is a trademark, registered in Germany.

We ♥ you - yes you.