Ever wished you could add a 'Sanity' score, 'Honor' points, or any other custom stat to your character sheet that your system doesn't offer? Introducing Custom Fields, the ultimate system-agnostic tool to add fully functional fields to any Actor or Item sheet. Go beyond simple text boxes: create fields with automatic formulas (e.g., #system.abilities.str.mod# * 2), link them as token bar resources, display them as counters on item icons, and set fine-grained view/edit permissions for players and GMs.

Stop hacking your character's biography and give your homebrew rules the first-class integration they deserve!

What is Custom Fields?

Custom Fields is a powerful and intuitive module that allows Game Masters to add new, custom-tailored data fields directly onto Actor and Item sheets. It's designed to be completely system-agnostic, meaning it works seamlessly with the vast majority of game systems available on Foundry VTT. Whether you need a new resource, a special counter, a place for notes, or decorative banners, this module makes it possible with just a few clicks.

Key Features

Versatile Field Types: Create the exact field you need:
- Short Text: For titles or simple labels.
- Long Text: For detailed descriptions or notes.
- Number: For any numerical value.
- Value/Max: For resources like HP, Mana, or Energy (e.g., 12/20).
- List (Dropdown): For a predefined list of options.
- Image: Add visual elements to your sheets! Configure aspect ratios (Square, Portrait, Banner, etc.) and set default images. You can even link this field to update the Actor/Item's main Portrait/Icon automatically.
- Checkbox: For simple Yes/No or On/Off toggles.
PDF Import & Conversion: Turn any fillable PDF into a functional character sheet instantly!
- Auto-Conversion: The module reads text inputs, checkboxes, and images from the PDF and creates the corresponding fields for you.
- Backgrounds: It automatically extracts and sets the PDF pages as the background for your containers.
- Dedicated Editor: Use the exclusive "PDF Fields" configuration window to tweak positions, permissions, and layout without cluttering your standard field settings.
- Smart Merging: Combine fragmented PDF lines (like multi-line text boxes) into single logical fields using the "Merge Down" feature.
Advanced Layout & Tabs: Organize your fields with powerful tools:
- Containers: Group fields together and configure widths (Quarter, Third, Half, Full, or Fill Available Space) to create multi-column layouts.
- Tabbed Interface: Toggle the "Display with Tabs" option on a container to transform its children into a clean, horizontal tab bar. Perfect for organizing complex sheets without clutter.
- Drag and Drop: Nest containers up to 4 levels deep and reorder fields easily.
Synchronized Fields (Formulas): Formerly known as "Formula Fields," these allow you to define fields that automatically calculate their value based on other data in the actor's sheet. The result updates dynamically whenever the source data changes.
- Features a "Picking Mode": when editing a formula, simply click on another field on the sheet to automatically insert its path. Also supports advanced math functions like round(), roundup()/ceil(), rounddown()/floor(), and specifying decimal places (e.g., round(10/3, 2)).
- Example: Create a "Carry Bonus" field with the formula #system.abilities.str.mod# * 2.
Dedicated "Custom Fields" Sheet: The module now adds a specific Sheet called Custom Fields. You can select this sheet for any Actor or Item to display only your custom fields.
Actor Resources (Token Bars & Macros): Mark any Number or Value/Max field as an "Actor Resource." This makes it instantly available in the token configuration to be linked to a token's resource bars. Once created, these resources can also be referenced in macros or chat commands just like any other system attribute (e.g., @custom-fields.honor.value).
Item Counters: Make a numeric field on an item display as a small counter over its icon in a character's inventory. This is ideal for tracking ammo, potion doses, or magic item charges at a glance.
Full Custom Mode for System-Agnostic Sheets: For ultimate control, you can enable "Full Custom Mode" in the module settings.
- This mode hides all native sheet elements, allowing you to build a character sheet from scratch using only your custom fields and containers.
- Use the "Advanced Protected Selectors" setting to specify native elements (like .sheet-header) that you wish to keep visible.
- An optional "Force Activate Protected Tabs" setting ensures any sheet tabs you protect remain visible and functional.
Granular Permissions: Control exactly who can see and who can edit each individual field. You can set permissions based on document ownership (Observer, Owner) and user role (Player, GM).
- You can also set permissions for entire Containers, allowing you to hide whole sections of a sheet based on the user's role.
Intuitive Configuration: All fields are managed through a clean, easy-to-use settings menu. Reorder fields with drag-and-drop, easily add or delete them, and configure all options in one place.
Workflow Power Tools:
- Import/Export: Share your creations! You can export your Actor or PDF configurations to JSON files to back them up or share them with the community.
- Duplication: Speed up creation by using the "Duplicate" button to clone fields or entire containers (including their children) instantly.
- Auto-Cleanup: An optional setting helps keep your data clean by removing flags from actors when the corresponding field is deleted from the configuration.

