Shattered Codex

Wiki

Modules/SC - Ascendant Items

SC - Ascendant Items

Foundry v13-v14System D&D 5ePremium

SC - Ascendant Items

Overview

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

Instead of duplicating separate items for every upgrade tier, you configure multiple stages on one item, capture a snapshot of the real item state for each level, and reapply the correct stage later with a single action.

Core capabilities:

  • a dedicated Levels tab on enabled items
  • progression by either XP or Milestone
  • multiple saved levels per item
  • full item snapshots per level
  • restore support for compatible item data, activities, Active Effects, and socket layouts
  • configurable permissions by user role
  • customizable XP bar gradients and animations
  • integrations with tidy5e-sheet and SC - Simple Sockets
  • a public API with hooks for automation and extensions

Example ascendant item with milestone-driven evolution

An ascendant item can keep the normal item-sheet workflow while still carrying its own staged progression, milestone text, and evolving presentation.

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:

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

Compatible integrations:

Quick Start

  1. Open an item.
  2. In the Details tab, enable Levels.
  3. Open the new Levels tab.
  4. Click Add Level.
  5. Adjust the item however you want for that stage.
  6. Use Capture Level to save the current item state into that level.
  7. Add more levels and repeat the process.
  8. When you want to restore a saved stage, use Apply Level.

Configured levels on an ascendant item

The same item can carry multiple saved stages, each with its own milestone text, metadata, and snapshot summary.

Core Concept

The module separates two different things:

  1. progression data
  2. the real item state for each level

Progression data includes:

  • progression mode
  • current XP
  • active level
  • last applied level
  • the list of configured levels
  • labels, milestones, and required XP

The real item state is stored in snapshots. Each snapshot is the saved state of that item at one level.

Practical rule:

  • editing a level label, milestone, or required XP does not update the snapshot
  • if you want the current item state to belong to that level, you must capture again
  • Add Level already creates an initial snapshot from the current item state

Enable and Disable Levels

The workflow is enabled per item, not globally.

To enable it:

  1. Open the item sheet.
  2. Go to the Details tab.
  3. Enable Levels.

Levels toggle in the item Details tab

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

Important behavior:

  • the enable toggle is visible only to the GM
  • once an item has saved levels, the module still treats it as enabled
  • if external updates partially rebuild flags, the module tries to preserve enabled state and saved data

You can only disable Levels if the item has no saved levels:

  1. remove all levels from the item
  2. return to Details
  3. disable Levels

Levels Tab and Progression Modes

Levels Tab Structure

The Levels tab is the main workspace for the module.

Levels tab overview with multiple configured stages

This tab brings together progression mode, current level, XP display, level rows, and snapshot actions in one place.

It can display:

  • progression mode
  • current level
  • XP bar when the mode is XP
  • add-level action
  • configured level list
  • capture, apply, and delete actions

Each level row can include:

  • generated numeric level
  • custom label
  • required XP or milestone text
  • snapshot summary badges
  • actions available for the current user

When you click Add Level, the module:

  • calculates the next numeric level automatically
  • creates the internal level entry
  • captures an initial snapshot of the current item state
  • marks that level as active

XP Progression

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

XP progression with required thresholds for each level

The progress bar compares the current XP to the next configured threshold instead of treating every level as a fixed global table.

Behavior in XP mode:

  • the first level is always locked to 0 required XP
  • the progress bar measures progress toward the next level
  • when current XP reaches or exceeds the next target, the item is ready to advance
  • if there is no next level, the item is already at the highest configured stage

Using Advance Level:

  • applies the next level snapshot if one exists
  • otherwise only changes the active level internally

Milestone Progression

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

Milestone progression mode

Milestone mode removes the XP bar and turns advancement into a purely manual story-driven flow.

Behavior in milestone mode:

  • the XP bar is hidden
  • each level stores milestone text
  • advancement is manual
  • the next level can be advanced to whenever it exists

Snapshots and Apply Level

The module persists two different kinds of data.

Progression Data

This is the editable state from the Levels tab, such as:

  • progression mode
  • current XP
  • level list
  • labels
  • milestones
  • required XP
  • active level
  • last applied level

