Functions

This is a list of functions included with the bot, along with their parameters, a description of what they do, and when they should be invoked.

##output ####Sample Call output({text: 'Rainbow Dash is best pony.', destination: 'speak'});

####Parameters text - The text that the bot will write to an output channel.

destination - Which output channel the bot should use - currently, this can be speak for chat or pm for PM.

userid - (Optional) For PM responses, tells which user to send the response to.

####Description This function writes output to an output channel.

##admincheck ####Sample Call admincheck(userid);

####Parameters userid of the user.

####Description This function checks if the given userid is allowed to execute mod-restricted functions of the bot. This function returns true if the user is a bot admin or room moderator, and false otherwise.

##reptarCall ####Sample Call bot.speak(reptarCall());

####Parameters None.

####Description This function returns a random variant of "rawr!"

##addToDb ####SampleCall addToDb();

####Parameters None.

####Description This function writes a new entry to the SONG table with the values of the currentsong object. It is designed to run at the end of a song play in a TT.fm room.

##welcomeUser ####Sample Call welcomeUser(data.name, data.userid);

####Parameters name of the user joining

id of the user joining

####Description This function says a welcome message in chat for a user. It ignores ttdashboard bots. The function first checks if it is a holiday (as per the holiday_greetings table), and displays that greeting if it is found. Otherwise, the generic greeting from the config.json file is used.

##enforceRoom ####Sample Call enforceRoom();

####Parameters None.

####Description Reminds a user that has just played their final song that they need to step down, and removes them from the stage if they do not step down.

##reducePastDJCounts ####Sample Call reducePastDJCounts(djid);

####Parameters djid - The userid of the current DJ

####Description Decrements the current DJ's song count by 1. If they need to step down (their songs remaining is 0), sets userstepped and usertostep so the bot can remove them. This function also reduces the song count of DJs that must wait to step up, and removes them from the past DJs list if this value reaches 0.

##addToPastDJList ####Sample Call addToPastDJList(userid);

####Parameters userid of the user to add to the past DJ list.

####Description This function runs when a user steps down after playing their max number of songs. It adds them to the past DJ list, initialized with the amount of time they must wait before trying for a spot again.

##addToWaitlist ####Sample Call addToWaitlist(userid, name, source);

####Parameters userid of the user adding themselves to the waitlist.

name of the user adding themselves to the waitlist.

source - How the user contacted the bot to be added (speak/pm).

####Description This function attempts to add a user to the waitlist/queue, if enabled. It will not allow users who are DJing or already on the list to add themselves to the waitlist.

##checkStepup ####Sample Call checkStepup(userid, name);

####Parameters userid of the user trying to step up

name of the user trying to step up

####Description This function checks if a user is allowed to step up. The bot will remove the user if they are not following the enforcement rules - if they didn't wait long enough to step up after DJing.

##checkWaitlist ####Sample Call checkWaitlist(userid, name);

####Parameters userid of the user trying to step up

name of the user trying to step up

####Description This function checks if a user is allowed to step up, if waitlist is enabled. The user will only be allowed to DJ if they are first on the waitlist or the waitlist is empty.

##getTarget ####Sample Call getTarget();

####Parameters None.

####Description Used for bonus awesoming. This function returns the number of "bonus" messages that must be said to the bot for the bot to awesome a song.

##getVoteTarget ####Sample Call getVoteTarget();

####Parameters None.

####Description Used for bonus awesoming. This function returns the number of awesomes needed for the bot to awesome a song.

##canUserStep ####Sample Call canUserStep(name, userid);

####Parameters name and userid of the person that wants to know if they can step up

####Description This function returns a text response telling a user if they can step up to DJ or not, based on what room rules are set in the room.

##handleCommand ####Sample Call handleCommand(name, userid, text, source);

####Parameters name and userid of issuing user, text of message, source of message (speak/pm).

####Description This function handles commands sent to the bot.

##initializeModules ####Sample call initializeModules();

####Parameters None.

####Description This function sets up the Node.JS modules used by the bot. The function attempts to load the ttapi, mysql, request, and xml2js Node modules. If database usage is enabled, this function starts a MySQL database connection (if the connection can't be established, the bot will continue running, but with database functionality disabled). This function also creates TCP and HTTP listeners (if enabled), and loads chat and HTTP commands from the commands/ and api/ folders in the project directory. This function should only be invoked by sparkle.js on launch.

##setUpDatabase ####Sample Call setUpDatabase();

####Parameters None.

####Description This function creates the SONG, CHAT, and USER tables if they do not exist. This function should only be invoked by sparkle.js on launch.

##populateSongData ####Sample Call populateSongData();

####Parameters data - A JS array provided by Turntable.fm containing a room field, containing a metadata field.

####Description This function populates the currentsong object with data from Turntable.fm on a roomChanged event.