When to Use Custom Fields?

The possibilities are limitless, but here are a few common scenarios:

Homebrew Mechanics: Add and track system-wide rules like Sanity, Honor, Reputation, or Doom Points.
Custom Resource Tracking: Create dedicated fields for class resources not native to the system, such as a Monk's Ki, a Barbarian's Rage, or a Sorcerer's spell points.
GM Information: Keep secret notes, plot triggers, or tactical information on NPC sheets, visible only to you.
Detailed Item Management: Track charges on a magic wand, the number of special arrows in a quiver, or the expiration of a potion.
Enhanced Roleplaying: Add fields for character Bonds, Ideals, Flaws, or personal goals to keep them front-and-center during gameplay.
Clean Sheets: Use the "Custom Fields Sheet" to create a simplified handout-style character sheet for rules-light games.

How to Use

Getting started is easy. Follow these steps:

1. Enable Document Types

Before creating fields, you must tell the module which sheets to modify.

Go to Settings -> Custom Fields.
Find and click Configure Types.
Select the Actor and Item types you want to add fields to (e.g., "character", "npc", "weapon").
Save changes.

2. Create Your Fields & Containers

Go back to the Custom Fields settings and open either Configure Actor Fields or Configure Item Fields.
Click Add Field to create a standard field, or click Add Container to create a layout group.
For fields, set a Display Label and choose a Data Type (Text, Number, etc.).
For containers, set a Display Label and a Width to control its layout behavior.
To organize, simply drag and drop fields (or other containers) into the dashed drop area within a container to nest them.

2.5. (Optional) Import a PDF

Go to Settings -> Custom Fields -> Convert PDF Sheet.
Upload a fillable PDF form.
Choose whether to Replace existing PDF fields or Append (keep existing pages).
The module will generate the layout. You can then fine-tune it in the Configure PDF Fields menu.

3. Configure Special Features

