Difference between revisions of "Homebrew: Adding Content"

From 5etools Community Wiki
Jump to: navigation, search
(DOCUMENTATION TOPICS)
m (Reorganization of the page)
 
Line 1: Line 1:
 
{{HomebrewHeader}}
 
{{HomebrewHeader}}
= 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 [https://github.com/TheGiddyLimit/homebrew repository], which contains numerous examples as reference for creating additional content.
 
: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 [https://github.com/TheGiddyLimit/homebrew repository], which contains numerous examples as reference for creating additional content.
----
+
 
<br>
 
 
<div style="margin-left: 30px">
 
<div style="margin-left: 30px">
==You will need==
+
=You will need=
 
:
 
:
 
::* [https://wiki.5e.tools/index.php/Homebrew:_Resources#Editors A Text Editor]
 
::* [https://wiki.5e.tools/index.php/Homebrew:_Resources#Editors A Text Editor]
Line 51: Line 49:
 
:: 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.  
 
:: 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
 
:: BUT because so often homebrew includes the concept
<br>
 
  
----
 
 
</div>
 
</div>
  
=='''The structure behind 5etools' homebrew files. JSON'''==
+
=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 [[Homebrew: JSON Overview|'''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.
 
: 5eTools uses JSON files/data structure to load Homebrew content. If you're not familiar with them here is an [[Homebrew: JSON Overview|'''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.
Line 63: Line 59:
 
<br>
 
<br>
 
<div style="margin-left: 30px">
 
<div style="margin-left: 30px">
===Logical Units===
+
==Logical Units==
 
[[File:JSONSample.jpg|220px|right|frameless]]
 
[[File:JSONSample.jpg|220px|right|frameless]]
  
Line 76: Line 72:
  
 
<br>
 
<br>
===OBJECTS===
+
==OBJECTS==
 
: Each Object will have Key/Pairs; some of which are noted as '''REQUIRED'''. (in bold text and marked at TRUE in the table)
 
: 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)
 
: 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)
Line 124: Line 120:
 
</div>
 
</div>
 
----
 
----
==Reference==
+
=Reference=
 
<div style="margin-left: 30px">
 
<div style="margin-left: 30px">
===Schema===
+
==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.
 
: 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.)
 
: (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.)
Line 216: Line 212:
  
 
<br>
 
<br>
=== Working Examples===
+
== 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.
 
: 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.
 
</div>
 
</div>
----
 
  
 
=Walk through of Creating Homebrew=
 
=Walk through of Creating Homebrew=
Line 238: Line 233:
  
 
<br>
 
<br>
:::: ''Reminder: please register/List your homebrew on the [https://docs.google.com/spreadsheets/u/1/d/1-STwoZlnscd6NyTtSakgFYp6unBgMNaHacmpUTklvYc/edit '''Tracking Worksheet'''] ''
+
:::: ''Reminder: please register/List your homebrew on the #brew-tracker channel in the [{{5eTCommunitylink}}| '''Discord Server'''] ''
 
::* Open what you're going to be using for the [[Template:Homebrew: ReferenceTable|Editor / Construction Tool]]
 
::* Open what you're going to be using for the [[Template:Homebrew: ReferenceTable|Editor / Construction Tool]]
 
::* Develop [[Homebrew: Meta| '''META header''']]
 
::* Develop [[Homebrew: Meta| '''META header''']]
Line 253: Line 248:
  
  
----
+
==Documentation Topics==
===DOCUMENTATION TOPICS===
 
 
:: Read more about the different documentation topics that go into a little more detail:
 
:: Read more about the different documentation topics that go into a little more detail:
  
Line 278: Line 272:
 
:::: Commmands and Codes that are available  
 
:::: Commmands and Codes that are available  
  
:''' '''
+
==Reference Table==
:::
+
In this table you will find links to all the different types of content you can add to the website.
  
 +
{{Homebrew: ReferenceTable}}
  
<br/><br/>
+
:::''entry templates are not linked yet, still testing.''
  
 +
=Formatting=
  
{{Homebrew: ReferenceTable}}
 
:::''entry templates are not linked yet, still testing.''
 
  
==='''Formatting'''===
+
=How to add Existing Homebrew to the site=
  
<br>
 
===How to add Existing Homebrew to the site===
 
<br/>
 
 
: The community has created a number of files that work with the system, adding custom (homebrew) content to the site's data.
 
: 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''',  
 
::* Go to the website and choose '''Utilities''',  
Line 300: Line 291:
  
 
<br/>
 
<br/>
----
 

Latest revision as of 11:28, 7 January 2021

framless
v1.1.0

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 #brew-tracker channel in the Discord Server
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:
  • References
Templates
A list of blank templates that can be filled out to create your own homebrew.
Schema
Master Schemata
Additional REQ Schemata
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

Reference Table

In this table you will find links to all the different types of content you can add to the website.


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.
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.
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)