SC - Resources

Overview

SC - Resources lets GMs and players track custom numeric resources on Actors, such as Mana, Corruption, Sanity, or ammunition. It keeps stored points, spendable points from Active Effects, and temporary modifiers distinct. Items can grant resources to their owner through Active Effects; Items do not store their own SC Resources balances.

Compatibility and Installation

SC - Resources is premium. Download and install it through the Shattered Codex Download Hub. Follow How to Download Premium Modules from the Download Hub, then enable SC - Resources in your world's Manage Modules dialog. Reload when Foundry requests it.

Compatibility:

• Foundry VTT v13–v14 (verified on v14).
• Game systems: Core resource management and recovery work on any system. The sheet tab, activity consumption, rest recovery, and roll formulas described below are D&D 5e integrations.
• D&D 5e integration: dnd5e 5.3 on Foundry v13 or v14, or dnd5e 6.0 on Foundry v14.
• Dependencies: No other modules are required. Tidy 5e Sheets and SC - More Activities have optional integrations.

To create your first resource, open an Actor's ⋮ sheet menu, select Manage Resources, and use Add resource to set its name and balance. On supported D&D 5e sheets, you can also use the Resources tab in edit mode.

What You Can Do

• Track custom Actor resources with stored balances, limits, and source pools.
• Grant points or temporary modifiers through Active Effects on Actors or Items.
• Recover resources and react to events or value thresholds with automations.
• Spend resources on D&D 5e activities and spells, or move points between Actors.
• Control access, appearance, and chat history; inspect balances in a world overview.

Video Overview

Watch Shattered Codex's introduction to SC - Resources alongside the written steps below.

Understand Resource Balances

Stored on the Actor                 5  (storedBase)
+ available Active Effect pool     3  (pool)
= spendable balance                8  (base)
+ temporary value modifier        2
= effective reading              10  (value)

Spendable pools are separate balances supplied by Active Effects. A modifier to the effective value changes what the resource displays but does not add points that can pay a cost. A modifier to the maximum raises the limit without automatically refilling the balance.

By default, a spend uses available source pools first, then stored points. Gains refill pools first, up to their capacities. The resource's Spend order can put stored points first. A pool's Spend priority puts lower-numbered pools first. When a pool exists, Sources lists the balances in their payment order and shows inactive pools separately.

An effect that grants five Mana as a pool can be spent down to two. Simply opening a sheet or preparing the Actor again does not refill it. Its reactivation and removal policies control what happens when the effect stops and returns.

Create And Manage Resources

1. Open the Actor's ⋮ menu and select Manage Resources, or open Resources on its sheet and switch to edit mode.
2. Select Add resource and enter its name. The new resource starts at 0, with a minimum of 0 and no maximum.
3. Open Configure to set a maximum if needed, then adjust its color, recovery, automations, and Pays for rules.
4. Set its stored value with the field or −/+ controls. Open Breakdown to inspect the spendable balance and effective reading.

The Resource Manager saves changes as you make them. It remains available even if the GM hides the Resources tab.

The resource ID is the stable name used by macros, Active Effects, formulas, and activities. It begins with a letter, uses only letters, digits, and underscores, and has at most 32 characters. IDs are case-sensitive and cannot be renamed; display names can. For example, bloodCharges works, while blood-charges does not.

Character, NPC, and vehicle sheets show a Resources tab in the sheet's style. Native dnd5e character sheets can also show selected resource bars in their sidebar. Appearance → Customize in Configure offers a color or gradient, animated bar style, speed, and text and frame colors. Motion stops when the user chooses Off for animated styles or requests reduced motion. Resource bars keep the same appearance in the Resource Manager and sheet.

The GM can hide the Resources tab in module settings. Manage Resources remains available from the sheet menu. Tidy 5e Sheets has its own supported Resources tab, including its edit lock; Tidy's own tab configuration can reorder or hide it.

Configure Recovery

