To build a custom script with a homebrew character, you will need:

• A ready-made script

• JSON data to insert

• A basic text editor. Notepad works just fine, but I prefer a program with validation built in, such as Sublime Text, which I'll be using throughout. I also recommend the usage of the Pretty JSON plugin: installation instructions can be found here.

In order to insert homebrew characters into existing custom scripts, let's start by building a script that will nest a homebrew character (or characters). The best tool for this by far is The Pandemonium Institute's own Blood on the Clocktower Script Builder. Let's look at the base 3 script Trouble Brewing as an example.

As a general rule, it's good to have 13 Townsfolk, 4 Outsiders, 4 Minions and up to 4 Demons to obey the basic structure of a standard Ravenswood Bluff script; although a number of scripts allow for an additional Marionette. There are also homebrew characters on this site such as the Stowaway and Evangelist that necessitate bending these rules. But, in order to stick to the standard amount, let's make room to insert a homebrew character. Let's remove, for example, the Mayor.

Once inserted and validated, save the script, making sure that the file format is still a .JSON, and load it in Clocktower.

That's it! The Martyr has successfully been added to the script, and is fully functional within the app. To add any additional characters, follow the same process, copying over the appropriate code.

If you want to try your hand at building your own custom characters, the process of inserting and testing them is as above. But let's look at the BOTC Script JSON Schema to see how these characters are put together. You don't need to understand all of these yet, but if you want to build in more advanced mechanics such as blocked selection while building a bag, "swapped" roles upon Grimoire reveal like the Drunk or the Marionette, or duplicable characters like the Village Idiot, the JSON schema has the appropriate arrays of code you'll need to make that happen, and I encourage you to explore what's possible.

For this tutorial, let's break down a more basic character to understand how each field operates. Let's look at the Butler, as it contains all of the basic data any character will require, as well as a few optional extras that you'll frequently encounter.

        {

            "id": "butler",

            "name": "Butler",

            "team": "outsider",

            "firstNightReminder": "The Butler chooses a player. :reminder:",

            "otherNightReminder": "The Butler chooses a player. :reminder:",

            "reminders": [

                "Master"

            ],

            "setup": false,

            "ability": "Each night, choose a player (not yourself): tomorrow, you may only vote if they are voting too.",

            "flavor": "Yes, sir... No, sir... Certainly, sir.",

            "firstNight": 52,

            "otherNight": 84,

            "jinxes": [

                {

                    "id": "organgrinder",

                    "reason": "If the Organ Grinder is causing eyes closed voting, the Butler may raise their hand to vote but their vote is only counted if their master voted too."

                }

            ]

        }

To break this down...

• The id entry represents how the script parses the character initially. These always need to be one word.

• The name entry is how the character's name will be shown in-game.

• The team entry, shown here as "outsider", indicates where the character will fall in the script. These can be "townsfolk", "outsider", "minion", "demon", "traveller" or "fabled".

• The firstNightReminder and otherNightReminder fields represent what the Storyteller will see in order to direct them in running the character when expanding the night order. Note that this field is dependent on having a firstNight and/or otherNight value, which will be explained later. Remember in this field that ":reminder:" will be shown as a small reminder token icon, and text *in asterisks* will be shown as bold text.

• The reminders array (in [square brackets]) represents any reminder tokens that may be associated with the character. Note that if you are storytelling, you can't place duplicate reminder tokens unless they are listed in this array. So, for instance, while a player bluffing Butler might indicate they have multiple masters, allowing players to mark those players as master, the Storyteller can only do this once. In order to actually have multiple masters, you need to have multiple "Master" entries like so:

• The setup entry, either true or false indicates if the character impacts setup in any way. This might be the addition or removal of Outsiders, the addition of a specific character, etc. Note that this doesn't automate the process of adding or removing anything as indicated on the token, but rather, simply gives the Storyteller an alert upon selection that something needs modifying prior to the game starting.

• The ability entry is fairly self-explanatory: this is where you state what the character actually does, and will appear both on the token and in the expanded script on the side. As a rule, characters tend to have descriptions around 130 characters long, so try to exercise some brevity!

• The flavor entry is also straightforward (but optional): it is the additional text that accompanies each character for the purposes of immersion and world-building.

• The firstNight and otherNight entries are crucial in determining if and when characters wake up at night. There is one value for the first night, and one value for any subsequent night. Note that most characters have different "waking" values and so you'll need to experiment to ensure that the integrity of the night order isn't disturbed. For instance, Dusk always has a night value of 1, but Dawn has a night value of 72 on the first night and 90 on other nights. Demons typically have an otherNight value of around 35, with Minions generally before, and Townsfolk generally after - but there are notable exceptions such as the Spy or Monk! Experiment with these values, noting that if you need finer tuning, decimal places are permitted.

• Lastly, the jinxes array is, as the name suggests, where you would insert any appropriate jinxes. Note that it's not possible to insert new jinxes for base characters unless you use their raw JSON data, so the better option is to simply attach them to the homebrew characters, if needed. Jinxes consist of an id value (which links to the id value noted above), and a reason value which is the jinx itself that will show on-script. Note that each jinx needs to be its own entry in {curly brackets}.

The only other field that is necessary specifically for homebrew characters is the image value, which should point to the icon on the token. There are a number of free resources like Bloodstar that can assist with this process, or your can make them yourself. In order for both the good and evil versions of a character to properly display, you will need to create two separate images and insert links for both, with the primary alignment being listed first. For an example, you can see the links to the Martyr's icon in the first tutorial. 

