Discord Bot
Economy & Progression
Activity earns XP and balance. Levels unlock perks. Every rate and constant is defined in one place so the whole economy can be retuned without touching feature code.
What's tracked per member
xpint | Experience earned from activity and completed contracts. |
balanceint | Spendable in-game currency. |
messagesint | Lifetime message count used for activity rewards. |
unlocked_levelslist | Levels the member has reached and the perks they grant. |
languagestr | Personal language preference for ephemeral responses. |
This record lives in Firestore at guilds/{guild_id}/users/{user_id} and is mirrored in memory for fast reads.
Tuning the numbers
XP rates, cooldowns and economy constants are all defined in settings.py. Because it holds no secrets, it is safe to commit and review like any other gameplay change.
settings.py (illustrative)
# Gameplay balance: no secrets, safe to commit
XP_PER_MESSAGE = 5
MESSAGE_COOLDOWN = 60 # seconds between XP-earning messages
CONTRACT_REWARD = 250 # base balance for a completed contract
LEVEL_CURVE = 1.35 # XP multiplier per levelOne source of truth
Cogs read these constants rather than hard-coding their own, so a single edit re-balances the entire economy consistently.
Reading and writing data
The store singleton in data/store.py buffers writes in memory and auto-saves on a timer. Reads are synchronous; writes are awaited.
# Synchronous read
user = store.get_user(guild_id, user_id)
# Awaited write
await store.add_balance(guild_id, user_id, CONTRACT_REWARD)