In a resource's Configure → Recovery, select Add recovery, a period, and a method. A bounded resource can Recover All, Recover Half, Lose All, or use a Formula such as 1d4 + 2. Unlimited resources use formulas. A negative formula reduces the balance. Only the first matching rule applies in a recovery pass.

In D&D 5e, rests, calendar/day changes, and combat periods can trigger recovery automatically. Long rest includes short rest rules. Available periods include long and short rest, day, dawn, dusk, initiative, turn start, turn end, and each turn. Recovery from a rest appears in the native rest chat card. For a manual recovery, a GM can call SCResources.recover(actor, "lr") from a macro.

An Active Effect pool can have its own recovery rules in Resource source policies, such as a staff refilling at dawn. Those rules recover that pool only; resource-level rules recover the other balances.

Build Automations

Open a resource's Configure → Automations and select Add automation. An automation has a trigger, optional condition and test, and an ordered list of consequences. Active Effects can also grant automations through ⋮ → Resource automations, the helper's JSON change, or shortcut keys.

Event formulas can use @scEvent values; value-trigger formulas can use @scThreshold. Value automations support steps, movement direction, re-arming, and an option to trigger if the resource is already past the threshold when the rule starts. resourceChanged and dieRolled come from SC Resources; D&D 5e adds damage, healing, rest, turn, activity, spell, saving throw, and other system events. Some attack and damage-attribution events depend on how targets and chat cards are used.

Conditions can be built in the visual Builder or edited as JSON. The editor shows whether a condition is Met, Not met, Invalid, or Needs a roll for the current Actor. Optional tests include a dice roll, a D&D 5e saving throw, or an ability check. The world setting chooses automatic rolls or a chat card that an owner answers.

Consequences run in order. They can change a resource, post a chat message, apply a condition or effect, emit an event, run a D&D 5e activity, run a GM-authored macro, or apply D&D 5e damage or healing. The automation editor allows more than one of each. Chains stop after three links to avoid endless loops. A failed consequence does not stop the remaining ones.

As an example, set a Value trigger at effective Corruption 10, add a saving throw test, and add an effect consequence that applies when the save fails. Check the summary and current condition state before leaving the editor. The thresholdCrossed hook can also notify another integration.

Resources on D&D 5e Sheets

On dnd5e 5.3 and 6.0, the Resources tab appears on supported character, NPC, and vehicle sheets. The tab meter displays the stored and source-pool balance and marks a different effective reading. Open Breakdown for its contributors and Sources for the balances that actually pay costs. The Configure panel is available to authorized users while the sheet is in edit mode.

Item effects can grant mod, pool, and accumulate resources to their owner. The Item itself does not carry a resource balance. An equipped item's effect follows dnd5e equipment, attunement, effect, and condition rules.

Roll formulas can read:

1d6 + @scResources.corruption.value
@scResources.mana.base

.value is the effective reading and .base is spendable, including available pools. .storedBase, .pool, .min, .max, .percent, and .unlimited are also available where applicable. An unlimited resource has no numeric .max.

Pay Activity And Spell Costs

For an activity, open its Consumption section, choose SC Resource, set Target to the Actor resource ID, and enter the amount. The target suggestions list the Actor's resources; you can type an ID even on an unowned Item. An old actor:<id> target still works. A positive amount spends points; a negative amount gains them. The usage dialog warns about an unaffordable cost, and its chat card can undo the consumption.

When several balances can pay, Pay … from in the usage dialog offers the default order, a specific balance, or an allowed substitute. To fix the source in an activity target, use mana@stored, mana@pools, or mana@item for that activity's own Item-granted pool. The refund restores the balances that actually paid.

Configure → Pays for on a resource can let it pay another resource's costs at a chosen rate. For a spell resource, configure spell-slot payments by level or with a formula; a payment can be the default choice in the casting dialog. Active Effects can grant these rules through the substitute keys in Active Effect Keys And Examples. A GM can hide the covered spell-slot pips on the native dnd5e character sheet. This changes their display, not the Actor's spell slots or a cast that chooses to spend one.

