How to make your own Script


#1

This guide is intended to only show you how to get your own script started in PhantomBot. It will go over the most common events and functions that PhantomBot has built-in.


PhantomBot's Core

PhantomBot uses Rhino JavaScript to run all of its scripts. All of the scripts are codded in JavaScript (Not NodeJS). There are a lot of differences between normal JavaScript and Rhino. I would suggest reading more about Rhino if you’re coming from Node or normal web development.


PhantomBot's DataBase

PhantomBot has functions to access its database, you can find all of them over here.


PhantomBot's Events

PhantomBot has multiple events for all sorts of things, the main ones that you will probably be using are the command event and the message event.

All events can be registered with the global function known as $.bind(event, callback).

The Command Event and the Event Object

The event object is sent with every callback functions. In that object, you will find multiple methods that are created in Java before the event is sent. Some are different depending on the event that is sent.

In the command event you can find the following method (functions).

String getCommand() - This method will return the command name with the default prefix of !.
String getSender() - The name of the user who triggered the command. This is not the user’s display name.
String getArguments() - This is the string of arguments that are given after the command. It can be a blank string if none are specified.
String[] getArgs() - This is the array of arguments. Each arguments are after a space.
Map<String, String> getTags() - This method returns the IRCv3 tags.

Below you will find some examples of using the $.bind(event, callback) function with the command event.

$.bind('command', function(event) {
	// All of the default methods are stored in the event argument. You can change `event` to anything you want.
	// To access a method, in this case, you would do `event.myMethod()`.

	// We are registering all method into variables to make it easier to remember.
	var command = event.getCommand();
	var sender = event.getSender();
	var arguments = event.getArguments();
	var args = event.getArgs();

	// You do not need to add the command prefix. This is already done in the bot's core in Java.
	if (command.equalsIgnoreCase('command')) {

		// You can use the `$.say('')` function to send any message to Twitch chat.
		$.say('This is a response from my custom script!');

		// You can also use the `$.consoleLn('')` function to print messages in the bot's console.
		$.consoleLn('My custom script works!');
	}


	// Example of using the arguments and sender method.
	// This command would work as the following. `!guess [anwser]`
	if (command.equalsIgnoreCase('guess')) {

		// Note that `arguments` and `sender` was used here and not `event.getSender()`. 
		// This is because we stored them in a variable at the top of the function.
		if (arguments.equalsIgnoreCase('i love phantombot')) {
			$.say(sender + ' you guessed the correct anwser!');
		}
	}


	// Alright, let's say you only want one argument. This is where you would use the `getArgs()` method.
	// This command would work as the following. `!color [color argument]`
	if (command.equalsIgnoreCase('color')) {
		// JavaScript and most codding langs count from 0, so we want to the first argument, being 0 in the case.
		// We want to make sure the user specified something, for that we can use `!==` to make sure that `args[0]` is not undefined.
		if (args[0] !== undefined) {
			$.say('Your favorite colour is ' + args[0]);
		} else {
			$.say('Please specify your favorite colour.');
		}
	}
});

Registering Commands

PhantomBot has an event that is called after all of the scripts are loaded, the event is used to register all of the commands. Here's an example below on how to register your own command.
$.bind('initReady', function() {
	// `script` is the script location.
	// `command` is the command name without the `!` prefix.
	// `permission` is the group number. 0, 1, 2, 3, 4, 5, 6 and 7. 
	// These are also used for the permcom command.
	// $.registerChatCommand('script', 'command', 'permission');


	// Here's what it looks like.
	$.registerChatCommand('./scripts/custom/funCommand.js', 'fun', 7);
});

The Message event and the event Object

The event object is sent with every callback functions. In that object, you will find multiple methods that are created in Java before the event is sent. Some are different depending on the event that is sent.

In the message event you can find the following method (functions).

String getMessage() - This method will return the message sent in chat.
String getSender() - The name of the user who triggered the command. This is not the user’s display name.
Map<String, String> getTags() - This method returns the IRCv3 tags.

Below you will find some examples of using the $.bind(event, callback) function with the message event.

$.bind('ircChannelMessage', function(event) {
		// All of the default methods are stored in the event argument. You can change `event` to anything you want.
		// To access a method, in this case, you would do `event.myMethod()`.
	
		// We are registering all method into variables to make it easier to remember.
		var message = event.getMessage();
		var sender = event.getSender();
		var tags = event.getTags();

		// Here the bot will only respond if the message only has `candy` in it.
		if (message.equalsIgnoreCase('candy')) {
			$.say(sender + ' likes candy!');
		}

		// But what if you want to check the message for a specific keyword? Here's how you would do it the simple way.
		if (message.contains('bot')) {
			$.say(sender + ' you have to try out PhantomBot. It\'s a great bot!');
		}

		// The message event does not have the fancy `getArgs()` method, but you can do it yourself like this.
		var args = message.split(' '); // This will create an array and split it at each space in the message.

		// Here's how you can use it. Here you have the get the second argument, `(1)` because it is not a command, if you get the first `(0)`
		// You will get `candy`.

		// The bot will only reply if there is a second argument in the message.
		if (message.contains('candy')) {
			if (args[1] !== undefined) {
				$.say(sender + '\'s candy is ' + args[1]);
			}
		}
	});

The Language System

PhantomBot has a language system that allows all users to translate each bot response. Using PhantomBot's language system is super easy. There are two steps, this will guide you through them.
  1. You’ll want to make a lang script. Most of the time we name our lang files like the following:
    type_of_script_script_name.js. Here are examples: systems-raffleSystem.js, commands-customCommands.js.
  2. Once you have the lang script, you can put it in the bot’s lang folder. Now you’ll want to register lang entries, but be sure that all entries are unique so they don’t conflict with other systems. To do this, we always start the lang ID with the system’s name. All lang IDs should be lowercase and you can only use periods (.) and hyphens (-) to separate the ID string. Here’s an example: rafflessytem.open.command-usage
  • This is how it would look in the code:
    $.lang.register('rafflessytem.open.command-usage', 'reply string');
    
    If your reply string has variables from the script, you can use $1-$9 to specify them, here’s an example:
     $.lang.get('rafflessytem.open.command-usage', 'Usage: !raffle $1 and !raffle $2');
    
  1. Now to get the lang reply for that ID, you can simply use the following function in your script:

    $.lang.get('rafflessytem.open.command-usage');
    

    If your reply has variables, you can do the following from your script which is what $1-$9 will get replaced with in your reply string:

     $.lang.get('rafflessytem.open.command-usage', variableOne, variableTwo);
    

You can find the full example script here: Script.

Hopefully this guides helps you a bit. Happy coding!


Twitch - custom commands for subscribers only
Rename !adventure command
List of bindable events