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:
"_meta"
array? (Creating Metadata)We will go through all of these steps, starting with how to write JSON in general.
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:
"monster"
above is a key that holds all the monster data you have in your homebrew file, for example."this"
, see "name"
object)18
, in the second "ac"
field above. They can also be floating numbers, like 0.444518755
)true
or false
statements, like "isNpc"
above. true
and false
must be lowercase)"from"
above) or"ac"
above)"key": null
),
(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.For further reading on JSON as a language, you can check the Learn X in Y Minutes or W3Schools websites.
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:
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.
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:
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.
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:
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.
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:
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.
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.
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:
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": true
in 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.
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:
Fork
button at the top-right.Create Branch
Author Name; Homebrew Name.json
Add file -> Upload files
dialogue at the top right of the files.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.Compare & pull request
button.Create Pull Request
button.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.
You have made your first homebrew file and shared it with the world! We hope your homebrew adventures continue in another chapter!