Modifying a Stock PhantomBot Module


#1

This guide aims to help those that customize scripts that exist within the PhantomBot stock distribution and speed up their upgrade migration time and reduce errors during upgrades.

Disable the PhantomBot Stock Script (Module)
Disable the module in PhantomBot that you wish to make a copy of. This way, when you start up PhantomBot with your customized copy of the script, the original is already disabled and you do not run into command conflicts. As a general reminder, below is how to disable the module:

To disable a module from chat:
!module disable ./path_to/script.js

To disable a module from the Console:
module disable ./path_to/script.js

To disable a module from the Control Panel:
Locate the Module in the Dashboard > Twitch Modules configuration tab and click the open circle icon to disable.

Make a Copy of the Script
Place a copy of the script that you are going to modify into the scripts/custom directory.

Configure the Script to Function from the Custom Directory
There are some minor changes to be made to a script once copied to the scripts/custom directory. In the initReady section of the script, the path for the isModuleEnabled() and registerChatCommand() method calls must be updated to point to the new path of the script. Here is an example using the quoteSystem.js file:

Original values will look like:

    /**
     * @event initReady
     */
    $.bind('initReady', function() {
        if ($.bot.isModuleEnabled('./systems/quoteSystem.js')) {
            $.registerChatCommand('./systems/quoteSystem.js', 'quotemodetoggle', 2);
            $.registerChatCommand('./systems/quoteSystem.js', 'searchquote', 7);
            $.registerChatCommand('./systems/quoteSystem.js', 'addquote', 2);
            $.registerChatCommand('./systems/quoteSystem.js', 'addquotesilent', 1);
            $.registerChatCommand('./systems/quoteSystem.js', 'delquote', 2);
            $.registerChatCommand('./systems/quoteSystem.js', 'delquotesilent', 1);
            $.registerChatCommand('./systems/quoteSystem.js', 'editquote', 2);
            $.registerChatCommand('./systems/quoteSystem.js', 'quote');
            $.registerChatCommand('./systems/quoteSystem.js', 'quotemessage', 1);
        }
    });

This will need to be updated in the scripts/custom directory like so:

    /**
     * @event initReady
     */
    $.bind('initReady', function() {
        if ($.bot.isModuleEnabled('./custom/quoteSystem.js')) {
            $.registerChatCommand('./custom/quoteSystem.js', 'quotemodetoggle', 2);
            $.registerChatCommand('./custom/quoteSystem.js', 'searchquote', 7);
            $.registerChatCommand('./custom/quoteSystem.js', 'addquote', 2);
            $.registerChatCommand('./custom/quoteSystem.js', 'addquotesilent', 1);
            $.registerChatCommand('./custom/quoteSystem.js', 'delquote', 2);
            $.registerChatCommand('./custom/quoteSystem.js', 'delquotesilent', 1);
            $.registerChatCommand('./custom/quoteSystem.js', 'editquote', 2);
            $.registerChatCommand('./custom/quoteSystem.js', 'quote');
            $.registerChatCommand('./custom/quoteSystem.js', 'quotemessage', 1);
        }
    });

These changes inform the PhantomBot module handler as to the new custom module and links all commands to this new custom module.

You will also copy the language file from scripts/lang/english/path_to/lang-script.js to scripts/lang/custom/lang-script.js so that you may make any specific updates. If you are not changing the language file, then there is no need to peform this step.

Loading the Custom Script
You will need to restart PhantomBot once you are done with your changes to the script or you have made changes that you wish to test. You should always restart when placing a brand new script into the PhantomBot script directory heirarchy.

If you are planning on making multiple changes, it is recommended to enable script reloading in PhantomBot during your development – it is recommended to disable this again when you are ready for production (live) use. In the botlogin.txt file, add the following new line:
reloadscripts=true

This directive will request that PhantomBot reload a script if it is modified and saved. Do not that some scripts that use timers (setInterval() method is used) may experience issues as multiple timers may be started. Please exercise caution in this instance.

There is another option you may use in the botlogin.txt to launch the Rhino Debugger for debugging the JavaScript modules. Note that this will require that you are running PhantomBot locally or, in the case of a Linux VPS that you have enabled Xwindow forwarding and have a Xwindow client running locally. Add the following new line to try to enable the Rhino Debugger:
rhinodebugger=true

The following provides a high level overview of how to use the Rhino Debugger:

https://community.phantombot.tv/t/phantombot-rhino-debugger-interface/451

Enable the Custom Script
Just as you disabled the original script, you will enable the new script, again a refresher:

To enable a module from chat:
!module enable ./custom/script.js

To enable a module from the Console:
module enable ./custom/script.js

To enable a module from the Control Panel:
Locate the Module in the Dashboard > Twitch Modules configuration tab and click the filled-in circle icon to enable.

Development Tools
One of the easiest ways to improving your development experience is a quality development environment. For JavaScript you will need a text editor, below are three of the best.

You may have wondered why there is no direct guide for making a module for PhantomBot. This is due to the fact that you must know JavaScript to truly develop your own module. Once you know JavaScript you will be able to look at existing modules to figure out the specifics related to PhantomBot. If you need help with the latter we will generally point you in the right direction, but will not code your module for you.

Learn JavaScript
Please note that PhantomBot uses Rhino JS, not Node JS or the more traditional implementations utilized for Web Development. There are some nuances that are specific to Rhino JS that way be different than the guides below, but that does not mean they are not good resources to learn.


Upgrading bot with modifications
Seeking Guidance on a Counting Code
Developing using vs code
Error message: onEvent()@ScriptEventManager.java:79, since latest bot update
Making changes persist through updates