Homebrew: Adding Content

From 5etools Community Wiki
Jump to: navigation, search

framless
v1.1.0

How to add Existing Homebrew to the site

If you just want to know who to add EXISTING community curated homebrews to your system, here is how to do that.
  • Go to the website and choose Utilities,
  • choose Manage Homebrew,
  • select Get Homebrew and choose what sources you'd like to add.
(for more information check the feature information for Manage Homebrew)


OTHERWISE... for how to Add your OWN homebrew (converting it to 5etools format)...

Preparations

You will need...

  • Content you wish to convert.
  • All your tools ready to go.
If you're just starting out and feel overwhelmed, just start by getting one of the recommended editors to work with.

You will make...

...something like this. Its a lot easier than it seems and mostly involves a lot of copy and paste.

{ 
	"_meta": {
		"sources": [
			{
				"json": "<your_unique_json>",
				"abbreviation": "<abrv>",
				"full": "<Title of the work>",
				"authors": [
 					"<your_name_here!>"
				],
				"version": "1.0.0",
				"url": "<where people will go to buy/get it",
				"targetSchema": "1.1.0"
			}
		],
		"dateAdded": 0,
		"dateLastModified": 0
	},
	"action": [
		{
			"name": "<Name of the item>",
			"entries": [
				"<description text>"
			],
			"source": "<your_unique_json>"
		}
	]
}

What you need to understand first: The 5eTools JSON structure

5eTools uses JSON files/data structure to load Homebrew content. Depending on what kind of Homebrew content you want to create, you will need to follow it's schema, which we will try to explain here.

General Structure

JSONSample.jpg

Keys and Values

"key": [ "value" ],

The two primary parts that make up JSON formatted elements are keys and values. Together they make a key:value pair.

Key: A key is always a string enclosed in quotation marks.
Value: A value can be a string, number, boolean expression, array, or object.
Key:Value Pair: A key:value pair follows a specific syntax, are separated by a colon (:) followed by the value. Key:value pairs are comma separated.

Types of Values

  • String: Several plain text characters that are wrapped by quotes.
  • Number: An integer.
  • Boolean: True or false.
  • Object: An associative array of key/value pairs.
  • Array: An associative array of values.

Numbers, booleans and strings are self-evident, so we'll skip over those sections. Arrays and Objects are explained in more depth below.

Arrays

"alignment": [
   "C",
   "E"
]

An array is like a list of one value type and is indicated by the []. An array can be of any value type listed above but it all values inside one array have to be the same. The example above is an array of strings.

Objects

{
 "bar" : "Hello"
}

An object is indicated by {}. Everything inside of the curly brackets is part of the object.

"foo" : {
 "bar" : "Hello"
}

Since an object is a value, "foo" and the following object in the curly brackets is a key:value pair. The key:value pair "bar" : "Hello" is nested inside the key:value pair "foo" : { ... }. That's an example of a hierarchy in JSON data.

5eTools JSON Structure

As mentioned before, 5eTools uses the JSON structure in a specific way and if you want your file to work and render on the site you need to follow a few things.

Types of content

For any type of content you want to make we also have a page that has been created for reference and guidance that you can find here under the "Documentation" column. Here is a quick explanation of the documentation layout with Action as an example.


At the very top you see the skeleton.

"action": [
    {
        "source": "",
        "name": "",
        "page": 0,
        "entries": [
            ""
        ],
        "time": [
            {
                "number": 0,
                "unit": ""
            }
        ]
    }
]

Every skeleton will have all required key:value pairs included. Required key:value pairs are the pairs that need to be included in the object for our site to render it correctly.

Important Note: A JSON validator will not show you an error if you do not include these pairs because this is limited to our site and has nothing to do with the correctness of your JSON structure in general.


After that you will see a section about deeper customization. In the example of the Action-object it's only for the key "time" but for other objects this may include additional key:value pairs that add extra information and so on.

"time": [
    {
        "number": 1,
        "unit": "action"
    },
    {
        "number": 1,
        "unit": "reaction"
    }
]


At the end you will see a handy table called that will show you what key:value pairs are available for the objects, which are required and which optional and what they do.

