SC - More Activities

Overview

SC - More Activities extends the native D&D 5e activity system in Foundry VTT. It does not replace the standard dnd5e activity workflow. It adds new activity types, a Shattered Codex-owned registration layer, a grouped activity creation dialog, GM-facing diagnostics, and explicit migration tools for worlds moving away from the legacy more-activities module.

The module is built for two different jobs:

• GMs who want more activity types without maintaining custom patches
• module authors who want to register custom dnd5e activity types through a stable public API

The module ships with built-in SC activity types and a registry flow that can also expose third-party activity types in the same creation UI.

Installation

1. In Foundry VTT, open Add-on Modules.
2. Choose Install Module.
3. Paste this manifest URL:

https://github.com/Shattered-Codex/sc-more-activities/releases/latest/download/module.json

4. Install the module.
5. Enable SC - More Activities in your world.
6. Install and enable libWrapper if you want the recommended compatibility layer.

Compatibility:

• Foundry VTT v13 to v14
• system: dnd5e
• dnd5e compatibility declared in module.json: minimum 5.0.0, verified 5.3.0
• localization: English and Brazilian Portuguese

Important behavior:

• the module exits early outside dnd5e worlds
• native dnd5e activities remain available
• the module relies on items and sheets that already support the dnd5e activity workflow

What It Adds

• built-in Shattered Codex activity types for automation, support, progression, inventory, and canvas workflows
• a public registration hook and API for Shattered Codex modules and third-party modules
• a grouped activity creation dialog that separates D&D 5e, Shattered Codex, and External activity groups
• a GM Activity Catalog with diagnostics, filters, and enable or disable controls
• explicit migration tools for legacy more-activities activity data
• per-user preview color settings for teleport, movement, wall, and portal overlays
• module settings shortcuts for the wiki, support links, catalog, migration tools, and preview colors

Built-In Activity Types

The built-in activities are registered under the Shattered Codex group in the activity creation dialog, but the catalog still tracks their category and source metadata separately.

Tap to expand

SC Advancement

Use a source item that already contains dnd5e advancements, then select the advancement entries this activity can trigger.

1 / 11

SC Sound

SC Sound plays one audio file after the activity is used. It is useful for item activation sounds, spoken cues, alarms, and short ambient effects that should stay attached to the item workflow.

Configure it from the activity's Effect tab:

1. Choose the Audio file.
2. Set Playback to the current user or everyone.
3. Adjust Volume from 0 to 1.
4. Save and use the activity normally.

Only a GM can broadcast the sound to everyone. If a non-GM uses an activity configured for everyone, the module warns that user and plays the sound only on their client. Playback does not loop.

SC Macro

SC Macro runs either a world Macro or JavaScript stored directly on the activity.

• World macro lets you choose an existing Macro from the world. Foundry still checks whether the current user can execute it.
• Inline code stores the script on the activity. Only a GM can edit or run this code.

Inline code receives the activity, item, actor, usage data, dialog data, chat message options, previous results, speaker, and current targets. Use this mode only for trusted code. For reusable automation, prefer a world Macro or a module-owned integration.

SC Hook

SC Hook is an integration activity for module authors and advanced world automation. Its Dispatch mode determines what happens when the activity is used:

• Hook calls the configured Foundry hook name and passes one payload object.
• Callback calls a function that another active module explicitly exposed through the SC - More Activities callback whitelist.

The payload contains the activity, item, actor, usage data, dialog data, message options, results, speaker, and current targets. A callback also needs the providing Module id and Callback id. SC Hook does not execute an arbitrary function path from another module.

SC Chain

SC Chain executes activities from the same item in a fixed order. Create the child activities first, then add them to the chain from its Effect tab.

The chain provides these flow controls:

• Depth limit stops excessively deep nested chains. The accepted range is 1 to 20, with 5 as the default.
• Continue after child errors moves to the next entry when a child is missing or throws an error.
• Stop when a child activity is canceled ends the chain when a child does not complete.
• Suppress child chat messages runs child activities without creating their individual chat messages.

Loop detection prevents a chain from calling an activity that is already in the current execution path. Use SC Conditional Chain instead when the next activity must depend on a result or a user choice.