Item Snapshot

The snapshot is the real saved state of the item for one level. To create or update it, use Capture Level.

Before capturing, the module tries to submit pending sheet edits so the saved snapshot reflects current item changes.

Level rows showing snapshot data badges

Snapshot badges help confirm what is actually stored for a given level, including activities, Active Effects, and sockets when available.

A snapshot can store:

  • item name
  • item img
  • supported system fields
  • activities
  • embedded Active Effects
  • supported socket data
  • the snapshot update timestamp

Applying a saved level restores supported data and updates:

  • the active level
  • the last applied level

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

What Is Not Saved or Restored

Explicitly unsupported fields:

  • system.advancement

Fields intentionally excluded from restoration:

  • system.equipped
  • system.attuned
  • system.attunement

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

Recommended Workflows

XP-Driven Item

  1. Enable Levels on the item.
  2. Create Level 1.
  3. Capture the base state.
  4. Create Level 2.
  5. Set the required XP.
  6. Edit the item to reflect the stronger stage.
  7. Capture level 2.
  8. Increase Current XP during the campaign.
  9. Use Advance Level when the target is reached.

Milestone-Driven Item

  1. Enable Levels.
  2. Create the levels you want.
  3. Fill in the milestone text for each level.
  4. Adjust the item for each stage and capture the snapshots.
  5. Use Advance Level or Apply Level when the story milestone happens.

Settings and Permissions

The main module settings live under:

code
World Settings > Module Settings > SC - Ascendant Items

Player Permissions

Player permissions configuration window

Permissions can be tuned per user role, so you can decide whether players may only use completed items or also build and maintain levels themselves.

You can configure who may:

  • add levels
  • delete levels
  • edit level names
  • edit milestones
  • edit required XP
  • capture snapshots
  • apply snapshots
  • change the progression mode

Available access thresholds:

  • GM only
  • Assistant GM+
  • Trusted Player+
  • All Players

Everything starts as GM only by default.

XP Bar Configuration

XP bar gradient settings

The XP bar can be styled independently from the progression logic, including color count, animation type, and animation speed.

The XP bar settings support:

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

Available animation modes:

  • flow
  • pulse
  • spin
  • pingpong
  • shimmer
  • wave
  • steps
  • neon
  • breathing
  • sparkle
  • dualflow
  • noise
  • scanline
  • liquid
  • radial

Integrations

Tidy 5e Sheet

When tidy5e-sheet is active, the module:

  • registers the same Levels tab directly on the Tidy item sheet
  • adds the enable toggle in the Tidy details area
  • keeps the same functional workflow as the standard D&D 5e item sheet

SC - Simple Sockets

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

Sockets tab on the same item used with Ascendant Items

Socket-aware snapshots let an evolving item change not only core fields, but also compatible socket layout data across stages.

Current behavior:

  • socket layout is saved in the snapshot
  • inserted gems are not serialized as permanent layout data
  • valid gems can be preserved when applying another level
  • extra slots may be removed if the restored level has fewer sockets
  • gem-derived activities and effects are cleaned up and reapplied when necessary

API and Data Storage

The module exposes a public API at:

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

Available methods:

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

Available 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:

js
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,
  });
});

Data is stored on the item through:

  • flags.sc-ascendant-items.enabled
  • flags.sc-ascendant-items.data

Inside data, the module keeps:

  • progressionMode
  • currentXp
  • activeLevelId
  • lastAppliedLevelId
  • levels

Each entry in levels can contain:

  • id
  • value
  • label
  • xpRequired
  • milestone
  • snapshot
  • updatedAt

Safeguards and Limitations

The module includes protections against accidental state loss during aggressive external updates:

  • if Levels was already enabled, partial flag rewrites try not to disable it accidentally
  • if levels already exist, external updates that rebuild flags try to preserve flags.sc-ascendant-items.data

Day-to-day reminders:

  • Add Level already creates a baseline snapshot
  • Capture Level replaces that level snapshot with the current item state
  • Apply Level restores the saved snapshot
  • active level and last applied level are stored separately
  • if you change the item outside the tab and want that state saved, capture again
  • if the next level has no snapshot, Advance Level only changes the active level