For a negative activity cost, Block gains above the maximum rejects a gain that would not fit in full. It is off by default; otherwise excess gain is discarded at the cap.

Modify And Transfer Resources

Modify Resource is a dnd5e activity with Add, Subtract, or Set balance. Choose the acting Actor or targets, name the resource, and enter an amount formula. It can optionally ask each recipient for a saving throw or ability check, automatically or through a chat card, and apply none, half, or the full change on a success. It can block gains above the maximum.

Transfer Resource moves points between the acting Actor and targets. Choose Drain or Give, the resource taken and received, the amount, and what happens when the source is short or the receiver is full. It supports the same resistance test. Transfers are coordinated so a failed credit can undo its debit.

Targeted Actors the user does not own normally require a GM to coordinate the change. The GM can disable player resource activities on targets in Permissions. Activity consumption refunds do not undo the separate changes made by Modify Resource; check the activity's result card.

Both activities are included in SC Resources. With SC - More Activities, they appear in its activity catalog and can be organized or disabled there; the module is not required.

Module Settings

Open Game Settings → SC - Resources → Open settings. GMs manage world options; each user can change the browser-specific Display and Diagnostics options. Save Changes applies changes. Reset defaults restores the visible tab without saving it.

Permissions (GM, world)

• Players' access to their resources — Only values (default) lets owners see and adjust values. View what they do also opens read-only details for recovery, automations, payments, sources, and breakdowns. Edit lets owners configure, create, and delete resources.
• Show the contribution breakdown to players — Off by default. When on, Actor owners can see which items and effects contribute to a resource.
• Resource activities may affect targeted actors — On by default. When on, a player's Modify Resource and Transfer Resource activities may affect targeted Actors they do not own. When off, players can affect only Actors they own.
• Activities and automations create the resources they name — On by default. When on, a qualifying activity or automation can create a missing resource, even if the player cannot create resources directly. Turn it off to restrict creation to users with permission.

A GM can override player access, chat visibility, and chat reversion for individual resources in the Actor's Permissions window. An individual resource's Edit access allows its owners to configure it; deleting it still follows the world's access level.

Appearance (GM, world)

• Theme — Arcane by default. Changes the Resource Manager, world overview, and settings window. A sheet's Resources tab keeps its sheet theme.
• Resource icon — Flask by default. Changes the icon used for the sheet tab, Manage Resources entry, manager, and source policy controls.

Character sheet (GM, D&D 5e worlds)

• Show the Resources tab — On by default. Adds the tab to supported character, NPC, and vehicle sheets, including Tidy 5e Sheets. When off, Manage Resources remains available from the sheet's ⋮ menu.
• Hide the spell slots a resource pays for — Off by default. Hides slot pips for spell levels a resource can pay for on native dnd5e sheets. The Actor's slots and casting choices still exist; edit mode shows all levels. Tidy draws its own slots and is unaffected.

Events (GM, world)

• Custom events — Empty by default. Declare an event ID and label to offer the event in automation editors. A macro or integration must emit the event with SCResources.events.emit(); declaring it does not fire it.

Automations (GM, world)

• Apply effects automatically — On by default. Effect and Condition consequences apply immediately. When off, they appear on a chat card for a GM or Actor owner to apply.
• Roll automation tests automatically — On by default. Saving throws, checks, and dice tests roll when the automation runs. When off, a GM or Actor owner must answer a chat card before consequences proceed.
• JavaScript in conditions — Only scripts a GM saved or approved by default. Always approve: every script runs permits any script written by someone who can edit an automation; None prevents scripted conditions from running.

Chat log (GM, world)

• Post resource changes to chat — Every resource by default. Resources marked in Configure posts only for resources with Post changes to chat enabled. Off posts no change cards.
• Who sees the cards — GM only by default. The other choices add the Actor's owners or everyone. Individual resources may override visibility in the Actor's Permissions window.
• Players may revert changes — Off by default. When on, owners can Revert changes to their Actors from chat cards; a GM can always do so. A revert reverses the resource change once, but does not undo automations it triggered. Creating or deleting a resource also requires the player's corresponding access level.