To create a Formula:
1. Check the Sync Data Paths box.
2. The field on the character sheet will now store mathematical formulas using data paths.
3. Rule: Always wrap data paths in hashes (#...#), like #system.abilities.str.mod#. Do not use @.
To create a Token Resource (Actor Fields Only):
1. Set Data Type to Number or Value/Max.
2. Check the Set as Resource box.
3. Save the settings (the world will reload).
4. Now you can open a Token's configuration and find your new field in the "Resource Bars" dropdown menus.
To create an Item Counter (Item Fields Only):
1. Set Data Type to Number.
2. Check the Enable Counter box.
3. Configure its position and color.
4. Now, any value greater than 0 in this field will appear as a number on the item's icon in an actor's inventory.

4. Automation: Running Macros from Fields

You can link any field to a Foundry Macro, creating buttons to roll dice, check attributes, or trigger scripts using the field's current data.

Enable: In the field configuration, check the "Run Macro" box.
Link: Paste an existing macro name or UUID.
Use: A dice icon will appear next to the field label (or inside the Right-Click Context Menu).

Using Data in Macros: When the macro is triggered, the module passes relevant data to it. The method depends on the Macro Type:

A. Chat Macros (Simple) Use the following placeholders in your chat command. The module will replace them before execution.

@value: The current value of the field.
@label: The name of the field.
@actor: The name of the actor.
@uuid: The uuid of the actor.
@path: The data path (flag) of the field.

Example:

/r 1d20 + @value # Rolling @label for @actor

B. Script Macros (Advanced) For Javascript macros, variables are injected directly into the execution scope. You can use them immediately:

value: The value of the field (Number or String).
label: The label of the field.
actor: The Actor document Name.
uuid: The Actor document UUID.
token: The Token document instance (if available).
path: The flag path string.

Example:

// A simple check macro
if (value >= 10) {
    ui.notifications.info(`${actor.name} passed the ${label} check!`);
} else {
    ChatMessage.create({ content: `${actor.name} failed. Value ${value} is too low.` });
}

5. Choose Your Sheet Style

Native Integration: By default, fields appear at the top of the standard sheet.
Custom Sheet: In the Actor's sheet header click "Configure Sheet" and select Custom Fields to see only your fields.
Full Custom Mode: Enable this in settings to force the native sheet to hide its own elements, leaving only your fields (useful for partial overrides).
4.1 (Advanced) Enable Full Custom Mode
- Go to Settings -> Configure Settings -> Custom Fields module settings.
- Check Enable Full Custom Mode to hide all native sheet elements.
- Use the Advanced Protected Selectors field to keep specific elements visible. For example, to keep the character sheet's header, you would enter .sheet-header.
- If you are protecting a sheet tab and its content is not visible, enable the Force Activate Protected Tabs option.

6. Save and Enjoy!

Click Save Changes.
Open an Actor or Item sheet of an enabled type, and your new fields will be there!

FAQ (Frequently Asked Questions)

Q: What is the difference between a "Number" field and a "Synchronized" field?
- A: A Number field is static; you type a value, and it stays there. It supports math operations and formulas (typing 1+5 sets 6 to the current value). A Synchronized field is dynamic; you write a formula (like #system.attributes.hp.max# / 2), and it updates automatically whenever the referenced HP changes. You cannot edit the result manually.
Q: How do I make the tabs work?
- A: Create a Container and check "Display with Tabs". Then, create other Containers inside it. Each direct child Container becomes a tab. You can assign icons to these child containers to appear on the tab bar.
Q: My Image field isn't updating the Token!
- A: Ensure you have checked "Use as Portrait" in the field configuration. The synchronization happens when you change the image or when you open the sheet.
Q: Will this work with my game system?
- A: Most likely, yes. The module injects HTML into standard sheets. If your system is heavily customized, try enabling "Compatibility Mode" in the module settings.
Q: How do I reference my new fields in macros or other modules?
- A: There are two ways:
  1. Attribute Key (Easy): If you've marked a field as a Resource, you can reference it with @custom-fields.field-id.value. You can get the exact ID from the "Copy Attribute Key" button (@) in the settings.
  2. Flag Path (Advanced): All fields are saved as flags. You can access them via flags.custom-fields.field-id. Use the "Copy Field Path" button (📋) in the settings to get the precise path.
Q: I created a field, but it's not showing up on the sheet.
- A: Check these three things:
  1. Did you enable the correct Actor/Item type in the Configure Document Types settings menu? This is the most common reason.
  2. Did you save your changes in the Actor/Item Fields configuration window?
  3. Try a hard refresh of your browser (Ctrl+F5).
Q: My formula just shows #ERR. What did I do wrong?
- A: This means the formula could not be calculated. Check for:
  1. Incorrect Syntax: Make sure every data path is wrapped in #...#.
  2. Invalid Path: The path inside the hashes might be wrong. Double-check the path on the actor's data structure.
  3. Wrong Data Type: The path must point to a single number. If it points to a Value/Max object (like system.attributes.hp), you must specify which part you want: #system.attributes.hp.value# or #system.attributes.hp.max#.

Manifest URL: https://gitlab.com/sir.sly/custom-fields/-/raw/main/module.json

Sostieni Sly

A proposito di Sly

Real Fog of War

Custom Fields: Your Game, Your Rules

MD to Journal