SYS // DOCS-01

ROGUE TALES ENGINE

TELEGRAM RPG BOT // FULL DOCUMENTATION

PROJECT
ROGUE

A massive multiplayer text-based RPG bot built on Kurigram (Pyrogram) and MongoDB. Deep economy, turn-based combat, dungeon exploration, alchemy, faith systems, and a persistent world cycle.

14+

PLUGINS

500+

USERS TARGET

GAME MODULES

v0.2

CURRENT BUILD

VIRTUAL CODE STRUCTURE

📁 ProjectRogue/

📁bot/

📄main.pyENTRY

📄config.pyCONFIG

📄__main__.pyRUNNER

📄config.txtENV

📁game/

⚔️combat.pyGAME

🗺️dungeon.pyGAME

⚙️mechanics.pyGAME

📜lore.pyGAME

🎯quests.pyGAME

🎒inventory.pyGAME

🌗world_cycle.pyGAME

📄__init__.pyEXPORTS

📁plugins/

▶️start.pyPLUGIN

⚔️combat.pyPLUGIN

🏰dungeon.pyPLUGIN

🎯quests.pyPLUGIN

🛒market.pyPLUGIN

🏆leaderboard.pyPLUGIN

🙏faith.pyPLUGIN

⚔️pvp.pyPLUGIN

🤝social.pyPLUGIN

🎮arcade.pyPLUGIN

🧪skills_alchemy.pyPLUGIN

🎒inventory.pyPLUGIN

📖lore_plugin.pyPLUGIN

📁database/

🗄️db.pyMONGO

📄__init__.pyEXPORTS

📁utils/

🔒decorators.pyUTIL

📁instructions/

📋instructions.mdSPEC

📁logs/

📝roguebot.logLOG

📋requirements.txt

📖CHANGELOG.md

🔨BUILD_PROMPT.md

📄README.md

ARCHITECTURE

      main.py · startup flow
# ── Startup Sequence ──────────────────────────────────────────────
async def boot():
    mk_log()                          # RotatingFileHandler (3MB × 5 backups)
    scan_plugins()                    # Dynamic importlib plugin loader
    await app.start()                # Pyrogram/Kurigram client
    await init_db()                  # Motor MongoDB connect (pool 20–200)
    await ping_db()                  # Health check
    await WORLD_CYCLE.start()        # Day/Night background service
    await send_gc(report)            # Boot report to LOG_GC
    await idle()
    

        config.py · env vars
class Config:
  API_ID        # Telegram API ID (required)
  API_HASH      # Telegram API hash (required)
  BOT_TOKEN     # Bot token (required)
  MONGO_URI     # MongoDB URI (required)
  SUDO_USERS    # Comma-sep int IDs
  LOG_GC        # Log group chat ID
  WORKERS       # default 64
  DAY_NIGHT_INTERVAL_SEC  # default 900
      

        database/db.py · collections
usersdb   = db.users
itemsdb   = db.items
questsdb  = db.quests
clansdb   = db.clans
nationsdb = db.nations
marketdb  = db.market
worlddb   = db.world_state
      

⚡

ASYNC FIRST

All DB calls, API requests and heavy math are awaited — never blocking the Pyrogram event loop. Motor driver throughout.

KURIGRAM · MOTOR

🔌

PLUGIN LOADER

scan_plugins() uses importlib to dynamically load all *.py files in bot/plugins/. Failed plugins log but never crash boot.

IMPORTLIB · SCAN

🗄️

MONGODB

7 collections: users, items, quests, clans, nations, market, world_state. Pool 20–200. DNS forced to 8.8.8.8 for VPS stability.

MOTOR · ASYNC

🌗

WORLD CYCLE

Background asyncio task ticks day/night phase at configurable intervals (DAY_NIGHT_INTERVAL_SEC). Survives tick failures gracefully.

WORLD_CYCLE_SERVICE

CORE GAME SYSTEMS

🎭

CHARACTER PATHS

