This topic contains useful information about using SAMMI [RPG] Levelling System.
Documentation
This extension requires you to have your SAMMI bridge open. This will not work if you're not conencted to your sammi bridge.
As these are extension commands, any command that returns a value requires you to wait until variable exists. (all the purple commands)
Setup
Once you've installed the extension by clicking on the "SAMMI Bridge" button then "Install an Extension", your SAMMI bridge should get a new tab under the name of RPG System. If you click on this tab, you will be greeted by the following user interface.
There are two main sections in this tab. "Add New Skill" and "Remove A Skill" if SAMMI isn't connected to the Bridge, these buttons wont function.
| 1 - Navigation Pills | You can use these buttons to navigate pages for this extension. Each page contains relevant settings/tools for the extension. You use the Skills tab to add/remove new skills. You use the Stats tab (Requires free Addon) to add new stats. You use the settings tab to change global settings that affect how the extension behaves. |
| 2 - Documentation | Clicking this button will open an itchio page taking you to this documentation. I've tried my best to include all details relavant to using this extension. |
| 3 - Internal Name | The internal name is used to save skill names internally. Skills are saved in snake case and have "_level" appended to them. So if you enter "Combat", it will be converted into "combat_level". This name does not support numbers or symbols. |
| 4 - External Name | The external name is used in chat messages and externally displaying the skill name. This field is more lax when it comes to what you can add. If you enter "Combat" then when someone levels up, a chat message like this will be sent "[UserName] just reached Level [X] Combat Level" |
| 5 - Add New Skill | Clicking this button will attempt to add a new skill based on the names you typed in the internal and external names. If you leave any of the above fields empty or try and add a skill that already exists, SAMMI will throw an Error alerting you that it could not be added. |
| 6 - [Skill Name] X | For every skill you've added, it will display under this section. Clicking on the button that gets added will prompt you to delete the skill permanently from SAMMI. You will be prompted with an input box asking you to type "DELETE [skill_name]" |
| 7 - Links Nav | Links to all my socials where you can contact me if you have any issues. (first twitter is bluesky) |
Chat Commands
Fields inside <> are required. Fields inside () are optional.
| Command | Alias | Usage | Description |
|---|---|---|---|
| !optin | !optin | Adds the user to the Exp system, this is an active action as it prevents hundreds of account that show up once from being stored in a CSV. (You can disable optin but it may cause issues as I never designed this extension to be used without opting in) | |
| !optout | !optout > !accept | Prompts the user that opting out will permanently delete their level data and makes them type "!accept" before going ahead and deleting everything. | |
| !leaderboard | !lb | !leaderboard <skill> (username/page) | Sends a chat message displaying the leaderboard for the particular skill that was input. User can optionally provide the username of someone else or the page of the leaderboard they want to view. |
| !level | !lvl | !level <skill> (username) | Sends a chat message displaying the users level and current exp for the skill provided. Optionally, the user can provide a user to view the request users level/exp. |
| !ignore | !ignore | Silently adds a user to an ignore list so warnings about not gaining Exp will not show up for them. | |
| !setignore | !setignore <target> | [MOD] Adds a targeted user to the ignore list so warnings about that user will not be sent to chat. Useful for mods/the streamer to ignore bot accounts. |
These commands are only usable if you have the Stats addon enabled.
| Command | Alias | Usage | Description |
|---|---|---|---|
| !stats | !stats <stat> (username) | Sends a generic chat message showing a users stat for the provided stat. This command isn't the best and you're encouraged to go out and make your own stats command to better represent the data being requested. | |
| !statsleaderboard | !statslb | !statsleaderboard <stat> (username/page) | Sends a chat message displaying the leaderboard for the particular stat that was input. User can optionally provide the username of someone else o r the page of the leaderboard they want to view. |
Sammi Lvl Commands
[RPG] Lvl: Add Exp
This command is used to add Exp to users skills. If SAMMI tries to add exp to a user who has not opted in, a chat message warning will be displayed once per 2 minutes globally and once per hour per user.
| Field | Description |
|---|---|
| User ID | User Id of the user you want to add exp to. |
| Skill | The skill you want to add EXP to for that user. (The skill drop down selection automatically gets populated with skills you add). |
| Exp to Add | The amount of Exp you want to add to the user for the selected skill. |
| Lvl up Msg | If the user levels up, should SAMMI play a sound and send a message to chat. |
| Exp Multiplier | Should the "Exp to Add" get multiplied by the users sub multiplier? |
[RPG] Lvl: Get Level
This command is used to get the level of a users skill. Useful for giving users 'advantages' when it comes to calculations. Returns -1 if the user has not opted into the levelling system.
| Field | Description |
|---|---|
| User ID | User Id of the user you want to grab the level of. |
| Skill | The skill you want to grab the level of for that user. (The skill drop down selection automatically gets populated with skills you add). |
| Return Object? | If SAMMI should return an object instead of just the level as a number. The object contains the users Level, exp and row in the CSV. |
| Output Variable | The variable that gets returned with the user level. |
[RPG] Lvl: Get Alias
This command returns a users 'alias' by default, this is a users Twitch Display Name, but you can set it up to let users change their alias. Returns undefined if a user has not opted into the levelling system.
| Field | Description |
|---|---|
| User ID | User Id of the user you want to grab the alias of. |
| Output Variable | The variable that gets returned with the users alias. |
[RPG] Lvl: Get Sub Multi
This command returns a users sub multiplier or sub tier. This works for anyone and it caches the result so it doesn't need to constantly make API calls to get someones sub tier.
If someones sub falls off during stream, there's no way of updating it. It will update it if someone subscribes during the stream though.
| Field | Description |
|---|---|
| User ID | User Id of the user you want to grab the alias of. |
| Return as sub tier | If true, will return "0", "1000", "2000", "3000" instead of the sub multiplier. |
| Output Variable | The variable that gets returned with the sub multiplier. |
[RPG] Lvl: Deny
This command will send a chat message telling the user they must opt-in to the levelling system before they can earn exp.
| Field | Description |
|---|---|
| User ID | User Id of the user you want to send a deny message to. |
Sammi Util Commands
[RPG] Util: Format Number
This command takes a number (as a string or number) and returns a formatted number thats more readable. If you input "1000000" it will return "1,000,000" (as a string)
This is useful for sending numbers to chat and is used to display how much exp someone has. You can use this command for whatever you would like.
| Field | Description |
|---|---|
| Number | The number (as a string or number) that you want to format. |
| Output Variable | The variable that gets returned with the formatted number. |
[RPG] Util: Set Cooldown
This command takes a User ID (or anything) and lets you add a cooldown to it.
To avoid storing lots of redundant data, when SAMMI opens, it will go through and remove any cooldowns that have expired.
| Field | Description |
|---|---|
| User ID | The User ID you want to add a cooldown to. You can also use something like 'global' if you want to put a global cooldown on a button. |
| Group | If left empty, uses the button id, otherwise this is the 'group' the cooldown is applied to. |
| Duration | The amount of time in time units the cooldown should last. |
| Time Unit | The time unit that should be used for applying cooldowns. Seconds, Minutes, Hours and Days. |
[RPG] Util: Get Cooldown
This command takes a User ID (or anything) and lets you get the cooldown of them.
This command by default, will return true if a user still has a cooldown. Alternatively you can return the amount of seconds left to output in chat.
| Field | Description |
|---|---|
| User ID | The User ID you want to get the cooldown of. You can also use something like 'global' if you want to get a global cooldown on a button. |
| Group | If left empty, uses the button id, otherwise you can specify the cooldown 'group' |
| Output | The variable that gets returned with True or False if someone still has a cooldown. |
| Output Seconds Left | If ticked, will return time in seconds left, otherwise returns true or false. |
[RPG] Util: Log
This command is really more of an internal troubleshooting tool I developed, but you can use it too if you wanna log stuff.
| Field | Description |
|---|---|
| Severity | The Severity rating of the log. INFO, WARN, ERROR and FATAL. |
| Section | Mainly just used to group stuff |
| Message | The message that will be logged. |
[RPG] Util: Explode Object
This command was added to make my life easier but figured you might get some use out of it too. It basically just takes an object variable and unpacks it into the root of the button.
| Field | Description |
|---|---|
| Object Name | Enter the name of the Object. If you trigger pull data and set the variable name to "data" then put "data" in this field. |
| Finished Variable | When the function finishes, it will set a variable of this name to true, so you can wait until variable exists. |
[RPG] Stat Commands
These commands require the stats addon which is included for free with the purchase of the RPG System. I figured not everyone would use these, so I made it an addon so its optional.
[RPG] Stat: Add To Stat
Add this command to buttons where you want to modify a users stat, they sent a new chat message? Add this to a button with chat message as a trigger with + 1 as the value to keep track of chat messages sent by a user.
| Field | Description |
|---|---|
| User Id | User Id of the user you want to modify the stat of |
| Stat | The stat you want to modify for the user. Stats are dynamically populated when you add more stats in the bridge. |
| Operation | (+ - =) The math operation you want to do to the users stat. + Adds, - Removes, = Sets it equal to. |
| Value | The value you want to modify the users stat with. Operation + with value 10, will add +10 to the users stat. |
[RPG] Stat: Get Stat
This command is useful if you want to add a command that lets a user pull their stat value in a nicely formatted message. By default the !stats <stat> exists but it isnt formatted nicely. Returns -1 if the user has not participated in the Levelling system.
| Field | Description |
|---|---|
| User Id | The user id of the user you wish to retrieve the stat information of. |
| Stat | The stat you would like to retrieve for the user. Stats are dynamically populated when you add stats in the bridge. |
| Output Variable | The variable you need to wait for that contains the stat value from the user requesting. Will return -1 if the user has not opted in. |