Skip to content

XP Command Reference

The !xp command allows DMs to manage character experience points during gameplay. DM-only command (requires active initiative).

Quick Reference

Command Description Example
!xp +<amount> <character> [note] Award XP !xp +10 gandalf solving the riddle
!xp -<amount> <character> [note] Deduct XP !xp -5 legolas reckless behavior
!xp show <character> Show current XP !xp show gandalf
!xp ledger <character> Show XP history !xp ledger gandalf

Features

  • Character name matching: Use partial names ("gan" matches "Gandalf")
  • Player notifications: Mentions players using server nicknames
  • Level-up alerts: Notifies when character is ready to level up
  • Detailed tracking: Creates ledger entries with timestamps and notes

Level-Up Integration

When players are ready to level up (XP ≥ XP needed), the bot will show: 

🎉 **Gandalf** is ready to level up! (105/100)

Level-Up Workflow

  1. DM awards XP via !xp commands during gameplay
  2. Bot notifies when character is ready to level up
  3. Player levels up in Shadowdarklings (XP resets to small amount)
  4. Player runs !update → Bot detects level change automatically
  5. Bot shows reconciliation → Player approves level up
  6. XP synchronized → Clean "Level up" entry created in ledger

Usage Examples

Basic XP Award

!xp +15 gandalf defeating the orc chieftain
Result: 
<@!123456> **Gandalf** gained 15 XP for defeating the orc chieftain
New XP: 78/100

Group XP Award (multiple commands)

!xp +20 gandalf completing the quest
!xp +20 legolas completing the quest  
!xp +20 gimli completing the quest

Checking Character Status

!xp show gandalf
Result: 
**Gandalf's** XP: 98/100

Viewing XP History

!xp ledger gandalf
Result: 
**Gandalf's** recent XP transactions:
1. +15 XP → 98 XP (2024-01-15) - defeating the orc chieftain
2. +10 XP → 83 XP (2024-01-15) - excellent roleplaying
3. +20 XP → 73 XP (2024-01-15) - solving the puzzle

Best Practices

During Sessions

  • Award XP immediately after noteworthy actions
  • Use descriptive notes to help players remember achievements
  • Monitor when characters are ready to level up
  • Award group XP with individual commands for each character

Level-Up Management

  • Encourage players to level up promptly when ready
  • Remind players to update their Discord character after leveling
  • Help players understand the level-up reconciliation process

Error Messages

Message Cause Solution
"Only DMs can manage XP" Non-DM tried to use command DM must use the command
"No active initiative found" No initiative running Start an initiative first
"Character not found" Typo in character name Check spelling or use more letters
"Insufficient XP!" Trying to deduct too much Check current XP with !xp show
"Usage: xp " Invalid syntax Follow command format
  • !init - Start initiative (required for XP commands)
  • !update - Update character sheet (triggers level-up reconciliation)
  • !character - Select active character (for viewing your own XP)
  • !sheet - View character sheet (includes tracked XP display)
  • !detail - View detailed character info (includes tracked XP display)

Technical Notes

  • XP values must be positive integers
  • Character names use fuzzy matching (case-insensitive, partial matches)
  • XP tracking persists across character updates
  • Level-up detection compares character sheet levels automatically
  • All XP transactions are logged with timestamps for audit trails

For detailed information about the level-up process and reconciliation system, see the XP Management Guide.