# Commands Commands allow you to assemble a set of [Actions](/docs/actions) together as a set of steps to perform. Commands come in a variety of forms (Chat, Event, Timer, etc), but share about 80% of the same functionality. All commands can be tested out by pressing the "Play" button next to them and can be edited by clicking the "Edit" button. Commands that are created by you can also be deleted by pressing the "Delete" button. By default, commands of the same type are locked together. This means that if two commands were to run at the same time (EX: 2 Chat commands), the 1st command would start running and the 2nd command will wait until the 1st is complete. This is designed to help prevent many commands of the same type from going off at the same time and cause some form of chaos. However, there can be circumstances in which you will want a command to always be able to run right away, regardless of if there are other commands of the same type already running. This can be done on a per-command basis or for all commands. - **Per-Command:** An individual command can run outside of our locking system by toggling the "Unlock Command" option on it. This will ensure that this command always runs when it's triggered as long as all Usage Requirements are met (EX: The command is not already on cooldown). - **All Commands:** In the Settings menu under the Commands section, there will be an option called "Command Lock System". This option controls how the command locking system works and on what specifically a command locks and prevents other commands from running. For details on how each option works, you can hover your mouse over the option for an explanation on how each option works. There are three parts that factor into when a command can run: Cooldowns, Waits, & Locks. - Cooldowns affect whether a command can get queued up to run or not. So if you had a chat command with a 10 minute cooldown, once the command has been queued up to run (not necessarily run yet), someone can't try to queue it up again for another 10 minutes - Waits allow you to extend the length of a command to an arbitrary amount of time. So adding a 10 second wait to a command will physically make it take 10 seconds longer to complete. Adding a 10 second wait to anywhere in the command will always make it wait 10 seconds, however where you put a wait factors into how the command itself will run. Think of it like a cooking recipe. If someone tells you to wait 10 minutes before putting pasta into boiling water VS someone telling you to wait 10 minutes after putting pasta into boiling water, those two steps aren't the same thing even though they have a 10 minute wait in them - Locks are what restrict how many commands can be actively running at the same time (not the same as how many can be queued up to run). The default option makes it so that only 1 command of every type can run at the same time (EX: Chat, Event, Timer, etc). So you can't have two Chat commands running at the same time, but you can have a Chat & Event running at the same time. Unlocked commands ignore this and run as soon as they are triggered. ## Command Lock System The Command Lock System in Mix It Up can be customized to meet the needs of how you want commands to interact in your stream. This setting can be adjusted by heading to Settings -> Commands. Below are the various options available for the Command Lock System: - Per Command Type: Each command type (Chat, Event, Timer, etc) has a lock that prevents other commands of the same type from running at the same time. - Per Action Type: Each action type (Chat, Sound, Conditional, etc) has a lock that prevents other commands also containing those actions from running at the same time. - Visual/Audio Actions: Commands containing visual/audio-based actions (Sound, Overlay, etc) share 1 lock while other commands will run as soon as they are triggered. - Singular: All commands share the same lock only allowing one command to run at a time. - None: All commands are unlocked and will run as soon as they are triggered. ## Usage Requirements Usage Requirements allow you to specify limitations on who and when a command can be used. Each icon corresponds to a different Usage Requirement below: ### User Role The User Role requirement allows you to specify the minimum user role that is required in order to run this command. All user roles that are "higher" than the one you specify can use this command as well. (EX: If set to Follower, then Subscribers, Mods, & Streamers can use this command) ### Cooldown The Cooldown requirement allows you to specify how often a command can be used. Cooldown amounts are in seconds and can be set up in the following ways: #### Standard The command cools down by itself for EVERYONE for the specified amount #### Group The command cools down itself and all others in the same group for EVERYONE for the specified amount #### Per Person The command cools down for ONLY the user that ran it, meaning each user has their own unique cooldown for it. #### Per Person Group The command, along with all others in the same group, cools down for ONLY the user that ran it, combining the Group and Per Person behaviors so each user has their own unique cooldown shared across the whole group. ### Currency/Rank/Inventory The Currency/Rank/Inventory requirement allows you to prevent a command from being run if a user does not meet a currency, rank, or inventory requirement. See below for a description of how each individual requirement works. For more information about Currencies, Ranks, or Inventories, please see the [Currency/Rank/Inventory](/docs/consumables) page. #### Currency The Currency requirement allows you to specify a minimum amount of Currency that the user is required to have in order to use this command. If the user has the correct amount, it will be deducted from them when they run the command. Below are the different options you can select: * Required Amount - The currency amount that is specified is required and is the only amount accepted. Also, this means no currency amount will need to be specified when running the command. * Minimum Only - The currency amount specified by the user must be at least the minimum amount, but can be any number higher than it. It will specifically check the first argument of the command for an amount, then attempt to check the second argument, and fall back to using the minimum amount specified. * Minimum & Maximum - The currency amount specified by the user must be between the minimum & maximum amount, including those values. It will specifically check the first argument of the command for an amount, then attempt to check the second argument, and fall back to using the minimum amount specified. #### Rank The Rank requirement allows you to specify a Rank that the user is required to be in order to use this command. You can additionally specify how that rank is checked, choosing from three match types: that rank or higher, only that exact rank, or that rank or lower. #### Inventory The Inventory requirement allows you to specify an amount of items for an Inventory that the user is required to have in order to use this command. If the user has the correct amount, it will be deducted from them when they run the command. ### Arguments The Arguments requirement allows you to specify a required set of arguments that need to be provided when the command is run. You can set what the name of the arguments are, what type they are, and whether they are optional or not. You also can optionally toggle the "Assign To Special Identifiers" option to have the corresponding argument text assigned to a Special Identifier matching the name of your argument (EX: Argument named "Cool Name" becomes the Special Identifier "$coolname") ### Threshold The Threshold requirement allows you to specify how many times the command must be performed before it will actually trigger. You must specify the number of UNIQUE users who need to run the command and the time frame that it must be done in. For example, if I had a chat command and specified 3 for the users and 30 seconds for the time frame, the command would not run until 3 different users run the command within 30 seconds of each other. By default, when the requirement is met, it will only run the command once for the last user who triggered the command. You can use the "Run For Each User" if you would like to have it run the command for each user that contributed to the Threshold requirement in the order they helped. ### Settings The Settings requirement has several different options you can enable that affect either the ability to run the command or how it is run. This options currently include: - The ability to delete chat commands when they are run - The ability to assign to command to the Chat context menu (Chat Commands Only) Note that requiring a specific Patreon benefit is **not** part of the Settings requirement. It is configured as part of the separate User Role requirement instead. ### Error Messages When a requirement fails validation, an error message will be sent informing the user as to why the requirement failed. Subsequent requirement failures can send more error message depending on what you have set as the Requirement Errors Cooldown Amount under Settings -> Command. This setting does the following: - When each requirement is validated, if an error message would be sent it will sent the message and then set a cooldown time based on the amount of seconds you have set - If **the same requirement for the same command** triggers another error message, it checks to see if it the cooldown time has finished - If the cooldown time hasn't been finished, then it doesn't send the error message. If it has, then it sends it and resets the cooldown - When all requirements are validated and the command is started, it resets all of the error message cooldowns on each requirement So if you have it set to let's say 30 seconds, then each individual requirement for a command can only send an error message once every 30 seconds. So an error message sent from a Role Requirement doesn't affect an error message from a Currency Requirement, as two different blocking issues. It's also on a per-command basis, so a Cooldown Requirement on a shoutout command won't affect a raid command. Effectively speaking if you set the number very high (EX: 999999), then it only ever sends 1 error message per requirement, per command, per run. ## Command History The Command History feature allows you to see recent command usage within your channel, including what commands have completed, are currently running, or pending. You're able to cancel or replay individual commands or the same for a selection of commands. You'll also be able to see the details of why a command failed to run. ## Community Commands The Community Commands feature allows you to download commands created by the Mix It Up community and upload your own to share out with others. Community Commands are user-submitted commands not specifically created or endorsed by the Mix It Up staff team. Commands that are inappropriate or violate our Terms of Service can be reported directly through the app.