Three paths at creation: Warrior 🛡️, Rogue 🗡️, Mage 🔮. Each unlocks path-specific skills from SKILLS_CATALOGUE with unique synergies and stat scaling.

MECHANICS.PY · START.PY

📦

INVENTORY SYSTEM

Item, Enchantment, ItemSkin, Inventory dataclasses (slots=True). 4-slot chests: weapons, armoury, potions, tools. 60-item cap. Enchants stack additively.

INVENTORY.PY

💰

DEEP ECONOMY

Gold/Gems/Bank wallet. Gold sinks via durability, market tax, healing costs. Player-to-player trading. NPC shop with programmatic sale events.

MARKET.PY · DB.PY

🧪

ALCHEMY

ALCHEMY_RECIPES catalogue with reagent requirements. apply_enchant() mutates items with stat bonuses. available_recipes() filters by player ingredients.

SKILLS_ALCHEMY.PY

🙏

FAITH SYSTEM

Full pantheon of gods, each with domains and day/night restrictions. Praying grants +10 favour. Blessings and curses applied as status effects.

FAITH.PY · LORE.PY

🤝

SOCIAL & CLANS

Friend requests, accept/decline flow. Clan creation with 24-char name limit, vault deposit, clan-wide buffs. Nation hierarchy above clans for politics.

SOCIAL.PY · DB.PY

COMBAT ENGINE

Turn-based combat with status effects, skills, mana, cooldowns, and lore drops on mob defeat. Every fight tick is a pure function: given state → return new state. Night mobs gain +12 ATK / +6 DEF.

STATUS EFFECTS

EFFECT	TYPE	TICK DMG	DUR	SPECIAL
🟢 Poisoned	DEBUFF	12	3	—
🩸 Bleeding	DEBUFF	8	4	-4 DEF
👁️ Blinded	DEBUFF	0	2	-15 ATK
🧊 Frozen	DEBUFF	0	1	Skip turn
🕳️ Void-Cursed	DEBUFF	5	5	-5 all
✨ Blessed	BUFF	—	4	+10 Faith
🔥 Enraged	BUFF	—	3	+20 ATK/-10 DEF
🌑 Shadow Step	BUFF	—	1	Pierce DEF
💜 Arcane Surge	BUFF	—	2	2× INT dmg

COMBAT STATE

@dataclass
class CombatState:
  player_hp:     int
  player_hp_max: int
  mob:           CombatMob
  player_mana:   int = 60
  turn:          int = 0
  log:           List[str]
  finished:      bool = False
  player_won:    bool = False
  loot_drop:     Optional[Dict]
  lore_drop:     Optional[Dict]
        

PVP DUEL ENGINE

# _sim_duel() runs up to 30 turns
# Random ±3–5 variance per hit
# Challenger issues /duel @target
# Target accepts via inline button
# Winner gets XP + wager gold
await log_pvp_result(uid, result)
        

MOB CATALOGUE

20 unique mobs across 5 regions. Level-scaled via CombatMob.from_catalogue(). Night mobs in night_only/voidmarsh/thornwood gain bonus stats under the world cycle.

🟢 Green Slime

HP 40 · ATK 5 · DEF 2
XP 15 · Gold 8

VAELTHORN · LVL 1–5

👺 Goblin Scout

HP 70 · ATK 12 · DEF 5
XP 35 · Gold 20

VAELTHORN · LVL 1–10

🐀 Void-Touched Rat

HP 55 · ATK 14 · DEF 3
XP 40 · Cursed on hit

VAELTHORN · LVL 2+

🗡️ Corrupt Guard

HP 110 · ATK 22 · DEF 14
XP 70 · Bleed on hit

VAELTHORN · LVL 5+

🐺 Dire Wolf

HP 100 · ATK 20 · DEF 8
XP 60 · Bleed on hit

THORNWOOD · LVL 8–14

🔪 Road Bandit

HP 130 · ATK 28 · DEF 12
XP 90 · Gold 55

THORNWOOD · LVL 8–20

🌿 Vine Horror

