SC - Simple Sockets

Overview

SC - Simple Sockets adds a socket workflow to D&D 5e items in Foundry.

The module treats configured loot items as gems, lets compatible host items receive socket slots, and then transfers gem behavior into the host item when a gem is inserted.

What the module currently covers:

• drag-and-drop gem socketing
• configurable socketable host item types
• gem definitions based on loot subtypes
• automatic transfer of Active Effects
• automatic mirroring of Activities
• optional gem combat data in +Details
• optional named resources with current and maximum charges
• reusable gem tags for socket conditions
• activity consumption from one gem, one host item, or a character-wide socket pool
• per-slot descriptions, tint colors, visibility, and JavaScript conditions
• socket feedback on item sheets, actor inventories, activity lists, and the damage roll dialog
• support for the default dnd5e item sheet and Tidy5e Sheet

Compatibility and Installation

This module is free.

Install it through Foundry with this manifest URL:

https://github.com/Shattered-Codex/sc-simple-sockets/releases/latest/download/module.json

Compatibility:

• Foundry VTT v13 and v14
• system: dnd5e
• recommended dependency: libWrapper
• recommended integration: SC More Activities
• optional sheet integration: Tidy5e Sheet

After installing:

1. Enable SC - Simple Sockets in your world.
2. Open Configure Settings > Module Settings > SC - Simple Sockets.
3. Configure socketable host item types.
4. Configure which loot subtypes count as gems.
5. Create or import a few test gems.
6. Test the workflow on one host item before expanding your content library.

Settings and Setup

Most setup starts in Configure Settings > Module Settings > SC - Simple Sockets. Under Module configuration, select Open configuration.

The Simple Sockets — Configuration window replaces the older collection of separate settings dialogs. It keeps all module options in four sidebar tabs: Socket rules, Display, Item types, and Gem subtypes.

Tap to expand

Socket rules

Set who may edit sockets, the maximum slots per item, and whether removed gems are destroyed or returned.

1 / 4

Changes are not applied until you select Save Changes. Reset defaults resets only the active tab, while the status pill marks unsaved or saved state.

Main rules and display settings:

The gem damage layout setting supports four modes:

• Group by gem
• Group by damage type
• Group by gem type
• Group by damage type with badges

By default, the module allows sockets on:

• weapon
• equipment

By default, a gem is:

• an item of type loot
• with subtype gem

If you want alternate gem families such as runes or shards, add them under Custom loot subtypes. New custom entries appear in the selectable subtype list immediately, but they are not committed until you save the configuration.

If Enable Socket Tab on all items is disabled, an eligible item can still opt in from Details.

Use Enable Socket Tab on that item's Details tab when you want sockets on selected items only instead of every valid host item.

Build Gems

Gem authoring uses normal dnd5e loot items plus the module's extra controls.

Each gem can define:

• its accepted loot subtype
• one or more descriptions
• Active Effects
• Activities
• +Details combat data
• a Socketed Resource with current and maximum charges
• reusable Gem Tags
• Allowed Item Types

Tap to expand

Descriptions

A gem can carry standard description content plus a dedicated socket description used after insertion.

1 / 7

Practical gem behavior:

• gem Active Effects are applied to the host item
• gem Activities are mirrored to the host item
• gem +Details data can add extra damage and attack modifiers
• gem resources can provide charges while the gem is socketed
• gem tags can be checked by slot conditions without depending on the gem name
• gem host restrictions are checked before insertion

Gem Tags and Socketed Charges

The module-added +Details tab is divided into three panes. A dot marks a configured Combat or Resource pane, while Tags shows its current tag count.

All three panes are optional. Existing gems continue to work without combat overrides, tags, or a socketed resource.

Add charges to a gem

A gem can carry a named resource such as energy, battery, or magic. The current and maximum values remain on that gem instead of being copied to the host item or actor.

1. Open the gem item.
2. Open +Details.
3. Under Socketed Resource, enter a short Resource Key such as battery.
4. Set Current and Maximum.
5. Choose Recharges on and Recovery if the gem should recover or lose charges automatically. Leave the period at Never (manual only) for a manually managed resource.
6. Optionally enable Destroy when out of charges if consumption should destroy and remove the gem when its last charge is spent.

The resource is available only while the gem is socketed. If the gem is removed and returned to inventory, it keeps its remaining charges. Setting the current value to 0 manually does not trigger Destroy when out of charges; that option applies when activity consumption drains the gem to zero.

Organize gems with tags

Tags provide stable categories for socket rules. This lets differently named gems share a tag such as fire, poison, healing, or dynamo-battery.

