Spellcasting System Workflow

This guide explains the current spellcasting workflow and what is already available in the app.

What Is Available Now

• spell creation and editing
• spell browsing and filtering
• spell deletion (with permissions)
• class spell list assignment workflows (data/API support)
• spell and power selection integration for special inventory items (Spell Scroll, Power Crystal)

Spell Authoring Workflow

1. Create a new spell.
2. Fill out core fields (name, level, school, range, duration, description).
3. Configure components (V/S/M), ritual, concentration, and attack/save metadata.
4. Save changes.

The spell editor also supports temporary effect trigger integration where configured.

Upcast Scaling Expressions

Spell and power cards support expression placeholders in these metadata fields:

• target count
• range
• area of effect

Use {...} expressions with parser variables such as slot, spell_mod, and cantrip (for spell cards):

• Up to {1 + slot} targets
• {30 + slot * 30} ft
• {10 + slot * 5} ft radius
• {cantrip * 1d8} fire

Custom parser variables can also be supplied by the current context. For example, a class scalable value with variable name rage_damage can be used in spell, power, feature, or action expressions when that class variable list is available:

• {1d6 + rage_damage} fire

cantrip scales by tier using caster level and defaults to 1 when no level-aware context is available:

• levels 1-4 -> 1
• levels 5-10 -> 2
• levels 11-16 -> 3
• levels 17-20 -> 4

At runtime, card metadata and per-target damage roll count both use the scaled target value.

Spell Search and Filtering

Spell queries support:

• name search
• level filter
• school filter
• ritual filter
• concentration filter
• source filter

Results are source-aware and paginated.

Class Spell Lists

Class spell list operations are supported by API and form workflows:

• search all spells
• add/remove spells in a class list
• persist changes in bulk

Inventory Integration

Spell Scroll and Power Crystal item flows use compendium searches.

• users choose a spell or power during item creation flow
• rarity and related metadata are computed for scrolls
• selected content is linked for quick hover-card lookup

Character Spell Tracker

Players can now track spells and slots directly from the character page (/characters/:characterId).

• spell tracker state is stored in the Character Durable Object
• tracked spells are stored in a SQL table with spell_id, name, level, and metadata
• spell slots are stored as a JSON blob keyed by spell level (1-9)
• AC, total HP, current HP, and temporary HP can be edited in the same view
• sheet view provides fast cast controls (+/-) for slot usage while playing
• settings view contains edit forms for HP, tracked spells, and slot configuration

This is intentionally a quick player workflow, not a full rules-enforced magic system.

Character Leveling

Character owners can level up from the character settings view. Level-up writes directly to the Character Durable Object over its WebSocket RPC connection; there is no HTTP mutation fallback.

Each level-up records the class compendium ID, a class-name snapshot, and rolled HP. The tracker adds the character’s current Constitution modifier to the roll and increments the existing maximum HP, preserving prior manual HP edits.

Existing characters keep their legacy level until their first tracker level-up. At that point, the legacy total is stored as an explicit baseline and only the new class level is added to history. The app does not invent historical class choices or HP rolls. The progression card identifies how many baseline levels do not have detailed class history.

Current Limitations

Some spellcasting features are still in progress:

• full class spellcasting table builder UI is not fully enabled
• spell preparation and rules-based validation are not enforced by the tracker

Use the current workflow for spell authoring and source-aware search while these features continue to expand.