Display and Diagnostics (each user, this browser)

• Animated bar styles in Display — Always by default. Only under the pointer limits animation to the hovered bar; Off keeps bars still. A reduced-motion preference also stops animation.
• Debug logging in Diagnostics — Off by default. When on, logs resource resolution and warns about Active Effects aimed at stored values.

Browse resources under Game Settings → SC - Resources opens the world overview. It groups resources by name or Actor and searches world Actors the user may observe. It does not scan compendiums or unlinked Token Actors.

Configure an individual resource

Open Configure on a resource in the Resource Manager or a supported sheet:

• Name changes its visible label. Its ID stays fixed for macros, effects, formulas, and activities.
• Minimum, Maximum, and Unlimited set the allowed balance range. A new resource starts at 0, has a minimum of 0, and has no maximum.
• Spend order chooses whether source pools or the Actor's stored points pay first. Pools pay first by default; a pool's Spend priority decides its order among pools.
• Appearance → Customize sets the bar's colors, gradient, animation style, speed, text, and frame. The appearance follows the bar between the Resource Manager and supported sheets.
• Recovery, Automations, and Pays for define refill rules, event or value responses, and which other costs the resource can pay. Their workflows are explained above.
• Post changes to chat selects this resource when the world setting is Resources marked in Configure. Show in sheet sidebar adds its bar to a native dnd5e character sheet's sidebar; it does not apply to NPC, vehicle, or Tidy sheets.

Resource source policies on an Active Effect control a granted pool's capacity, spending, recovery, reactivation, and removal behavior. They are explained in Active Effect Keys And Examples below.

Active Effect Keys And Examples

Use an Active Effect for an ongoing modifier, a separate spendable pool, a grant applied on activation, or an automation supplied by an item or state. Add changes to the effect's native Changes list. For an effect on an Item, make sure dnd5e applies or transfers it to the Actor. Equipment, attunement, suppression, and conditions determine whether it contributes.

Replace <id> with the exact resource ID. Foundry 13 has no Subtract mode, so use Add with a negative amount. For example:

Key:   flags.sc-resources.mod.corruption.value
Mode:  Add
Value: 3

This raises effective Corruption by three while the effect applies. The stored balance is unchanged. Set Value to -2 for a penalty. To grant five points that the Actor can spend, use flags.sc-resources.pool.mana.value, Add, 5. To add points to the Actor's own balance on activation, use flags.sc-resources.accumulate.corruption.value, Add, 1.

The mod keys accept numbers or formulas evaluated with Actor roll data. They can modify .min, .max, and .value. Only Add and Subtract apply to finite resources. An unlimited resource can receive a finite cap through Override or Downgrade on .max; additive maximum changes do nothing there. A .min or .max modifier alone does not create a resource. A valid .value modifier can show an effect-only resource with stored base zero and no maximum; its bonus still cannot be spent.

For a pool, save the effect's changes and open ⋮ → Resource source policies on the Active Effect sheet. Set its capacity, spend priority, recovery, and behavior when reactivated or removed:

• Keep remaining balance, Restore starting amount, or Add starting amount again when the effect activates again;
• Pause while inactive; discard when deleted, Keep available on actor, or Discard remaining points when the source becomes inactive;
• Only the first activation or Every activation for an accumulate grant.

A pool can introduce a resource even when the Actor has no stored definition. Its balance remains distinct from the Actor's own points. An accumulate grant stores points permanently; it does not remove them when its effect ends.

Do not target a stored resource flag directly from an Active Effect. Use mod, pool, or accumulate for their respective behaviors, or use a sheet control, activity, or API call for a one-time change.

Use The Active Effect Helper

The module has its own Active Effect helper under Game Settings → SC - Resources. It builds keys for modifiers, grants, automations, resource substitution, and D&D 5e spell payment.