1. Open the gem's +Details tab.
2. Add one or more values under Gem Tags.
3. Open a socket's settings and reference the tag in Slot condition.

Tags are normalized automatically: uppercase becomes lowercase, accents are removed, and spaces become hyphens. For example, Dynamo Battery becomes dynamo-battery.

To accept only gems tagged fire, use:

return hasGemTag("fire");

Socket Items

Once your world has valid gems and valid host items, the main socketing workflow is straightforward:

1. Open a compatible host item.
2. Open the Sockets tab.
3. Add one or more empty slots.
4. Drag a gem into an empty slot.

Tap to expand

List layout

Default list shows the slot name and a complete row of controls, making each socket easier to inspect.

1 / 2

At insertion time, the module validates:

• whether the dropped item is a configured gem
• whether the host item type is socketable
• whether the gem allows that host item type or subtype
• whether the slot's custom condition accepts the gem

When a gem is removed, the result depends on the active removal mode:

• if gem deletion is enabled, the gem is destroyed
• otherwise the gem is extracted back into inventory

That behavior can come from the global Delete Gem on Removal setting or from a per-slot override.

Holding Shift while removing a gem or deleting a slot skips the confirmation prompt.

Spend Socketed Charges

Activities can use the Socketed Charges consumption type to spend a gem's resource. In the activity's consumption settings, choose where the charges come from:

For compatible target modes, Pool scope controls which host items contribute:

Character pools are calculated from the socketed gems; they are not a second balance stored on the actor. Consumption checks the activity's item first, then the actor's other eligible items and their sockets in order. If the complete pool cannot pay the cost, the activity is blocked instead of partially spending it.

The optional SC More Activities integration also provides socket activities for inserting and extracting gems, recharging one gem, or recharging a shared resource pool.

Tap to expand

Filled resource gems add a summary table below the slots. Current charges remain on each gem, even when several gems share the same resource key.

Open a filled slot's settings to edit that gem's current charges or recovery configuration. The maximum still comes from the gem's +Details > Resource pane.

Filter host items in a character pool

Host item filter is an optional JavaScript condition on a socket consumption target. It is separate from Slot condition: the slot condition decides whether a gem may be inserted, while the host item filter decides which socketed items may contribute to an activity's charge pool.

The filter receives these useful values:

A truthy result includes the candidate host; a falsy result excludes it. Both an expression and a block with return are accepted. Invalid code or a runtime error blocks the entire consumption so charges are not taken from an unintended item.

return item?.type === "weapon";

return item?.id !== sourceItem?.id;

const group = getProperty(sourceItem, "flags.world.socketPool");
return Boolean(group)
&& getProperty(item, "flags.world.socketPool") === group;

const sourceSet = getProperty(sourceItem, "flags.sc-setforge.setId");
return Boolean(sourceSet)
&& getProperty(item, "flags.sc-setforge.setId") === sourceSet;

Socket Formulas and Native Item Uses

SC - Simple Sockets adds two different formula families to dnd5e roll data. Keep them separate: @sockets... reads named charges stored on gems, while @sc.sockets... counts slots and inserted gems.

Bind Limited Uses to a named gem resource

For a resource named Soul Harvest, use its normalized key soul-harvest in Details > Usage > Limited Uses > Max:

Use one of these exact formulas to bind native Item Uses to the gem pool. The module derives Spent from the gems and deducts the activity's Item Uses cost from them in a stable order. If the activity also has an explicit Socketed Charges target, that target owns the deduction so the cost is not charged twice.

Native dnd5e Limited Uses recovery does not recharge the underlying gems. Recharge those gems through their resource controls or a socket recharge activity; the derived Spent value then updates automatically.

Count slots and socketed gems

Socket counts are live formula values:

Setting Limited Uses Max to exactly @sc.sockets.gems or @sc.sockets.total makes the item's native Item Uses capacity follow that count. Configure recovery on the item, not on the consuming activity. The module keeps the remaining uses stable when capacity changes, clamping only when the new maximum is smaller; newly added capacity starts empty until it is recovered.

The same paths can be used in an Active Effect change value. For example, system.attributes.ac.bonus with mode Add and value @sc.sockets.gems grants +1 AC per filled socket on the item carrying the effect. Arithmetic such as @sc.sockets.gems * 2 is supported. Effects placed directly on an actor have no item scope, so use an .actor.* path there.

Slot Settings and Slot Conditions

Each socket can carry its own configuration instead of behaving like every other slot on the item.

Tap to expand

Description and rules

