XP Management & Level-Up System¶

This guide explains how StingbatBot manages experience points (XP) for Shadowdark characters, including the unique level-up reconciliation process.

Overview¶

StingbatBot tracks XP separately from your character sheet, creating a detailed ledger of all XP gains and losses. This system is designed to work seamlessly with Shadowdark's unique level-up mechanics where XP resets to zero (or a small amount) when you level up.

How XP Tracking Works¶

For DMs: Awarding XP¶

Use the !xp command to award or deduct XP from characters in your initiative:

!xp +10 gandalf excellent roleplaying
!xp +25 party defeating the dragon
!xp -5 legolas poor decision making
!xp show gandalf
!xp ledger gandalf

Key Features: - Works with character name fuzzy matching ("gan" matches "Gandalf") - Mentions the player in responses using their server nickname - Creates detailed ledger entries with notes - Only DMs can use XP commands (requires active initiative)

For Players: Checking Your XP¶

Players can view their current XP in several ways:

XP Commands:

!xp show gandalf          # Shows current XP and XP needed for next level
!xp ledger gandalf        # Shows recent XP transaction history

Character Sheet Commands:

!sheet                    # Shows your selected character's sheet (includes tracked XP)
!detail                   # Shows detailed character information (includes tracked XP)
!sheet gandalf            # Shows specific character's sheet

The sheet and detail commands show your tracked XP (what the bot is monitoring) alongside all your other character stats, making it easy to see everything at once.

The Level-Up Process¶

Shadowdark uses a unique XP system where XP resets when you level up. Here's how the bot handles this:

Step 1: Earning XP in Discord¶

DM awards XP via Discord: !xp +15 gandalf solving the puzzle
Bot tracks XP in its ledger (e.g., character now has 105 XP)
When ready to level up, bot notifies: "🎉 Gandalf is ready to level up! (105/100)"

Step 2: Leveling Up in Shadowdarklings¶

Go to Shadowdarklings website
Add all the XP you've earned (105 XP in this example)
Complete the level-up process (Level 2 → 3)
Important: Make sure your XP is correct in Shadowdarlkings post level-up

Step 3: Updating Your Character in Discord¶

Run !update command with your updated character sheet
Bot detects the level change and shows a reconciliation preview:

🎉 Level Up Detected: Gandalf (2 → 3)

📊 Current tracked XP: 105 XP
📄 New sheet XP: 15 XP  
📝 Action: Create level-up ledger entry (-90 XP)

This will create an XP transaction: "Level up - Level 2 to 3"

[✅ Approve Level Up] [❌ Cancel Update]

Click "Approve Level Up" to confirm
Bot creates a special "Level up" entry in your XP ledger
Your tracked XP now matches your sheet (15 XP)

Understanding XP Reconciliation¶

When you update your character, the bot may need to reconcile differences between what it's tracking and what's on your character sheet.

Scenario 1: Normal Level Up ✅¶

Tracked XP: 105 (you earned XP via Discord)
Sheet XP: 15 (you leveled up and reset XP)
Bot Action: Automatically detects level-up, creates reconciliation entry
Result: Clean level-up transaction in ledger

Scenario 2: XP Changes Without Level Up ⚠️¶

Tracked XP: 45 (via Discord commands)
Sheet XP: 60 (you manually adjusted XP)
Bot Action: Shows reconciliation options
Your Choice: Keep tracked (45) or accept sheet (60)

Scenario 3: Both Coins and Level Up 🔄¶

Bot detects: Level up AND coin changes
Preview shows: Both reconciliation decisions needed
Your choices: Approve level up + choose coin reconciliation

Best Practices¶

For DMs¶

Award XP promptly after sessions using Discord commands
Use descriptive notes to help players remember what they earned XP for
Check if players are ready to level up by monitoring XP totals
Encourage players to update their sheets after leveling up

For Players¶

Level up in Shadowdarklings when the bot says you're ready
Set your post-level-up XP correctly on the character sheet
Run !update after making changes to keep Discord in sync
Review reconciliation previews carefully before approving
Check your XP ledger with !xp ledger to see transaction history

Common Questions¶

Q: Why does my XP reset to a low number after leveling up?¶

A: This is normal in Shadowdark! XP resets when you level up. The bot tracks this properly and creates a "Level up" ledger entry to record the transition.

Q: What if I forget to award XP via Discord?¶

A: You can award XP retroactively, or players can update their character sheets and use the reconciliation system to sync up.

Q: Can I manually adjust XP on my sheet?¶

A: Yes, but you'll need to choose during reconciliation whether to keep the bot's tracked XP or accept your sheet's XP.

Q: What happens to my XP history when I level up?¶

A: All your XP history is preserved! The bot just adds a "Level up" entry showing the XP reset. You can always see your full history with !xp ledger.

Q: Can players award XP to themselves?¶

A: No, only DMs can use XP commands. This prevents cheating and maintains game balance.

Troubleshooting¶

XP Reconciliation Issues¶

If you see unexpected XP reconciliation prompts:

Check your math: Ensure your sheet XP matches what you intended
Review the ledger: Use !xp ledger to see recent transactions
When in doubt, keep tracked XP: The bot's ledger is usually accurate
Cancel and fix: You can cancel the update, fix your sheet, and try again

Level-Up Not Detected¶

If the bot doesn't detect your level up:

Verify level change: Make sure your character sheet shows the new level
Check XP tracking: Use !xp show to see current tracked XP
Contact your DM: They may need to manually award missing XP

Character Update Fails¶

If character updates fail:

Try again: Temporary issues often resolve themselves
Check file format: Ensure you're using a valid JSON export
Review changes: Make sure your character data is valid

Examples¶

Example 1: Typical Level-Up Flow¶

# During the session
DM: !xp +20 gandalf completing the main quest
Bot: <@!user123> **Gandalf** gained 20 XP for completing the main quest
      New XP: 95/100

DM: !xp +10 gandalf excellent problem solving  
Bot: 🎉 **Gandalf** is ready to level up! (105/100)
     New XP: 105/100

# Player goes to Shadowdarklings:
# - Adds 105 XP (total becomes 105)
# - Levels up 2 → 3  
# - Sets XP to 5 (leftover after leveling)

# Back in Discord:
Player: !update
Bot: 🎉 Level Up Detected: Gandalf (2 → 3)
     📊 Current tracked XP: 105 XP
     📄 New sheet XP: 5 XP
     [✅ Approve Level Up] [❌ Cancel Update]

# Player clicks Approve Level Up
Bot: 🎉 **Gandalf** has leveled up from 2 to 3! XP has been synchronized.

Example 2: XP Ledger After Level-Up¶

Player: !xp ledger gandalf
Bot: **Gandalf's** recent XP transactions:
     1. Level up - Level 2 to 3 → 5 XP (2024-01-15) - Leveled up in Shadowdarklings
     2. +10 XP → 105 XP (2024-01-15) - excellent problem solving  
     3. +20 XP → 95 XP (2024-01-15) - completing the main quest

This system ensures that XP tracking remains accurate across Shadowdark's unique level-up mechanics while providing full transparency and player control over the reconciliation process.