Developer Building Games In Firebot V5

Overview

In Firebot v5.13.0, a new game system was introduced, allowing us to easily define new game types. This page details how to create them.

The Game definition model

Here's how to define a game in code:

/**
 * @type {import('../../game-manager').FirebotGame}
 */
module.exports = {
    id: "", // unique id for the game
    name: "", // human readable name for the game
    subtitle: "", // very short tagline for the game, shows up in the games tab
    description: "", // verbose description of the game, shown when clicking edit on the game
    icon: "", // Font Awesome 5 icon to use for the game
    settingCategories: {}, // definition of setting categories and the settings within them (more on this below)
    onLoad: gameSettings => {}, // this is called when the game is enabled, either on app load or if the user enables the game later. You can register a system command here or set up any required game state.
    onUnload: gameSettings => {}, // this is called when the game was previously active but has since been disabled. You should unregister any system commands here and clear out any game state.
    onSettingsUpdate: gameSettings => {} // this is called whenever the settings from settingCategories are updated by the user
};

To register your game with Firebot, simply add it to the loadGames() method in builtin-game-loader.js

To have IntelliSense for the game definition object within VS Code, simply add the following above your game def object (same as example above). Just make sure the path to game-manager is correct.

/**
 * @type {import('../../game-manager').FirebotGame}
 */

settingCategories

The Why

Inspired by the "parameters" in the Custom Scripts feature, you can define all the settings you need for your game without needing to create and manage any frontend code or HTML. This has a number of benefits:

1. Easier to implement and maintain
2. Keeps UI consistent
3. The frontend can be swapped out or updated in the future without needing to update the game definition

The How

Example

Here is an example settingCategories object:

settingCategories: {
    currency: { // this is the "id" of the category, you use this to reference later
        title: "Currency Settings", // human readable title (required)
        description: null, // human readable description, this is put in parenthesis next to the title (optional)
        sortRank: 1, // angular is inconsistent at rendering object properties in the same order, this property allows you to explicitly specify the how you want your categories ordered. (optional)
        settings: { // object containing all the settings within this category
            minWager: { // this is the "id" of the setting, you use this to reference later
                type: "number", // this determines what UI element is rendered on the front end. The different types detailed below
                title: "Min Wager Amount", // human readable title (optional)
                description: "The minimum a user can wager", // human readable description (optional)
                placeholder: "Enter amount", // placeholder in the input field (if type is text or number) (optional)
                tip: "Optional", // human readable tip, this is rendered below the field in smaller, muted text (optional)
                default: 1, // the default value that is set for the first time (optional)
                sortRank: 2, // same purpose as the sortRank at the category level, lets you define your settings display order
                showBottomHr: true, // if you want to show a line under this setting to separate it more from the next (optional)
                validation: { // (optional)
                    required: false, // if true, user cant save game settings unless this setting has a value (optional)
                    min: 0, // only when 'type' is 'number', user cane save unless value is >= min (optional)
                    max: null // only when 'type' is 'number', user cane save unless value is <= max (optional)
                }
            }
    },
}

Setting Types

Current Types

• "string" - input field that allows any text
• "number" - input field that allows only numbers
• "boolean" - checkbox
• "enum" - a dropdown with preset options
• "filepath" - a file picker, you can include options to limit the type of file that can be picked
• "currency-select" - a specialized dropdown that displays saved currencies
• "chatter-select" - a specialized dropdown that displays available accounts, defaults to bot if its available
• "editable-list" - a user editable array of strings (this could be upgraded to support only numbers too)
• "role-percentages" - a specialized type that lets the user define percentage value (via a slider) per user role type (ie subs or mods), with a fallback "everyone" value for anyone that doesnt have the other roles
• "role-numbers" - similar to "role-percentages" but instead of a percentage sliders, it's number input fields

Note: Each type can have various different properties. To know what properties a type has, look at current examples (in slots & heists) to see what those may be or ask ebiggz!

Creating New Types

If none of the current setting types work for what you need and you want to define a new bespoke type, take a look at commandOption.js in the front end to see how to define a new one. Please feel free to ask ebiggz too!

Accessing Settings

The three game methods (onLoad, onUnload, and onSettingsUpdate) all have a gameSettings object passed to them as the first argument. It looks like this:

{ 
    active: true; // whether or not the game has been enabled by the user
    settings: {}; // settings object containing all saved setting values
}

You can access a setting in the settings object like so:

settings.categoryId.settingId

For example, to access the minWager setting from the example earlier, you would do:

const minWager = gameSettings.settings.currency.minWager;

You can also grab settings for your game directly from the Game Manager, like so:

const gameManager = require("./game-manager"); // make sure your path to game-manager is correct
const yourGameSettings = gameManager.getGameSettings("YOUR_GAMES_ID");