Select a socket in the left rail, then edit its name, tint, description, visibility, and removal behavior without reopening the item sheet.

1 / 2

Per-slot settings currently include:

Slot Condition

Slot condition is the advanced rule field for deciding whether a specific gem can enter a specific socket.

If the field is empty, the slot accepts any gem that already passed the module's normal checks.

If the field contains code:

• a truthy result allows the gem
• a falsy result blocks the gem
• invalid code or runtime errors also block the gem and show a warning

Both styles work:

gem?.name?.toLowerCase().includes("ruby")

return gem?.name?.toLowerCase().includes("ruby");

Available variables:

Basic Condition Examples

These examples all assume the slot already passed the module's normal checks for gem identity, host compatibility, and socketability.

return gem?.name?.includes("Ruby");

return hasGemTag("fire");

return getProperty(gem, "system.rarity") === "rare";

return (actor?.system?.abilities?.int?.value ?? 0) >= 16;

return gem?.name?.includes("Ruby") && getProperty(gem, "system.rarity") === "rare";

return actor?.effects?.some?.((effect) => effect.name === "Arcane Focus" && !effect.disabled);

const sockets = getProperty(hostItem, "flags.sc-simple-sockets.sockets") ?? [];
return sockets.some((entry) => (entry?.gem?.name ?? entry?._gemData?.name) === "Ruby");

Writing Tips

• Start with the simplest rule that solves the slot restriction.
• Prefer getProperty(...) when a field may not exist on every gem.
• Use slotIndex for position-based rules and gem for gem-data rules.
• If a condition becomes hard to read, split the logic into several named checks inside the code block before returning the final result.
• If the code is invalid or throws an error at runtime, the module blocks the gem and shows a warning instead of failing silently.

UI Feedback

The module surfaces socket state outside the Sockets tab as well.

Tap to expand

Filled descriptions

Filled slots show the gem's image, socket description, current charges, and a button for sending that entry to chat.

1 / 5

This feedback appears on:

• the standard dnd5e item sheet
• Tidy5e Sheet item tabs and descriptions
• the host item's Sockets tab and Socket Descriptions block, including charge values
• actor inventory rows
• item activity lists
• the damage roll configuration dialog

API and Included Content

The module ships with included content and an exposed API.

Included from module.json:

• one item compendium with socket-ready gem content
• one macro compendium for socket workflows

Create Slots with the Included Macro

If you want to add sockets without opening each item sheet first, import a macro from the SC - Simple Sockets Macro compendium.

Current included macro examples include:

• Add Socket Slot to Item
• Add Conditional Socket Slot to Item

The standard add-slot workflow uses the same interactive helper exposed by the module API:

1. Run Add Socket Slot to Item from your hotbar or macro directory.
2. Click a supported item anywhere in the Foundry UI.
3. Confirm the prompt to add the new socket.

The workflow shows Click an item to add a socket. Press Esc to cancel. while selection is active.

Use Add Conditional Socket Slot to Item when you want the new slot to start with predefined rules such as a name, description, color, or slot condition.

Public API reference

The module registers its public API during Foundry's ready hook. Call it from a macro or integration after the world is ready:

const api = game.modules.get("sc-simple-sockets")?.api;
const sockets = api?.sockets;
const macroApi = api?.macro;

Every socket API method is asynchronous. itemOrUuid accepts an Item document or an Item UUID. Slot indexes are zero-based: 0 is the first socket.

const result = await sockets.addSlot(item, { slotConfig: { name: 'Ruby Socket', color: '#9f1239' } });

const result = await sockets.addGem(item, gem); // first empty slot

Use removeSlot only after confirming the target slot is empty. It removes the stored slot directly and does not perform gem, effect, or activity cleanup. removeSlotWithContents is the safe general-purpose choice when the slot may be filled.

Mutation methods return this stable shape:

{
  success: true,
  changed: true,
  reason: "slot-added",
  data: { slotIndex: 0, totalSlots: 1 }
}

Common reason values include slot-added, slot-removed, slot-not-removed, gem-added, gem-removed, slot-config-updated, slot-config-not-updated, item-not-found, invalid-slot-index, empty-slot, no-available-slot, cannot-resolve-item, host-not-socketable, not-a-gem, gem-incompatible, socket-condition-failed, socket-condition-error, permission-denied, and max-sockets-reached. Check success before using data.

Common mutation options are:

Slot colors accept three- or six-digit hexadecimal values and are normalized to uppercase #RRGGBB. Slot conditions are JavaScript expressions evaluated by the module; invalid code blocks the operation.

API examples