Field Name Data Type Description Required
name String The action's title True
source String json (_meta's json value) True
entries Array of Strings action description True
page Integer page number within source False
fromVariant Object descript False
time Array of Objects descript False

Other things of note

  • Try to use tabs instead of spaces in the file for legibility/line indents, most editors do this automatically, but mixing them will cause problems down the line. Be consistent.
  • Do not reuse meta names in new documents. Duplication doesn't exist, the cite will ignore one of the duplicates, and you don't get any say on which one remains when there is a conflict around such.
  • Try to tag elements so that the document is dynamic and mouse over tips can bring up the content easily: {@spell Fireball}.
Learn everything you need to know about tags in the Render Demo.
All available tags:@disease, @spell, @creature, @item, @background, @race, @optfeature, @class, @condition, @disease, @reward, @feat, @psionic, @boon, @trap, @hazzard, @deity, @variantrule, @cult, @table

Reference

Schema

As mentioned before the JSON structure we use on this site is unique to this site. That means it follows certain rules which are all described in the Schema. What you find in the Schema we tried to put into the "Documentation"-column of each type of content, but Schema is the first thing that gets updated with changes and so on, so its the most up to date and complete set of rules we have for the JSON structure the site uses. It can be very hard to decipher if you're not familiar with Code documentation, but its a very powerful tool to make your homebrew the best it can be.

Here is the Schema for Action again. You can go over to the documentation page for it and try to figure out what corresponds with what in the schema.

{
	"$schema": "http://json-schema.org/draft-07/schema#",
	"version": "1.1.0",
	"type": "object",

	"properties": {
		"action": {
			"type": "array",
			"items": {
				"type": "object",
				"properties": {
					"name": {
						"type": "string"
					},
					"entries": {
						"type": "array",
						"items": {
							"$ref": "entry.json"
						}
					},
					"source": {
						"type": "string"
					},
					"page": {
						"type": "integer"
					},
					"fromVariant": {
						"type": "string"
					},
					"time": {
						"type": "array",
						"items": {
							"oneOf": [
								{"type": "string"},
								{
									"type":  "object",
									"properties": {
										"unit": {
											"type": "string",
											"enum": ["action", "bonus", "reaction"]
										},
										"number": {
											"type": "integer"
										}
									},
									"required": ["unit", "number"],
									"additionalProperties": false
								}
							]
						}
					},
					"srd": {
						"$ref": "util.json#/definitions/srd"
					}
				},
				"required": [
					"name",
					"entries",
					"source",
					"page"
				],
				"additionalProperties": false
			}
		}
	},
	"required": [
		"action"
	],
	"additionalProperties": false
}

Reference Table

This table will provide you with all that you need to convert any type of content on the site. From documentation to example files and the schema.


Section Name Documentation 5eTools Link Example File(s) Schema
πŸ“‘
Description
Action

πŸ“š

noframes

πŸ’Ύ

[πŸ“‘]

Reference for the mechanical economy of a creature's combat turn.
Adventure

πŸ“š

noframes

πŸ’Ύ

[πŸ“‘]

A playable adventure. Should include maps, event descriptions, etc.
Background

πŸ“š

noframes

πŸ’Ύ

[πŸ“‘]

A background which provides rich content for developing a Character's history, beliefs, and motivations.
Book

πŸ“š

noframes

πŸ’Ύ

[πŸ“‘]

Books are like Compendiums but include more information, 'fluff' and the like.
Bestiary

πŸ“š

noframes

πŸ’Ύ

[πŸ“‘]

Bestiary - Monsters, NPCs and the like
Boon

πŸ“š

noframes

πŸ’Ύ

[πŸ“‘]

Special rewards from Extraordinarily powerful creatures for a character's service.
Class

πŸ“š

noframes

πŸ’Ύ

[πŸ“‘]

Character class information
Class Features

πŸ“š

noframes

πŸ’Ύ

[πŸ“‘]

Features such as Invocations, Fightstyles, or the like.
Collection A Brew with multiple section types defined within it, which doesn't lean more towards any one type.
Conditions

πŸ“š

noframes

πŸ’Ύ

[πŸ“‘]

Conditions and their effects
Creature

πŸ“š

noframes

πŸ’Ύ

[πŸ“‘]

Bestiary - Monsters, NPCs and the like
Cult

πŸ“š

noframes

πŸ’Ύ

[πŸ“‘]

A shadowy organization or guild, usually with a religious cohessive element
Deity

πŸ“š

noframes

πŸ’Ύ

[πŸ“‘]

The gods of the worlds of D&D through various campaigns.
Disease

πŸ“š

noframes

πŸ’Ύ

[πŸ“‘]

Diseases and illnesses.
Feats

πŸ“š

noframes

πŸ’Ύ

[πŸ“‘]

Custom Feats
Hazard

πŸ“š

noframes

πŸ’Ύ

[πŸ“‘]

These are most often enviromental hazards and climate issues, not as simple as traps but still worthwhile.
Item

πŸ“š

noframes

πŸ’Ύ

[πŸ“‘]

Items are the most complicated. Magical and Mundane, Trade goods, Kits, Mounts etc etc etc.
Language

πŸ“š

noframes

πŸ’Ύ

[πŸ“‘]

Sets of written and spoken languages, who speaks them, what font they use, etc.
Magic Variant

πŸ“š

noframes

πŸ’Ύ

[πŸ“‘]

??
Make Homebrew's Monster Traits

πŸ“š

noframes

πŸ’Ύ

[πŸ“‘]

Extensible Sets of Monster trains and feature usable by the Homebrew builder.
Meta tag

πŸ“š

noframes

[ πŸ’Ύ]

πŸ“‘

This is required for each JSON
Monster

πŸ“š

noframes

πŸ’Ύ

[πŸ“‘]

Bestiary - Monsters, NPCs and the like
Object

πŸ“š

noframes

πŸ’Ύ

[πŸ“‘]

Objects are special items, being seige weaponry, explosives etc - usually mundane items that have specific features that exceed simple items but don't really have traditional combat aspects and need special descriptions.
NPC

πŸ“š

noframes

πŸ’Ύ

[πŸ“‘]

Bestiary - Monsters, NPCs and the like
Optional Features

πŸ“š

noframes

πŸ’Ύ

[πŸ“‘]

Optional features are things like Eldritch Innvocations, Powers, etc
Psionics

πŸ“š

noframes

πŸ’Ύ

[πŸ“‘]

Psionics are currently unique to Mystics and are similar to spells.
Races

πŸ“š

noframes

πŸ’Ύ

[πŸ“‘]

Playable races.
Recipe

πŸ“š

noframes

πŸ’Ύ

[πŸ“‘]

These are recipes for cooking/drinking
Reward

πŸ“š

noframes

πŸ’Ύ

[πŸ“‘]

Rewards and Boons, these are extraordinary results.
Ships

πŸ“š

noframes

πŸ’Ύ

[πŸ“‘]

Ships are part of a UA expansion to better identify how naval (space) combat would work.
Spells

πŸ“š

noframes

πŸ’Ύ

[πŸ“‘]

Spells are the magical powers for spellcasters, being divided into 10 tiers of power (cantrips + 1..9 level spells)
Subclass/Archetype

πŸ“š

noframes

πŸ’Ύ

[πŸ“‘]

Subclasses for an existing class
Table

πŸ“š

noframes

πŸ’Ύ

[πŸ“‘]

Tables can be random result tables or just a means to store data in a more helpful way.
Trap

πŸ“š

noframes

πŸ’Ύ

[πŸ“‘]

Traps and Lair like features that threaten characters - most often without combat resolutions.
Variant Rules

πŸ“š

noframes

πŸ’Ύ

[πŸ“‘]

These are sets of Rules for 5e that are House Rules, or expansions of existing rules - like crafting, mass combat/warfare, Strongholds and Travelling
Vehicles

πŸ“š

noframes

πŸ’Ύ

[πŸ“‘]

Ships are part of a UA expansion to better identify how naval (space) combat would work.

If you want to see the code of any 5eTools element you can also do this:

Click: Shift + LMB

Walk through of Creating Homebrew

Step by Step instructions on how to convert your homebrew:

Reminder: If you plan on making this brew public through the Homebrew Manager please use the #Brew-Tracker Channel and Bot on Discord to track the brew as being converted, to avoid duplicate work.
Just an editor is all you need if you can't make sense of the rest.
  • Find references
I.e., example files from the repo or anything else listed in the "Reference"-section above.
  • Now start the conversion:
  • Make the Meta header for your file. One of these is required for each JSON file.
  • Now repeat:
1. Use the skeletons or example files to slowly copy and paste and/or fill our your file.
Recommended: Use an example file and render it on the site, now look at the code and see what elements from the site correspond with what section of the code. Then change it to what you want that section to look like for your own homebrew. If you don't understand something look into the documentation for that type of content in the Reference Table or ask the community over on the #Brew-Conversion Channel on Discord.
2. Use a Validator tool and fix all errors.
3. Upload the brew through the Homebrew Manager to see if it also renders correctly on the site.
Not needed, if the file works fine you can go ahead and submit it to the repo if you want.
  • (Optional) Submit to the repo through a Pull Request to keep the file up to date through site changes.
If you don't know how to do that join us over on the #Brew-Conversion Channel on Discord and ask for instructions.
You have the option to make your homebrew hidden in the repo, so it isn't available through the Homebrew Manager. Its also worth mentioning that it doesn't matter how "good" your conversion is, nobody will judge you for what you upload to the repo.