PDFoundry

User Manual
For v0.7.X

If you’re seeing this - it means your system now supports PDFoundry, a FoundryVTT PDF reader. This
guide goes over the features available and their use. This user manual also functions as a demo, and you can
always access it through the settings menu, if you wish to do so later.

Contents
1 Creating & Opening PDFs 2
1.1 Adding a PDF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
1.2 Context Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

2 Rich PDF Links in Journals & Editors 4

2.1 Permissions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

3 Form Fillable PDFs 5

3.1 Form Fillable (Unlinked) PDFs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
3.2 Form Fillable (Actor Sheet) PDFs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

4 Data Paths 6

1
5 Settings 7
5.1 PDF Cache Size . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
5.2 Show Shared PDFs in Existing Viewer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

1 Creating & Opening PDFs

Once you’ve installed PDFoundry, you’re almost ready to view a PDF - the only thing you’ll have to do is
tell PDFoundry where to find it, and what type of PDF it should be opened as.

1.1 Adding a PDF

This section outlines basic steps required to adding a new PDF and outlines what each PDF setting does.

Step 1 Open the Journal Entries and click Create PDF. Enter a Name, in Figure ?? I’ve chosen to
add the core rule book for the RPG Lancer (available for free online!), so I’ll name this one Lancer
Core Rulebook. Select PDFoundry PDF for the Type drop-down, then click Create Item.
Step 2 After you’ve hit Create PDF the PDF Config should open automatically and look something
like Figure 1. You’ll also see the PDF get placed in your Journal Entries, as in Figure 2. There are
a bunch of fields on the PDF Config, PDF Name is already filled in for us (but we can change it if
we want!). Next let’s fill in all the fields.

Figure 1: The PDF Config

PDF Code This is a short (usually five characters or less, but as many as you want) identifier you will use
in most systems. Systems with support for PDFoundry (or modules that add support for PDFoundry
to a system) may make use of this as a short-hand to open PDFs or display links.

PDF URL This is the path to the PDF on your server. The browse button will allow you to select or
upload a PDF from your computer, or choose a PDF from a S3 bucket.
Page Offset Some PDF files have extra pages before the first page, such as a title or an unnumbered index
page. You can use this to synchronize the PDF page to the book page. The Lancer book doesn’t need
an offset, so it’s zero here.

2
Enable Caching Tick this box to enable caching for this PDF. Caching will help PDFs load signifi-
cantly faster after the first time they are loaded by preserving a copy locally on the user’s computer.
To preload PDFs, this must be enabled.
PDF Type PDFoundry supports three types of PDFs - Static PDFs, Form Fillable (Unlinked) PDFs,
and Form Fillable (Actor Sheet) PDFs. If you don’t want any interactive elements like you may find
in some character sheets, select Static for now. The difference between Form Fillable (Unlinked)
PDFs and Form Fillable (Actor Sheet) PDFs is explained in Section 3.
Step 3 Now that we’ve entered all our settings in, we can use the Test Settings button to open the PDF
to page 5. We want the PDF to open to page 5 of the book, so that when we have a page reference it
opens to the correct page. Play around with the offset until the viewer opens the PDF to the correct
pages.
That’s it, we’ve added a new PDF!

1.2 Context Menu

We saw the PDF appear in the Journal Entries earlier, when we created a new PDF. Figure 2 shows the
context menu options for PDF items, and highlights two import elements. You can open the context menu
with right click. There are a bunch of options that you as the GM can see, while players will only be able
to see the Open PDF option, provided they have permissions of at least Observer.

Figure 2: The PDF Sidebar & Context Menu

Left Clicking the blue area will open the PDF Config window. Right Clicking it will open the context
menu. Left Clicking the red PDF thumbnail will open the PDF to the first page, which can save you a
click.
Open PDF (All Users) This one should be mostly self explanatory. It won’t show up unless the PDF
URL has been fully configured in the PDF Config window. Clicking on it opens the PDF to the very

3
 first page. Note that you can’t open Form Fillable (Actor Sheet) PDFs this way, they have to be
opened with the actor.
Preload PDF (GM Only) Click on it will immediately cache the PDF on all connected users’ computers.
This may be advantageous in cases where you expect to often use a single large book and don’t want
users downloading the PDF files to interrupt other goings on in the game.
Delete (GM Only) This will irrevocably delete the link to the PDF file. The PDF file itself is not affected.
Duplicate (GM Only) This will duplicate the link to the PDF file by creating a copy of the journal entry.
Configure Permission (GM Only) This will allow you to grant visibility of the PDF to players, either
individually or all players. The permissions work much like permissions for other things in Foundry;
however, if the PDF is visible to the player at all (that is if their permissions are anything except ’None’)
the user will be able to right click on the PDF to open it, and any other links to the PDF will function
correctly (such as ’open to page’ links added by a system).
Export Data (GM Only) This will allow you to export a file that can later be used with the Import Data
option.
Import Data (GM Only) This will allow you to import the settings for a PDF (Name, Code, URL, etc)
from a file created with the Export Data option.

2 Rich PDF Links in Journals & Editors

Once we’ve added a PDF to Foundry, it can be embedded in journals and other rich text editor areas added
by systems in items, actors, and more. You can quickly create a PDF link by dragging and dropping a PDF
item from the Journal Entries, which will create a link to the first page of the PDF. You can then adjust
the page to a page of your choosing.
The format for a rich text link in a Journal or Item Sheet is as follows.
@PDF[Core Rulebook|page=135]{Combat: Grappling & Shoving}
PDF Source Page Link Text

