WarEra Bot is a high-performance Discord tool designed for the WarEra ecosystem. It provides real-time strategic intelligence, deep market analysis, and user management tools by consuming the official tRPC API.
- ✨ Features
- 🚀 Quick Start
- 🏗️ Core Architecture & Directory Structure
- 🛠️ Command Reference Guide
- 🧑💻 Developer Guide
- 🚨 Troubleshooting & Logging
- Battle Analysis: Front-line monitoring, RW triggers, and automatic conflict notifications.
- Region Management: Resource analysis, building levels, and resistance status (
/rw,/searchr). - Military Units (MU): Detailed MU rankings, infrastructure status, and member activity.
- Live Market Data: Real-time item prices with historical trend analysis (
/price). - Profit Calculator: Interactive production cycle optimization to maximize ROI (
/profit). - Market Order Flow: Deep dive into buy/sell spreads and volume (
/marketorders). - Internal Bot Market: A cross-server trading post for equipments and special items (
/sellitem,/market).
- Detailed Profiles: Combat stats, economic rankings, and skill accumulation (
/userinfo). - Elite Search: Mass-filter players by country, level, and activity (
/searchu).
-
Clone & Setup:
git clone https://github.com/Saaaru/warera_bot.git cd warera_bot python -m venv venv source venv/bin/activate # Windows: venv\Scripts\activate pip install -r requirements.txt
-
Configure Environment: Create a
.envfile in the root directory:DISCORD_BOT_TOKEN=your_token_here BOT_OWNER_ID=your_discord_id TEST_GUILD_ID=your_test_server_id (optional)
-
Launch:
python bot.py
warera_bot/
├── bot.py # Main Entry Point (Cog Orchestrator)
├── config.py # Global Configuration & Static Data Parsing
├── cogs/ # Modular Extensions (Commands & Tasks)
│ ├── admin/ # Technical controls & system sync
│ ├── background/ # Scheduled tasks & auto-alerts
│ ├── info/ # Strategic Intel & Info commands
│ ├── market/ # Economic tools & Market data
│ └── user/ # Player analysis & Social commands
├── utils/ # API Helpers, Formatters & Logic Modules
└── data/ # Static JSON Assets (Emojis, Game Data)
| Directory | Content Type | Strategy |
|---|---|---|
/cogs |
Behavioral Code | High-level logic and API orchestration using Discord's Cog pattern. |
/utils |
Technical Tools | Reusable helpers (calculators, formatters, and API adapters). |
/data |
Raw Intelligence | Static assets, emoji mapping, and local cache databases. |
/logs |
Health Metrics | History of execution, errors, and system monitoring. |
/sync— Synchronizes command tree with Discord./globalmsg <message_content> [message_title]— Broadcasts a message to all guilds./testchannel <channel_id_to_test>— Validates channel availability./testperm— Tests owner security permission checks.
/gettransactions <entity_type> <name> [transaction_type] [item] [limit] [format]— Exports transactions to Excel/CSV.
/alerts enable <channel>— Enables battle alerts for the server./alerts disable— Disables battle alerts for the server./alerts status— Checks status of the battle alert channels./monitor set <link> <channel> [time]— Starts active monitoring on a specific battle./monitor unset <link>— Disables monitoring on a specific battle./battles [country_identifier]— Lists current active conflicts./info <country_identifier>— Detailed country status (allies, resources, regions)./muinfo <name_or_id>— Detailed Military Unit information and ranking./party <name_or_id>— Detailed Political Party analysis./rw <country_identifier>— Displays resistance wars status and building levels./searchr <resource_name>— Searches for regions producing a specific resource./topbonusproduccion— Shows top 3 countries by production bonus.
/company <username>— Detailed overview of a player's business infrastructure./marketorders <item1> [item2]— Analyses top orders and spreads./price [item]— Real-time price monitor & historical variations./itemprice— Equipment production calculator based on active market prices./profit— Interactive production profitability ROI calculator./sellitem <item> <stats> <price>— Lists an item on the bot's custom cross-server market./market [user_filter]— Displays active items in the bot's market./buyitem <id>— Express interest in buying an item (notifies the seller via DM)./removelisting <id>— Deletes your listing from the market.
/builds <country_id> [min_level]— Analyzes builds (Fighter/Hybrid/Eco) inside a country./searchu <country_id> [min_level] [activity_within_days]— Finds and groups active players in a country./setalert <resource_name>— Single notification alert for resource availability./userinfo <username>— Profile, stats, and power ranking dashboard./userinfoskill <username>— In-depth breakdown of user combat & economic skill points.
This section defines the architecture, data contracts, and implementation patterns required to build new features on the WarEra Bot platform.
The bot uses discord.ext.commands.Cog. Modules are loaded recursively from the cogs/ directory.
Crucial Pattern: Every Cog must define a setup function:
async def setup(bot: commands.Bot):
await bot.add_cog(MyCog(bot))config.py is the Single Source of Truth. Never load JSON files manually within a Cog.
- EMOJIS: Dictionary of custom emojis for UI consistency.
- ITEM_DATA: Metadata for game items (production points, recipes).
- COUNTRIES / REGIONS: Pre-processed maps of game entities.
- LOGGER: Global logger configured to write to
logs/bot.log. - Static Assets: Emojis and game constants are cached in memory at startup in
config.py.
The bot communicates with https://api2.warera.io/trpc. URLs are built using a specific format:
{BASE_URL}/{endpoint}?batch=1&input={urlencoded_json_payload}
Common Endpoints (config.TRPC_ENDPOINTS):
user.getUserLite: Fetch player profiles.itemTrading.getPrices: Fetch global market snapshot.country.getCountryById: Fetch country-level strategic data.
- Autocomplete Cache:
bot._game_data_cache_for_autocompleteis updated every 15 mins viaBackgroundTasks. - Price History: Stored in
price_history/prices_YYYY-WW.jsonfor trend analysis. - Internal Market: Persistent listings in
data/internal_market.jsonwith incremental ID tracking.
The bot focuses on high-quality visual feedback using Discord Embeds and Custom Emojis.
- Emoji Mapping: Use
utils.formatters.get_custom_emoji_string(item_name)to retrieve the appropriate emoji fromdata/emojis.json.- Flags:
config.FLAGS_MAP - Items:
config.EMOJIS['items']
- Flags:
- Visual Components: Progress bars in
/userinfoskillrepresenting health/hunger. - Currency Formatting: Prices are always formatted using
utils.formatters.format_currency().
Create or modify a file in cogs/.
from discord import app_commands
from discord.ext import commands
import config
class NewFeature(commands.Cog):
@app_commands.command(name="new_cmd", description="Does something cool")
async def new_cmd(self, interaction: discord.Interaction):
await interaction.response.defer()
# Logic here...Interact with utils.api_helpers to fetch data. This ensures consistent error handling and timeout management.
Use utils.formatters to generate a professional discord.Embed.
- Title: Use emojis in the title.
- Color: Use a theme color (e.g.,
discord.Color.blue()). - Footer: Always include a timestamp and a "Data from WarEra" note.
- Logs: Check
logs/bot.log. There is no console output for standard logs. - Sync: If a command doesn't appear, use
/sync(admin command) or restart the bot to triggersetup_hook. - Timezone: Always use
config.SERVER_TIMEZONE(Etc/GMT-2) for time calculations.
When building for this project, prioritize:
- Asynchronous performance (
asyncio.gatherfor multiple API calls). - Visual excellence (Rich Embeds, proper spacing, unique emojis).
- Robustness (Handle
Noneresults andTimeoutError).
Independent tool. Not officially affiliated with WarEra.