Twelves, the Discord Bot¶
Introduction¶
Chartopia has its own Discord bot, and its name is Twelves. You can add Twelves to your Discord Server by following this link.
IMPORTANT
On 29th August 2022, Twelves was updated to use Discord's slash commands. This method of communicating with verified Discord bots is now mandatory, meaning the prefixed commands, which Twelves used to use with the 12s! prefix, is no longer possible.
Twelves can be used to roll on charts, search for content and even generate results from Chartopia syntax. Twelves is called upon in Discord using a forward slash /. From there a range of options are available from which to choose. If you have other bots installed that share the same command, e.g. /roll, Discord's slash command dialog will allow you to select which bot to use.
Although Discord makes it easy to dynamically construct a slash command as you type it, all the examples in this document can be copy-pasted into Discord's chat. If different bots share the command, then use Discord's prompt to select Twelves.
Roll on a chart or generator¶
It's possible to roll on any public random table or generator in the Chartopia library using the /roll command.
To roll on a chart, use /roll chart_id:<chart_id> where <chart_id> is the unique id of the chart. Note that in Chartopia, all ids of charts are visible in the browser's url bar.
For example, to roll on this Star Wars loot table, use /roll chart_id:288
There are two optional arguments that can be used for /roll, mult and input_vars.
Roll multiple¶
/roll chart_id:288 mult:5 will roll on the Star Wars loot table 5 times.
Input variables¶
If a chart accepts input variables, then they can be set using the input_vars argument.
For example, to set the theme on this Star Wars Quests generator, use /roll chart_id:9809 input_vars:theme=Heist. If input variables are omitted for a chart that accepts them, then the defaults defined by the chart's author will be used.
When multiple input variables need to be set, continue to list name, value pairs. For example, the VtM V5 - Vampire Generator can be rolled by using /roll chart_id:12043 input_vars:_gen=9th _clan=Banu Haqim.
Note that surrounding a value in quotes is optional, e.g. _clan=Banu Haqim and _clan="Banu Haqim" are treated identically.
Note that on the Chartopia website, some chart's input variables use drop lists (i.e. there are a finite list of options). Behind the scenes, the variable is still assigned text, so it's possible to give Twelves an input variable value outside the original author's intention. The result will be undefined though.
Roll using an alias¶
To roll using chart names rather than ids, refer to the section: Aliasing.
Roll on anything, randomly¶
For fun, there's a roll 'any' command that will roll on a randomly selected public chart from the entire Chartopia library. You may find something amazing.
/any
Search¶
Twelves can do basic search of all public charts using the search command, e.g. /search query_str:<query_str> page_num:<page_num> where <query_str> is the search query term and <page_num> is an optional page number. For example, /search query_str:star wars will return the first 10 results for "star wars" and /search query_str:star wars page_num:5 will return the 40th-50th results.
Aliasing¶
The content on Chartopia is vast, making name collisions common; that is why there is a preference toward using chart IDs. Twelves though, can assign an alias to a chart id for those preferring to refer to a chart via a name rather than an ID. This can be done using the alias command.
Create¶
Creation of an alias requires mapping a chart id against a text string.
/alias create chart_id:<chart_id> alias:<alias>
For example, to assign "SW Quests" to a chart with id 9809, use /alias create chart_id:9809 alias:SW Quests.
Roll using an alias¶
To roll on a chart represented by an alias, use the roll subcommand of /alias, for example /alias roll alias:SW Quests. A multiplier can also be used to roll multiple times, e.g. /alias roll alias:SW Quests mult:5, as well as input variables e.g. /alias roll alias:SW Quests input_vars:theme=Heist
List your aliases¶
All your current aliases can be listed in alphabetical order. Only a certain number show at a time, so the alias can be paged through.
/alias list page_num:<page_num> where <page_num> is optional.
For example /alias list will list your initial alphabetically ordered aliases. /alias list page_num:2 will list the second page of results.
Remove an alias¶
To remove an alias, use /alias remove alias:<alias> where <alias> will require quotes if there is a space in the alias.
Remove all aliases¶
To delete all aliases in one go, use /alias remove_all. There are no warning messages and there is no undo, so be absolutely sure you want to do this.
Executing Chartopia Syntax¶
It's possible for Twelves to generate a result from any Chartopia syntax by using the /gen command.
To do a dice equation:
/gen command:{d12+5}
To roll on a chart using a macro with a name:
/gen command:CHART("Dark Age Encounters")
To use a combination of text, rollable list and piped functions:
/gen command:There's {{{dragon|owl bear|fluffy rabbit} |> a_an}} on the other side of the door.
Discord has limitations¶
Unfortunately there are things that Discord can't do, so we've had to make some compromises. Here's a list of known issues.
- There's a 2000 character limit per message, so if you roll on a chart with a massive result (and this includes image urls in html), Twelves won't be able to render it. There is a possibility of splitting the result into multiple messages, but this will have to be done in such a way as to not split a img or url tag in half (for example).
- Discord doesn't support all of Markdown. Things like h1, h2 etc headers we've had to make do with a mix of bold and italics. Things like tables (which are an extension to markdown) won't work at all.
We did try Discord embeds, but they're also very limiting. They do offer an ability to have links, but they can't handle rolled results that have images.
Feedback is welcome¶
There will definitely be charts that don't play nice, so in order to improve Twelves, we'd like to know about any charts or generators that you believe could render better in Discord. We're also open to any Discord bot functionality suggestions.
Premium Features¶
Have you noticed that Chartopia is free? Our gracious patrons allow us to pay for the basic server requirements to keep Chartopia running, but we have to acknowledge that in order to continue development, and improve the server performance, we need to start adding premium content. Initially, premium features are some of the Twelves' functionality, including being able to roll on private charts, and being able to use the alias command.
In order to roll on private charts or access the alias command, a couple of things need to happen:
- You've synced your Chartopia account with a Discord account (you can do this from your profile page in Chartopia) and...
- We've added you as a subscriber to Chartopia.
So how to subscribe to Chartopia? Well, we haven't really gotten that far along in automating any kind of payment system, and Chartopia has been free since forever. Eventually we'll integrate some payment systems, but for the time being, if you really, really, really want Twelves to access your private charts, consider heading over to the ko-fi page where a few coffees for us devs can give you a few months of usage. Alternatively, consider being a patron. In short, it's kind of PWYW, and we'll hook you up.