Custom Commands

From Vivbot
Jump to: navigation, search

Custom commands can be used to quickly relay long messages in chat. Vivbot can also automatically use these commands in specified intervals. Custom Commands can be enabled or disabled in the Settings Tab. There are two way of creating and managing custom commands. First through the commands tab on Vivbot's dashboard. The second is though commands entered into chat.

Commands Tab

The commands tab can be located in the Vivbot's dashboard. To create a new command, enter the desired trigger text and press "Add new command". You can additionally select a premade template to create a command from that template.

Below, you see a table of all commands that currently exist. Each command has the following properties: ID, Command, Response, Permission, Rank, Cost, Cooldown, Repeat Frequency and Delete.

Further down, there is a quick access panel for settings related to commands.

ID

The permanent id of the command. Can be used to reference the command when trying to make changes.

Trigger

This is the text that triggers the command.


VERY IMPORTANT NOTE: After the command overhaul, commands are no longer required to start with "!". If you want to have your command starting with "!", make sure to include it. Additionally, command trigger can now contain spaces. This column can be edited.

Response

The text Vivbot responds with when the command is triggered. If the response is empty, Vivbot doesn't respond with anything.

Permission

This column determines the privilege required to trigger the command. The dropdown menu has 3 options: Viewer, Mod, Owner. Default is Viewer.

Rank

This column determines the rank required to trigger the command. The dropdown has the ranks used in your channel.

If you modify rearrange the ranks, custom commands will use the rank of the same level as the rank before.

Cost

This determines how much of your currency is required to use a command. After the command is used, the cost will be removed from a User's currency count. The default is set to 0.

Cooldown

This determines how many seconds must pass in between each use of the command. Measured in seconds. This is useful to avoid viewers from spamming certain commands.

Repeat frequency

How frequently the command is automatically repeated. The default value is 0, meaning that the command is not automatically repeated.

For a more detailed explanation and on how to use this, see Auto Repeating.

Delete

This button will Delete the command. This cannot be undone! Make sure you really want to delete the command before you do so.

Commands

In addition to the Commands tab, custom command can also be created through in chat commands. If the command trigger contains a space, the only way to modify the command through chat is to use the command ID.


Moderator Commands

Creates a command. The response text is what Vivbot will say in chat when the command is used. This can be as long or as short as you want, and can be changed freely.

Note: For commands with trigger containing spaces, use command ID to modify them.

!command add [trigger/ID] [response]

Change the text that triggers the command. This can be thought as renaming the command.

!command settrig [current trigger/ID] [new trigger (can contain spaces)]

Deletes the command. This cannot be undone!.

!command delete [trigger/ID]

Change the response text of an existing command.

!command settext [trigger/ID] [response text]

Change the minimum privilege of an existing command.

!command setperm [trigger/ID] [viewer|mod|owner]

Change the cost (in coins) of an existing command. After the command is used, the cost will be removed from a User's currency count. Default is 0.

!command setcost [trigger/ID] [cost number]

Change the cooldown of an existing command. Cooldown disables this command after being called, for x seconds. Default is 0.

!command setcooldown [trigger/ID] [cooldown number in seconds]

!command setrepeat [trigger/ID] [repeat frequency]

Auto Repeating

Auto repeating is now much simpler. Vivbot will automatically send a command every X seconds and (optionally) every Y chat lines.

Vivbot will until the time delay and chat lines delay are fulfilled, and send the next command.

The next command selected depends on the frequencies set for commands.

Frequency is how often the command will be repeated relative to other commands. Set frequency to 1 or higher to make the command auto-repeat. Maximum frequency is 100.

Example

Command A has frequency 1. Command B has frequency 3.

The auto-commands will be sent in the following order:

A -> B -> B -> B -> A -> B -> B -> B -> A...

The higher the frequency the more often the command will appear relative to other commands.


Settings

There are two settings that control how often auto-repeat commands appear.

Delay in seconds

How long to wait between sending auto-repeat commands.

Delay in chat lines