HP 160 · ATK 25 · DEF 18
XP 110 · Poison on hit

THORNWOOD · LVL 14+

🧙 Forest Witch

HP 140 · ATK 35 · DEF 8
XP 130 · Blind on hit

THORNWOOD · LVL 14+

🪨 Stone Troll

HP 220 · ATK 40 · DEF 20
XP 150 · Bleed on hit

ASHPEAK · LVL 18–25

🤖 Dwarf Automaton

HP 280 · ATK 50 · DEF 30
XP 200 · Gold 120

ASHPEAK · LVL 25+

🌋 Lava Sprite

HP 200 · ATK 55 · DEF 15
XP 220 · Poison on hit

ASHPEAK · LVL 14+

👻 Night Wraith

HP 180 · ATK 55 · DEF 10
XP 200 · Cursed on hit

NIGHT ONLY · LVL 15+

🦀 Void Crawler

HP 300 · ATK 65 · DEF 22
XP 300 · Cursed on hit

VOIDMARSH · LVL 18+

🌑 Shade Lord

HP 420 · ATK 80 · DEF 28
XP 420 · Bleed on hit

VOIDMARSH · LVL 22+

🕯️ Void Cleric

HP 360 · ATK 70 · DEF 20
XP 380 · Cursed on hit

VOIDMARSH · LVL 20+

🛡️ Dungeon Guardian

HP 350 · ATK 65 · DEF 30
XP 320 · Gold 200

DUNGEON · LVL 20+

🐉 Young Dragon

HP 800 · ATK 120 · DEF 50
XP 1000 · Gold 600

DUNGEON BOSS · LVL 30+

🌀 Void Herald

HP 1200 · ATK 160 · DEF 60
XP 3000 · Cursed on hit

SOLARIUM · LVL 40+

🐲 Ancient Dragon

HP 2000 · ATK 200 · DEF 80
XP 5000 · Gold 2000

SOLARIUM · LVL 45+

PLUGIN REGISTRY

All handlers live in bot/plugins/. Auto-loaded on boot via importlib scanner.

▶️

START

Character creation, path selection (Warrior/Rogue/Mage), profile display with all stats, world phase banner.

⚔️

COMBAT

Turn-based PvE fights. /fight command. Skill use, status effect resolution, loot and lore drops on defeat.

🏰

DUNGEON

Procedural floor generator. Room types: empty, mob, chest, trap, shrine, boss. Hidden dungeon rare spawns.

🎯

QUESTS

Daily quests from 30-quest pool (level-filtered). 10-chapter story arc. Quest progress tracking in DB.

🛒

MARKET

Player-to-player trading. NPC shop listings. Buy/sell/list commands. Tax sink on transactions.

🏆

LEADERBOARD

Global rankings by XP, gold, kills, dungeon clears, and faith score. Paginated output.

🙏

FAITH

/pray command with god pantheon keyboard. +10 faith favour per prayer. Day/night god restrictions. NPC interactions with rumours.

⚔️

PVP

/duel @target command. Inline accept/decline. Simulated combat up to 30 turns. XP and gold rewards. log_pvp_result() to DB.

🤝

SOCIAL

Friend requests, accept/decline flow. /clan create with 24-char cap. Clan vault gold deposits. Friend list display.

🎮

ARCADE

Slots (8 symbols, weighted), dice duel, coin flip. Bet 10–5000 gold. Triple 💎 pays 50×. Two-of-a-kind breaks even.

🧪

SKILLS & ALCHEMY

Brew potions from reagents using ALCHEMY_RECIPES. apply_enchant() upgrades gear stats. available_recipes() filters by inventory.

🎒

INVENTORY

/inventory command. View 4-slot chests. Equip/unequip items. rolled_stats() shows final stat bonuses from enchants.

📖

LORE

Lore fragment viewer. random_rumour(), random_ambient() surface world flavour. roll_lore_drop() on mob kill.

STATS & ECONOMY

PLAYER STAT WEIGHTS (LVL 50)

STR

AGI

INT

