Homebrew: Adding Content

From 5etools Community Wiki
Jump to: navigation, search

framless
v1.1.0

Homebrew

In this brief documentation you will find details that can help you to create your own homebrew content for use within 5etools, and perhaps to build out the community repository, which contains numerous examples as reference for creating additional content.


You will need


and with that you will make something like....

... this (a quick example)
{ 
	"_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>"
		}
	]
}


(its easier then you think)


There are a number of tools as part of the site that make creating homebrew just like filling out a form; or just copy & pasting from Homebrewry/GMbinder. CritterDB to export to 5etools format. Use one of the DnD Beyond scrapers to pull from there. The Roll20 converter. Forth coming converter FROM Foundry.
BUT because so often homebrew includes the concept



The structure behind 5etools' homebrew files. JSON

5eTools uses JSON files/data structure to load Homebrew content. If you're not familiar with them here is an overview of JSON, which explains briefly how it works. Depending on what kind of Homebrew content you want to create, you will need to follow it's '''schema'''. Below you will find a list of all the different content types, with the necessary links.


Before you start converting homebrew, however, you will want to take a look at the Meta Tag. It is necessary in every homebrew file, otherwise it will fail to load.


Logical Units

JSONSample.jpg
The data is broken into logical units (Objects and Keys / Pairs) these are are better defined in the Adding Content page.


Because computers require Data to have precise structures. So your Homebrew must work within those structures and Pass JSONLINT validation, and then additionally 5eTools Validation. (More information here).


Each object is defined below for reference, and in each such page describing them you will have a set of tools for making them


Homebrew examples.png



OBJECTS

Each Object will have Key/Pairs; some of which are noted as REQUIRED. (in bold text and marked at TRUE in the table)
If you fail to define (include) a required Object; the file may will pass JSONLint, but will fail to work on the site (we'll mention this again, so while that may make NO SENSE, you've been introduced now so you that you'll feel super smart when we mention it later)


An example of a such an object definition is provided.
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


If you look into the table (This one is for the ACTION object) you will see that there are three keys that are required (name, source, entries); the others are not.


If you are not familiar with the Data Types:
Data Type Description Example
String This is a set of alphabetical and numerical values contained in quotation marks This is a string value.
Integer A number and ONLY numbers 10
Object Objects are containers for Keys (see notes)
Array of <Data_Type> This is a structure of holding multiple values for a specific data type under that Key array of integers
"keyname": [1;2;3;4;5]
array of strings
"keyname": ["1"; "a"; "1a"; "purple"; "none"]


If the structures above are completely unfamiliar to you - revisit the JSON overview on when semicolons are used; when brackets []; curly brackets {}; are discussed.
Understanding when you use them and how they interact is something that comes with use and experiencing the errors from misusing them. Don't be discouraged if you don't get it immediately, there are tools that will help point you in the correct direction. (JSONlint).



Reference

Schema

The JSON information has a set of rules it must follow; each site or even each JSON can be required to follow a specific structure. This set of rules are called Schemas.
(This is why a JSON from Roll20 doesn't necessarily work with Herolab, why CritterDB or Gifflglyph's monster creator all don't seem to automatically work with Foundry, Roll20 or even 5etools.)
{
	"$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
}


that one is for Actions; and while it may not make sense. Once you become more familiar it can be helpful to see what keys are usable for that object.
For simplicity's sake, note that action schema shows


"required": [
	"name",
	"entries",
	"source",
	"page"
],


this is where we can see requirements; and definitions for Data Types and values.
Again, this may not make a lot of sense at this point, but by introducing you to the resources and patterns the data structures and tools to learn what is possible you will rapidly gain functional knowledge so when something in your attempts to convert content that doesn't match the pattern of a RAW structure, you can attempt to test structures and now to 'nudge' it into the 5etools JSON structure.


Working Examples

Each of the objects have in the reference a link to examples for the object's structure with both sample (simple) examples; and more complicated functional examples from the Homebrew Repository.

Walk through of Creating Homebrew

You now have a basic foundation, and its time to apply that information to create homebrew


Online Tools

When creating Homebrew there are number of tools.
To convert homebrew into 5eTools you will:
The following is a listing of common used applications for homebrewing content on 5eTools. They are text editors with some additional features to help with coding.
Each will list ; Where to download them (πŸ’Ύ), and how to configure them (πŸ“).
Online: The 5eTools Website
Client


Reminder: please register/List your homebrew on the Tracking Worksheet
fix any errors that occur until it passes successfully
  • Attempt a upload through Manage Homebrew
  • Test each section that was added
fix any errors that occur until it passes successfully
  • Have your conversion peer-reviewed
  • Submit to the Repo.
Through a Pull Request (preferred)
Or posting the file in the Discord Community's #Brew Conversion Channel and tagging an (@Support; @brewer @Giddy; or )



DOCUMENTATION TOPICS

Read more about the different documentation topics that go into a little more detail:
  • Anatomy of the Element
  • Extending Elements
  • Character Options
  • References
Templates
A list of blank templates that can be filled out to create your own homebrew.
Schema
5eTools Respository
Hosting your own Content Repo
Tools
Tools that assist in creating and converting content into 5eTools schemata.
Homebrew LEXICON
Commmands and Codes that are available




Master Schemata


Additional REQ Schemata



Section Name noframes Example File(s) Template Schema
πŸ“‘
Tool(s) 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.
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.
entry templates are not linked yet, still testing.

Formatting


How to add Existing Homebrew to the site


The community has created a number of files that work with the system, adding custom (homebrew) content to the site's data.
  • 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)