Item Piles

Latest version1.4.8
Minimum Core0.8.9
Compatible Core9
Last updated4 months ago
Created7 months ago
Languages English
Systems All systems
Dependencies socketlib
Project source Project URL
Report bugs Bug tracker URL

Item Piles

Chest sprites used on this page is from Forgotten Adventures*

*not included in this module


What is Item Piles?

Have you ever wished you could represent items in your scenes? A pile of items, something to interact with - or perhaps chests whose appearance changes depending on what happens to it, whether it's open, closed, full, or empty. Do you want an easy way to split loot between players?

Then you need Item Piles!

In short, this module enables dropping items onto the canvas, which then get represented as a pile of items. In order to work in all systems without breaking or messing too much with the core functionality of Foundry, this creates an unlinked token & actor to hold these items. When a player double-clicks on an item pile token, it opens a custom UI to show what the pile contains and players can then take items and currency from it.

Item Piles can also be configured to act as a container, where it can be open or closed, locked or unlocked, with the ability for the token that represents the pile to change image depending on its state.

In addition, when an item pile is interacted with it can also play sounds for the action, such as opening, closing, or attempting to open a locked item pile. Sounds are only played for the user who attempted the action.

Last but not least, the module features a robust and well documented API, where module and system creators can leverage Item Piles to enrich your looting experience.



Any player or GM can drag & drop items - if you drag & drop an item from an actor's inventory, you will be prompted how many of that item that you wish to drop (if they have more than 1 of the item). GMs can also drop items from the item list in the right sidebar.


Holding ALT before dragging & dropping an item will make you automatically drop 1 of the items into a new pile without a prompt. You can also drag and drop items onto an existing pile, where holding ALT is also supported.

When players double-click on the item pile (or Left Control + double-click for GMs to inspect, or to inspect as someone else select two tokens, and repeat), they will get a custom UI where they can choose what they want to take from the item pile, or all of it (if they're loot goblins).

Initial Setup

When a player or a GM drops the first item into a scene, the default item pile actor will be created. Do not delete this actor, as it is the actor and token that is used for all item drops. It's not recommended to change this actor or token styling unless you know what you're doing.

Instead, we recommend that you duplicate the default item pile to create new versions of that pile, and experiment with that. Alternatively, turn existing actors into new item piles through the Item Pile button on the actor sheets' header bar. This UI has a wide range of customization, which allows you to control exactly how your players interact with the item pile.

Sharing and splitting

When you configure an item pile, you can set it up to handle splitting quantities of items and/or currencies in the item pile's configuration:

The notable settings are Sharing Enabled: Items and Sharing Enabled: Currencies - when these are enabled, players can only take their share of the given type. By default, items are "free for all" and currencies can only be split.

If there's any quantity that is uneven and cannot be split between players, there may be some left over from the split, which you will have to pick up manually.

When both sharing options are disabled, only then can you enable the Take All button.


Be sure to set any new Item Piles as unlinked from its actor data! Unless you know what you're doing, keeping this enabled will be confusing as all tokens of this pile will share the same images and inventory.

Extra UI and settings

In addition, item piles have a few extra buttons on the right click Token HUD to open, close, lock, and unlock containers, and a quick way to access the configuration of that token.

In the module settings, you can configure all sorts of things, such as whether empty piles auto-delete once they're empty, and which item types are allowed to be picked up. These are by default configured to the D&D5e system, so adjust them accordingly for your own system.

Currencies and attributes

For most systems, currencies or other physical things aren't considered "items" in Foundry, but rather just numbers on the sheet, so dragging and dropping them is hard. However, Item Piles still allow you to pick up such items from piles using its flexible "Dynamic Attributes" feature. With this feature, you can configure what types of these "numbers only" things that can still be picked from piles up by players.

Each row represents a field on a character sheet that may be picked up. As you can see, the D&D5e system denotes the number of gold coins a character has with the field, so by putting as a valid field in this UI, Item Piles figures out that if an actor has more than 0 in this field, it can be "picked up" and transferred to the character who picked it up.

Keep in mind that the name field in here accepts localization strings, so for D&D5e's currencies, you could enter DND5E.CurrencyGP in the name field.


Useful Macros

Item Piles has a powerful API, which allows you to quickly modify the item piles in your scenes.

Turn selected tokens into item piles

if(!canvas.tokens.controlled.length) return;


Revert selected tokens from item piles

if(!canvas.tokens.controlled.length) return;



Required Modules


This module uses the socketlib library so that players can modify the contents and the look of item piles without having to have full ownership of the item piles. Without it, they could only drop items and create item piles using pile actors they own.


This module uses the libwrapper library for wrapping core methods. It is a hard dependency, and it is recommended for the best experience and compatibility with other modules.

Optional Modules

Advanced Macros

This module leverages the Advanced Macros module so that any macros can use extra data provided by the Item Piles module. This is an optional install, but highly recommended.

Natively Supported Systems

Item Piles is designed to work in all systems, but may require some setup for it to fully function. Please refer to the module settings to configure that.

Semi-Supported Systems

  • Pathfinder 2e - While Item Piles works in this system, item piles is not strictly needed as PF2e already has a robust loot actor & token system, and feature rich systems.

Requesting New Systems

If you wish to request a new system, please create a new system request here.

Fill in all of the information, and ask in the system's discord channel if you don't know what something means.

Incomplete requests will be rejected.

Notify of
Inline Feedbacks
View all comments
Would love your thoughts, please comment.x