LUK

FAITH

          stat formula
# Base + gear_bonus + potion_bonus + lvl_scale
attack  = str * 2 + max(lvl-1, 0)
defense = agi + faith // 2
hp      = base_hp + (lvl-1) * 8
        

CURRENCY TIERS

TIER	SYMBOL	USAGE
Copper	🪙	Basic trades, healing
Silver	🥈	Equipment, enchants
Gold	💰	Rare items, market tax
Gems	💎	Premium cosmetics, skins

DUNGEON LOOT TIERS

TIER	ITEMS	STAT BONUS
Common	HP Potion, Wood Sword	HP+50 / ATK+8
Rare	Iron Shield, Silver Blade	DEF+15 / ATK+25
Epic	Mithril Mail, Void Blade	DEF+40 / ATK+60

QUEST SYSTEM

30 daily quests filtered by player level. 10-chapter story arc. Joint quests for 2+ players. Post-game 1000+ quest database unlocks after the main storyline.

QUEST TYPES

TYPE	DESCRIPTION
kill	Slay N specific mob
kill_any	Win any N fights
dungeon_rooms	Survive N dungeon rooms
gold	Accumulate N gold
pray	Pray N times today
brew	Craft N alchemy items
pvp_win	Win N duels
lore_drops	Collect N lore fragments
arcade_plays	Play N arcade rounds
clan_deposit	Deposit N gold to vault
market_txn	Complete N market trades
visit	Visit a specific system

STORY ARC — 10 CHAPTERS

CH 1–3

VAELTHORN ORIGINS

Player awakens as a Rogue. Defend hometown, uncover the Sundering's aftermath.

CH 4–6

THORNWOOD TRIALS

Journey into the cursed forest. Confront the Void Clergy's growing influence.

CH 7–8

ASHPEAK ASCENSION

Reach the dwarven ruins. Seek a way to harness the Anima Cores.

CH 9–10

THE VOIDMARSH ENDGAME

Descend into the Voidmarsh. Face the Void Herald and discover what Solarius sealed.

      quests.py · key functions
generate_daily_quest(user_level)           # Returns filtered quest from pool
make_story_quest_doc(chapter, user_id)      # Creates chapter quest document
advance_quest_progress(doc, event, count)   # Increments quest counter
total_story_chapters()                      # Returns 10
    

LORE & WORLD

In the age before memory, the God-King Solarius forged five kingdoms from chaos and bound them with the Eternal Covenant. The Sundering tore it apart. His divine essence shattered into Anima Cores. You are one who touched a Core. A Rogue. And Aethermoor is running out of time.

🏚️

VAELTHORN

The Shattered Hometown. A market town at the edge of Thornwood, half-ruined by the Sundering. Levels 1–10.

STARTER REGION

🌲

THORNWOOD

A cursed ancient forest haunted by bandits, vine horrors, and forest witches. Levels 8–20.

MID REGION

⛰️

ASHPEAK

Volcanic highland of the dwarven ruins. Home to automatons, trolls, and lava sprites. Levels 18–35.

HIGH REGION

🌑

VOIDMARSH

The edge of known reality. Void crawlers and shade lords stalk the dark. Night mobs amplified. Levels 30+.

ENDGAME REGION

☀️

SOLARIUM

The sealed pinnacle. Ancient dragons and void heralds guard the truth of the Sundering. Levels 40–50.

FINAL REGION

⚡

GODS & FAITH

Full pantheon with domains, day/night restrictions, boons, and curses. Faith stat affects defence formula. Praying costs no gold.

LORE.PY · FAITH.PY

      lore.py · functions
path_info(path_key)       # Returns path lore dict
random_ambient(region)    # Random ambient flavour line
random_rumour()           # Random world rumour string
roll_lore_drop(lore_src)  # Returns lore fragment on mob kill
available_npcs(phase)     # Returns NPCs active in day or night
    

BUILD PHASES

PHASE 1 · v0.1.0

FOUNDATIONS