1. Open Active Effect helper.
2. Choose the behavior, the resource ID, and the needed values or automation steps.
3. Copy each generated key, mode, and value.
4. Add those rows to the Active Effect's Changes list and save.
5. For a pool, open Resource source policies on the effect to set capacity, recovery, and reactivation behavior.
6. Inspect the Actor's Breakdown or Sources panel to verify the effect's actual result.

The helper can generate an automation as a JSON change. Simple event automations can instead become shorter on or cast keys. It has no Actor context, so it checks whether a condition is readable, not whether that condition currently holds for a character.

SC - Active Effects Search is a separate, optional property picker. Its magnifying glass helps fill discovered keys in an effect editor; SC Resources' own helper is the tool for constructing resource-specific changes. If a virtual resource key is absent from the search results, copy it from Active Effect helper or enter it manually.

Macros, API, And Integrations

SCResources, game.modules.get("sc-resources").api, and ShatteredCodex.resources expose the same API. Resource operations accept an Actor or Actor UUID. A read returns null when a resource is missing; a write returns an { ok, ... } result for expected failures. This macro reads Mana from the selected token's Actor:

const actor = canvas.tokens.controlled[0]?.actor;
if (!actor) {
  ui.notifications.warn("Select a token first.");
} else {
  const mana = SCResources.get(actor, "mana");
  console.log(mana ?? "This actor has no Mana resource.");
}

Use SCResources.getBase(actor, "mana") for the spendable balance and SCResources.getValue(actor, "mana") for the effective reading. SCResources.sources.list(actor, "mana") shows its source pools. To change a balance, call create, set, add, subtract, spend, or restore. SCResources.recover(actor, "lr") applies long-rest recovery. Check each mutation's ok result before relying on it.

SCResources.openManager(actor) opens the Actor's Resource Manager. SCResources.events.emit(id, actor, data) fires a custom event; SCResources.automations.list(actor) and preview(actor, eventId, data) help inspect rules. SCResources.debug.explain(actor, "mana") prints a resolution breakdown.

For an exact source, use SCResources.spend(actor, "mana", 2, { sources: "stored" }). This uses only stored points; "pools", item:<itemUuid>, effect:<effectUuid>, and ledger IDs are other selectors. SCResources.transfer() moves an exact amount by default; drain() moves up to what is available. An operationId makes retries safe when a result is uncertain.

Integration hooks include sc-resources.changed, .created, .updated, .deleted, .event, .thresholdCrossed, .registerEvents, and .registerProviders. The change event reports spendable and effective before-and-after values. Other modules should use the public API instead of reading or writing raw resource flags.

Troubleshooting

I cannot find the resource controls

Check the Actor sheet's ⋮ → Manage Resources entry. The Resources tab can be hidden by a world setting, the sheet's layout, or permissions. An Item has no SC Resources tab; configure the Active Effect that grants points to its owner.

An Active Effect does not change a resource

Check the exact ID and key, the change mode, whether its formula resolves, and whether the effect currently applies to the Actor. Open Breakdown, Sources, or From effects to see inactive reasons. A .min or additive .max change does not create a resource. Use the Active Effect helper for a new key and Resource source policies for a pool's behavior.

The displayed value is higher than I can spend

A mod.<id>.value contribution changes the effective reading, not the balance. Compare stored, Sources, base, and effective. Use pool.<id>.value for separate spendable points or accumulate.<id>.value to credit the Actor.

Recovery or an automation did not run

Check that the period or event actually occurred. For manual recovery, call SCResources.recover(actor, "lr") from a macro. Inspect the automation's trigger, condition state, test card, enabled state, and effect source. Custom events must be emitted or registered.

An activity cannot pay or change a resource

Confirm the Actor has the named resource or an active grant, check the Pay … from choice and source pool balance, and inspect any Block gains above the maximum setting. A targeted Actor the player does not own may need a connected GM and permission for targeted resource activities.

A change timed out

Check the Actor's current balance before trying again. A timed-out operation may already have completed. An operationId can prevent a repeated value change from applying twice.