Developer Documentation

Developer Documentation

This page is for contributors and anyone interested in the internal structure of Idleology.

The project has been developed iteratively. The architecture described here reflects the main design principles that have guided the code, though not every file follows them perfectly.

See the Architecture Overview page for the detailed structural description.

Project Overview

Idleology is a text-based idle RPG Discord bot.

• Runtime: Python 3.11.5+
• Discord library: discord.py
• Database: SQLite via aiosqlite (database/schema.sql)
• Game data: CSV/JSON/TXT files in assets/ (monsters, items, exp tables, partners, etc.)
• Current version: See UPDATES.md and README.md

High-Level Architecture

cogs/          → Discord command handlers (primarily thin entry points)
core/          → Game logic, models, UI views, and mechanics
  base_view.py → Base class for most Discord views
  models.py    → Dataclass wrappers for DB rows + computed properties
  [module]/    → mechanics, views (or views/), ui builders, data
  items/       → factory + equipment/essence mechanics
  combat/      → full combat subsystem
database/
  __init__.py  → DatabaseManager (includes codes repo)
  repositories/ → all SQL (player_currencies table for most consumables)
assets/        → game data
scripts/       → maintenance tools

Observed separation: Cogs stay relatively light. Logic and views live in core/. SQL is confined to database/repositories/. Currencies live in dedicated table with helper methods on users repo.

Full details are on the Architecture Overview page (layers, BaseView usage, module splitting patterns, combat breakdown, models, and common implementation notes).

Key Systems

• Combat (stamina, modifiers, passives, jewels, many view variants)
• Inventory & Equipment (forge, refine, temper, imbue, essences, factory-built models)
• Settlement (buildings, workers, Black Market, projects, plots, Zeal/DT)
• Partners & Companions (gacha, dispatch, affinity, mastery)
• Endgame: Ascent, Codex, Uber bosses, Maw, Apex
• Progression: Slayer (tasks + tree), Alchemy, Consume/Hematurgy/Hatchery, Journey, Quests, Prestige
• Other: Delve, Gathering (skills + mastery), Curios, Events, Minigames, Trade, PvP, Ideology
• Redeem codes (new /redeem_code utility for admin-distributed rewards)

Common Patterns (Summary)

• Views generally extend BaseView (supports parent= chaining and auto cleanup).
• bot.database.<repo> for data access; commit after writes.
• Child views inherit context via parent.
• Guard mutating buttons with a _processing flag.
• Use state_manager around interactive sessions.
• Look at core/inventory/, core/settlement/, and core/combat/ for how larger features are organized.

Adding Features

Typical steps:

1. Schema + repository methods if needed.
2. Models and pure logic in core.
3. UI views + stateless builders.
4. Thin entry in a cog.
5. Wire state management and assets as appropriate.

Getting Started

• Main entry: bot.py
• Commands: cogs/
• Everything else: core/
• Data layer: database/

Study existing modules to match the local style.

Run the bot and test changes interactively.

See the main README.md for installation and running instructions.

Contributions are welcome.

---

Last updated: June 2026 — synced for codes/redeem feature, player_currencies migration, model splits, and recent refactors. Design principles are sound even if the project is mostly vibe-coded.