Config env loader, Motor DB setup (7 collections), user profile schema, @sudo_only / @group_admin_only decorators, plugin bootstrap with importlib, graceful shutdown.

PHASE 2 · v0.2.0

GAMEPLAY CORE

Full turn-based combat engine with 9 status effects and skills. Procedural dungeon floor generator. World cycle day/night service. Inventory dataclasses with enchants and skins. Faith, PvP, Social, Arcade, Alchemy, Quests (30 daily + 10-chapter story), Leaderboard, Lore plugins — all 13 plugins loaded.

PHASE 3 · PLANNED

ECONOMY & POLITICS

Full P2P market with tax sinks. Clan vs Clan battles. Nation/political hierarchy. Hometown property ownership. Programmatic sale events. Black Friday discounts.

PHASE 4 · PLANNED

ENDGAME CONTENT

World bosses requiring team effort. Post-story 1000+ quest unlock. Solarium region full implementation. Seasonal events. PvP ranked season system.

UPDATES

v0.2.02026-04-15

ADDITIONCHANGEFIX

Full turn-based combat engine (combat.py) with 9 status effects, skills, passives, mana, lore drops

Procedural dungeon floor generator (dungeon.py) — 8 room types including boss and shrine

20-mob catalogue across 5 regions with level scaling and night bonuses

game/mechanics.py — STATUS_CATALOGUE, SKILLS_CATALOGUE, ALCHEMY_RECIPES, ENCHANTMENTS

game/lore.py — WORLD_LORE, REGIONS, GODS, NPCS with day/night scheduling

game/quests.py — 30 daily quests, 10-chapter story arc, advance_quest_progress()

Inventory models (Item, Enchantment, ItemSkin, Inventory) with enchants and skins support

WorldCycleService background task wired to main.py boot/shutdown

13 plugins loaded: start, combat, dungeon, quests, market, leaderboard, faith, pvp, social, arcade, skills_alchemy, inventory, lore_plugin

Rich async MongoDB layer for all 7 collections with character-path helpers and world-state helpers

Reworked /start into character-creation flow: path selection → profile → world phase display

User profile schema extended with STR/AGI/HP/INT/LUK/Faith/Reputation, wallet, and inventory chest

DAY_NIGHT_INTERVAL_SEC config support added

World cycle tick failures no longer crash the background loop

v0.1.02026-04-15

ADDITIONCHANGEFIX

bot/config.py — env loading/parsing for BOT_TOKEN, MONGO_URI, SUDO_USERS, all optional overrides

bot/database/db.py — async Motor setup with pool sizing, DNS fix (8.8.8.8), and profile helpers: get_user, create_user, update_user

bot/utils/decorators.py — @sudo_only and @group_admin_only async access guards

bot/plugins/start.py — bootstraps user profiles and sends RPG welcome UI with inline keyboard

bot/main.py — plugin loader (importlib scan), DB init/ping, graceful shutdown

bot/__main__.py — package runner entrypoint

Standardised runtime flow to the in-package bot/ structure

Removed misplaced root-level scaffold in favour of in-package implementation

DEPLOYMENT

      terminal · install & run
# 1. Clone and enter project
git clone <repo> && cd ProjectRogue

# 2. Install dependencies
pip install -r requirements.txt

# 3. Configure environment (bot/config.txt)
API_ID=your_api_id
API_HASH=your_api_hash
BOT_TOKEN=your_bot_token
MONGO_URI=mongodb+srv://...
SUDO_USERS=123456789

# 4. Run the bot
python -m bot
    

        requirements.txt
kurigram
motor
pymongo
python-dotenv
dnspython
      

        optional env vars
LOG_GC=-100123456      # Log group chat
LOG_LEVEL=INFO           # DEBUG|INFO|WARNING
WORKERS=64               # Pyrogram workers
DB_NAME=rogue_tales      # MongoDB db name
DAY_NIGHT_INTERVAL_SEC=900  # 15 min cycle
      

PROJECT ROGUE // DOCS ROGUE TALES ENGINE · v0.2.0