Skip to content

XP Command Reference

The /xp command allows DMs to manage character experience points during gameplay. DM-only for gain/lose (requires active initiative). Players can use show/ledger.

Quick Reference

Command Description Example
/xp show character:<name> Show current XP /xp show character:gandalf
/xp ledger character:<name> Show XP history (default 5 entries) /xp ledger character:gandalf
/xp ledger character:<name> count:<n> Show specific number of entries /xp ledger character:gandalf count:10
/xp gain amount:<int> note:<string> Award XP to entire party /xp gain amount:15 note:defeating the dragon
/xp gain amount:<int> note:<string> character:<name> Award XP to specific character /xp gain amount:10 note:solving the riddle character:gandalf
/xp lose amount:<int> note:<string> Deduct XP from entire party /xp lose amount:5 note:poor teamwork
/xp lose amount:<int> note:<string> character:<name> Deduct XP from specific character /xp lose amount:5 note:reckless behavior character:legolas

Features

  • Character name autocomplete: Type to search characters in initiative
  • Party-wide XP awards: Omit the character option to 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 gain amount:15 note:defeating the orc chieftain character:gandalf
Result: 
<@!123456> **Gandalf** gained 15 XP for defeating the orc chieftain
New XP: 78/100

XP Award Triggering Level-Up

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

Party XP Award

/xp gain amount:20 note: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

Checking Character Status

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

Viewing XP History

/xp ledger character: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
  • Omit the character option for group rewards (awards entire party)
  • Specify a character 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 gain/lose DM must use the command
"No active initiative found" No initiative running Start an initiative first
"Character not found" Invalid character name Check spelling or use autocomplete
"Insufficient XP!" Trying to deduct too much Check current XP with /xp show
  • /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 autocomplete from the current initiative
  • Party awards: Omit the character option to award the entire party
  • 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.

Legacy Prefix Commands

The prefix command syntax still works but will be removed in a future update:

Legacy Syntax Slash Equivalent
!xp show gandalf /xp show character:gandalf
!xp ledger gandalf /xp ledger character:gandalf
!xp +10 gandalf solving the riddle /xp gain amount:10 note:solving the riddle character:gandalf
!xp -5 legolas reckless behavior /xp lose amount:5 note:reckless behavior character:legolas
!xp +15 defeating the dragon /xp gain amount:15 note:defeating the dragon