SC Conditional Chain

SC Conditional Chain is the branching version of SC Chain.

Use it when one activity should lead to different outcomes depending on what just happened. A simple example is:

• roll an attack
• deal damage only if the attack hits
• trigger a bonus effect only if the damage total is high enough

Important scope:

• a conditional chain can call only activities that already exist on the same item
• every step can either run one activity or be Decision only (no activity)
• decision-only steps keep using the most recent child activity result until a later step runs another activity

Before You Build The Flow

Build the child activities first. Then add SC Conditional Chain to the same item and use it as the controller.

This is the easiest order for non-technical setup:

1. Create the attack, damage, healing, grant, macro, or other activities you want the item to use.
2. Add SC Conditional Chain.
3. Open the chain's Effect tab.
4. Add your steps in the order you want to think about them.
5. Pick the First step.
6. Configure how each step decides where the flow goes next.

Restrict A Child Activity To Chains

If SC - Conditional Activities is also enabled, you can prevent a child activity from being used directly and allow it only when an SC Chain or SC Conditional Chain calls it.

1. Open the child activity that should run only as part of a chain.
2. Open its Condition tab.
3. Enter this condition:

usage?.scMoreActivitiesChain

4. Save the activity. Optionally set its locked badge to Chain only so players can understand why direct use is unavailable.
5. Add that activity to a step in SC Conditional Chain.

When a user tries to use the child activity directly, the usage data does not contain scMoreActivitiesChain, so SC - Conditional Activities blocks it. When a chain calls the same activity, SC - More Activities adds that marker to the child usage data and the condition passes.

This restriction applies to both SC Chain and SC Conditional Chain because they share the same execution marker. It makes the child activity chain-only; it does not restrict the child to one specific chain or to the conditional variant alone. See SC - Conditional Activities for condition setup, badges, and warning-message controls.

Main Fields

Condition Types

Canceling a roll or canceling the manual-choice dialog always ends the flow.

Roll Types

The DC field accepts either a number or a deterministic formula such as 8 + @prof or 10 + @scLast.roll.dice.count. The roll succeeds when its total meets or exceeds that DC.

Last Activity Result

Last activity result means the result from the most recent step that actually ran an activity.

That rule has two important consequences:

• if a step is Decision only (no activity), it does not clear the previous result
• several decision-only steps in a row can branch from different parts of the same stored result

Tap to expand

The result picker shows grouped suggestions, but you can switch to Custom path… whenever you need to type a raw path yourself.

When Decide the next step by is Last activity result, the row is made of three parts:

What the picker supports:

• for known result types such as attacks, damage or healing rolls, sc-grant, and sc-contest, the picker can suggest the most useful grouped paths
• Custom path… lets you type any raw path, such as roll.totals.1 or roll.dice.values.2
• the Value field accepts numbers, true or false, text, and deterministic formulas
• includes works on text and lists, so it is useful for cases like tags, damage types, or text fragments

Result Path Reference

Use these paths when you need something more specific than the first suggested options.

For custom or unsupported activity types, only the fields that activity really records will return a value. If a path does not exist in the result, the chain cannot evaluate it.

General Paths

These are the most common fields and are available on every tracked result.

Roll Paths

These are the most useful fields for attack, damage, healing, save, and grant-check style results.

Individual Dice Paths

These fields inspect the kept dice only. Discarded dice from advantage, rerolls, and similar effects are ignored.

Attack Paths

Use these when the previous child activity is an attack activity.

Grant Paths

Use these when the previous child activity is SC Grant.

Contest Paths

Use these when the previous child activity is SC Contest.

Using @scLast In Formulas

The previous result is also exposed to formulas as @scLast.

That is useful when a later roll should reuse the number produced by an earlier step. A common example is a heal or bonus-damage activity that copies the previous damage total.

Tap to expand

This heal formula uses @scLast.roll.sum, so it can read the total rolled by the previous step.

Practical formula notes:

• @scLast.roll.sum is the safest way to reuse the previous total across multi-part rolls
• @scLast.attack.hit and other booleans resolve as 1 or 0 inside formulas
• @scLast by itself resolves to the previous main numeric total when one is available

Flow Policies

