Modules/SC - Ascendant Items

SC - Ascendant Items

Foundry v13-v14System D&D 5ePremium

SC - Ascendant Items

Overview

SC - Ascendant Items adds a level-based progression workflow to supported D&D 5e item sheets.

Use it when one item should evolve across multiple stages instead of being split into separate item copies. Each level stores progression data and can also store a snapshot of the real item state for that stage.

Validated module scope:

a per-item Levels tab
progression by XP or Milestone
multiple saved levels on one item
per-level snapshots of supported item data
snapshot apply and level advance actions
configurable player permissions by role
configurable XP bar gradient and animation
integrations with tidy5e-sheet and SC - Simple Sockets
a public API with level hooks

An ascendant item keeps the normal item-sheet workflow while adding staged progression and snapshot-based restores.

Installation

This module is premium.

Install access is handled through the Shattered Codex Download Hub.

See How to Download Premium Modules from the Download Hub for the full access and installation flow.

After installing:

Enable SC - Ascendant Items in your world.
Make sure lib-wrapper is also active.
Open a supported dnd5e item.

Compatibility:

Foundry VTT v13 to v14
system: dnd5e
required dependency: lib-wrapper
optional integrations: tidy5e-sheet, SC - Simple Sockets

Enable Levels On An Item

The module is enabled per item, not globally.

To enable it:

Open the item sheet.
Go to Details.
Enable Levels.

Enabling Levels adds the dedicated tab only for that item and starts storing the progression workflow in item flags.

Important behavior:

the Levels toggle is GM-only
if an item already has saved levels, the module still treats it as enabled
you can only disable Levels after removing all saved levels from that item

Build The Level Progression

After enabling Levels, open the new Levels tab.

The main workflow is:

Click Add Level.
Edit the item into the state you want for that stage.
Use Capture Level to save the current state into that level.
Add more levels and repeat as needed.
Use Apply Level or Advance Level later to restore a saved stage.

Each level row stores progression metadata and can also show snapshot summary badges for activities, Active Effects, and sockets.

The Levels tab can show:

progression mode
current level
XP progress when the mode is XP
a list of configured levels
level labels, required XP, or milestone text
snapshot summary badges
actions such as Capture Level, Apply Level, and Delete

When you click Add Level, the module:

creates the next numeric level automatically
stores it on the item
creates an initial snapshot from the current item state
marks that level as active

Choose XP Or Milestone Progression

The module supports two progression modes.

XP Progression

In XP mode, the item tracks Current XP and each level can define its own XP Required threshold.

Behavior in XP mode:

the first level always keeps XP Required = 0
the XP bar measures progress toward the next configured level
when current XP reaches the next threshold, the item is ready to advance
if there is no next level, the bar shows Highest configured level

Milestone Progression

In Milestone mode, each level stores milestone text instead of numeric XP requirements.

Behavior in Milestone mode:

the XP bar is hidden
each level can store milestone text
progression is manual
the item can advance whenever a next level exists

Capture And Apply Snapshots

The module separates two kinds of data:

progression data
the real item snapshot for each level

Progression data includes:

progression mode
current XP
active level
last applied level
level labels
milestone text
required XP

The snapshot stores the real item state for a level.

Use Capture Level when you want to save the current item state into that level. Before capture, the module tries to submit pending sheet edits so the snapshot reflects the current sheet state.

Snapshot summary badges help confirm what is currently stored for each level.

A snapshot can include:

item name
item img
supported system fields
activities
embedded Active Effects
supported socket layout data
snapshot update time

Use Apply Level to restore a saved snapshot for a specific row.

Use Advance Level to move to the next configured level:

if the next level has a snapshot and the user may apply snapshots, that snapshot is applied
if the next level has no snapshot, the module only changes the active level

The camera button can also highlight when the current item no longer matches the comparison baseline, which is a practical sign that you may want to capture the level again.

Module Settings And Permissions

Open:

code

Configure Settings > Module Settings > SC - Ascendant Items

Available menus:

Menu	What it does
Open documentation	Opens the SC - Ascendant Items wiki page.
Configure XP Bar	Opens the XP bar gradient and animation settings window.
Configure Permissions	Opens the role-based player permissions window for levels, snapshots, and progression.

Player Permissions

All permission settings default to GM Only.

Configurable role thresholds:

GM Only
Assistant GM+
Trusted Player+
All Players

Configurable permissions:

add levels
delete levels
edit level names
edit milestone names
edit required XP
capture snapshots
apply level snapshots
change progression mode

XP Bar Configuration

The XP bar settings support:

between 2 and 8 gradient colors
animation on or off
animation type
animation duration

Available animation types include:

Flow
Breathing
Wave
Pulse
Ping-Pong
Shimmer
Steps
Dual-Layer Flow
Spin
Neon Glow
Sparkle
Scanline
Liquid
Radial Sweep
Noise / Grain

Integrations

Tidy 5e Sheet

When tidy5e-sheet is active, the module:

registers the same Levels tab on the Tidy item sheet
adds the Levels toggle to the Tidy details area
keeps the same progression and snapshot workflow

SC - Simple Sockets

When SC - Simple Sockets is active, socket layout data becomes part of the snapshot workflow.

Current validated behavior:

socket layout is saved in the snapshot
extra slots can be removed when a restored level has fewer sockets
gem activities and effects can be removed and reapplied during restore
socket-related update data is merged into the item restore flow

API And Hooks

The module exposes a public API at:

game.modules.get("sc-ascendant-items")?.api?.levels

Validated methods:

getState(itemOrUuid)
getLevels(itemOrUuid)
getActiveLevel(itemOrUuid)

Validated hook constants:

HOOK_LEVEL_ADDED
HOOK_LEVEL_SELECTED
HOOK_CURRENT_XP_UPDATED
HOOK_LEVEL_ADVANCED
HOOK_LEVEL_METADATA_UPDATED
HOOK_LEVEL_DELETED
HOOK_LEVEL_CAPTURED
HOOK_LEVEL_APPLIED
HOOK_MODE_CHANGED

Example:

const api = game.modules.get("sc-ascendant-items")?.api?.levels;
 
Hooks.on(api.HOOK_LEVEL_ADVANCED, ({ item, previousLevel, level, snapshotApplied }) => {
  console.log("Item advanced:", item?.name, {
    from: previousLevel?.value,
    to: level?.value,
    snapshotApplied,
  });
});

Limits And Safeguards

Explicitly unsupported fields:

system.advancement

Fields intentionally excluded from restoration:

system.equipped
system.attuned
system.attunement

That means Apply Level should not be treated as a way to restore equipped or attunement state.

Other important safeguards:

if an item already has stored levels, external flag changes should not accidentally disable the workflow
if Levels is enabled and levels already exist, the module tries to preserve flags.sc-ascendant-items.data
active level and last applied level are stored separately
if you change the item after capture and want that state saved, you must capture again