A Discord bot where players hatch elemental pets, raise them through four evolution stages, equip armor, learn skills, battle each other, and compete on the leaderboard. Ten elements, two variants each, fully illustrated with custom art.
- What is Elementals?
- Elements
- Evolution Path
- Stats
- All Commands
- Systems Overview
- Server Setup
- Self-Hosting
- Admin Commands
- Hosting on Railway
Players pick an elemental egg, feed and level it up, send it on expeditions for loot, equip armor, teach it skills from scrolls, and evolve it all the way to a powerful Mega form. Everything is driven by slash commands and interactive Discord menus — no prefixes needed.
| Element | Display | Emoji | Strong Against |
|---|---|---|---|
| void | Void | 🌑 | Phantom, Cosmic |
| ember | Ember | 🔥 | Bloom, Crystal |
| storm | Storm | ⚡ | Tide, Forge |
| bloom | Bloom | 🌿 | Tide, Phantom |
| crystal | Crystal | 💎 | Storm, Void |
| cosmic | Cosmic | ✨ | Void, Phantom |
| toxin | Plague | ☠️ | Bloom, Tide |
| forge | Forge | ⚙️ | Crystal, Cosmic |
| phantom | Phantom | 👻 | Forge, Plague |
| tide | Tide | 🌊 | Ember, Forge |
Each element has 2 variants with different names and art but identical base stats. Assigned randomly on /start. A pity system guarantees that picking the same element twice in a row gives you the other variant.
🥚 Egg ──( Feed 3× )──► Evo 1
Evo 1 ──( Level 20 + Uncommon Evo Stone )──► Evo 2
Evo 2 ──( Level 50 + Rare Evo Stone )──► Evo 3
Evo 3 ──( Level 100 + Exploration 100 + Mega Stone )──► ⭐ MEGA
- Evo Stones drop from expeditions and occasionally from channel drops
- Mega Stones only drop from expeditions when your pet's Exploration stat is at 100
- Evolution embeds show the stone's art as a thumbnail alongside the newly evolved pet
| Stat | Raised By |
|---|---|
| HP | Apple 🍎, Potion 🧪, Life Crystal |
| ATK | Carrot 🥕, Chicken 🍗, Ancient Fang 🦷, Dragonfruit 🐉 |
| DEF | Bread 🍞, Steak 🥩, Iron Scrap 🔩, Ironbark 🪵 |
| SPD | Grape 🍇, Noodles 🍜, Swift Feather 🪶, Windleaf 🍃 |
| MGK | Cheese 🧀, Mushroom 🍄, Crystal Shard 🔷, Honey 🍯, Cake 🎂 |
| RES | Fish 🐟, Berry 🫐, Mystic Root 🌱, Starfruit ⭐ |
Food rarities: Common (shop 500c) · Uncommon (shop 800c) · Rare (expedition drops only)
Stat items give a permanent flat bonus. Each stat has a cap based on base stat and level.
Exploration increases with every expedition (3–35 points depending on duration). Reaching 100 unlocks Mega Stone drops from expeditions.
| Command | Description |
|---|---|
/start |
Browse all 10 eggs and choose your element |
/profile [@user] |
View your or another player's active pet and coins |
/pet |
Full stat sheet: base + bonuses, caps, exploration, equipped armor |
/rename |
Give your active pet a nickname (leave blank to reset) |
/restart |
Delete all your data and start over |
| Command | Description |
|---|---|
/feed |
Pick a pet, food, and quantity (1/2/3/5/10/All) from dropdown menus |
/incubate |
Place an egg from your inventory to start hatching it |
/inventory |
View all items grouped by type — paginated with Prev/Next |
/use |
Use a stat item or evo stone on a pet (dropdown picker) |
/claim |
Grab a randomly spawned drop in the channel |
/train |
Daily training — boost a random stat + XP (20h cooldown) |
| Command | Description |
|---|---|
/expedition 30m |
Quick 30-minute run — light loot |
/expedition 1h30 |
1.5-hour expedition |
/expedition 4h |
4-hour expedition — guaranteed rare drop |
/expedition 6h |
Best loot and highest rarity chances |
/expedition status |
Check all active expedition timers |
/expedition cancel |
Recall a pet early — no loot awarded |
/expedition accelerate |
Use an accelerator item to shorten an expedition ⏩ |
/collect |
Collect your returned pet and all loot |
Loot by duration:
| Duration | Items | Guaranteed | Scroll chance | Armor chance |
|---|---|---|---|---|
| 30m | 3–4 | — | 5% | 5% |
| 1h30 | 4–5 | 1 uncommon | 12% | 15% |
| 4h | 5–7 | 1 rare | 28% | 38% |
| 6h | 6–8 | 2 rares | 50% | 60% |
Legendary loot only drops at 6h and only if Exploration is 100.
| Command | Description |
|---|---|
/armor |
View your full armor collection — paginated with Prev/Next |
/equip |
Equip armor to a pet — choose slot first, then filtered armor list |
/sellarmor |
Sell a piece of armor via dropdown (common 150 · uncommon 400 · rare 1000 · legendary 3000) |
/upgradearmor |
Sacrifice armor pieces as fodder to level up another piece (level 1→15) |
Armor adds flat stat bonuses visible in /pet. Four rarities: ⚪ Common · 🟢 Uncommon · 🟣 Rare · 🟡 Legendary.
Substats unlock at upgrade levels 3, 6, 9, and 12.
| Command | Description |
|---|---|
/dungeon <name> |
Farm a dungeon for 3–4 armor pieces (costs 20 🌙 Moon Shards) |
/moonshard |
Check your Moon Shard balance, regen timer, and player level |
- 🌙 Moon Shards regen +1 every 2 minutes, cap 120 (full in 4 hours)
- Better armor rarity at higher player levels
- 5 Dungeons: Ashen Ruins · Sunken Depths · Verdant Forge · Tempest Hollow · Void Nexus
- 4-piece armor set bonus = +20% element damage in battle
| Command | Description |
|---|---|
/learn |
Teach your pet a skill from a scroll — element filter shown if you have many |
/skills |
View all your pets' learned skills |
/forgetskill |
Remove a skill from a pet to free a slot (dropdown picker) |
/sellscroll |
Sell a scroll for coins (by typing the name) |
- Each pet can learn up to 4 skills
- 40 skills total across all 10 elements, 4 rarities each (common/uncommon/rare/legendary)
- Multipliers: common 1.3× · uncommon 1.6× · rare 2.1× · legendary 3.0×
- Each element can learn from itself and 2 compatible elements
- Skills are used during battle alongside normal attacks
| Command | Description |
|---|---|
/setparty |
Set your party order — use ⬆⬇ buttons, first pet starts battles |
/battle @user |
Challenge someone to PvP turn-based combat |
/battlelog |
View your recent battle history |
Battle is turn-based. Each turn you choose: Attack · Skill (pick from learned skills) · Defend · Item. Type advantages deal 1.5× damage. Speed determines who goes first.
| Command | Description |
|---|---|
/bossbattle |
Join the active boss raid and deal damage with your party |
/bossleaderboard |
View the server damage rankings for the current boss |
- Bosses spawn every Saturday at 10 UTC and end Monday midnight
- The boss is shared server-wide — all damage from all players counts toward the same HP pool
- The boss levels up as players deal damage, getting stronger each phase
- You cannot flee — fight until your last pet falls, then return later
- Rewards on boss defeat (by damage rank):
- 🥇 #1 — 35,000 coins · 3 Legendary armor · Legendary scroll
- 🥈 #2 — 20,000 coins · 2 Rare armor · Rare scroll
- 🥉 #3 — 12,000 coins · 1 Rare armor · Rare scroll
- ⚔️ #4+ — 8,000 coins · 1 Uncommon armor · Common scroll
| Command | Description |
|---|---|
/shop |
Browse available food and stat items |
/buy <item> [qty] |
Purchase an item with coins |
/sell |
Sell items back for coins (dropdown picker) |
/balance |
Check your coin balance |
/daily |
Daily login bonus — 100 coins + XP (24h cooldown) |
/give @user <amount> |
Transfer coins to another player |
/trade @user offer:<item> request:<item> |
Propose an item trade |
/coinflip <amount> |
Bet coins on a coin flip — win 2× or lose it all (min 50) |
/dice <amount> |
Roll dice — roll higher than the bot to win (min 50) |
| Command | Description |
|---|---|
/fish |
Cast a line for coins, items, and accelerators (10min cooldown) |
/dig |
Excavate for buried treasure and accelerators (10min cooldown) |
/trivia |
Answer a question for coins — 80+ questions, no cooldown |
/leaderboard |
Top 10 highest-level pets on the server |
Random items spawn in the configured drops channel every 20–60 minutes and expire after 12 minutes if unclaimed. Use /claim to grab one. First person to claim wins it.
All non-egg pets that aren't on expedition earn passive XP every hour automatically — no action needed.
Separate from pet levels. Gained by completing activities (expeditions, dungeons, daily, etc.). Higher player level unlocks better armor rarity from dungeons.
Tracked per pet from 0–100. Increases each time the pet returns from an expedition:
| Duration | Exploration Gained |
|---|---|
| 30m | +3 |
| 1h30 | +8 |
| 4h | +20 |
| 6h | +35 |
Visible in /pet with a progress note. At 100/100 Mega Stones become available in expedition loot.
When picking a starter egg, if you've chosen the same element before and got variant 1, your next pick of that element is guaranteed to be variant 2 (and vice versa). After the pity triggers it resets to 50/50.
Run these once as a server admin:
/setup drops #channel — Set the channel for automatic item drops
/setup announcements #channel — Set the channel for Mega Evolution announcements
/setup info — Confirm your current configuration
Use /admin drop to immediately test that drops are working.
- Python 3.11+
- A Discord bot token (Discord Developer Portal)
git clone https://github.com/AsmaArrak/elements.git
cd elements
pip install -r requirements.txt
cp .env.example .env
# Fill in BOT_TOKEN (and optionally GUILD_ID, ADMIN_IDS) in .env
python bot.py| Variable | Required | Description |
|---|---|---|
BOT_TOKEN |
✅ | Your Discord bot token |
DB_PATH |
Optional | Custom path for the SQLite database file |
GUILD_ID |
Optional | Guild ID for instant slash command sync during development |
ADMIN_IDS |
Optional | Comma-separated Discord user IDs allowed to use /admin |
Users listed in ADMIN_IDS can use:
| Command | Description |
|---|---|
/admin drop |
Force a drop in the drops channel immediately |
/admin give @user <item> [qty] [element] |
Give any item to a player |
/admin coins @user <amount> |
Add or remove coins (negative to deduct) |
/admin xp @user <amount> |
Add XP to a player's active pet |
/admin announce <message> |
Post to the announcements channel |
/admin stats |
Server-wide stats (players, hatched pets, megas, expeditions) |
/admin backup |
DM yourself the database file |
/admin restore <file> |
Overwrite the database from a .db attachment |
/spawnboss |
Manually spawn the weekend boss |
/endboss |
Manually end the current boss and distribute rewards |
Tip: Before every Railway redeploy, run
/admin backup. After the deploy, run/admin restorewith the file it DM'd you to restore your data.
- Push this repo to GitHub
- Create a new project on Railway and connect the repo
- Add environment variables in the Railway dashboard:
BOT_TOKEN,ADMIN_IDS, optionallyGUILD_ID - Turn off auto-deploy in Railway Settings → Source to prevent accidental data loss on every push
- To deploy a new version: Settings → Source → "Check for updates"
⚠️ Railway's free tier does not include persistent volumes. The database lives on the container's ephemeral filesystem. Always run/admin backupbefore deploying and/admin restoreafter to preserve player data.