The collapsible Flow policies section controls global safety rules for the chain.

Tap to expand

These policies affect the whole chain, not just the currently selected step.

Example Flow: Attack, Then Damage, Then Reuse The Damage Total

This is a practical setup for a non-technical item builder:

1. Create an Attack activity on the item.
2. Create a Damage activity on the same item.
3. Create a Heal or bonus effect activity that uses @scLast.roll.sum in its formula if you want it to copy the previous damage total.
4. In SC Conditional Chain, make the first step run Attack and branch on Last activity result with Attack hit = true.
5. Send the true route to a Damage step and the false route to End flow.
6. After Damage, either continue directly to another step or add a new branch that checks roll.sum, roll.dice.max, or any other value you need.

SC Contest

SC Contest resolves one roll for the initiating actor and one for a defender, then compares their totals. It supports ability checks, saving throws, skill checks, and custom formulas for either side.

Configure the Defender as the currently targeted token or the initiating actor. When using a target, select exactly one token with a valid actor. Then choose the Tie rule:

• keep the result as a tie
• award the tie to the initiator
• award the tie to the defender
• reroll both sides once, keeping a second tie as a tie

The result is posted to chat and can be inspected by SC Conditional Chain through fields such as contest winner, tie state, and both roll totals.

SC Grant

SC Grant adds configured Items to the activity actor or to exactly one targeted actor. Each grant row accepts an Item or Roll Table UUID and a quantity formula.

To configure it:

1. Choose Self or Target as the recipient.
2. Add an Item or Roll Table by drag and drop, UUID, or the add control.
3. Enter the quantity. Values such as 2, 1d4, and @prof are supported.
4. Optionally expand Grant Check and choose an ability or skill check plus its Difficulty Class.

For a Roll Table, quantity means the number of draws. The module grants Item results from those draws and ignores results that cannot resolve to Items. The current user must have permission to update the recipient actor. If an optional check fails, no Items are granted.

SC Advancement

SC Advancement opens the D&D 5e advancement workflow for selected advancement entries on a source Item.

1. Drop or paste the UUID of an Item that contains D&D 5e advancements.
2. Select one or more advancement entries and levels exposed by that Item.
3. Save and use the activity from an actor-owned Item.

At use time, the actor must own the source Item and the current user must have permission to manage that actor. The activity then opens the native D&D 5e Advancement Manager; it does not silently apply advancement choices.

SC Teleport

SC Teleport lets the user choose eligible tokens and then click their destination on the active Scene.

Its Effect tab controls:

• Only self, which skips target selection and teleports the activity actor
• Maximum targets, Allow self, and Target range for normal selection
• Teleport range, measured from the activity actor to the destination
• Keep arrangement or a Cluster radius for multiple tokens
• Snap to grid for the final token positions

Use 0 for an unlimited target or teleport range. After using the activity, choose the tokens, continue to destination placement, and left-click the canvas. Right-click or press Escape to cancel. An active GM is required to perform the Scene update for player-initiated use.

SC Movement

SC Movement pushes or pulls tokens relative to the activity actor. The affected tokens can come from the user's targets, controlled tokens, or the activity actor itself.

Choose Push, Pull, or Either. The last option asks the user which direction to apply when the activity is used. Distance controls how far the tokens move, Range limit controls which tokens are eligible, Maximum targets limits the selection, and Snap to grid rounds destinations to the grid. A range limit of 0 is unlimited.

Using the activity opens a preview where the user can review eligible tokens before confirming the move. Moving the activity actor itself also requires a direction point on the canvas. An active GM mediates Scene updates initiated by players.

SC Wall

SC Wall creates Foundry Wall documents by placing points on the active Scene. It supports three placement styles:

• Continuous joins each placed point into a connected path.
• Circular uses the placement gesture to create a circle.
• Panels creates separated wall segments using the configured panel size, spacing, and optional maximum panel count.

Configure the maximum number of walls, maximum length, direction relative to the activity actor, and reference range. These distance and count fields accept formulas. You can also choose whether the generated Walls block movement, sight, and sound.

Scene document creation is GM-controlled. Enable Allow player requests only when Item owners should be able to ask an active GM client to create the Walls. The activity actor's token must be present on the active Scene before placement begins.