Figure 3: The PDF journal link created from the above example.

PDF Source This specifies which PDF should be opened, and can be either a PDF Name or PDF Code.
Page (Optional) This specifies which page should be opened. You can omit this option and the PDF will
be opened to the first page. If you were to omit the page from the example above, the example would
be changed to look like this, and would open the ”Core Rulebook” to the first page.

@PDF[Core Rulebook]{Combat: Grappling & Shoving}

PDF Source Link Text

Link Text The link text field specifies what text should be displayed. It supports rich text, so you can have
bold links, underlined links, header links, and more. Unicode characters and emoji are also supported.

4
2.1 Permissions
A quick note on permissions - PDF links in journals will only be displayed to those with the ability to see
the PDF in the Journal Entries. If a player is unable to see the PDF, they will instead see the link text
by itself and no link will be rendered. An example of what this looks like is shown in Figure 4.

Figure 4: The PDF journal link created from the above example as seen by a player who cannot view the
specified PDF.

3 Form Fillable PDFs

Support for Form Fillable PDFs is the largest and most ambitious feature that PDFoundry supports. You
can almost entirely make use of existing PDF character sheets, inventory trackers, and more.
Please note that ’JavaScript’ areas are not supported at the moment, so currently you cannot set up
automation.
Two types of Form Fillable PDFs are available - Form Fillable (Unlinked) PDFs and Form Fillable
(Actor Sheet) PDFs.

3.1 Form Fillable (Unlinked) PDFs

Unlinked PDFs contain form fillable elements and save the data contained within those elements. However,
they save the data once per PDF. That is, all users who view the PDF will see the same data, and changes
will be synchronized between all viewing users, but there is no way to link the data with an actor or instance
it in any way. This type of PDF is useful for party inventory sheets, board game sheets, and any other type
of PDF where you want only a single copy of the data on the PDF.

3.2 Form Fillable (Actor Sheet) PDFs

This is the more complex but potentially more useful type of form fillable PDF. It allows you to use a form
fillable PDF to act as an actor sheet! PDFoundry is even capable of synchronizing the data with the game
world in real time, so with a little bit of effort, you can edit a form fillable PDF so it reflects changes to an
actors HP or have it display system specific information.

3.2.1 Linking an Actor

Once you’ve created a Form Fillable (Actor Sheet) as outlined in the section on creating a new PDF,
open the actor you wish to use the sheet for and click the Sheet button on the title bar as shown in Figure 7.
After, select ”pdfoundry.PDFActorSheetAdapter” from the drop-down as shown in Figure 6. The top drop-
down will let you select the sheet for an individual actor, while if you wish to use PDFoundry for all actors,
select it for the bottom drop-down as well.

Figure 5: Select the Sheet here.

5
 Figure 6: Foundry VTT Sheet Configuration

You’ll see a blank sheet should come up. The header for this sheet should look pretty similar to the
header from the last one. This time you’ll notice two new buttons Inspect Data and Sheet Select.

Figure 7: The PDFoundry Actor Sheet Header

Sheet Select (Red, GM Only) This will allow us to tell PDFoundry which of the configured PDF sheets
should be used to display this actor. You’ll want to set a sheet for PDFoundry to use when you first
set the actor to be opened by PDFoundry, otherwise it will open to a blank viewer.
Inspect Data (Blue, GM Only) Will allow us to see data paths PDFoundry will recognize and their current
values. For more of an explanation, see Section 4: Data Paths.

4 Data Paths
Finally there’s the Inspect Data button found at the top of PDFoundry actor sheets, which will give you the
special names (called data paths) that may be used for the fields that will be synchronized with Foundry.
These are system specific, and their value is listed next to them so you can play around and find which you
are looking for.
For example, if you want to set up a character sheet with the ”Simple Worldbuilding” system to re-
flect changes to current and maximum hit points, you can use the data paths ”data.health.value” and
”data.health.max” for current and maximum hit points respectively. You use the name attribute when you
edit the PDF in Acrobat (or whatever other editor you use). So, to reiterate - a value of data.health.value
would synchronize the field’s value with the actor’s current hit points only in the ”Simple Worldbuilding”
system. Again, see the Inspect Data window for system-specific paths.
Note these paths are only viewable when data currently exists there, so you may see them appear and
disappear as you make edits to the actor with a normal actor sheet if the system does not place some value
there by default - this may or may not be improved in the future.
Note that any other data path will work (so you could set the name attribute of a field to ”FooBar”, and
it would save and load just fine), but will only the special data paths visible in the Inspect Data window will
be synchronized for use in the game world natively (without some programming knowledge, at least). That
means you can use a form fillable sheet as-is, but with a little work you can make it pretty dynamic. The
only other special data path that is available at the moment is name, which is used for the actor’s name (so
you would set the name attribute of the field to the value name when you edit the PDF in Acrobat).
Note there will likely be improvements to this helper window in the future.

6
 Figure 8: The Inspect Data Window

5 Settings
There two settings at present for PDFoundry. They are located with your system settings in the Game
Settings > Configure Settings > System Settings menu.

5.1 PDF Cache Size

This allows individual users to set how much hard drive space should be allowed to be taken up by the
PDF cache. When this amount is exceeded, PDFoundry will prune existing cached PDF files in reverse
order of most recently accessed. That is to say, PDF files will be removed from the cache starting with
the file that has least recently accessed.

5.2 Show Shared PDFs in Existing Viewer

With this setting enabled, when a user opens a PDF for you with the ’Show to...’ button on the top
of the PDF viewer, the PDF will open in your existing viewer if you are already looking at the PDF.