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 to run all of its scripts. All of the scripts are codded in JavaScript. 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).

getCommand() - This method will return the command name with the default prefix of !.
getSender() - The name of the user who triggered the command. This is not the user’s display name.
getArguments() - This is the string of arguments that are given after the command. It can be a blank string if none are specified.
getArgs() - This is the array of arguments. Each arguments are after a space.
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).

getMessage() - This method will return the message sent in chat.
getSender() - The name of the user who triggered the command. This is not the user’s display name.
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]);
			}
		}
	});

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