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. The backend synchronizes the authoritative character level and Constitution modifier before opening the Character WebSocket and after stat updates; client requests carry only expected snapshots, so stale or forged values cannot establish progression or recalculate HP. The authorized route also attaches a server-derived edit capability: campaign viewers can read progression, but owner-only progression mutations are rejected inside the WebSocket RPC server.

Existing characters keep their legacy level as an explicit baseline. The progression card’s Manage Levels dialog lists every fixed level number from 1 through the character’s current level without inventing historical choices. Owners are prompted to set the class and rolled HP for each legacy level. Selecting a class suggests its hit die, but the owner can choose d6, d8, d10, or d12 directly. The roll defaults to the selected die’s rounded-up average (d6 → 4, d8 → 5, d10 → 6, d12 → 7) and remains editable. These edits remain staged and do not change maximum HP automatically.

The class picker is source-aware. The default SRD source provides stubs for Barbarian, Bard, Cleric, Druid, Fighter, Monk, Paladin, Ranger, Rogue, Sorcerer, Warlock, and Wizard. The Talent (d6) stub comes from The Talent and Psionic source and appears only when that TAP source is available to the player.

After every level has a class and roll, Use Recalculated Max HP previews and confirms an opt-in total: the sum of all saved rolls plus the character’s current Constitution modifier for every level, plus all saved maximum-HP adjustments. Activation replaces the existing maximum HP, does not carry forward manual maximum-HP edits, and preserves current HP. Activation is blocked when the recalculated maximum is not a positive safe integer, would be lower than current HP, or any level would contribute less than 1 HP.

After recalculated HP is active, rolled-HP corrections on both legacy and recorded levels adjust maximum HP only by the difference. Every correction and the activation are recorded through immutable, idempotent audit events, and the correction history is available through the validated Character WebSocket RPC contract. Concurrent editors must submit the revisions they loaded; stale saves are rejected and the editor reloads the latest values. Levels cannot be deleted, reordered, or renumbered.

Maximum HP Adjustments

The main character sheet shows a read-only Maximum HP Adjustments panel beneath the HP/vitals header. It lists each signed amount and note, marks pending entries, and shows the applied total. This total is already included in maximum HP; it is not added again. The panel updates with the live tracker state and is visible to both owners and viewers. Editing remains in Settings.

Character owners can add signed, flat maximum-HP adjustments in character settings for effects such as feats, conditions, or magic. Each adjustment requires a note and can be edited or deleted by the character owner; campaign viewers can only read the saved entries. Saving applies only the change from the previously applied amount; confirmed deletion reverses that applied amount. Current and temporary HP are preserved, and changes that would lower maximum HP below current HP or 1 are rejected. Adjustment changes retain immutable audit records, stale revisions are rejected, and deleted IDs cannot be reused.

Total HP remains an absolute manual value. It is not a modifier, formula, or per-level automation. Adjustments are additive entries, and the recalculated-HP preview includes the sum of all saved adjustments while explicitly excluding manual Total HP edits.

Older saved adjustment rows may be marked Pending application after migration. They are safely dormant until saved again or included when recalculated HP is activated, so no historical adjustment is silently applied twice. Deleting a dormant entry does not change maximum HP. The additive Character Durable Object migration runs automatically; no Turso/Drizzle schema migration is required.

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.