¶ How Homebrew Works
Homebrew for 5eTools are created by converting homebrew into JSON files. The JSON file is then fed to the site and if all the data within the file is valid, displayed on the site as content. There is a short checklist you need to go through to make sure your file is OK:
- Do you know JSON enough to create a file from scratch? (How JSON Works)
1.a Which program do you need to write JSON? (Preferred Editors) - Does your file have an appropriate
"_meta"array? (Creating Metadata) - What are you creating/converting? (Converting Homebrew)
- Is you homebrew file valid as a JSON file? (JSON Validation)
- Do sections you added to your file adhere to the 5eTools schema? (Schema Validation)
- Does your file work on the site? (Testing Your File)
- If you want to share your file, do you know how to submit a Pull Request? (How Homebrew Repo Works)
We will go through all of these steps, starting with how to write JSON in general.
¶ How JSON Works
JSON (JavaScript Object Notation) is a simple, lightweight data interchange format. Its use case for our purposes is to tell the site’s code what to display on the site. You may consider it as a giant pile of key-value pairs if you are a bit more programming-savvy.
For example, a JSON file can look like this:
{
"monster": [
{
"name": "Your future monster!",
"source": "YourBREW",
"isNpc": true,
"ac": {
"ac": 18,
"from": [
"natural armor"
]
}
}
]
}
To break down what is happening there up there:
- Every JSON file is written inside a set of curly braces. Otherwise, it does not work.
- Inside those curly braces, keys are written to hold different types of data.
"monster"above is a key that holds all the monster data you have in your homebrew file, for example. - Keys can hold several data types, such as:
- strings (like
"this", see"name"object) - numbers (integers like
18, in the second"ac"field above. They can also be floating numbers, like0.444518755) - booleans (
trueorfalsestatements, like"isNpc"above.trueandfalsemust be lowercase) - arrays (keys that hold multiple instances of data, like the
"from"above) or - objects (like arrays, but holds more nuanced data. See the first
"ac"above) - null (when a key needs to be present, but doesn’t hold data. Used as
"key": null)
- strings (like
- Every key must have a
,(comma) after it, to signify it is done taking in data, unless it is the last (or only) key inside an array or object (see how the first"ac"object does not have a comma after its closing curly brace). Missed commas are the #1 reason JSON files fail validation. Adding more commas than necessary also breaks the file, so be careful. - White space is only there for human eyes. The computer does not care how much whitespace is there.
For further reading on JSON as a language, you can check the Learn X in Y Minutes or W3Schools websites.
¶ Preferred Editors
You can write JSON on any piece of software that can create a text file (Notepad still works!) but, you can do so much better than plain old Notepad. The community recommeds:
- Visual Studio Code by Microsoft (VSCode for short). It is the most used editor in the community and has some extensions that make editing JSON specifically for 5eTools much easier. Also, VSCode supports automatic schema validation, which is very useful for fledgeling converters. Before downloading it, you may demo it at https://vscode.dev/
1.a If you do not want any Microsoft flavour in your editor, check out VSCodium, a version of VSCode that is stripped of any and all Microsoft telemetry and tracking. Supports extensions and automatic schema validation as VSCode does. - Notepad++ by Don Ho. A very lightweight and quick to set-up editor for your code needs. UI might look a bit dated, but it is feature-rich nonetheless. Does not support schema validation.
Many of the features of the editors mentioned above are too plenty to mention here, so please check them out yourselves. At the end, the editor you are most comfortable with is the best editor for you.
¶ Creating Metadata
For our homebrew files to be recognized by 5eTools we must include some metadata or else our creations will not show up properly. This is done through the "_meta" array.
"_meta"contains crucial info such as:
- Sources, as one homebrew file can contain more than one homebrew.
- The file’s JSON identifier (to distinguish this file from the rest of the files).
- Abbreviation (because those are cool and easily identifiable in one glance).
- Name.
- Author.
- Converter (in case there are errors or updates, the converter should leave contact info in order to be reachable).
- Version of the homebrew file, to make sure everything is up-to-date.
- URL to the homebrew source.
- Creation date and last change date.
These are some of the data
"_meta"holds, and there are more bells and whistles to it, should you need them. See the _meta page for more.
¶ Converting Homebrew
Now that you are set with the knowledge of JSON, a "_meta" section, and have a homebrew source to convert, you are off to the races. Depending on the content you want to convert, you might take some different routes:
- If you are trying to convert monsters, spells or legendary groups for said monsters, you can use the Homebrew Builder for GUI-based homebrew creation. While your creations can live happily on the site, everything the site has is saved in your cookies, and if you were to delete them your creations would go down with those cookies. Creating homebrew in the builder and copying the data to a local file on your system is not a bad idea.
- If you are converting monsters, races, feats, spells, items or tables, you may want to use the Text Converter. Text Converter takes plain text or Markdown based source data and converts it to ready to use homebrew JSON. You can directly add the converted output to your file on the site or copy the converted data into a local file on your system. Note that Text Converter is rather picky about the wording and spacing of the input value, so depending on how well the input is formatted, you might want to do manual conversion.
- For any other content not mentioned yet in this section, and/or you are limited by the site’s capabilities, you must do manual conversion. This entails either copying similar enough data from the site’s data and modifying them to suit your needs, or referencing the site’s schema to build something you can truly call your own. The Table of Reference page is your friend. Make sure to check out the thing you are converting’s page to get a grip of it beforehand.
As you are converting your homebrew, you might want to spice up the content with links to references, italic, bold, and color modes, and adding different headers. On that topic, you should check out the Renderer Demo. It is a special page that documents all of the text styling options you can employ for your homebrew needs.
All of the tools mentioned above (Homebrew Builder, Text Converter, and Renderer Demo) can be found under the Utilities tab on 5eTools.
Be careful when you are adding the tags and entries you see in the Renderer Demo. Broken tags may prevent the pages from loading and broken entries can throw your content to oblivion.
Another point of consideration is that you should be careful when you are working with objects. While mostly harmless, some of the keys are so important that if you put wrong values into them they may purge existing homebrew data on page load. This is why copying your homebrew into a local file is so important; you can always re-enable the homebrew from the repo, but you cannot get back the deleted cookies.
¶ JSON Validation
You are at the home stretch, you are ready to upload your homebrew file to the site! But, you encounter a popup like this:
This may be one of the many JSON file mistakes you may have committed. Thankfully, there are ways of easily getting rid of such errors:
- If you are using an editor that supports linting JSON files, you will immediately be notified of such errors, in the form of error messages or squigly lines behind the erroring part, like so:
- If you are not using an editor with such capabilities, a site like JSONLint can be used to quickly see such errors.
For your file to work on 5eTools, it must have none such errors. Even one of them is enough for file to be rejected by the Homebrew Manager.
While not such an error, make sure all of your keys are where they are supposed to be. Schema validation may catch those, but in the event it doesn’t, it is possible to have a key in the wrong place and have a JSON file valid. This may cause unwanted formatting, broken pages, or purged homebrew at the extreme end.
¶ Schema Validation
Now that you are done with converting you should use the schema to validate your brew and tell you the errors it may have. There are two main ways of doing it: Live validation through your editor or with a test script. If you are unsure with which one you should go with, if you are using VSCode you can use the live validation. It is easier and faster than setting up the test script. Another advantage of live validation is that VSCode will tell you the possible keys you can include in your creation, according to the 5eTools schema.
The Schema page details how live validation or test script can be set up.
Depending on your system’s capabilities, the live validation method can quickly become a slog as your homebrew file’s line count grows bigger. In such circumstances, you may want to create a separate file to work on and copy-paste your end result, or use the test script, which is quite fast but only tells you the first error it encounters.
One last warning, if schema errors are present in a file, those errors will not prevent it from Homebrew Manager accepting it. But, that does not mean these schema errors are benign. Depending on severity, they can cause in data loss. Try to squash them as they come, before you test your file on the site.
¶ Testing Your File
After you fix any JSON errors, you can hit the Upload File button and see your homebrew on 5eTools!
Even though the button is called Upload File, no files are sent across the Internet. All that button does is adding the contents of your homebrew file (technically uploading), to the existing localStorage and cookies so that they show up alongside site data.
Check out the pages you converted homebrew for, and see if each entry works as intended. Fix typos, add missing styling, match data. Do as many iterations as you like.
A happy converter is a converter that tests frequently. Going through the trouble of converting lots of things and trying to find one small error that messes the whole homebrew after you are done with all of it is a very bad feeling. Consider doing a round of testing at set intervals, such as “I will test my brew every 10 monsters I convert!” or “I will test my homebrew after I am done with this category!”
When you believe you are ready to share this file with others, consider these outcomes:
- If you intend on using this file for private use only, you are done! Congratulations!
- If you are sharing this file with a few people only, you must send them a valid link each time you make a change. You may want to look into something like a GitHub repo.
- If you would like for everyone to use your converted homebrew, consider uploading to the 5eTools Homebrew Repo. There, every 5eTools user can find your conversion through the Homebrew Manager, and it will be automatically updated to match any changes to 5eTools schema.
Alternatively, if you want your homebrew to be updated with future schema changes but not show up on the Homebrew Manager, you can add
"hidden": truein the"_meta"of your file and upload it to the repo that way. Doing so will disable it from being displayed on the Homebrew Manager, but a person looking for the file can still find it in the Homebrew Repo.
¶ How Homebrew Repo Works
If you want to share your file with every 5eTools user, you must make a Pull Request. If you are unsure about the process, here is a rundown:
- Sign-up/Sign-in to GitHub.
- Navigate to the Homebrew Repo.
- Click the
Forkbutton at the top-right.
- Navigate to your own fork of the Homebrew Repo.
- Within the repo, go to the folder your homebrew can best be summarized as.
- Find the branch button, right next to the folder info, and click it. Write a name for a new branch and click
Create Branch
- You will automatically be redirected to this branch. In the mean time, rename your file to fit the following format:
Author Name; Homebrew Name.json - Drag and drop your file to GitHub, or use the
Add file -> Upload filesdialogue at the top right of the files. - At the bottom, you will be presented with a form that is labeled
Commit Changes. Add a brief explanation as to what this PR for is inside the first field, and at the second field add a more detailed explanation. When you are done, make sure the branch it adds this file to is the same as the branch you created. - Go to the main repo, and click the
Compare & pull requestbutton.
- You will be presented with the Open Pull Request page. You can fill additional details here and when you are done, click
Create Pull Requestbutton.
And that’s it! After a while, it will be reviewed by both machines and humans and it will be publicly available. If there are breaking problems found, you will be notified in the Pull Request and you can make changes.
You do not need to make another Pull Request for a file that is already waiting in a Pull Request if you made a change to it. The existing pull request will automatically update.
¶ Congratulations!
You have made your first homebrew file and shared it with the world! We hope your homebrew adventures continue in another chapter!