As a disclaimer to this section, I am not employed by, nor endorsed by The Pandemonium Institute, however I have been fortunate enough to attend a panel on BOTC character design, and have spoken to a number of key members of the community that have further illuminated how BOTC characters come to exist - so please note that the following is mostly taken from them, with a few additional notes.

Characters should adhere to the following basic principles:

Have a clearly stated purpose and identity

On purpose, take a look at the text directly underneath the ability on the BOTC Wiki for any given character. For instance, this is the Juggler's purpose:

The Juggler takes the risk of convincing people to reveal their characters on the 1st day, in the hope of guessing as many as possible that are telling the truth. 

Or we can look at the Wraith's purpose:

The Wraith knows and shares what happens at night. 

In short, try to sum up what purpose your character serves in a sentence. If you can, you're probably already on the right track. If you can't, it may need refining: either because it's just "it's the Washerwoman again, but..." - or because there is simply too much to pack into a single statement.

To expand, consider the purpose of the Menagerie character, the Stowaway:

The Stowaway sows discord among Outsiders by claiming to be one of them.

Or this one, for the Mechanical Man:

The Mechanical Man performs outrageous, risky tasks to learn valuable information.

This is a crucial exercise in distilling the "essence" of characters you create, and serves as the initial "check" that you have a solid idea.

Identity is mostly about "feel", but basically boils down to offering a unique experience for the player that draws it. This might mean a unique way to interact with the game, such as the Mutant, a mechanic that only they are privy to, like the Savant, or a contribution to the "solve" that only they have, like the Chef.

When creating a character, ask if this idea has been done before, and if so, how it could be adapted or changed to offer a fresh take. Generally, it's good to avoid simply tacking on additional powers to existing roles, not just because it's contrived, but because if a character is "X, but better", that negates the existence of the original, which already serves its own distinct function.

Be bluffable by good, and by evil

Although some roles are harder to bluff than others (ie. the Cannibal, the Undertaker, or the Dreamer), this doesn't mean they're impossible to bluff. Characters that are impossible to bluff have some level of clear mechanical confirmation. If your character has a unique mechanic that is necessary for it to function as intended, it may need to be either a Minion, Demon, Traveller or Fabled, since Townsfolk and Outsiders cannot be mechanically confirmed simply by existing without ruining the conceit of the game.

This can often be confused with having a unique game mechanic, but isn't the same thing. For instance, the Banshee has a unique mechanic which is confirmable if killed by the Demon, but up until that moment, they can never be 100% trusted. And even if an evil player claims Banshee as the Imp and passes in the night, they can always claim to be poisoned.

If your character idea contains a mechanic that cannot be bluffed (such as the Beggar removing dead votes, or the Bureaucrat adding additional votes during the day), it is a Traveller and should be made as such. This isn't a bad thing!

When creating a character, ask yourself how you would bluff this character if evil to misinform town; and how you might bluff it as good as a cover for other roles. If both of those are doable, you have a solid idea to work with.

Be appropriate to the character type

In short, Townsfolk should help town, Outsiders should be detrimental to town but ultimately work with it, and Minions and Demons should cause harm. Travellers are ambiguous in alignment, so their abilities should be appropriately suited to work in either circumstance.

If you have a Townsfolk with a distinct downside (usually as a balancing mechanic, such as the Balloonist adding Outsiders, or the Bounty Hunter adding an evil Townsfolk), consider if the upside outweighs it. If it doesn't, it may work better as an Outsider, or may need some tweaking to better balance out the benefit with the drawback.

Similarly, Outsiders, while good, should ultimately be unhelpful to town, so ensure that the balance tips that way. If the downside is so extreme that they actively detract from any game they're in, perhaps they may work better as a Minion or Demon!

Work alongside, or in contrast to other characters

Part of the beauty of BOTC is that no character exists in a vacuum. There are ways to corrupt good information, make certain powers misfire, or nullify the effects of evil characters. Sometimes, a useful way to balance, or add more depth to the way a character functions is to create another that acts as its foil. For example, the Undertaker learns the character of executed players, but that is something that the Spy can bluff, having access to the Grimoire. Or - the Menagerie character the Gatekeeper learns information if they nominate, but the Gerrymanderer capitalises on failed nominations. 

Have agency, and allow others to have agency

There's simply nothing fun about having your agency taken away from you. There are "soft" versions of this that are perfectly reasonable, like the Poisoner who interrupts abilities, or the Psychopath who kills during the day, but the players themselves are still able to play the game. On the other hand, character concepts that prevent players from talking or using their abilities entirely remove that agency, and essentially eliminate those players from the game. Given that Blood on the Clocktower operates on the premise that everyone is able to play until the very end whether alive or dead, it's essential that player agency is retained, even if slightly altered given certain conditions like madness or poisoning.

Be fun, be unique

Above all else, it's important to ensure that characters have a unique identity among the current cast, and actually be fun to play as, and against! There's little point in implementing a character that is the Empath but more - or less. Either iteration makes the Empath, or itself, redundant. So consider mechanics within the bounds of the game that make for a unique experience without leaning on existing ideas. Moreover, while unique, an ability that states, for instance, "you might win or lose arbitrarily" isn't fun. Not only does it remove player agency, but with nothing to do, and no outcome to strive for, that player simply floats through the game having no impact, and doesn't even know if they'll win in the end. So making sure that abilities are fun to interact with - even if detrimental - and don't harm the player's experience for having drawn them is crucial.

Good luck!