Need a 'Sanity' score or homebrew resource? Custom Fields lets you add any field to Actor and Item sheets. Features auto-formulas (e.g. #system.abilities.str.mod# + 1), token bar linking, item counters, images and individual permissions. System-agnostic, it's the perfect way to integrate your custom rules seamlessly.

Your Game, Your Rules.

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.

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

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

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

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.

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

5. 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#.