Optional additional delay in chat lines. Naturally, setting this to 0 will make it a non-factor.

Global Wildcards

Wildcards allow you to insert simple global information into the response of a custom command. Global means that it's the same regardless of the command that uses the wildcard.

Wildcards are denoted with * before and after the name of the wildcard.

Example usage (assuming you are playing CS:GO):

Command: Currently playing: *game*

Result: Currently playing: Counter Strike: Global Offensive

Incorrect wildcards are ignored. For example:

Command: Currently playing: *gaemm*

Result: Currently playing: *gaemm*

Available Global Wildcards

Wildcard Response
uptime_hours Hours that stream has been live
uptime_minutes Minutes that stream has been live
uptime_seconds Seconds that stream been been live
is_live Is the stream currently live (true/false). Can be used in $if() and $ifelse().
channel The name of your channel. (Also your username)
followers Number of followers of your channel
viewers Number of viewers your stream currently has
game The name of the game you're streaming
title The title of your stream
curr_single The singular name for currency (Default: coin)
curr_plural The plural name for currency (Default: coins)

Local Wildcards

Local Wildcards work similarly to global wildcards, but instead it refers to the stuff related to the particular command.

Call data has a different syntax. It begins with { and ends with }

Example: {user}

will return the name of the user who triggered the command.

Available Local Wildcards

Call argument Response
{user} Returns the name of the user who triggered the command
{count} Returns the number of times the command has been used.

Call Parameters

Call parameters are a type of local wildcards.

The following explanation will use this scenario throughout:

There is a command named !test

A user triggered the command by sending this message in chat: !test jimmy a flyswatter

We want to use the additional stuff the user said.

The input is split into parts by space and numbered starting from 1.

Parameter 1 Parameter 2 Parameter 3
jimmy a flyswatter

To access these parameters, simply use the number of the parameter as the local wildcard.

{1} will return jimmy


Adding a + after the number will return the parameter and every parameter after that.

{1+} will return jimmy a flyswatter

Adding a ? before the number will make Vivbot ignore this parameter if it's not set.

Without the ?, {?5} will make the command fail and respond with an error. However, with ? it will simply be ignored.

You can match ? and + together.

If the response of the "!slap" command is set to Vivbot slaps {1} with {2+}!

The result of calling the command will be: Vivbot slaps jimmy with a flyswatter!


Summary

  • n is a number ranging from 1 to 20
Call argument Response
{n} Returns n-th argument passed to the command. If n-th argument doesn't exist, the command exists with an error.
{n+} Returns all text starting from the position of n-th argument.
{?n} Returns n-th argument. If n-th argument doesn't exist, returns nothing.
{?n+} Returns all text starting from the position of n-th argument. If n-th argument doesn't exist, returns nothing.

Functions

Functions are similar to wildcards in how they work, but they are more powerful and more complicated.

Unlike wildcards, functions can perform actions and accept input. We will refer to that input as "arguments".

All functions follow this syntax:

$function_name(argument1) for functions with 1 argument.

$function_name(argument1::argument2) for functions with 2 arguments.

$function_name(argument1::argument2::argument3) for functions with 3 arguments and so forth.

Examples

$curr(vivec28)

Will return the amount of currency user named vivec28 has.


$rnd_num(1::10)

Will return a random (integer) number ranging from 1 to 10 (both inclusive).


Some functions can also perform actions. For example:

$add_curr(vivec28::20)

Will add 20 currency to user named vivec28. Also, unlike the previous examples, this function does not return any text, so it can be used without it messing up the response of the command.


Function list