SC Portal

SC Portal opens a linked entry and exit on the active Scene. A token that enters or clicks a configured side can be asked whether it wants to cross.

Availability: SC Portal is currently implemented on the official feature/portal-activity branch and is not included in the public 0.9.1 release. The workflow below applies to builds that include that feature.

The activity creates Foundry Scene documents rather than moving a token as part of the initial activity use:

• each side is a Region with an SC Portal Region behavior
• optional entry and exit art is created as a matching Tile
• both Regions share one portal id, so closing either side removes the pair and their art

Configure A Portal Activity

Add SC Portal to an Item, then configure its Effect tab.

Choose Hidden (art only) when a custom image or video should be the visible portal. The Region remains active and can still be managed by the GM from the Regions layer.

An even-sized area snaps around a grid corner. For example, a 2×2 portal covers four complete grid cells. On a gridless Scene, the module uses the Scene's nominal grid size for the footprint but places each side exactly where you click.

Place The Two Sides

1. Activate the intended Scene. If Placement range is greater than 0, select or place the activity actor's token on that Scene.
2. Use the SC Portal activity.
3. In Portal Placement, choose Place on canvas.
4. Left-click to place Entry.
5. Left-click again to place Exit.
6. Review the range and placement summary.
7. Choose Open portal.

Right-click stops canvas placement, and Clear sides removes the pending points so you can place them again. Both sides must satisfy Placement range; when configured, they must also satisfy Maximum distance between sides. Changing the active Scene cancels the placement workflow.

Cross A Portal

With Ask on entry enabled, the module uses Foundry's tokenMoveIn Region event. A token that walks across a portal stops on it and receives the prompt; declining leaves the token there.

With Ask on click enabled, click the portal with an eligible owned token in or next to it. The module first considers a controlled token, then the current user's assigned character, and finally a single unambiguous owned token already inside the portal.

The prompt goes to the first active player who owns the token. If no active player owner can answer, it goes to the GM. The actual token movement is always performed by the active GM client.

When Avoid occupied spaces is enabled, the destination search expands from the exit until it finds room. If no nearby position is valid, the token stays in place and the crossing is not consumed.

Close A Portal

A portal closes when:

• it spends its final configured crossing
• its duration expires
• a GM chooses Close portal on the whispered chat card
• a GM deletes either side from the Regions layer

Deleting one Region closes the complete pair and removes its optional art Tiles. A duration of 0 and an empty crossing limit keep the portal open until a GM closes it.

Restart After Installing Or Updating

Restart the Foundry server after installing or updating a build that includes SC Portal. Foundry reads the module's custom RegionBehavior document type from module.json only at server startup.

If the behavior is not registered yet, the portal can still be created and Ask on click continues to work, but walking into it cannot trigger Ask on entry. Existing portal Regions repair their behavior the next time the Scene loads after the restart.

The SC Portal icon uses Magic Portal by Lorc from Game-icons.net under CC BY 3.0.

Activity Creation Flow

SC - More Activities keeps the normal dnd5e activity workflow intact and extends the creation dialog instead of replacing it.

When supported activity types are present, the dialog is grouped into:

• D&D 5e for native activity types
• Shattered Codex for the built-in SC activity set
• External for third-party modules that register through the SC registry

This matters for both users and builders:

• GMs can distinguish native types from SC or third-party additions
• module authors can register external activity groups without writing directly into CONFIG.DND5E.activityTypes
• disabled activity types are filtered out of creation and blocked from use

Tap to expand

The creation dialog keeps native D&D 5e types visible, then adds a separate Shattered Codex group for the built-in SC activity set.

Module Settings

From Configure Settings > Module Settings > SC - More Activities, the module adds visible settings and menus for both GM administration and personal preview preferences.

The module also stores hidden world or client data for disabled activity types, preview colors, and migration backups. Those are managed through the UI and are not intended for direct manual editing.

Activity Catalog

The Activity Catalog is the GM-facing control center for registered activity types.

It includes:

• summary cards for Registered, D&D Ready, Rejected, and Warnings
• filters for search, category, status, and availability
• separate sections for Registered Activities, Rejected Registrations, and Warnings
• actions to Refresh, Copy report, Clear filters, and open Migration