Add a configured socket and inspect the result:

const sockets = game.modules.get("sc-simple-sockets")?.api?.sockets;
const result = await sockets?.addSlot(item, {
  slotConfig: {
    name: "Ruby Socket",
    description: "Accepts one adornment ruby.",
    condition: "return hasGemTag('adornment-ruby');",
    color: "#9f1239",
    deleteGemOnRemoval: false
  }
});
 
if (!result?.success) {
  ui.notifications.warn(`Could not add socket: ${result?.reason}`);
}

Insert a gem into the first empty slot, or choose slot 1 explicitly:

const automatic = await sockets.addGem(item, gem);
const selected = await sockets.addGem(item.uuid, gem.uuid, 1);
console.log(automatic.data?.slotIndex, selected.data?.slotIndex);

Remove a gem while always returning it to the actor's inventory:

const result = await sockets.removeGemKeepingItem(item.uuid, 0);
if (result.success) console.log("Gem removed and kept.");

Check a normalized gem tag in a conditional activity:

const sockets = game.modules.get("sc-simple-sockets")?.api?.sockets;
return sockets && await sockets.hasItemGemTag(item, "Dynamo Battery");

Interactive macro API

The macro API is intended for workflows that ask the user to select an item or socket in the Foundry interface:

await macroApi.addSocketInteractive({ promptSlotConfig: true });

Example:

await game.modules.get("sc-simple-sockets")?.api?.macro?.addSocketInteractive({
  notifications: true,
  promptSlotConfig: true,
  slotConfig: {
    name: "Runeword Socket",
    description: "Accepts one curated rune.",
    color: "#C44D24"
  }
});

The hook constants are also exposed through api.sockets:

const sockets = game.modules.get("sc-simple-sockets")?.api?.sockets;
console.log(sockets.HOOK_SOCKET_ADDED);   // "sc-simple-sockets.socketAdded"
console.log(sockets.HOOK_SOCKET_REMOVED); // "sc-simple-sockets.socketRemoved"

Both hooks receive an object with item, itemId, itemUuid, actor, actorId, slotIndex, slot, totalSlots, and userId. The slot value is a cloned socket snapshot from before removal or after creation.

Use the same names with Foundry's Hooks.on:

Hooks.on("sc-simple-sockets.socketAdded", ({ item, slotIndex, totalSlots }) => {
  console.log(`Socket ${slotIndex} added to ${item?.name}; total: ${totalSlots}`);
});
 
Hooks.on("sc-simple-sockets.socketRemoved", ({ item, slotIndex, totalSlots }) => {
  console.log(`Socket ${slotIndex} removed from ${item?.name}; total: ${totalSlots}`);
});

If you want ready-made expansion content instead of building every gem by hand, see SC - More Gems.

Troubleshooting and Notes

Useful current behaviors and limits:

• gems are still normal loot items, so gem identity starts from loot subtype rules instead of a new item type
• container is intentionally excluded from the socketable item-type picker
• if global socket-tab visibility is disabled, items that already have sockets keep their local socket-tab access
• gems with the same resource key contribute to one calculated pool; the host item and actor do not store a duplicate charge balance
• manually setting a gem to zero charges does not trigger Destroy when out of charges
• Source gem and Specific slot consumption stay on the activity's own item even when a character-wide scope is selected
• invalid slot-condition code blocks the gem and shows a warning instead of failing silently
• invalid Host item filter code blocks the entire consumption instead of falling back to a broader pool
• replacing a gem removes the previous gem's transferred effects and mirrored activities before applying the new one

Troubleshooting checks:

• if an item cannot receive sockets, verify its type is enabled in Configure Socketable Item Types
• if an item is not recognized as a gem, verify its loot subtype is included in Configure Gem Loot Subtypes
• if the Sockets tab is missing, check the global Enable Socket Tab on all items setting and then the per-item Enable Socket Tab toggle in Details
• if a gem is rejected by one slot only, inspect that slot's Slot condition
• if a gem does not contribute charges, verify that Resource Key is not blank and that the activity uses the same key
• if a character pool misses an item, verify the selected Pool scope; the equipped scope only includes items currently marked as equipped
• if filtered consumption finds no charges, check Host item filter separately from the socket's Slot condition
• if gem damage looks confusing in the roll dialog, change Gem damage layout in roll dialog and compare the four layouts
• if you need deeper debugging, enable Debug trace logging in module settings and inspect the browser console

Client-side notes:

• the module can show an automatic What's New popup after updates
• Hide automatic What's New popup until next update controls whether that popup stays hidden after you acknowledge it