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 to specific character !xp +10 gandalf solving the riddle
!xp -<amount> <character> [note] Deduct XP from specific character !xp -5 legolas reckless behavior
!xp +<amount> <description> Award XP to entire party !xp +15 defeating the dragon
!xp -<amount> <description> Deduct XP from entire party !xp -5 poor teamwork
!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")
  • Party-wide XP awards: Award XP to all party members at once
  • 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 @mention the player and show: 

<@!user123> **Gandalf** gained 10 XP for excellent problem solving
🎉 **Gandalf** is ready to level up! (105/100)

The level-up notification appears as a second line after the normal XP award message, ensuring the player is notified they can now level up in Shadowdarklings.

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

XP Award Triggering Level-Up

!xp +5 gandalf clever tactics
Result: 
<@!123456> **Gandalf** gained 5 XP for clever tactics
🎉 **Gandalf** is ready to level up! (105/100)

Party XP Award (single command)

!xp +20 completing the quest
Result: 
**Party gained 20 XP** for completing the quest
• <@!123456> **Gandalf**: 120/100 🎉 Ready to level up!
• <@!789012> **Legolas**: 70/100
• <@!345678> **Gimli**: 45/100

Group XP Award (individual 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
  • Use party XP commands (!xp +amount description) for group rewards
  • Use individual commands when awarding different amounts to different characters

Level-Up Management

  • Monitor @mention notifications - players get notified automatically when ready to level up
  • Communicate excess XP policy - decide whether excess XP carries over or resets to 0
  • Encourage prompt level-ups - avoid confusion by leveling up soon after notifications
  • Guide reconciliation process - help players understand the "trust the sheet" approach

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)
  • Party awards require multiple words in the description to distinguish from character names
  • Player notifications include @mentions using Discord user IDs
  • Level-up detection compares current tracked XP to character's XP threshold
  • Party XP exclusions: DM's characters (NPCs) are automatically excluded from party awards
  • Reconciliation preserves history - all XP transactions remain in audit trail
  • XP tracking persists across character updates and level-ups
  • All transactions are logged with timestamps and detailed notes

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