Availability states are important:

• Active means the activity type is available for creation and use
• Disabled means the GM has blocked that type for the world
• Unavailable means the type is not in a state that can be enabled for use

Only activity types that successfully reach the D&D-ready state can be toggled for world use. This makes the catalog useful both as a user control panel and as a diagnostic report for module integrations.

Tap to expand

The catalog combines registration state, lifecycle metadata, capability markers, and per-type availability controls in one GM-facing window.

Preview Colors

The Preview colors menu is a client-scoped preference, so each user can pick their own overlay colors without changing the world for everyone else.

It is used by the canvas-oriented workflows:

• SC Teleport
• SC Movement
• SC Wall
• SC Portal

The menu includes:

• separate sections for Teleport, Movement, Wall, and Portal
• Fill color and Border color controls
• a Live Preview area
• reset and save actions

These colors affect preview overlays only. They are not an activity authoring setting and they do not change the underlying activity data.

Tap to expand

Preview colors are saved per user, so one GM can change overlay colors without changing the world for everyone else.

Migration from More Activities

SC - More Activities ships with an explicit migration flow for the legacy more-activities module.

The migration window is GM-only and split into four tabs:

• Overview
• Preview
• Apply
• Backups

Recommended workflow:

1. Keep the legacy module enabled only long enough to inspect or migrate old data.
2. Open More Activities migration from module settings.
3. Run Preview first.
4. Review convertible and blocked entries.
5. Use Apply migration only after the preview looks correct.
6. Export the preview or final report if you need a record.
7. Use Restore latest backup if you need to roll back the last migration.

Important limits:

• migration does not run automatically
• a preview is required before apply
• migration backups are stored in world settings
• some blocked or partially compatible legacy entries may still need manual cleanup after conversion
• the module warns when the legacy more-activities module is still active

Tap to expand

The preview report makes it clear which legacy entries can be converted, which SC type they map to, and what still needs manual review.

Developer Registration API

If you are building another module, register activity types through the SC registry instead of mutating CONFIG.DND5E.activityTypes directly.

Public API access:

• game.modules.get("sc-more-activities")?.api
• globalThis.ShatteredCodex.activities for the published activities API

Main lifecycle hooks:

• sc-more-activities.registerActivities
• sc-more-activities.registryLocked
• sc-more-activities.apiReady
• sc-more-activities.activityRegistered
• sc-more-activities.activityAvailabilityChanged
• sc-more-activities.activityUseStart
• sc-more-activities.activityUseComplete
• sc-more-activities.activityUseError

Registration timing:

• register during Hooks.on("sc-more-activities.registerActivities", ...)
• late registrations are rejected after the registry locks during initialization
• if you need the final published API object, listen for sc-more-activities.apiReady

Minimum registration contract:

• moduleId
• type
• label
• hint
• icon
• documentClass

Your documentClass must provide:

• static metadata.type that matches the registered type
• static availableForItem(...)
• static localize(...)

Minimal example:

Hooks.on("sc-more-activities.registerActivities", (activities) => {
  activities.registerType({
    moduleId: "my-module",
    type: "my-module-ignite",
    label: "MYMODULE.Activity.Ignite.Label",
    hint: "MYMODULE.Activity.Ignite.Hint",
    icon: "modules/my-module/icons/ignite.svg",
    documentClass: MyIgniteActivity,
  });
});

The public activities API also exposes helper methods such as:

• listTypes()
• listTypeAvailability()
• setTypeEnabled(type, enabled)
• getRegistrationReport()
• createActivityOnItem(item, type, data, options)

Developer Example: SC Simple Sockets

If you want a concrete external-module example, SC - Simple Sockets is the best reference currently in the Shattered Codex module set.

It does not patch sc-more-activities directly. Instead, it keeps the entire integration inside its own module and registers two external activity types when both modules are active:

• sc-socket-slot
• sc-socket-extraction

This example focuses on sc-socket-slot, because it shows the full lifecycle for a custom activity type.

What Files The Example Uses

How The Bootstrap Works

SC - Simple Sockets loads the integration from its own scripts/main.js and registers it at startup:

import { ScMoreActivitiesIntegration } from "./core/integrations/sc-more-activities/ScMoreActivitiesIntegration.js";
 
ScMoreActivitiesIntegration.register();

That register() method does two jobs:

1. It listens to sc-more-activities.registerActivities.
2. It registers a query handler during init so socket mutations can be routed through an active GM when needed.

This is important because the integration owns both the activity definition and the mutation flow. The external module is responsible for its own runtime behavior.

The Real Registration Call

Inside ScMoreActivitiesIntegration.js, SC - Simple Sockets registers sc-socket-slot like this:

return activitiesApi.registerType({
  moduleId: Constants.MODULE_ID,
  type: SC_MORE_ACTIVITIES_ACTIVITY_TYPES.SOCKET_SLOT,
  label: "SCSockets.Integrations.ScMoreActivities.SocketSlot.Title",
  hint: "SCSockets.Integrations.ScMoreActivities.SocketSlot.Hint",
  icon: SC_MORE_ACTIVITIES_ICONS.SOCKET_SLOT,
  documentClass: ScMoreActivitiesSocketSlotActivity,
  dataModel: ScMoreActivitiesSocketSlotActivityData,
  sheetClass: ScMoreActivitiesSocketSlotActivitySheet,
  configurable: true,
  category: "sockets",
  ui: {
    scope: "external",
    group: "sockets",
    groupId: SC_MORE_ACTIVITIES_GROUP.id,
    groupLabel: SC_MORE_ACTIVITIES_GROUP.label,
    groupIcon: SC_MORE_ACTIVITIES_GROUP.icon,
    groupOrder: SC_MORE_ACTIVITIES_GROUP.order,
    order: 140
  },
  tags: ["sockets", "slot", "inventory"],
  compatibility: {
    dnd5e: "5.x",
    scMoreActivities: { moduleId: "sc-more-activities", required: true },
    scSimpleSockets: { moduleId: "sc-simple-sockets", required: true }
  },
  templates: [
    "modules/sc-simple-sockets/templates/integrations/sc-more-activities/socket-slot-effect.hbs"
  ],
  ownership: {
    execute: "item-owner",
    hostItem: "activity-item",
    mutation: "gm-mediated"
  },
  source: Constants.MODULE_ID
});

Why this registration is useful:

• ui.scope: "external" places the type in the external registration flow
• groupId, groupLabel, and groupOrder create a module-specific activity group in the create dialog
• dataModel, sheetClass, and templates turn the type into a configurable authoring experience instead of a bare runtime document
• ownership.mutation: "gm-mediated" matches the real workflow, because socket mutations may need GM execution

The Activity Class

The activity class extends the standard dnd5e activity mixin and connects the registered type id to the custom schema, metadata, availability check, and runtime execution:

export class ScMoreActivitiesSocketSlotActivity extends dnd5e.documents.activity.ActivityMixin(
  ScMoreActivitiesSocketSlotActivityData
) {
  static metadata = Object.freeze(
    foundry.utils.mergeObject(super.metadata, {
      type: SC_MORE_ACTIVITIES_ACTIVITY_TYPES.SOCKET_SLOT,
      img: SC_MORE_ACTIVITIES_ICONS.SOCKET_SLOT,
      title: "SCSockets.Integrations.ScMoreActivities.SocketSlot.Title",
      hint: "SCSockets.Integrations.ScMoreActivities.SocketSlot.Hint",
      sheetClass: ScMoreActivitiesSocketSlotActivitySheet
    }, { inplace: false })
  );
 
  static availableForItem(item, ...args) {
    const base = typeof super.availableForItem === "function"
      ? super.availableForItem(item, ...args)
      : true;
    return base && ScMoreActivitiesIntegration.isTypeEnabled(
      SC_MORE_ACTIVITIES_ACTIVITY_TYPES.SOCKET_SLOT
    );
  }
 
  async use(usage = {}, dialog = {}, message = {}) {
    const results = await super.use(usage, dialog, message);
    if (results === undefined) return results;
    return ScMoreActivitiesSocketSlotActivityService.execute(this, { usage, dialog, message, results });
  }
}

The pattern to copy into your own module is:

1. Extend dnd5e.documents.activity.ActivityMixin(...).
2. Put the registered type id into static metadata.type.
3. Route availability through availableForItem(...).
4. Call super.use(...) first.
5. Hand off the actual side effects to a dedicated service class.

The Data Model

ScMoreActivitiesSocketSlotActivityData extends dnd5e.dataModels.activity.BaseActivityData and stores all custom fields under slot.

Real schema fields in the example include:

• slot.operation
• slot.name
• slot.color
• slot.cursorImage
• slot.description
• slot.condition
• slot.targetCondition
• slot.hidden
• slot.deleteGemOnRemoval
• slot.ignoreMaxSockets

That structure is worth copying because it keeps custom activity state grouped under one schema branch instead of scattering unrelated top-level fields.

The Sheet and Template

ScMoreActivitiesSocketSlotActivitySheet extends dnd5e.applications.activity.ActivitySheet and injects a custom effect-part template:

static PARTS = {
  ...super.PARTS,
  effect: {
    template: TEMPLATE_PATH,
    templates: [...super.PARTS.effect.templates]
  }
};

That template is templates/integrations/sc-more-activities/socket-slot-effect.hbs, and it renders the actual authoring controls for:

• slot operation
• slot name and color
• cursor image
• description
• condition code
• target condition code
• behavior toggles such as hidden, delete on removal, and ignore socket limit

Use this pattern when your custom activity needs real item-authoring UI instead of a small number of primitive fields.

The Runtime Service

The actual socket behavior does not live in the activity class. It lives in ScMoreActivitiesSocketSlotActivityService.

That service decides whether the configured operation is:

• add a slot to a selected item
• remove one empty slot from the host item

The service also validates the target condition, launches the slot-picker UI when needed, and hands the mutation back to ScMoreActivitiesIntegration.

That separation matters:

• the activity class stays small and predictable
• the data model only describes stored state
• the service owns workflow branching, validation, dialogs, and user feedback

How GM-Mediated Execution Works

SC - Simple Sockets is a strong example because it shows how to handle mutations that may require GM authority.

Inside ScMoreActivitiesIntegration.js, the integration:

1. Builds a request payload with activityUuid, itemUuid, operation, and requestUserId.
2. Executes directly when the current user is a GM or already has socket-edit permission.
3. Falls back to an active GM query using a registered query id when direct execution is not allowed.
4. Resolves the request on the GM side and turns the result into a normalized success or failure object.

This is the concrete pattern to follow when your custom activity mutates actors, items, scenes, or other documents that should not be changed blindly by every player client.

Minimal Blueprint For Your Own Module

If you are building a new external activity, the smallest practical file set is:

scripts/main.js
scripts/integrations/sc-more-activities/MyIntegration.js
scripts/integrations/sc-more-activities/MyActivity.js
scripts/integrations/sc-more-activities/MyActivityData.js
scripts/integrations/sc-more-activities/MyActivitySheet.js
scripts/integrations/sc-more-activities/MyActivityService.js
templates/integrations/sc-more-activities/my-activity-effect.hbs

Build it in this order:

1. Register an integration class from scripts/main.js.
2. Listen to sc-more-activities.registerActivities.
3. Call activitiesApi.registerType(...).
4. Create a document class with metadata, availableForItem(...), and use(...).
5. Add a data model for your stored fields.
6. Add a sheet class and Handlebars template for configuration.
7. Move the actual side effects into a service class.
8. Add GM-mediated dispatch only if your workflow really needs it.

When To Copy This Pattern

Use the sc-simple-sockets structure when your activity:

• needs custom authoring fields
• performs complex runtime logic after super.use(...)
• may require GM-mediated document changes
• belongs to a module-specific activity group in the create dialog
• should stay fully owned by the integrating module instead of by sc-more-activities

Notes and Limits

• This module supports only the dnd5e system.
• It extends native activities instead of replacing them.
• World macros, inline code, hooks, and callbacks still follow their own permission and ownership limits.
• Canvas actions such as teleport, movement, wall placement, and portals rely on GM-mediated scene updates.
• The migration workflow is explicit by design, which is safer than an automatic conversion but still requires review before apply.