Function Description
$curr(username) Returns the currency balance of the specified user
$tp(username) Returns the time points of the specified user
$cp(username) Returns the chat points of the specified user
$hours(username) Returns how many hours the specified user has watched the stream for
$xp(username) Returns the XP the specified user has
$xp_next(username) Returns the XP the specified user needs to reach next level
$rank(username) Returns the rank of the specified user
$level(username) Returns the level of the specified user
$math(expression) Evaluates a mathematical expression and returns a number. Allowed operators: addition (+), subtraction (-), division (/), multiplication (*), exponent (^). Also supports brackets for order of operations. The command returns an error if the expression is invalid (Psst, don't divide by 0)
$has_curr(username::amount) Returns whether or not the specified user has the specified amount of currency (true/false). Can be used in $if() and ifelse()
$rem_curr(username::amount) Removes the specified amount of currency from the specified user. Can make the user's balance go into the negative. Returns nothing
$add_curr(username::amount) Adds the specified amount of currency to the specified user. Returns nothing
$rnd_num(min::max) Returns a random integer number ranging from the specified min (inclusive) and max (inclusive)
$tset(key::value) Stands for temporary set. Stores a value with the associated key, for use somewhere else in the command. The storage only persists for the duration of command evaluation
$tget(key) Returns the value that was previously set with $tset(). The command will return an error if there is no value stored for the key
$fmt_curr(amount) Returns a the number of currency properly appended with singular or plural currency name

Special Functions

There are four functions that work differently from others. They are:

  • $if(condition::outcome_if_true)
  • $ifelse(condition::outcome_if_true::outcome_if_false)

Unlike all other functions $if() and $ifelse() will not evaluate their arguments before evaluating themselves. This is important if you want to have action performing commands inside


Example

$ifelse(*is_online*::The stream is online::The streamer will probably be back tomorrow!)

If the *is_online* is true, the function will return "The stream is online". If it's false, the function will return "The streamer will probably be back tomorrow!".

Conditions

The condition follows a very similar syntax to most programming languages.

Firstly, text true will always be evaluated as true, and text false will always be evaluated as false.

The condition can perform number and text comparisons.

Number comparing

Operator Explanation
A == B True if A and B are exactly equal
A > B True if A is bigger than B
A > B True if A is less than B
A >= B True if A is bigger or equal to B
A <= B True if A is less or equal to B

Text comparison

If you want to check if some text is equal to other text, you can use the == operator with one modification. You have to place both texts in double quotes ".

For example:

"vivec28" == "vivec28" will be evaluated to true.

Multiple Conditions

You can check multiple conditions in the $if() or $ifelse() function. To do this connect the two conditions with either AND or OR.

Example

A == B OR A < C

If one or both of A == B and A < C is true, then the entire condition is evaluated to be true.


A == B AND A < C

The condition is evaluated to true only if both A == B and A < C are true.


Brackets can be used for order of operations, the same way they would be used in math.


Alias and embed

These are the other two special functions that are quite different.

Alias

Alias has the following syntax:

$alias_v1(command)

The "command" argument is the alternative command that will be called. Vivbot will simply think that the user who triggered the custom command also said what's given to the alias. This includes the base Vivbot commands.

For example, lets say we have a custom command !plsno

with the response text set to Good luck! $alias(!roulette)

When the user sends !plsno, Vivbot will say

Good luck!

And then perform !roulette as if the user simply said !roulette.

Embed

Alias has the following syntax:

$embed(command)

This evaluates the mentioned custom command, and returns the text from this. This can be very useful for keeping redundant text in one place so if you want to change it, you only need to change it in one place.

For example, you can have a custom command called !lastvid with response https://www.youtube.com/watch?v=WlCGZwc2A9M which contains the link to your latest youtube highlight.

You can create another auto-repeating command, with response being Check out my last highlight: $embed(!lastvid).

When you change the link, you only need to do it once.

Limitations

You can have up to 5 embed functions within a single command, and the embeds can be "nested" with depth of up to 3. Nested meaning embed function calling a command that also has an embed function.

Combining Function and Wildcards

The true power of functions and wildcards come when you use them together. This section is a little more complex, but it does not introduce anything new.

Custom my currency

You can recreate many of the Vivbot's commands using custom commands.

{user}, you have $fmt_curr($curr({user})).

Will turn into vivec28, you have 923 coins.

Custom commands evaluate from left to right, and nested functions evaluate from inside to outside.

In this case, Vivbot will first get user and replace it with vivec28.

Then, it will find $fmt_curr(), but since it has a function inside of it, that function will be evaluated first. The function inside is $curr() which, again, contains something inside of it that will be evaluated first.


Step Outcome
0 (start) {user}, you have $fmt_curr($curr({user})).
1 vivec28, you have $fmt_curr($curr({user})).
2 vivec28, you have $fmt_curr($curr(vivec28)).
3 vivec28, you have $fmt_curr(923).
4 (done) vivec28, you have 923 coins.

Custom uptime

$ifelse(*is_live*::Stream online for *uptime_hours* hours *uptime_minutes* minutes *uptime_seconds* seconds::Stream is offline. Come back tomorrow!)

$if() and $ifelse() is different from all other commands due to the order of how it evaluates what's inside of it.

It will first evaluate the first argument. Here's the step by step of what Vivbot will, assuming that stream is online.

Step Outcome
0 (start) $ifelse(*is_live*::Stream online for *uptime_hours* hours *uptime_minutes* minutes *uptime_seconds* seconds.::Stream is offline. Come back tomorrow!)
1 $ifelse(true::Stream online for *uptime_hours* hours *uptime_minutes* minutes *uptime_seconds* seconds.::Stream is offline. Come back tomorrow!)
2 Stream online for *uptime_hours* hours *uptime_minutes* minutes *uptime_seconds* seconds.
3 Stream online for 0 hours *uptime_minutes* minutes *uptime_seconds* seconds.
4 Stream online for 0 hours 47 minutes *uptime_seconds* seconds.
5 (done) Stream online for 0 hours 47 minutes 10 seconds.


A small improvement

In the above example, The "0 hours" is entirely unnecessary. We can fix this with more $if() functions:

$ifelse(*is_live*::Stream online for if(*uptime_hours* > 0::*uptime_hours* hours) if(*uptime_minutes* > 0::*uptime_minutes* minutes) *uptime_seconds* seconds::Stream is offline)

This adds a condition to only print hours and minutes the values are more than 0. While this is cumbersome, it gives you much more control over the outcome of the command.


Random Kappa

$tset(num::$rnd_num(0::3)) $if($tget(num) == 0::Kappa) $if($tget(num) == 1::Keepo) $if($tget(num) == 2::KappaPride) $if($tget(num) == 3::KappaWealth)

The first thing we do is get and store a random number. $rnd_num(0::3) returns a random number ranging from 0 to 3. Since we need it for multiple comparisons, we want to store it using $tset(). $tset() will associate the number with "num" as the name for when we want to use it.

After, we have 4 $if() functions, and we know only one of them will evaluate to true because the value stored with name "num" can only be satisfy one of the conditions.


Simple Gamble

Simple isn't always elegant.

$tset(roll::$rnd_num(0::1)) $ifelse( $has_curr({user}::{1}) :: $ifelse($tget(roll) == 0 :: $add_curr({user}::{1}) You won $fmt_curr({1})! :: $rem_curr({user}::{1}) You lost $fmt_curr({1})) :: You don't have {1} to bet. Your current balance is $fmt_curr($curr({user})).)

Similarly to Random Kappa, we want to store a random number first. {1} will give us the number the user is supposed to put after the command name to indicate how much they want to bet. We check if the user actually has the currency required. If he does, we check if the user won by checking the random number to be 0 or 1. If he wins, the currency is added, if he loses the currency is removed.

All in

You can do some interesting stuff by combining alias and wildcards.

$ifelse($has_curr({user}::20) :: $alias_v1(!bet $curr({user}) {1}) {user} went all in and bet $curr({user}) on {1}! :: You are too poor to go all in :( )

This command checks if the user has at least 20 currency, and if he does, calls alias with all of user's currency.

Math

A simple command that makes use of {1+} wildcard.

{1+} = $math({1+})

The "+" allows the mathematical expression to contain spaces.

If this command is called !math.

Call: !math 19 * 77

Response: 19 * 77 = 1463