Books, Packaging, Pins & Included Content
Managing pins is one of the trickiest aspects of building a package and we get lots of questions around how to make things work. Hopefully this article will help provide some insights on this, and included content in general, to make that easier.
One of the goals with Pins and Encounters is to make it possible for packages to build on top of each other. If someone builds a cool map or adventure, then we want to allow others to add points of interest, adventure add-ons, or map details to enrich the experience. Additionally, we want to make sure that building a package doesn’t end up including excessive amounts of content by chasing through pins, maps, books, and encounters.
Book Contents
While it is tempting to think that books contain entries like, maps, monsters, or encounters, they in fact don’t technical contain any of those and really only include the text of the book and pointers to other entries. Additionally, there are some things like pins or encounters that are not contained at all, but instead pins and encounters point to books.
Each chapter, section or subsection of a book can included references to other content. The “Pick Content” menu in the book allows you to add and update these references. The referenced content is displayed in the book. Because it is referenced it means that when those entries are changed outside of the book that what is shown in the book.
Pins
Pins can include references to books. When viewing a book the list of pins referencing a specific section of the book are shown with the map icon. Since pins can have multiple book links allowing a pin to show up in different parts of a book or even in multiple books. This also means that adding a link from a pin to a book requires modifying the original pin. This can cause problems if you want to extend something published from another package or publisher since you may not have permission to publish that modified pin and if you do there could be conflicts in the future if the original publisher modifies the pin.
Encounters
Encounters also include a reference to a book. Ideally this is the location in the book that describes running the encounter. Encounters also include a reference to a pin. This means that it is possible to add an encounter to an existing pin without modifying the pin. Using this a publisher can add new encounters to an existing pin to extend someone else’s adventure, maybe to add different difficulty encounters.
Packaging a Book
So what goes into a package when building a package based on a book? Building a package is really a two step process behind the scenes. First, a list of all referenced content is generated, and then referenced content is either included in the package or listed as a dependency.
Referenced Content
Referenced content includes both direct content and some dependent content.
Direct Content:
Content referenced and displayed in a book using the “Pick Content” menu.
Pins that point to the included book.
Encounters that point to the included book.
Dependent Content:
Artwork for maps, including alternate map images.
Artwork and tokens for monsters, pre-generated characters, items and other types that include artwork.
Monsters, and tokens for creatures and map tokens used in the encounter.
Pins referenced by encounters.
Monsters from random tables.
Pins on an included map.
Pins that have a link to an included map.
Note that dependent content can be recursive. For example, a monster found in an encounter would then also find the artwork for the monster.
Embed vs. By Reference
Once all of the referenced content is found, there are two ways to handle that content: Embed or Reference.
Embed: this includes a copy of all of the content. A user will always have this content available to them when they get the package. Note: publishers can prevent this to restrict people from republishing their content.
Reference: this content won’t be included in the package, but will instead list a dependency on the package. For the new package to work the user will have to have a version, typically by having a copy of the referenced package.
How to choose?
If the content is from the SRD, choose embed. This content will always be available and will ensure that the user always has the most recent published version.
If the content is from another publishers package, choose reference. This will support the publisher and in some cases may be required due to the publisher restricting.
If the content is from another package that you publish, then you have more options.
If you are building standalone content and want the user to have everything they need, choose embed.
If you are building on another package/product and want the user to have or purchase that package/product, choose reference.
For products in the marketplace the user will be prompted to purchase any missing content. If you just share the package then you will need to communicate dependencies with the user.
Copying a Book
Because of all of the type of references it can be hard to figure out what happens when you copy a book. There are also two different ways of copying a book that behave differently.
Create New Book Copy
Creating a new book based on another book produces the most basic type of copy. The new book will include all of the content where the book points to the content, which is the content created with “Pick Content”. The new book will mostly look the same but will be missing all of the cases where pins or encounters point to the book. Effectively this means that there will be no pins or encounters in the new book.
Insert Book
If you insert a book contents into another book using the “Insert Book” menu on a chapter, the behavior is a bit different. The assumption is that you want to combine books, including pins and encounters. In addition to the normal create a new book behavior, “Insert Book” also changes all of the encounters and pins that pointed to the original book to instead point to the new book.
Hopefully this provides some advanced insights into how books and packages work together.