Usage Documentation
These docs will assume the command prefix is !.
Command Reference
| Usage | Permissions | Description |
|---|---|---|
!subathon |
All Users | Displays summary information about the currently running subathon. |
!subathon setup <initial_hours> <t1score> <t2score> <t3score> <bitscore> <timescore> [cap] |
Only Broadcaster | Setup and start a new subathon. |
!subathon link |
Moderators | Displays the OBS/browser link for the subathon timer. |
!subathon pause |
Moderators | Pause the subathon. |
!subathon resume |
Moderators | Resume the subathon so the timer resumes counting down. |
!subathon config |
Moderators | Display a summary of the current subathon configuration. |
!subathon config name [new name] |
Moderators | View or update the subathon name. |
!subathon config cap [new cap] |
Moderators | View or update the subathon timer cap. |
!subathon config scores [<t1score> <t2score> <t3score> <bitscore>] |
Moderators | View or update the score table (number of points contributions are worth). |
!subathon config timescore [new score] |
Moderators | View or update the seconds-per-point score of the subathon. (⚠️ Retroactive) |
!subathon adjust <amount> [@user] |
Moderators | Add amount points (may be negative to remove) points to the subathon. Optionally on behalf of @user. |
!subathon lb |
All Users | Display the top 10 contributors to the subathon, in order, by points. |
!subathon stop |
Only broadcaster | ⚠️ Permanently stops the subathon. Cannot be reversed. Subathon cannot be accessed after stopping. |
!goals |
All Users | Show the goals that have been setup for the active subathon. |
!goals remaining |
All Users | Show the subathon goals that have yet to be achieved. |
!goals add <points> <description> |
Moderators | Add a new goal with required points and name description. |
!goals remove <points> |
Moderators | Remove all goals which required exactly points. |
Setting up
To start a new subathon, the broadcaster should first choose how much each contribution will be worth, how much time the timer should start with, and whether there is a time cap, and create a new subathon with that information by using !subathon setup described below. Note that all options except initial_hours are also adjustable post-creation with !subathon config. If you want to customise the name of the subathon, that should also be done through !subathon config name.
The creation command will return a link to the subathon timer, which may be copied and included as an OBS browser source.
Note that the browser source/timer does not have any disconnection protection, so if the bot is restarted or if there is a connection issue on the side of the computer running OBS, the timer may disconnect and not update. To fix this, if there has been a disconnection, open the OBS browser source and press "Refresh Cache" to refresh the page and reconnect the timer. This will not affect the tracked contributions in any way, as all data is stored server-side. The OBS timer link can be retrieved at any time by the broadcaster using !subathon link.
At this point the subathon has been started, but will be in a 'paused' state. The timer should be showing the number of hours given in initial_hours, but should not be running. Sub and bit contributions will be counted and will raise the timer even while paused.
For further configuration, see the next section.
| Usage | Permissions | Description |
|---|---|---|
!subathon setup <initial_hours> <t1score> <t2score> <t3score> <bitscore> <timescore> [cap] |
Only Broadcaster | Setup and start a new subathon. |
!subathon link |
Moderators | Displays the OBS/browser link for the subathon timer. |
Setup Arguments
| Argument | Required | Accepts | Description |
|---|---|---|---|
initial_hours |
yes | Integer | Number of hours to start the subathon with. |
t1score |
yes | Float | Number of points a t1 subscription is worth. |
t2score |
yes | Float | Number of points a t2 subscription is worth. |
t3score |
yes | Float | Number of points a t3 subscription is worth. |
bitscore |
yes | Float | Number of points a single bit is worth. |
timescore |
yes | Integer | Number of seconds to add to the timer per point. |
cap |
no | Integer | Optional number of hours to cap the subathon at. |
Setup Example
!subathon setup 6 5 10 20 0.1 10 6
croccyhelper: Setup your subathon! Use !subathon resume to get the timer running. Use !subathon config to see and set options, including the name. Your timer link for OBS: https://izashi.thewisewolf.dev/tracker/timer?community=3
Configuration
The name, points added per contribution, seconds added per point, and timer cap of the subathon are all dynamically configurable with !subathon config. Running !subathon config itself will show you the list of options and their values, !subathon config <option> will show you the current value and further information about that option, and !subathon config <option> <value> will set that option to the provided value, if possible.
Scoretable (scores) adjustments are not retroactive. If, for example, a t1 subscription was given that contributed 5 points, and the t1score was then later raised to 10, that contribution would still only contribute 5 points.
Timer cap (cap) adjustments are retroactive. That is, even if a contribution was given while the timer was capped and did not raise the timer, if the cap is increased, then that contribution will now be counted towards the timer.
Timescore adjustments are also retroactive. This means that if the timescore is updated, every previous contribution will now be treated as contributing the new amount of time to the timer. This is particularly dangerous because if the timescore is reduced, the subathon may end prematurely.
Technical note: Each contribution is saved separately with a user (if given), timestamp, number of points, and associated event (e.g. subscription or bit contribution) if it exists. Time earned is calculated by summing the contribution points and multiplying by the current timescore. This is what gives rise to the sometimes-retroactive behaviour of the configuration. Since the contributions are saved separately with their event data this also means that in a pinch the historical score contributions can be adjusted or rebalanced if they do need to be, with some database magic server-side.
| Usage | Permissions | Description |
|---|---|---|
!subathon config |
Moderators | Display a summary of the current subathon configuration. |
!subathon config name [new name] |
Moderators | View or update the subathon name. |
!subathon config cap [new cap] |
Moderators | View or update the subathon timer cap. |
!subathon config scores [<t1score> <t2score> <t3score> <bitscore>] |
Moderators | View or update the score table (number of points contributions are worth). |
!subathon config timescore [new score] |
Moderators | View or update the seconds-per-point score of the subathon. (⚠️ Retroactive) |
Configuration Examples
!subathon config
croccyhelper: name="Testing" ; cap=6 (hours, 0 means no cap) ; scores=5.0 10.0 20.0 0.1 (t1, t2, t3, and 1 bit point scores) ; timescore=10 (seconds per point) ; Use !!subathon config [value] to see or set each option!
!subathon config name
croccyhelper: Name of the subathon, used whenever the subathon is mentioned. Accepts any string. Currently: "Testing" Example: !subathon config name Birthday Subathon
!subathon config name Birthday Subathon
croccyhelper: Updated the subathon name to "Birthday Subathon"
!subathon config cap
croccyhelper: Duration cap for this subathon, in hours, including the initial time. Contributions given after the cap has been reached will be accepted, but will not raise the timer. Accepts an integer, with 0 meaning no cap. Currently: 6 hours. Example: !subathon config cap 24
!subathon config cap 0
croccyhelper: The timer cap has been removed! To infinity and beyond!
!subathon config cap 10
croccyhelper: The subathon timer has been capped to 10 hours.
!subathon config scores
croccyhelper: The number of points each type of contribution (t1 sub, t2 sub, t3 sub, and 1 bit) will add to the subathon. Not retroactive. Accepts four floats. Currently: 5.0 10.0 20.0 0.1 Example: !subathon config scores 5 10 20 0.1
!subathon config scores 5 10 20 0.1
croccyhelper: Successfully updated subathon score table.
!subathon config timescore
croccyhelper: The number of seconds each contributed point adds to the timer. WARNING: This setting is retroactive and should generally not be used. Accepts an integer. Currently: 10 (seconds per point) Example: !subathon config timescore 10
!subathon config timescore 5 croccyhelper: Subathon time score updated (NOTE: This is retroactive).
Pausing and Resuming
Use !subathon pause to pause a subathon and !subathon resume to continue it.
Subathons will continue to accept contributions and raise the timer while paused, but the timer will no longer count down with the regular passage of time.
Subathons will automatically pause when the stream goes offline, but they do not automatically resume.
Typically, you will want to pause the timer for breaks or sleep, and resume it when you come back.
| Usage | Permissions | Description |
|---|---|---|
!subathon pause |
Moderators | Pause the subathon |
!subathon resume |
Moderators | Resume the subathon so the timer resumes counting down |
Tracking Contributions
The core function of a subathon tracker is to keep track of the contributions to the subathon, and raise the timer when a contribution is received. Our tracker is no different. The tracker will automatically keep track of (re)subscriptions, bits, and Blerp messages, and will raise the timer when they are received according to the configured score table. It is also possible for moderators to manually add or remove points from the subathon, either anonymously or on behalf of a specific user.
Whenever a user contributes, with the exception of contributions via Blerp, a message is sent thanking them for the contribution and informing them how many points and how much time they added to the timer (when not capped). For example:
When a user (re)subscribes (capped)
testFromUser contributed 5 points towards our subathon! Thank you <3
When a user (re)subscribes (uncapped)
testFromUser contributed 5 points and added 5 minutes to the timer! Thank you <3
Subscription contributions
When a user subscribes, re-subscribes, or gifts subscriptions, we add points to the tracker by number of subs * tier score where tier score is one of the configured t1score, t2score, or t3scoremultipliers, andnumber of subsis the number of users affected. In the first two cases, thenumber of subsis always1`, even if the user subscribes for multiple months.
We then send a message thanking that user, and informing them of how many points and how much time they added to the timer (if not capped).
If Gift subscriptions are given anonymously, then we still send a message, thanking 'Anonymous Gifter'.
Prime subscriptions are counted as a Tier 1 subscription, however a miscalculation may occur with Prime subscriptions if the user first subscribes and then chooses to later send their subscription message, since it is possible both will be counted as a subscription. Whether this does occur depends on undocumented details of the Twitch API. Keep an eye out for this and please contact the developer if there are any issues.
Bits and cheers
When bits are used in the channel via cheers, chat modifiers (large emotes etc), celebrations, or by sending bits along with a chat message, we add points to the tracker by number of bits * bitscore.
Blerp messages
When we receive a message from the blerp user in either of the following forms:
blerp: Machinestalkerwolfie used 0 bits to play Laughing Barney
blerp: !For 25 bits, LaPierreDeSlimeVT played Laughing Barney!
We add points to the tracker by number of bits * bitscore.
These points are contributed on behalf of the blerp user instead of the source user, by client request.
Manual adjustment
Moderators may also add points to the timer manually, either on behalf of a target user, or as the 'anonymous' user. The target user does not need to be active in chat, and it may be useful to add points on behalf of various e.g. bots to categorise manually adjusted points.
| Usage | Permissions | Description |
|---|---|---|
!subathon adjust <amount> [@user] |
Moderators | Add amount points (may be negative to remove) points to the subathon. Optionally on behalf of @user. |
Adjustment Examples
!subathon adjust 10
Added 10 point(s) to the timer
!subathon adjust -10
Removed 10 point(s) from the timer
!subathon adjust 10 @croccyhelper
Added 10 point(s) to the timer on behalf of croccyhelper
!subathon adjust -10 @croccyhelper
Removed 10 point(s) from the timer on behalf of croccyhelper
Statistics
The only contribution statistics command we currently have is !subathon lb which displays the top 10 contributors to the subathon.
!subathon lb
Birthday Subathon top 10 leaderboard: Unknown: 25 points, ralphluv: 25 points, Unknown: 25 points, Unknown: 25 points, Unknown: 25 points, Nuevois: 25 points, Unknown: 25 points, Theblackop241: 5 points, Unknown: 5 points, ItsKalcefy: 5 points
Goals
The tracker also has rudimentary support for 'subathon goals', by means of the below commands.
The goal progress will be mentioned in !subathon, and when a goal is achieved, the tracker will send a message to chat with the goal description.
croccyhelper: testFromUser contributed 25 points and added 25 minutes to the timer! Thank you <3
croccyhelper: We have reached Goal #1: Do some cool stuff !! Thank you everyone for your support <3
| Usage | Permissions | Description |
|---|---|---|
!goals |
All Users | Show the goals that have been setup for the active subathon. |
!goals remaining |
All Users | Show the subathon goals that have yet to be achieved. |
!goals add <points> <description> |
Moderators | Add a new goal with required points and name description. |
!goals remove <points> |
Moderators | Remove all goals which required exactly points. |
When the timer (or you) finishes
When the timer runs out (i.e. the timer duration exceeds the (possibly capped) earned time), there are a few small things to note.
- Nothing happens in the moment, except the timer will tick down to 00:00 and stay there.
- Contributions will not longer be accepted, and will not trigger any message or add to the timer, or be tracked as contributions.
- Until the subathon has been explicitly paused (or stopped), a moderator may use
!subathon adjustto add points to the timer, which, if the timer is not capped, may 'unfinish' it with no negative effects. - The subathon still counts as 'active', so commands such as
!subathon lbwill still work as expected, until the subathon has been fully stopped with!subathon stop.
Technical Note: The 'end' of a subathon is represented entirely virtually, with a subathon being considered as finished if the duration equals or exceeds the earned time. If a subathon is finished in this sense, it may be paused, but it can not be resumed or contributed to except via adjust. All reported durations will act as if the subathon total duration is equal to the earned time.
Afterword
Thank you for using the HoloTech Subathon Tracker, produced by Holodoxical Technology Solutions!
We hope you have a great subathon.
For questions and support, please feel free to reach out to @conatum on Discord, or email me at mailto:holo.tech@thewisewolf.dev