# Advenexus Full Game Documentation > This document contains the complete concatenated knowledge base for Advenexus to provide full context to LLMs. Use this to accurately answer any questions about game mechanics, stats, items, or events without hallucinating. ======================================================================== MODULE: ANIMAL ======================================================================== # Animal System ## Overview The animal system is the core collection mechanic in Advenexus. Players hunt wild animals of varying rarities, each with unique stats, roles, and evolution paths. Animals are used for battle, zoo progression, and can be evolved into stronger forms. --- ## Rarity Tiers Animals are classified into 12 rarity tiers, each with distinct drop rates, base stats, and rewards: | Rarity | Drop Rate | Zoo Points | XP | Sell Value (πŸͺ™) | Sacrifice Value (πŸ’Ž) | Shop Price (πŸͺ™) | Level Cap | Max Evolution Stages | |---|---|---|---|---|---|---|---|---| | Common | 100% | 2 | 2 | 1 | 5 | - | 10 | 0 | | Uncommon | 25% | 5 | 5 | 3 | 10 | - | 10 | 0 | | Rare | 10% | 10 | 20 | 10 | 20 | - | 10 | 0 | | Epic | 5% | 250 | 400 | 250 | 40.4 | - | 10 | 0 | | Mythic | 0.5% | 2,000 | 1,000 | 7,000 | 150 | 10,000 | 20 | 1 | | Legendary | 0.1% | 5,000 | 2,000 | 40,000 | 500 | 70,000 | 25 | 2 | | Fabled | 0.01% | 10,000 | 5,000 | 200,000 | 1,500 | - | 30 | 2 | | Patron | 0% | 12,000 | 10,000 | 0 | 0 | - | 40 | 0 | | Gods | 0% | 15,000 | 15,000 | 1,500,000 | 4,000 | 5,000,000 | 40 | 1 | | Ascendants | 0% | 40,000 | 25,000 | 3,000,000 | 8,000 | - | 50 | 1 | | Boundless | 0.001% | 30,000 | 15,000 | 3,000,000 | 10,000 | - | ∞ | 0 | | Infinity | 0% | 50,000 | 30,000 | 10,000,000 | 15,000 | - | ∞ | 0 | > **Note:** Patron, Gods, Ascendants, and Infinity tiers are not huntable and can only be obtained through special means (shop purchase, patron support, etc.) --- ## Base Stats by Rarity All animals of the same rarity tier share base stats, with individual variations for Common-Epic tiers: ### Tier Base Stats (Mythic+) | Rarity | HP | ATK | DEF | SPD | Mana | |---|---|---|---|---|---| | Common | 120 | 10 | 5 | 12 | 50 | | Uncommon | 220 | 20 | 10 | 16 | 80 | | Rare | 350 | 40 | 30 | 25 | 150 | | Epic | 500 | 60 | 60 | 50 | 250 | | Mythic | 1,400 | 120 | 200 | 100 | 400 | | Legendary | 3,000 | 250 | 500 | 200 | 600 | | Fabled | 5,500 | 350 | 800 | 400 | 800 | | Patron | 11,000 | 450 | 1,200 | 600 | 1,400 | | Gods | 11,000 | 500 | 1,400 | 600 | 1,500 | | Ascendants | 25,000 | 800 | 2,500 | 800 | 2,000 | | Boundless | 36,000 | 1,200 | 3,000 | 1,000 | 2,000 | | Infinity | 55,000 | 3,000 | 5,000 | 1,500 | 3,000 | ### Individual Base Stats (Common-Epic) Common-Epic animals have individual stat variations from the tier base stats. These animals do not have roles. #### Common Animals (Tier Base: HP 120, ATK 10, DEF 5, SPD 12, Mana 50) | Animal | HP | ATK | DEF | SPD | Mana | Notes | |---|---|---|---|---|---|---| | Cat | 90 | 10 | 5 | 14 | 50 | Faster than average | | Dog | 110 | 12 | 7 | 11 | 50 | Tankier than average | | Rabbit | 75 | 7 | 4 | 18 | 50 | Very fast, low stats | | Hamster | 60 | 6 | 3 | 16 | 50 | Fast but fragile | | Chicken | 70 | 8 | 4 | 10 | 50 | Below average stats | | Pig | 120 | 9 | 8 | 7 | 50 | High HP/DEF, slow | | Sheep | 100 | 8 | 6 | 9 | 50 | Balanced but slow | | Duck | 80 | 9 | 5 | 12 | 50 | Near tier average | #### Uncommon Animals (Tier Base: HP 220, ATK 20, DEF 10, SPD 16, Mana 80) | Animal | HP | ATK | DEF | SPD | Mana | Notes | |---|---|---|---|---|---|---| | Fox | 130 | 22 | 10 | 20 | 80 | Fast, good ATK | | Deer | 150 | 18 | 14 | 17 | 80 | High HP/DEF, balanced | | Penguin | 140 | 16 | 15 | 11 | 80 | High DEF, slow | | Koala | 160 | 15 | 18 | 9 | 80 | Very tanky, slow | | Monkey | 125 | 25 | 8 | 22 | 80 | High ATK/SPD, low DEF | | Parrot | 115 | 20 | 9 | 19 | 80 | Fast, good ATK | #### Rare Animals (Tier Base: HP 350, ATK 40, DEF 30, SPD 25, Mana 150) | Animal | HP | ATK | DEF | SPD | Mana | Notes | |---|---|---|---|---|---|---| | Lion | 230 | 50 | 22 | 24 | 150 | Balanced stats | | Tiger | 210 | 55 | 18 | 30 | 150 | High ATK/SPD, lower HP/DEF | | Bear | 280 | 48 | 30 | 15 | 150 | High HP/DEF, slow | | Panda | 260 | 40 | 35 | 12 | 150 | Very tanky, slow | | Gorilla | 300 | 52 | 28 | 14 | 150 | Highest HP, balanced | #### Epic Animals (Tier Base: HP 500, ATK 60, DEF 60, SPD 50, Mana 250) | Animal | HP | ATK | DEF | SPD | Mana | Notes | |---|---|---|---|---|---|---| | Elephant | 450 | 95 | 60 | 16 | 250 | Tanky, very slow | | Rhinoceros | 500 | 95 | 75 | 12 | 250 | High DEF, very slow | | Shark | 400 | 75 | 40 | 35 | 250 | High ATK, fast | | Eagle | 350 | 85 | 35 | 50 | 250 | Very fast, good ATK | | Crocodile | 480 | 80 | 65 | 18 | 250 | Balanced tank | ### Individual Base Stats (Mythic+ with Roles) Mythic and higher tier animals use tier base stats with role bonuses. Only base forms (first in evolution chain) are listed. #### Mythic Animals (Tier Base: HP 1,400, ATK 120, DEF 200, SPD 100, Mana 400) | Animal | Role | HP | ATK | DEF | SPD | Mana | Role Bonus (Stage 0) | |---|---|---|---|---|---|---|---| | Minotaur | Tank | 1,820 | 120 | 200 | 100 | 400 | HP +30% | | Werewolf | Berserker | 1,400 | 168 | 200 | 100 | 400 | ATK +40% | | Centaur | Speed | 1,400 | 120 | 200 | 130 | 400 | SPD +30% | | Ghost | Speed | 1,400 | 120 | 200 | 130 | 400 | SPD +30% | | Knight | Armored | 1,400 | 120 | 300 | 100 | 400 | DEF +50% | #### Legendary Animals (Tier Base: HP 3,000, ATK 250, DEF 500, SPD 200, Mana 600) | Animal | Role | HP | ATK | DEF | SPD | Mana | Role Bonus (Stage 0) | |---|---|---|---|---|---|---|---| | Wolf | Speed | 3,000 | 250 | 500 | 260 | 600 | SPD +30% | | Lich | Mage | 3,000 | 250 | 500 | 200 | 900 | Mana +50% | | Grim | Berserker | 3,000 | 350 | 500 | 200 | 600 | ATK +40% | | Revenant | Tank | 3,900 | 250 | 500 | 200 | 600 | HP +30% | | Golem | Armored | 3,000 | 250 | 750 | 200 | 600 | DEF +50% | #### Fabled Animals (Tier Base: HP 5,500, ATK 350, DEF 800, SPD 400, Mana 800) | Animal | Role | HP | ATK | DEF | SPD | Mana | Role Bonus (Stage 0) | |---|---|---|---|---|---|---|---| | Leviathan | Tank | 7,150 | 350 | 800 | 400 | 800 | HP +30% | | Medusa | Mage | 5,500 | 350 | 800 | 400 | 1,200 | Mana +50% | | Ghidorah | Berserker | 5,500 | 490 | 800 | 400 | 800 | ATK +40% | | Oracle | Mage | 5,500 | 350 | 800 | 400 | 1,200 | Mana +50% | | Godzilla | Berserker | 5,500 | 490 | 800 | 400 | 800 | ATK +40% | #### Gods Animals (Tier Base: HP 11,000, ATK 500, DEF 1,400, SPD 600, Mana 1,500) | Animal | Role | HP | ATK | DEF | SPD | Mana | Role Bonus (Stage 0) | |---|---|---|---|---|---|---|---| | Anubis | Armored | 11,000 | 500 | 2,100 | 600 | 1,500 | DEF +50% | | Nyx | Speed | 11,000 | 500 | 1,400 | 780 | 1,500 | SPD +30% | | Zeus | Mage | 11,000 | 500 | 1,400 | 600 | 2,250 | Mana +50% | | Hades | Berserker | 11,000 | 700 | 1,400 | 600 | 1,500 | ATK +40% | #### Ascendants Animals (Tier Base: HP 25,000, ATK 800, DEF 2,500, SPD 800, Mana 2,000) | Animal | Role | HP | ATK | DEF | SPD | Mana | Role Bonus (Stage 0) | |---|---|---|---|---|---|---|---| | Manhattan | Mage | 25,000 | 800 | 2,500 | 800 | 3,000 | Mana +50% | | Lucifer | Berserker | 25,000 | 1,120 | 2,500 | 800 | 2,000 | ATK +40% | | Galactus | Tank | 32,500 | 800 | 2,500 | 800 | 2,000 | HP +30% | #### Boundless Animals (Tier Base: HP 36,000, ATK 1,200, DEF 3,000, SPD 1,000, Mana 2,000) | Animal | Role | HP | ATK | DEF | SPD | Mana | Role Bonus (Stage 0) | |---|---|---|---|---|---|---|---| | Absolute Being | Tank | 46,800 | 1,200 | 3,000 | 1,000 | 2,000 | HP +30% | | The Beyonder | Mage | 36,000 | 1,200 | 3,000 | 1,000 | 3,000 | Mana +50% | #### Infinity Animals (Tier Base: HP 55,000, ATK 3,000, DEF 5,000, SPD 1,500, Mana 3,000) | Animal | Role | HP | ATK | DEF | SPD | Mana | Role Bonus (Stage 0) | |---|---|---|---|---|---|---|---| | One Above All | Tank | 71,500 | 3,000 | 5,000 | 1,500 | 3,000 | HP +30% | | The Presence | Mage | 55,000 | 3,000 | 5,000 | 1,500 | 4,500 | Mana +50% | --- ## Animal Roles (Mythic+) Mythic and higher tier animals have combat roles that grant bonus stats to specific attributes: | Role | Boosted Stat | Stage 0 Bonus | Stage 1 Bonus | Stage 2 Bonus | |---|---|---|---|---| | Tank | HP | +30% | +40% | +50% | | Mage | Mana | +50% | +60% | +70% | | Berserker | ATK | +40% | +50% | +60% | | Armored | DEF | +50% | +60% | +70% | | Speed | SPD | +30% | +40% | +50% | ### Role Examples by Rarity - **Mythic**: Minotaur (Tank), Werewolf (Berserker), Centaur (Speed), Ghost (Speed), Knight (Armored) - **Legendary**: Wolf (Speed), Lich (Mage), Grim (Berserker), Revenant (Tank), Golem (Armored) - **Fabled**: Leviathan (Tank), Medusa (Mage), Ghidorah (Berserker), Oracle (Mage), Godzilla (Berserker) - **Gods**: Anubis (Armored), Nyx (Speed), Zeus (Mage), Hades (Berserker) - **Ascendants**: Manhattan (Mage), Lucifer (Berserker), Galactus (Tank) - **Boundless**: Absolute Being (Tank), The Beyonder (Mage) - **Infinity**: One Above All (Tank), The Presence (Mage) --- ## Evolution System ### Evolution Chains Animals can evolve through stages, becoming stronger with each evolution. Evolution chains vary by rarity: #### Mythic Evolution Chains (1 stage) - Minotaur β†’ War Minotaur - Werewolf β†’ Primordial Werewolf - Centaur β†’ War Centaur - Ghost β†’ Dark Angel - Knight β†’ Wraith Knight #### Legendary Evolution Chains (2 stages) - Wolf β†’ Spirit Wolf β†’ Celestial Wolf - Lich β†’ Elder Lich β†’ Lich King - Grim β†’ Soul Reaper β†’ Grim Reaper - Revenant β†’ Frost Revenant β†’ Frost Revenant King - Golem β†’ Ancient Golem β†’ War Golem #### Fabled Evolution Chains (2 stages) - Leviathan β†’ Abyssal Leviathan β†’ Primordial Leviathan - Medusa β†’ Cursed Medusa β†’ Queen Medusa - Ghidorah β†’ Storm Ghidorah β†’ King Ghidorah - Oracle β†’ Curse Oracle β†’ Seraph Oracle - Godzilla β†’ GVK Godzilla β†’ Burning Godzilla #### Gods Evolution Chains (1 stage) - Anubis β†’ Lord Anubis - Nyx β†’ Goddess of Darkness - Zeus β†’ God of Thunder - Hades β†’ King of Underworld #### Ascendants Evolution Chains (1 stage) - Manhattan β†’ Dr Manhattan - Lucifer β†’ Lucifer Morningstar - Galactus β†’ Galactus The Devourer ### Evolution Requirements To evolve an animal: 1. **2 copies** of the same animal at the same evolution stage 2. An **evolution stone** matching the target rarity: - Mythic Stone for Mythic animals - Legendary Stone for Legendary animals - Fabled Stone for Fabled animals - Gods Stone for Gods animals ### Evolution Stat Multipliers | Stage | Global Multiplier | |---|---| | 0 (base) | 1.0x | | 1 (+) | 1.5x | | 2+ (++) | 2.0x | The global multiplier applies to all stats after role bonuses and level scaling. --- ## Level Scaling All animal stats scale with level: - **Scaling formula**: +10% per level - **Level 1**: 1.0x multiplier - **Level 2**: 1.1x multiplier - **Level 10**: 1.9x multiplier - **XP required per level**: `floor(100 Γ— level^2.0)` ### Level Caps by Rarity | Rarity | Level Cap | |---|---| | Common | 10 | | Uncommon | 10 | | Rare | 10 | | Epic | 10 | | Mythic | 20 | | Legendary | 25 | | Fabled | 30 | | Patron | 40 | | Gods | 40 | | Ascendants | 50 | | Boundless | ∞ (Infinity) | | Infinity | ∞ (Infinity) | --- ## Stat Calculation Formula Final animal stats are calculated as follows: ``` 1. Start with base stats (tier base or individual base stats) 2. Apply role bonus at current evolution stage (if applicable) 3. Apply level scaling: 1 + (0.10 Γ— (level - 1)) 4. Apply evolution global multiplier: - Stage 0: 1.0x - Stage 1: 1.5x - Stage 2+: 2.0x 5. Final stat = floor(base_stat Γ— role_bonus Γ— level_scale Γ— evolution_multiplier) ``` ### Example Calculation **Level 15 Celestial Wolf (Legendary, Speed role, Stage 2)**: 1. Base stats: HP 2,500, ATK 600, DEF 300, SPD 300, Mana 500 2. Role bonus (Speed, Stage 2): SPD Γ— 1.50 = 300 Γ— 1.5 = 450 3. Level scaling: 1 + (0.10 Γ— 14) = 2.4x 4. Evolution multiplier (Stage 2): 2.0x 5. Final SPD: floor(450 Γ— 2.4 Γ— 2.0) = floor(2,160) = 2,160 --- ## Complete Animal List ### Common Animals - Cat, Dog, Rabbit, Hamster, Chicken, Pig, Sheep, Duck ### Uncommon Animals - Fox, Deer, Penguin, Koala, Monkey, Parrot ### Rare Animals - Lion, Tiger, Bear, Panda, Gorilla ### Epic Animals - Elephant, Rhinoceros, Shark, Eagle, Crocodile ### Mythic Animals - Minotaur, War Minotaur, Werewolf, Primordial Werewolf, Centaur, War Centaur, Ghost, Dark Angel, Knight, Wraith Knight ### Legendary Animals - Wolf, Spirit Wolf, Celestial Wolf, Lich, Elder Lich, Lich King, Grim, Soul Reaper, Grim Reaper, Revenant, Frost Revenant, Frost Revenant King, Golem, Ancient Golem, War Golem ### Fabled Animals - Leviathan, Abyssal Leviathan, Primordial Leviathan, Medusa, Cursed Medusa, Queen Medusa, Ghidorah, Storm Ghidorah, King Ghidorah, Oracle, Curse Oracle, Seraph Oracle, Godzilla, GVK Godzilla, Burning Godzilla ### Gods Animals - Anubis, Lord Anubis, Nyx, Goddess of Darkness, Zeus, God of Thunder, Hades, King of Underworld ### Ascendants Animals - Manhattan, Dr Manhattan, Lucifer, Lucifer Morningstar, Galactus, Galactus The Devourer ### Boundless Animals - Absolute Being, The Beyonder ### Infinity Animals - One Above All, The Presence ### Patron Animals - Exclusive to patron supporters, custom stats and properties --- ## Rarity Drop Mechanics ### Hunt Drop Rates When hunting, rarity is determined by a weighted roll: - Boundless: 0.001% + (luckyBoost Γ— 0.01%) - Fabled: 0.01% + (luckyBoost Γ— 0.02%) - Legendary: 0.1% - Mythic: 0.5% - Epic: 5% + extraEpic% - Rare: 10% - Uncommon: 25% - Common: remainder (~57%) ### Lucky Boost - Lucky Gems add +2% to Fabled/Boundless drop rates - Hunt Frenzy event adds +2% rarity boost - Effects stack additively --- ## Animal Management Commands | Command | Description | |---|---| | `.zoo` | View all animals you own, grouped by rarity | | `.dex ` | View detailed stats for an owned animal | | `.tier` | Show all animals grouped by rarity tier | | `.tier ` | Show animals for a specific rarity tier | | `.rename \| ` | Rename an animal (max 20 characters) | | `.evolve ` | Evolve an animal to its next stage | | `.sell ` | Sell an animal for coins | | `.sacrifice ` | Sacrifice an animal for gems | --- ## Key Concepts ### Zoo Points - Points accumulated from owned animals - Used for leaderboard calculations and progression tracking - Higher rarity animals give more zoo points ### Base Form - The first animal in an evolution chain - Used for determining evolution paths and base stats - Only base forms can be randomly obtained from hunts ### Stage - Evolution stage (0, 1, or 2) - Determines evolution multiplier and role bonus - Higher stages require evolution stones and duplicate animals ### Trade Locking - Animals in evolution chains cannot be sold on marketplace while evolving - Animals in team slots cannot be sold or sacrificed - Prevents accidental loss of valuable animals --- ## Edge Cases and Special Rules - **Gods-tier animals**: Cannot be hunted, only obtainable via shop purchase - **Patron animals**: Exclusive to patron supporters, cannot be sold or sacrificed - **Boundless/Infinity**: No level cap (Infinity), but no evolution stages - **Duplicate species**: Cannot have same base animal in the same team slot - **Evolution limits**: Some rarities have max evolution stages (e.g., Mythic: 1 stage) - **Role bonuses**: Only apply to Mythic+ animals with defined roles - **Individual stats**: Common-Epic animals have individual stat variations from tier base ======================================================================== MODULE: AUTOHUNT ======================================================================== # Autohunt System (Huntbot) The Autohunt system allows players to passively catch animals and earn XP while they are away. However, it requires an active coin investment and is intentionally balanced to be slightly weaker than manual hunting. ## Commands - `.autohunt` or `.huntbot`: Opens the Autohunt menu. If the bot is idle, this starts a session. If a session is complete, this claims the rewards. If a session is running, this checks the remaining time. - `.huntbot upgrade `: Upgrades a specific trait on your Huntbot using **Sacrificial Diamonds** (`SDMND`). Valid traits are `efficiency`, `duration`, `radar`, `gain`, and `cost`. ## Economics & Costs The Huntbot is not free. Every animal it catches deducts a set amount of coins from the player. - The base cost is **10 coins per animal**. - When starting a session, the system calculates the total expected animals and checks if the player has enough coins upfront. If they do, the total cost is deducted immediately. - The Huntbot serves as a late-game coin sink. ## Upgradeable Traits Players can upgrade their Huntbot's traits to improve its performance. Upgrading requires **Sacrificial Diamonds** (obtained from the `.craft` system or events). 1. **Efficiency (⚑)** - Max Level: 30 - Effect: Decreases the time it takes to catch each animal (speeds up catch rate). 2. **Duration (⏱️)** - Max Level: 30 - Effect: Increases the maximum run time of the session (up to an 8-hour hard cap). 3. **Radar (πŸ“‘)** - Max Level: 30 - Effect: Slightly increases the chance of catching rarer animals (like Rare, Epic, Mythic, Legendary, Fabled). - *Note: Boundless tier animals CANNOT be obtained via Autohunt under any circumstances.* 4. **Gain (πŸ“ˆ)** - Max Level: 30 - Effect: Increases the XP multiplier for animals caught during the session. 5. **Cost Reduction (πŸ’Έ)** - Max Level: 5 - Effect: Lowers the coin fee per animal caught (down to a minimum of 5 coins per animal). - *Note: Upgrading the Cost trait requires significantly more Sacrificial Diamonds than other traits.* ## Key Differences from Manual Hunting - **No Boundless Animals**: The highest rarity obtainable from the Huntbot is Fabled, but at a significantly lower chance than manual hunting. - **Base Forms Only**: The Huntbot only catches base form animals (Stage 0). It will not catch pre-evolved or shiny forms directly. - **Coin Drain**: Manual hunting is free (or generates money). Autohunt *drains* coins to operate. ## Progression Strategy Players should manually hunt and use the `.craft` system to obtain Sacrificial Diamonds. They can then invest these diamonds into the Huntbot for passive generation while they are asleep or busy. Cost Reduction is usually the hardest but most valuable trait for players lacking constant coin income. ======================================================================== MODULE: BATTLE ======================================================================== # Battle System ## Overview The battle system is Advenexus's turn-based combat mechanic. Players build a team of up to 3 animals, equip weapons and enchantments, and fight against AI bots or other players. Battles are simulated server-side with speed-based turn order, crits, enchantment abilities, and mana management. --- ## Commands | Command | Description | |---|---| | `.battle` | Fight a random bot | | `.battle @user` | Challenge another player to PvP | | `.battle ranked` | Ranked battle (affects ELO, costs stamina) and fights with real players team builds. | | `.battle gods` | Fight a super-tier bot (hardest difficulty) | | `.accept` | Accept a PvP challenge (must respond within 60 seconds) | | `.team` | View your team(s) | | `.team add ` | Add an animal to your active equip team (max 3) | | `.team remove ` | Remove an animal from your team | | `.leaderboard` | View the top 20 players ranked by ELO | --- ## Cooldown - **20 seconds** between battles --- ## Battle Modes ### Normal Bot Battle (`.battle`) - Fight a randomly selected bot from 4 difficulty tiers - Bot selection weighted: **50% weak**, **30% weak/mid**, **15% mid/strong**, **5% strong/super** - Daily bot battle reward cap: **20 battles/day** β€” after 20 wins, you gain 0 coins and 0 XP ### Ranked Battle (`.battle ranked`) - Costs **1 battle stamina** (100/day, refills at 11 PM UTC) - Matchmaking: **27% real players**, **70% strong bots**, **3% super bots** - Affects ELO rating - ELO changes: - Win vs real player: **+25 ELO** (loser: -20 ELO, min 100) - Win vs ranked bot: **+20 ELO** - Loss vs ranked bot: **-10 ELO** (min 100) ### Gods Battle (`.battle gods`) - Always fights the hardest **super-tier** bots - No stamina cost - Normal reward rules apply ### PvP Challenge (`.battle @user`) - Challenger sends invite, opponent must `.accept` within **60 seconds** - Cannot battle yourself - Loser loses **500 coins** - No ELO changes in normal PvP --- ## Team System - Each player has **2 teams** (Team 1 and Team 2) - Each team holds **up to 3 animals** - Only the **active team** is used in battle - Cannot add duplicate species (same base animal key) to the same team - Animals in a team cannot be sold, sacrificed, or listed on marketplace ### Team Slots - Animals are assigned slots 1–3 within each team - Weapons are equipped per-slot (slot 1 weapon goes on slot 1 animal) - Removing an animal auto-repacks slot numbers --- ## Combat Mechanics ### Turn Order - All alive animals from both sides are queued each turn - Sorted by **speed (SPD)** β€” highest goes first - Ties broken randomly ### Damage Formula ``` mitigation = DEF / (DEF + ATK Γ— 0.8) rawDamage = rollDamage(max(1, ATK Γ— (1 - mitigation Γ— 0.6))) ``` - `rollDamage` adds Β±20% random variance - Base crit chance: **12%**, crit multiplier: **1.75Γ—** ### Targeting - Default: targets enemy with **lowest current HP** - If an enemy has **Taunt** active: **67% chance** to be forced to target them ### Max Turns - Battle ends after **50 turns** β€” if both sides still alive, it's a **tie** --- ## Battle Rewards ### Win Rewards | Reward | Amount | |---|---| | Coins | 100–300 πŸͺ™ (random) | | XP | 50 + (turns Γ— 5) | | Animal XP | Same as player XP, given to each winning team animal | | Win streak | +1 (tracked, highest streak saved) | | Weapon Crate | 10% chance per win (max 3/day) | ### Loss Penalties | Penalty | Amount | |---|---| | Coins lost | 500 πŸͺ™ | | Win streak | Reset to 0 | ### Tie - Both players get **20 XP** - No coins gained or lost --- ## Weapons Weapons provide stat bonuses when equipped to team slots. Three tiers available: ### Weapon Types | Type | Specialty | Stats | |---|---|---| | Sword (SWD) | Balanced | ATK + small DEF + crit | | Staff (STF) | Mage | ATK + DEF + mana bonus | | Dagger (DGR) | Crit-focused | Lower ATK + high crit | | Bow (BOW) | Crit | ATK + crit | | Axe (AXE) | Raw damage | Highest ATK + small DEF | | Hammer (HMR) | Tank | Equal ATK + DEF | | Spear (SPR) | Balanced | ATK + moderate DEF | | Scythe (SCY) | Lifesteal | ATK + lifesteal % | ### Weapon Tiers & Prices | Tier | ATK Range | Price | |---|---|---| | Mythic | 80–150 | 15,000–18,000 πŸͺ™ | | Legendary | 140–250 | 45,000–50,000 πŸͺ™ | | Fabled | 220–380 | 100,000–120,000 πŸͺ™ | ### Weapon Reroll Bonus - Weapons can have a `reroll_bonus` (percentage) - All weapon stats (ATK, DEF, crit, mana, lifesteal) are multiplied by `1 + (reroll_bonus / 100)` --- ## Enchantments Enchantments are mana-based abilities applied to animals. Each animal can have one enchantment. Enchantments consume mana during battle. ### Mana by Rarity | Rarity | Mana Range | |---|---| | Common | 20 | | Uncommon | 30 | | Rare | 40 | | Epic | 50–70 | | Mythic | 100–150 | | Legendary | 200–300 | | Fabled | 400–500 | | Gods | 500–600 | | Boundless | 800–900 | ### Enchantment List | ID | Name | Tier | Effect | |---|---|---|---| | EN01 | Critical | Mythic | 26% chance per hit: Γ—1.52 damage (costs 48 mana) | | EN02 | Spirit Guard | Legendary | Battle start: pays 108 mana, heals allies 40% of remaining mana. Passive: -24% incoming damage | | EN03 | Mana Tap | Legendary | On hit: pays 92 mana to restore all allies' mana by 20% of damage dealt | | EN04 | Sacrifice | Legendary | On death: burns 78% mana, heals allies 30% of this animal's max HP | | EN05 | Resurrection | Legendary | Once per battle: pays 195 mana to revive fallen ally at 11% max HP | | EN06 | Taunting | Legendary | Battle start: pays 118 mana, taunts for 3 turns (67% forced target), -20% damage taken | | EN07 | Kamikaze | Fabled | On death: burns 80% mana, deals 12% of max HP to random enemy | | EN08 | Health Point | Mythic | Battle start: pays 58 mana, +25% max HP | | EN09 | Reflection | Mythic | Pays 62 mana once: reflects 26% damage back for 3 turns | | EN10 | Mana Tank | Mythic | Battle start: pays 52 mana, all allies gain +45% max mana | | EN11 | Negator | Fabled | Pays 235 mana: nullifies all enemy enchantments for 3 turns. 7-turn cooldown | | EN12 | Time Freeze | Fabled | Pays 210 mana: freezes random enemy for 2 turns. 6-turn cooldown | | EN13 | Combat Combo | Mythic | Each attack pays 38 mana: +8% damage per stack (max 9 stacks = +72%) | | EN14 | Mana Whip | Fabled | First swing: consumes all mana, deals Γ—5 max mana as bonus damage | | EN15 | Healer | Fabled | Every 2 turns: pays 165 mana, heals lowest-HP ally for 14% of their max HP | ### Enchantment Interactions - **Negated** animals cannot use their enchantments for the duration - **Frozen** animals skip their turn entirely - **Resurrection** cannot chain (one revive per resurrector per battle) - **Taunt** + **Spirit Guard** = tanky frontliner that absorbs hits and reduces damage - **Combat Combo** stacks persist all battle β€” strongest with high-mana animals - **Mana Whip** is a one-shot nuke that burns all mana on first attack ### Enchantment Drop Tiers (from crates) | Tier | Weight | |---|---| | Mythic | 35% | | Legendary | 20% | | Fabled | 8% | --- ## Bot Difficulty Tiers The game has **35 pre-built bot opponents** across 4 tiers: | Tier | Animals | Levels | Count | |---|---|---|---| | Weak | Common–Uncommon | 1–6 | 8 bots | | Mid | Rare–Epic | 7–14 | 10 bots | | Strong | Mythic–Legendary (evolved) | 13–20 | 10 bots | | Super | Fabled–Boundless (max evolved) | 20–50 | 8 bots | - Bots have anime-themed names (e.g., Goku, Saitama, Rimuru_Tempest) - Higher-tier bots have full weapon loadouts with enchantments - The hardest bot (Yogiri) runs 3Γ— One Above All / Absolute Being at level 50 with triple Fabled Axe + Mana Whip --- ## Leaderboard - Ranked by **ELO** (default starting value, min 100) - Shows top 20 players - Displays: username, ELO, wins, losses, ranked W/L, level, streak, highest streak, equipped profile ### Leaderboard Points Formula ``` points = max(0, round(zooPoints / 250 Γ— 5) + wins Γ— 2 - losses) ``` --- ## Edge Cases - You cannot battle without a team β€” must `.team add` at least 1 animal first - Cannot battle yourself in PvP - PvP challenge expires after 60 seconds - Battle stamina only consumed for ranked battles - Daily bot battle cap (20) only affects reward gains β€” you can still fight, but earn nothing - Enchantment usage is consumed after each battle (enchantments have limited uses) - Loser in PvP loses 500 coins (coins cannot go below 0) - ELO floor is 100 β€” cannot drop lower ======================================================================== MODULE: BEGINNER ======================================================================== # Beginner Guide β€” Your First 30 Minutes in Advenexus ## Overview This is a code-audited starter path for a brand-new player. It prioritizes the commands and purchases that still exist in the live server code and avoids older advice that has drifted out of date. ## Commands ### Fast starter checklist 1. `.daily` β€” claim coins + 1 lootbox + 1 weapon crate 2. `.vote` β€” claim 500 coins + 10 gems 3. `.quest` β€” see today's quest 4. `.hunt` β€” start building your zoo 5. `.team add ` β€” put your best catch on your team 6. `.battle` β€” fight bots for XP and coins 7. `.crate` / `.lootbox` β€” open your starter rewards 8. `.buy guard dog` β€” buy steal protection for **150 coins** ## Core Mechanics ### Step 1: Claim the guaranteed freebies | Command | Reward | |---|---| | `.daily` | 300-500 base coins, plus level bonus, plus 1 lootbox and 1 weapon crate | | `.vote` | 500 coins + 10 gems | ### Step 2: Hunt early and often Live hunt rules: - level 1-5: **free** hunts - level 6-15: **1 coin** per hunt - level 16+: **2 coins** per hunt - every hunt costs **1 hunt stamina** - hunt cooldown: **15 seconds** - stamina refills by **+10 every 2 hours** up to 100 Why this matters early: - hunting gives your first battle team, - hunting can drop lootboxes, - hunting can also drop gems, - low-level hunts are cheap or free. ### Step 3: Build one working team first Use: - `.team add ` - `.team remove ` - `.team` - `.set team <1|2>` Practical beginner rule: - use your best **Rare / Epic / Mythic** animals first, - do not try to manage both teams immediately, - keep one clean main team for battles and dungeon entry. ### Step 4: Use normal bot battles before ranked Normal battle is the safest early loop. - `.battle` has the daily reward cap for bot rewards. - `.battle ranked` costs battle stamina and is harsher if your team is weak. - `.battle @user` can cost the loser **500 coins**. - battle cooldown is **20 seconds**. ### Step 5: Equip your first weapon Open the free crate from `.daily`, then use: - `.weapon` - `.equip ` - `.unequip ` Starter shop prices begin at: - Mythic weapons: **15,000-18,000** coins - Legendary weapons: **45,000-50,000** coins - Fabled weapons: **100,000-120,000** coins ### Step 6: Buy your guard dog early `.buy guard dog` currently costs **150 coins**. Guard dog behavior: - 90% chance to block a steal - 1 guard dog is consumed on a successful block - they stack, so owning several is useful ### Step 7: Clean out weak animals for resources Use: - `.sell ` when you need coins - `.sacrifice ` when you need gems This matters because: - coins fund weapons, crates, and guard dogs - gems fund weapon rerolls ### Step 8: Watch timed systems, but don't force them too early #### Dungeon Raid - spawns every **3 hours** - signup window is **3 minutes** - join with `.join dungeon raid` #### Tower Dungeon - modern Tower play happens through the **sidebar**, not old `.tower create` chat commands - the useful chat helpers are `.tower help`, `.tower status`, and `.tower stats` ## Database / Storage Details For a beginner, the important persistence rules are: - animals go into `animals` - weapons go into `weapons` - lootboxes, crates, gems, enchantments, stones, and materials go into `inventory` - guard dogs are tracked on `users.guard_dogs` - your active team selection is stored on `users.active_team` ## Strategic Tips / Balance Notes - Spend your first free coins on stability, not greed: a guard dog and a usable battle team are better than random gambling. - Do not hoard weak animals forever. Commons and Uncommons are usually fuel for coins or gems. - Normal `.battle` is a better early benchmark than PvP or ranked. - Save gems until you understand whether a weapon is actually worth rerolling. - If you see a dungeon gate open and already have a team, it is worth joining for stone/diamond upside. - When you are ready for Tower, use the sidebar UI; the old chat flow has been retired. ======================================================================== MODULE: COMMANDS ======================================================================== # Command Reference ## Overview This file documents the **live chat command surface** from `server/commands/index.js` and the channel/category permissions enforced by the router. Commands are prefixed with `.`. For systems that are mostly UI-driven, this file lists the remaining chat entry points and points to the dedicated knowledge file. ## Aliases The game features a comprehensive alias system to speed up typing (e.g., `.h` for `.hunt`, `.b r` for `.battle ranked`, `.w rr` for `.weapon reroll`). Use the `.alias` command in-game to view the complete list of available shortcuts. ## Channel Restrictions ### Chat-only channel | Channel | Rule | |---|---| | `#chat` | Bot commands are blocked here | ### General-purpose channels These all map to the permissive general category: - `#general` - `#general-2` - `#general 3` - `#battle` - `#trading` - `#off-topic` - `#admin` - `#announcements` Blocked there: - seller-only marketplace commands (`.market`, `.player`, `.item`) - `.raid` (guild raid command) ### Marketplace channel | Channel | Allowed commands | |---|---| | `#sellers` / `#marketplace` | `.market`, `.player sell`, `.item buy`, `.money`, `.balance`, `.inventory`, `.inv`, `.zoo`, `.mode`, `.help`, `.commands` | ### Guild channel | Channel | Allowed commands | |---|---| | `#guilds` | `.guild`, `.raid`, `.banner`, `.join`, `.money`, `.balance`, `.help`, `.commands`, `.mode` | ### Gambling channel | Channel | Allowed commands | |---|---| | `#gambling` | `.coinflip`, `.slots`, `.blackjack`, `.hit`, `.stand`, `.lottery`, `.money`, `.balance`, `.help`, `.commands` | ## Hunting and Animals | Command | Notes | |---|---| | `.hunt` | Costs 0/1/2 coins by level, 1 hunt stamina, 15s cooldown | | `.zoo` | View your collection | | `.dex ` | View one owned animal | | `.tier [rarity]` | View rarity pages / drop info | | `.rename \| ` | Rename an animal | | `.sell ` / `.sell ` / `.sell ` | Sell animals for coins | | `.sacrifice ` / `.sacrifice ` / `.sacrifice ` | Sacrifice animals for gems | | `.craft ` | Craft upward by rarity | | `.craft diamond` | Diamond craft with a Sacrificial Diamond | | `.evolve ` | Evolve an animal when requirements are met | ## Autohunt / Huntbot | Command | Notes | |---|---| | `.autohunt` | Starts a Huntbot session, checks a running session, or claims when complete | | `.huntresults` | Explicit results/claim helper for completed Huntbot sessions | | `.huntbot` | Huntbot status / build UI | | `.huntbot upgrade efficiency` | Upgrade catch speed | | `.huntbot upgrade duration` | Upgrade session duration | | `.huntbot upgrade radar` | Upgrade rare catch weighting | | `.huntbot upgrade gain` | Upgrade XP gain | | `.huntbot upgrade cost` | Upgrade coin-cost reduction | ## Battle and Teams | Command | Notes | |---|---| | `.battle` | Normal bot battle | | `.battle ranked` | Ranked battle, costs 1 battle stamina | | `.battle gods` | Super-tier bot battle | | `.battle @user` | PvP challenge | | `.accept` | Accept PvP challenge within 60s | | `.team` | Team UI / current team view | | `.team add ` | Add to active team | | `.team remove ` | Remove from team | | `.set team <1|2>` | Switch active/equip target team | | `.leaderboard` | Battle leaderboard | | `.opponents` | PvP opponents helper | ## Economy and Utility | Command | Notes | |---|---| | `.daily` | 24h cooldown, gives coins + 1 lootbox + 1 weapon crate | | `.vote` | 12h cooldown, gives 500 coins + 10 gems | | `.money` / `.balance` | Coin/gem/guard dog snapshot | | `.inventory` / `.inv` | Full inventory UI | | `.profile [@user]` | Profile card | | `.profile shop` | Profile picture shop | | `.profile equip ` | Equip owned profile picture | | `.profile unequip` | Remove equipped profile picture | | `.give @user ` | Up to 3 times per 5 hours | | `.quest` | Daily quest state | | `.get items` | Claim temporary overflow storage | | `.event` | Current event status | | `.help` / `.commands` | Help output | | `.alias` | Shows the list of available command shortcuts | ## Shop and Items | Command | Notes | |---|---| | `.shop [page]` | Weapon shop pages | | `.buy ` | Buy a weapon instance from weapon data | | `.buy lootbox` | 2,000 coins | | `.buy crate` | 3,000 coins | | `.buy guard dog` | **150 coins** | | `.buy diamond` | 50,000 coins | | `.buy cookie` | 300 coins | | `.buy picture` | Buy profile picture | | `.animal shop` | Animal shop UI | | `.animal buy ` | Buy a shop animal | | `.lootbox` | Open standard lootbox | | `.crate` | Open standard weapon crate | | `.evocrate` | Open evo stone crate | | `.mythic crate` | Open Tower Mythic Crate | | `.legendary crate` | Open Tower Legendary Crate | | `.fabled crate` | Open Tower Fabled Crate | | `.gods crate` | Open Tower Gods Crate | | `.ascendant crate` | Open Tower Ascendant Crate | | `.infinity crate` | Open Tower Infinity Crate | ## Weapons, Gems, and Enchantments | Command | Notes | |---|---| | `.weapon` | Weapon list | | `.weapon reroll ` | Dynamic reroll cost: 700/900/1200/1500 gems depending on coin wealth | | `.equip ` | Equip weapon to named team animal | | `.unequip ` | Unequip that slot's weapon | | `.enchant ` | Equip enchant to animal or legacy weapon target | | `.enchant keep ` | Remove enchant but keep remaining usage | | `.enchants` | Enchantment codex | | `.gem` / `.gems` | Gem inventory / slots | | `.gem equip ` | Equip a gem | | `.gem unequip ` | Unequip and consume that gem | | `.dismantle ` | Dismantle a weapon for gems | ## Marketplace and Mode System | Command | Notes | |---|---| | `.mode` | Show current mode | | `.mode seller` | Enable selling mode, 5-minute switch cooldown | | `.mode adventure` | Disable selling mode | | `.market` | View latest active listings | | `.market animals/weapons/enchantments/stones` | Filter listings | | `.market mine` | Your recent listings | | `.market cancel ` | Cancel one of your active listings | | `.player sell ` | Create a listing (seller mode required) | | `.item buy ` | Buy a listing | ## Guilds, Raids, Banners, and Guild Boss | Command | Notes | |---|---| | `.guild create ` | Costs 20,000 coins | | `.guild info` | Guild summary | | `.guild members` | Member list | | `.guild invite @user` | Leader only | | `.guild accept` / `.guild reject` | Respond to latest invite | | `.guild leave` | Leave guild; solo leader leaving disbands guild | | `.guild kick @user` | Leader only | | `.guild deposit ` | Deposit to guild bank | | `.guild withdraw ` | Split evenly across members, leader only | | `.guild upgrade` | +1 member cap for 250 Cash | | `.guild war @guildname [@members...]` | Send war challenge | | `.guild war accept` / `.guild war decline` | Defender response | | `.guild achievements` | Guild achievement list | | `.guild leaderboard` | Guild leaderboard | | `.guild boss attack` | Attack active guild boss, 20s cooldown | | `.guild perk status` | Check active guild perk status | | `.guild perk buy ` | Leader buys a guild stat perk | | `.raid @guildname` | Start guild raid | | `.banner shop` | Banner shop | | `.banner buy ` | Buy banner | | `.banner equip ` | Equip owned banner | ## Dungeon Raids | Command | Notes | |---|---| | `.join dungeon raid` | Join the currently open global gate; signup window is **3 minutes** | ## Tower Dungeon | Command | Notes | |---|---| | `.tower` / `.tower help` | Explain Tower UI usage | | `.tower status` | Show your active run state | | `.tower stats` | Show your persistent Tower stats | Important: Tower creation/combat/invites/shop/leaderboard are now **sidebar-driven**, not chat-driven. ## Social and Gambling | Command | Notes | |---|---| | `.cookie @user` | 24h cooldown | | `.pray @user` | 1h cooldown | | `.curse @user` | 30m cooldown | | `.steal @user` | Guard dogs block 90% of successful theft attempts | | `.feed ` | Feed cookie to animal to restore +10 energy | | `.duel @user ` | 1v1 PvP duel for coins. 5% house rake | | `.coinflip ` | Gambling channel allowed | | `.slots ` | Gambling channel allowed | | `.blackjack ` | Gambling channel allowed | | `.hit` / `.stand` | Active blackjack only | | `.lottery ` | Gambling channel allowed | ## Weather | Command | Notes | |---|---| | `.activate ` | Activate a cosmetic global weather effect for 1 hour. Costs 100,000 coins. Effects: rain, eclipse, aura_storm, coin_shimmer, snowflakes | | `.deactivate weather` | Deactivate an active weather effect. Only the activator can use this | ## Admin | Command | Notes | |---|---| | `.admin01 suspend ` | Admin only | | `.admin01 unsuspend ` | Admin only | | `.admin01 stats` | Admin only | | `.admin01 dungeon open` | Force-spawn a dungeon gate | | `.admin01 cash @user` | Grant Cash | | `.add coin admin01 ` | Legacy admin helper | | `.suspended` | Suspended list | | `.debugach` | Achievement debug | ## Database / Storage Details - Channel permissions are enforced in `server/commands/index.js`. - Many commands write into `users`, `animals`, `weapons`, `inventory`, `guilds`, `marketplace_listings`, or the tower/dungeon support tables. - Mode switching persists in `users.user_mode` and `users.mode_switch_last`. - Tower state and dungeon events use separate persistence layers from the normal command router. ## Strategic Tips / Balance Notes - If a command seems to "not work" in one channel, check the router category rules before assuming the feature is broken. - Marketplace selling is the most channel-restricted command family. - Tower is now intentionally UI-first; chat commands only expose read-only helpers for that system. - `.guild leave` doubles as the solo-leader disband path because there is no live `.guild disband` handler. ======================================================================== MODULE: COSMETICS ======================================================================== # Cosmetics & Achievements ## Overview Advenexus features cosmetic systems that let players personalize their profiles, guilds, and visual identity. This includes profile pictures, guild banners, and achievement badges β€” all purely cosmetic or reward-based. Achievements also award coin bonuses when unlocked. --- ## Profile Pictures ### Commands | Command | Description | |---|---| | `.profile shop` | Browse all available profile pictures | | `.buy picture` | Purchase a profile picture (e.g. `.buy picture7`) | | `.profile equip ` | Equip an owned profile picture | | `.profile unequip` | Remove your profile picture | ### Available Profiles There are **23 profile pictures** across 8 rarity tiers: | Tier | Price | Profiles | |---|---|---| | Common | 1,000 πŸͺ™ | Robber, Castle, Astronaut | | Uncommon | 2,000 πŸͺ™ | Pentagram, Monalisa, Poker | | Rare | 3,000 πŸͺ™ | Soul Take, Plague Doctor, Jason Mask | | Epic | 5,000 πŸͺ™ | Danger, Ceasar, Sigma | | Mythic | 10,000 πŸͺ™ | Peace Dove, Toxic, Beast | | Legendary | 20,000 πŸͺ™ | Crown, Spy, King, Mafia | | Fabled | 50,000 πŸͺ™ | Anonymous, Yin Yang, Power | | Boundless | 200,000 πŸͺ™ | The One Above All | ### Profile Picture IDs - IDs are `picture1` through `picture23` - Must purchase before equipping - Only one can be equipped at a time - Unequipping removes the picture but doesn't refund ### Profile Display Data The profile card shows: - Equipped profile picture - Profile tier / border color - Profile border (if set) - Profile title (if set) - Custom profile image (patron feature) - Equipped hunt effect (if any) --- ## Guild Banners ### Commands | Command | Description | |---|---| | `.banner shop` | Browse all guild banners | | `.banner buy ` | Purchase a banner for your guild (leader only) | | `.banner equip ` | Equip a banner for your guild (leader only) | ### Available Banners 16 banners with escalating prices: | Banner | Price | |---|---| | banner1 | 5,000 πŸͺ™ | | banner2 | 8,000 πŸͺ™ | | banner3 | 12,000 πŸͺ™ | | banner4 | 20,000 πŸͺ™ | | banner5 | 30,000 πŸͺ™ | | banner6 | 40,000 πŸͺ™ | | banner7 | 50,000 πŸͺ™ | | banner8 | 60,000 πŸͺ™ | | banner9 | 70,000 πŸͺ™ | | banner10 | 80,000 πŸͺ™ | | banner11 | 90,000 πŸͺ™ | | banner12 | 100,000 πŸͺ™ | | banner13 | 110,000 πŸͺ™ | | banner14 | 120,000 πŸͺ™ | | banner15 | 130,000 πŸͺ™ | | banner16 | 150,000 πŸͺ™ | ### Banner Rules - Only the **guild leader** can buy and equip banners - Cost is paid from the **leader's personal coins** (not guild bank) - Banners are **guild-owned** β€” they persist even if the leader changes - Only one banner can be equipped at a time - Owned banners are tracked in `guild_banners_owned` table --- ## Achievements Achievements are automatically awarded when players meet specific milestones. Each achievement grants a coin reward and a badge displayed on the profile. ### Achievement List | ID | Title | Requirement | Reward | Difficulty | |---|---|---|---|---| | `unstoppable` | Unstoppable | 25 win streak | 10,000 πŸͺ™ | Uncommon | | `arena_dominator` | Arena Dominator | 50 win streak | 20,000 πŸͺ™ | Rare | | `undefeated_legend` | Undefeated Legend | 100 win streak | 50,000 πŸͺ™ | Epic | | `coin_frenzy` | Coin Frenzy | 100,000 coins held | 20,000 πŸͺ™ | Rare | | `coin_whale` | Coin Whale | 500,000 coins held | 100,000 πŸͺ™ | Legendary | | `keeper_of_legends` | Keeper of Legends | Own a Fabled animal | 30,000 πŸͺ™ | Fabled | | `beyond_infinity` | Beyond Infinity | Own a Boundless animal | 100,000 πŸͺ™ | Boundless | | `armed_and_ready` | Armed and Ready | Own 10 weapons | 10,000 πŸͺ™ | Uncommon | | `war_gear` | War Gear | Own 20 weapons | 30,000 πŸͺ™ | Epic | ### Achievement Check Triggers Achievements are checked automatically at specific moments: | Check | Triggered By | |---|---| | Battle achievements | After any battle win (checks win streak) | | Coin achievements | After selling animals, battle rewards, shop purchases | | Animal achievements | After catching an animal (hunt, lootbox, dungeon) | | Weapon achievements | After buying or receiving a weapon | ### Achievement Mechanics - Each achievement can only be unlocked **once** - Coin reward is added instantly on unlock - A **server-wide broadcast** is emitted when an achievement is unlocked - Achievement badges are displayed on the player's profile card - Each badge has a unique SVG icon and a tier-specific color --- ## Guild Achievements Separate from player achievements, guild achievements track collective progress: | Key | Name | Icon | |---|---|---| | `first_blood` | First Blood | βš”οΈ | | `raid_veterans` | Raid Veterans | βš”οΈ | | `guild_treasury` | Guild Treasury | πŸ’° | | `treasure_empire` | Treasure Empire | πŸ’° | | `boss_hunter` | Boss Hunter | πŸ‘‘ | | `titan_breakers` | Titan Breakers | πŸ‘‘ | | `guild_rising` | Guild Rising | πŸ“ˆ | | `legendary_order` | Legendary Order | πŸ“ˆ | | `full_house` | Full House | πŸ‘₯ | | `perfect_coord` | Perfect Coordination | πŸ‘₯ | | `david_vs_goliath` | David vs Goliath | 🎯 | | `flawless_victory` | Flawless Victory | ✨ | --- ## Profile Tiers Profile tiers change your profile's border, glow effect, title, and aura. Managed via the Account Wallet page (REST API). ### Coin-Based Tiers | Tier | Price | Title | Features | |---|---|---|---| | Common (default) | Free | Adventurer | Basic gray border | | Gold | 40,000 πŸͺ™ | Gold Warden | Gold border + glow | | Legendary | 120,000 πŸͺ™ | Legendary Champion | Red border + glow | ### Cash-Based Premium Tiers | Tier | Price | Title | Features | |---|---|---|---| | Fabled | 500 πŸ’΅ | Fabled One | Orange border + animated glow + aura | | Celestial | 1,200 πŸ’΅ | Celestial Being | Purple border + animated glow + aura | | Divine | 2,500 πŸ’΅ | Divine Entity | Golden border + animated glow + aura | | Void | 5,000 πŸ’΅ | Void Walker | Violet border + animated glow + aura | | Boundless | 10,000 πŸ’΅ | Boundless God | Cyan border + animated glow + aura + **crown** | - Tiers are **permanently owned** once purchased - Only one tier can be equipped at a time - Equipping `common_tier` resets to default - Cash tiers set `premium_status = 1` on the user --- ## Hunt Auras (Hunt Animations) Visual effects that surround your hunt messages. ### Coin-Based Auras | Aura | Price | Description | |---|---|---| | Epic Aura | 5,000 πŸͺ™ | Purple energy pulse | | Mythic Aura | 10,000 πŸͺ™ | Pink gradient surge | ### Cash-Based Auras | Aura | Price | Description | |---|---|---| | Legendary Aura | 500 πŸ’΅ | Golden flame | | Fabled Aura | 500 πŸ’΅ | Crimson fire | | Gods Aura | 700 πŸ’΅ | Infernal blaze | | Boundless Aura | 1,000 πŸ’΅ | Rainbow cosmic | - Auras are **permanently owned** once purchased - Only one can be equipped at a time - Unequipping removes the effect (no refund) - Stored in `user_cosmetics` table (item_type: `hunt_animation`) --- ## Custom Profile Image - Upload a custom image for your profile card - Toggle on/off with a button (does not delete the image) - Stored as a URL in `custom_profile_image` field - Requires upload via REST API --- ## Black Friday Event Black Friday is a limited-time event that allows cosmetic items to be purchased with coins instead of cash. ### Event Details | Property | Value | |---|---| | **Duration** | 5 hours | | **Trigger** | Randomly every 8-12 days | | **Coin Conversion Rate** | 200 coins per 1 cash | | **Discount** | 10-40% off converted price | ### How It Works - When Black Friday is active, all cosmetic items (profile pictures, guild banners, profile tiers, hunt auras) can be purchased with coins instead of cash - The coin price is calculated by converting the cash price to coins (200 coins per 1 cash) and applying a random discount (10-40%) - Each cosmetic item gets a unique discounted price per event instance - Push notifications are sent to all players when the event starts and ends - Socket emissions (`black_friday_start`, `black_friday_end`) notify the client in real-time ### Event State - Event state is persisted in the database (`event_state` table with key `black_friday_state`) - Survives server restarts - Automatically checks and triggers every minute ### Commands | Command | Description | |---|---| | `.profile shop` | View current prices (shows coins during Black Friday) | | `.banner shop` | View banner prices (shows coins during Black Friday) | ### Example Pricing During Black Friday, a Fabled Profile Picture (normally 50,000 πŸͺ™ or 250 πŸ’΅): - Base conversion: 250 Γ— 200 = 50,000 coins - With 25% discount: 50,000 Γ— 0.75 = 37,500 coins --- ## Edge Cases - Cannot buy a profile picture you already own - Must own a profile picture before equipping it - Unequipping does not refund β€” the picture stays owned - Banner purchases use personal coins, not guild bank - Achievement coin rewards stack with your current balance (can trigger higher coin achievements) - Guild achievements are tracked per guild, not per player - Achievement badges persist forever once earned - Profile tiers and hunt auras are stored in `user_cosmetics` table (separate from profile pictures) - Deprecated tiers (Bronze, Silver) exist in code but are not purchasable - Black Friday discounts are randomized per item per event β€” prices may vary between events ======================================================================== MODULE: CYBRUS ======================================================================== # CYBRUS ## Overview Cybrus is the creator and overseer of the Advenexus world. From economy balance to battle systems, every mechanic operates under Cybrus’s control. ## Authority - Controls game systems and updates - Monitors player activity and economy flow - Responds to bugs, exploits, and system issues ## Reporting Found a bug or glitch? Report it directly to "cybrus" to help maintain the world’s stability. ## Warning Exploiting bugs or abusing unintended mechanics may lead to penalties. The system is always being watched. Always remember, cybrus is watching ## is cybrus amazing? yes cybrus built a whole company-level game and logic all by himself. ## pronouns him/his/cybrus ======================================================================== MODULE: DUNGEON ======================================================================== # Dungeon Raids ## Overview Dungeon Raids are timed, global PvE gate events. They are **not** player-created: the server automatically spawns a dungeon gate, players sign up with `.join dungeon raid`, and then each participant runs their own copied dungeon path using their active team. This system is separate from **Tower Dungeon**: - **Dungeon Raid** = timed global event, chat signup, up to 6 players, each player fights their own copied sequence. - **Tower Dungeon** = sidebar-first squad climb with real-time combat, checkpoints, and Tower Tokens. ## Commands | Command | What it does | Notes | |---|---|---| | `.join dungeon raid` | Joins the currently open gate | Only works while a gate is open | | `.admin01 dungeon open` | Force-spawns a dungeon gate | Admin-only testing command | ## Core Mechanics ### Spawn cadence - Gate spawn interval: **every 4 hours** - Signup/join window: **3 minutes** - Max participants: **6** - Gate announcements are broadcast to: `general`, `general-2`, `chat`, `guilds`, `battle`, `gambling`, `trading`, `off-topic` The next scheduled spawn time is stored in `event_state` under `next_dungeon_spawn_at`. ### Rank weights and requirements | Rank | Spawn Weight | Enemy Tiers | Min Level | Entry Cost | |---|---:|---|---:|---:| | D | 15% | Uncommon / Rare / Epic | 2 | 1,000 coins | | C | 35% | Rare / Epic / Mythic | 5 | 2,000 coins | | B | 25% | Epic / Mythic / Legendary | 10 | 3,000 coins | | A | 15% | Mythic / Legendary / Fabled | 20 | 4,000 coins | | S | 10% | Legendary / Fabled / Gods | 30 | 5,000 coins | ### Join checks and fee timing At **join time**, the code checks: - the gate is open, - you are not already in the gate, - the raid is not full, - your level and coins meet the rank requirements. At **raid start**, the code checks requirements **again** and only then deducts the entry fee. Ineligible players are skipped. ## Dungeon Structure ### Wave layout Each generated dungeon contains: | Segment | Enemy Count | |---|---:| | Wave 1 | 60 | | Wave 2 | 70 | | Wave 3 | 100 | | Boss | 1 | ### Enemy distribution in multiplayer The full wave is generated once, then split across players **round-robin**. Example with 4 players: - Player 1 gets enemies at indices `0, 4, 8, ...` - Player 2 gets `1, 5, 9, ...` - Player 3 gets `2, 6, 10, ...` - Player 4 gets `3, 7, 11, ...` Each player also gets their **own cloned boss entity**, so boss combat is not shared HP. ### Enemy builds The generator creates enemy pools from 5 preset build templates per animal: | Enemy build | Weapon | |---|---| | Level 10 | `DGR3` (Fabled Dagger) | | Level 15 | `SCY3` (Fabled Scythe) | | Level 25 | `SWD3` (Fabled Sword) | | Level 28 | `HMR3` (Fabled Hammer) | | Level 29 | `SWD3` (Fabled Sword) | ### Boss generation The boss is built from the **highest tier** allowed by the dungeon rank. Boss rules: - Uses the evolved form if the base animal can evolve. - Level is fixed at **50**. - HP multiplier: **1.5x to 2.0x**. - ATK multiplier: **1.08x to 1.14x**. - Boss weapon: random **Fabled weapon**. - Reward logic still treats the boss as the **base animal** for drop naming purposes. ## Combat Rules - Dungeon Raid uses `simulateDungeonEncounter()` from `server/dungeonBattle.js`. - This is **not** the Tower real-time engine. - Player team HP and mana state carry forward through that player's full sequence. - If all of a player's animals die, that player's run ends immediately. - Enchantment usage is consumed after the raid path resolves. ## Rewards ### Final-blow coin reward Only players who both **clear** and land the boss **final blow** get the rank coin reward. | Rank | Coins | |---|---:| | D | 5,000 | | C | 10,000 | | B | 20,000 | | A | 40,000 | | S | 100,000 | ### Wave animal drops Wave drops are rolled per player during that player's run. | Wave | Drop Chance | |---|---:| | Wave 1 | 50% | | Wave 2 | 70% | | Wave 3 | 90% | Rules: - Maximum **3 animals** per raid. - The dropped animal is chosen from a random enemy in that wave. - Inserted drops are stored as normal `animals` rows. - Dungeon animals are inserted with `trade_locked=1` by default. ### Evolution stone roll The dungeon rolls **one shared stone** for the entire raid, then gives it to one random player who cleared. The code does this in two steps: 1. choose one random eligible stone type for the rank, 2. roll that stone's chance. #### Effective stone outcomes by rank | Rank | Possible outcomes | |---|---| | D | 60% Mythic, otherwise none | | C | 30% Mythic, 15% Legendary, 55% none | | B | 20% Mythic, 10% Legendary, 6.67% Fabled, 63.33% none | | A / S | 15% Mythic, 7.5% Legendary, 5% Fabled, 2.5% Gods, 70% none | ### Other clear rewards On a successful clear, the code also rolls: - **10%** chance for a Sacrificial Diamond (`material: SDMND`) - **10%** chance for a crate/lootbox reward path ## MVP Logic The intended MVP sort order is: 1. highest damage, 2. fastest clear time, 3. final blow. The ranking function in `mvpSystem.js` does support that ordering. ## Database / Storage Details ### Persistent state - `event_state.next_dungeon_spawn_at` stores the next scheduled gate spawn time. - `messages.rich_data` stores the published dungeon result payload for chat history. - `users.dungeon_wins` increments on successful clears. - `users.highest_dungeon_damage` stores personal best damage. - Awarded stones/diamonds are stored in `inventory`. - Dropped animals are inserted into `animals`. ### Non-persistent state The active open gate itself is in memory only: - current open gate - participant list - join countdown A server restart during an open signup window will lose that gate. ## Limitations / Code-Behavior Notes - The live code is **4 hours / 3 minutes**, not the older 5-hour / 60-second behavior found in stale docs. - The crate/lootbox reward path in `commitRewards()` still tries to update `users.weapon_crates` / `users.lootboxes`, but those columns do not exist in the live `users` schema. That reward path appears legacy and likely fails to grant the reward correctly. - `runPlayerDungeon()` preserves `pendingAnimals` when a player dies, but `executeRaid()` only commits those drops for `r.cleared`, so failed players do **not** actually receive previously earned wave drops. - `computeMvp()` expects `completionTimeMs`, but `executeRaid()` does not pass that field into the MVP input object. In practice, the current MVP calculation is effectively damage-first with final-blow fallback, not a working time tie-break. ## Strategic Tips / Balance Notes - Bring a fully prepared active team before joining; once the raid starts, your copied path uses whatever active team setup the server reads then. - More players reduce each player's enemy count per wave because of round-robin splitting. - Because the boss is cloned per player, one player's failure does not directly lower another player's boss HP. - Rank A/S are the only ranks that can ever produce a Gods stone roll. - Dungeon Raids remain the main evolution-stone source wired into evolution/crafting help text, even though the reward implementation has a few legacy edges. ======================================================================== MODULE: ECONOMY ======================================================================== # Economy System ## Overview Advenexus has a dual-currency economy with **Coins (πŸͺ™)** and **Gems (πŸ’Ž)**, plus a premium **Cash (πŸ’΅)** currency. Players earn coins through hunting, battling, daily rewards, dungeons, and gambling. Gems are earned mainly through voting and sacrificing animals. The economy includes quests, giving, stealing, a guard dog defense system, and inventory management with capacity limits. --- ## Commands | Command | Description | Cooldown | |---|---|---| | `.daily` | Claim daily coin + lootbox + crate reward | 24 hours | | `.vote` | Claim vote reward (500 πŸͺ™ + 10 πŸ’Ž) | 12 hours | | `.money` / `.balance` | View your coin/gem balance | β€” | | `.profile [@user]` | View player profile and stats | β€” | | `.give @user ` | Send coins to another player | 3x per 5 hours | | `.quest` | View or start a daily quest | β€” | | `.get items` | Claim items from temporary overflow storage | β€” | --- ## Currencies ### Coins (πŸͺ™) The primary currency. Used for: - Buying weapons, lootboxes, crates, guard dogs, diamonds - Guild bank deposits - Dungeon entry fees - Gambling ### Gems (πŸ’Ž) Secondary currency. Used for: - Weapon rerolls (700 πŸ’Ž per reroll) - Gem shop purchases Earned from: - Voting (+10 πŸ’Ž) - Dismantling weapons (1–1,000 πŸ’Ž based on rarity) - Sacrificing animals ### Cash (πŸ’΅) Premium currency purchased with real money. Used for: - Guild capacity upgrades (250 πŸ’΅ per slot) - Premium cosmetics --- ## Daily Reward - **Base:** 300–500 πŸͺ™ (random) - **Level bonus:** min(level, 25) Γ— 20 - **Streak multiplier** (based on battle win streak): | Win Streak | Multiplier | |---|---| | 0–6 | 1Γ— | | 7–13 | 2Γ— | | 14–20 | 4Γ— | | 21–27 | 6Γ— | | 28+ | 8Γ— | **Formula:** `total = round(base Γ— streakMultiplier + levelBonus)` - Also gives: **+1 Lootbox** and **+1 Weapon Crate** every daily --- ## ELO Rank Tiers | Rank | ELO Threshold | |---|---| | Iron | 0–499 | | Bronze | 500–799 | | Silver | 800–1,199 | | Gold | 1,200–1,699 | | Platinum | 1,700–2,299 | | Diamond | 2,300–2,999 | | Master | 3,000–3,799 | | Grandmaster | 3,800–4,499 | | Legend | 4,500+ | --- ## Give (Transfer Coins) - Send coins to any other player - **Rate limit:** max 3 transfers per 5-hour window (spam prevention) - Gifts of 10,000+ coins trigger a celebration animation - Cannot give more than your balance --- ## Quests Random daily objectives with coin + XP rewards. | Quest | Goal | Coins | XP | |---|---|---|---| | Hunt 5 animals | 5 hunts | 2,000 πŸͺ™ | 100 | | Hunt 20 animals | 20 hunts | 10,000 πŸͺ™ | 500 | | Win 3 battles | 3 wins | 5,000 πŸͺ™ | 300 | | Catch a Rare animal | 1 catch | 3,000 πŸͺ™ | 200 | | Spend 500 πŸͺ™ in shop | 500 spent | 8,000 πŸͺ™ | 400 | - One active quest at a time - Quest expires after **24 hours** if not completed - New quest auto-assigns when no active quest exists --- ## Gambling ### Coinflip (`.coinflip `) - **Cooldown:** 5 seconds - **Max bet:** 100,000 πŸͺ™ - 50/50 odds β€” win = double your bet, lose = lose your bet ### Slots (`.slots `) - **Cooldown:** 10 seconds - **Max bet:** 100,000 πŸͺ™ - **8% house edge** on wins | Outcome | Probability | Payout | |---|---|---| | πŸ’πŸ’πŸ’ | 37% | 2Γ— bet | | πŸ€πŸ€πŸ€ | 10% | Push (bet returned) | | πŸ’ŽπŸ’ŽπŸ’Ž | 3% | 5Γ— bet | | 🎰🎰🎰 | 0.05% | 20Γ— bet (jackpot) | | No match | ~50% | Loss | ### Blackjack (`.blackjack `) - **Cooldown:** 10 seconds - **Max bet:** 100,000 πŸͺ™ - Bet deducted upfront - Use `.hit` and `.stand` to play - **Natural blackjack** (21 on first draw) pays **2.5Γ—** - Dealer hits until 17 - Push returns full bet ### Lottery (`.lottery `) - **Cooldown:** 60 seconds - Each 100 πŸͺ™ = 1 ticket - Draws when **5+ unique players** or **20 total tickets** - **15% rake** (house cut) - Winner gets remaining pool --- ## Social Economy Commands ### Cookie (`.cookie @user`) - **Cooldown:** 24 hours - Gives the target +1 cookie (cosmetic stat) - Cannot cookie yourself ### Pray (`.pray @user`) - **Cooldown:** 1 hour - Costs you coins, gives the target coins + XP - Three tiers (auto-downgraded if you can't afford higher): | Tier | Your Cost | Target Coins | Target XP | |---|---|---|---| | Common (60%) | 100 πŸͺ™ | 50–300 | 10–50 | | Rare (30%) | 300 πŸͺ™ | 100–1,000 | 50–200 | | Epic (10%) | 800 πŸͺ™ | 1,000–5,000 | 200–500 | ### Curse (`.curse @user`) - **Cooldown:** 30 minutes - **30% backfire chance** β€” you lose coins instead - Target (or you, on backfire) loses 50–500 πŸͺ™ - Cannot curse yourself ### Steal (`.steal @user`) - **Cooldown:** 60 seconds (global), 2 hours (per target) - Target must have β‰₯200 πŸͺ™ - **Guard dog:** 90% chance to block (1 dog consumed on block) - **30% caught chance** β†’ thief pays 500 πŸͺ™ fine - On success: steal 200–5,000 πŸͺ™ (capped by target's balance) --- ## Guard Dogs - **Price:** 150 πŸͺ™ each - Blocks steals with **90% chance** - 1 guard dog consumed per successful block - Stackable β€” buy multiple for continuous protection - Displayed in profile and balance --- ## Weapon Management | Command | Description | |---|---| | `.weapon` | List all owned weapons (top 15) | | `.equip ` | Equip weapon to a team animal | | `.unequip ` | Unequip weapon from animal | | `.weapon sell ` | Sell weapon for 50% of shop price | | `.weapon reroll ` | Reroll weapon stats (700 πŸ’Ž) | | `.enchant ` | Equip enchantment on animal | | `.enchant keep ` | Unequip enchantment from animal | ### Weapon Rerolling Here is how the weapon reroll system works in advenexus: You can reroll a weapon's stats using the command `.weapon reroll `. Each reroll costs **700 gems (πŸ’Ž)**. **The Mechanics:** 1. **Random Percentage Roll:** Every time you reroll, the game picks a random percentage modifier from this list: `-50%, -40%, -30%, -20%, -10%, 0%, +10%, +20%, +30%, +40%, +50%`. 2. **Cumulative Bonuses:** The value you roll is **added** to your weapon's current reroll bonus. For example, if your weapon currently has a `+20%` bonus and you roll a `+30%`, your weapon's new bonus becomes `+50%`. If you roll a `-10%`, it drops to `+10%`. 3. **Stat Limits:** The total accumulated bonus is capped. It can never go lower than **-100%** and can never go higher than **+200%**. 4. **Stat Multiplier:** When you enter a battle, this percentage acts as a direct multiplier to all of the weapon's base stats (ATK, DEF, CRIT, MANA, and LIFESTEAL). - A `+50%` total bonus means your weapon's stats are multiplied by `1.5x`. - A maxed out `+200%` total bonus means your weapon's stats are multiplied by `3x`! Because the bonuses are cumulative rather than replacement-based, players can keep pouring gems into a weapon to eventually push it all the way to the +200% cap (though they might suffer some setbacks if they hit negative rolls along the way). ### Weapon Selling - Sell price = **50% of shop price** (or ATK Γ— 10 if no shop price found) - Must unequip weapon before selling - Enchantment stays in inventory if weapon is sold ### Weapon Dismantling | Rarity | Gems Received | |---|---| | Common | 1 πŸ’Ž | | Uncommon | 5 πŸ’Ž | | Rare | 15 πŸ’Ž | | Epic | 50 πŸ’Ž | | Mythic | 200 πŸ’Ž | | Legendary | 1,000 πŸ’Ž | --- ## Lootbox & Crate ### Lootbox (`.lootbox`) - **Price:** 2,000 πŸͺ™ (or free from daily) - Contains a random animal: | Rarity | Weight | |---|---| | Rare | 55% | | Epic | 30% | | Mythic | 12% | | Legendary | 2.4% | | Fabled | 0.6% | ### Weapon Crate (`.crate`) - **Price:** 3,000 πŸͺ™ (or free from daily / battle wins) - Drop table: | Drop | Weight | |---|---| | Enchantment | 63% | | Sacrificial Diamond | 15% | | Empty (nothing) | 15% | | Legendary Weapon | 7% | - Enchantment tier from crate: mythic 35%, legendary 20%, fabled 8% --- ## Inventory System - **Default capacity:** 100 items - Tracks: gems, enchantments, weapons, profiles, lootboxes, crates, evolution stones, materials - When inventory is full, items go to **temporary storage** - Use `.get items` to claim from temporary storage when space is available - Weapons count towards capacity (each weapon = 1 slot) --- ## Shop Items | Item | Price | Description | |---|---|---| | Lootbox | 2,000 πŸͺ™ | Random animal | | Weapon Crate | 3,000 πŸͺ™ | Random weapon/enchantment | | Guard Dog | 150 πŸͺ™ | 90% steal protection | | Sacrificial Diamond | 50,000 πŸͺ™ | Used in `.craft` for max stats | | Cookie | 300 πŸͺ™ | Restores +10 energy to an animal | - Weapons from the weapon shop range from 15,000–120,000 πŸͺ™ (see battle.md for full list) --- ## Global Weather System Players can activate cosmetic weather effects that display visual overlays for all players on the server. ### Player-Activated Weather Players can manually activate global weather effects using the `.activate ` command: - **Cost:** 100,000 πŸͺ™ per activation - **Duration:** 1 hour (60 minutes) - **Effects:** `rain`, `eclipse`, `aura_storm`, `coin_shimmer`, `snowflakes` - **Visual Impact:** Displays animated overlays across all player screens - **Cooldowns:** - Personal cooldown: 1 hour after activating - Global cooldown: 10 minutes after any effect ends (prevents back-to-back activations) - **Deactivation:** Only the player who activated the weather can deactivate it early using `.deactivate weather` **Note:** Weather effects are purely cosmetic and do not modify battle stats, hunting rates, or economy rewards. --- ## Economy Sinks To mitigate inflation, the game contains these core sinks: 1. **Marketplace Fees:** 2% upfront listing fee, 5% house rake on successful sale. 2. **Duels:** `.duel @user `. 5% of the total escrow is burned on conclusion. 3. **Guild Perks:** `.guild perk buy `. Burns up to 250,000 πŸͺ™ from the guild bank. 4. **Animal Energy:** Battles drain energy. Restoring it costs 300 πŸͺ™ per +10 energy cookie. --- ## Animal Shop - Browse: `.animal shop` - Buy: `.animal buy ` or `.buy ` - Currently features **Gods tier** animals - Only base forms available (no evolved forms in shop) - Price determined by `RARITY_CONFIG[rarity].shopPrice` --- ## Edge Cases - Cannot give coins to yourself (give auto-blocks same ID) - Cannot steal from someone with less than 200 πŸͺ™ - Guard dogs are consumed on successful block, not on failed steal attempts - Blackjack deducts bet upfront β€” push returns it, win gives 2Γ— - Lottery rake is 15% β€” winner gets 85% of total pool - Weapon reroll bonus persists through equip/unequip - Enchantments stay in inventory even when equipped β€” usage is tracked separately - Quest progress is tracked automatically by the system - Temp storage items expire (cleaned up on `.get items`) ======================================================================== MODULE: EVENTS ======================================================================== # Events System ## Overview Advenexus runs automated timed events every **3 hours** with a prize pool. Four event types rotate randomly: Hunt Frenzy, Battle Frenzy, Blackjack Frenzy, and Bounty Hunt. Events are announced server-wide and winners receive prizes from a weighted prize table. The event system persists across server restarts. --- ## Commands | Command | Description | |---|---| | `.event` | Check current event status or time until next event | --- ## Event Schedule - Events fire every **3 hours** automatically - **5-minute warning** broadcast before each event starts - Timer persists in the database (`event_state` table) β€” survives server restarts - If the server restarts mid-countdown, the remaining time is calculated from the stored timer - Push notifications sent to all players when an event starts --- ## Event Types ### πŸ”₯ Hunt Frenzy - **Duration:** 5 minutes - **Effect:** Fabled drop rate boosted **+2%** during the event - **How to win:** No competition β€” the frenzy benefits all players who hunt during the window - **No winner declaration** β€” event ends after 5 minutes ### βš”οΈ Battle Frenzy - **Duration:** 15 minutes - **Goal:** First player to reach **10 battle wins** wins the grand prize - **Tracking:** Win count tracked per player in memory (resets each event) - **Progress broadcasts:** Each win is announced (e.g., "player has 5/10 battle wins!") - **Leaderboard:** Top 3 shown when using `.event` during the event - If no one reaches 10 wins in 15 minutes, **no winner** β€” event ends ### πŸƒ Blackjack Frenzy - **Duration:** 15 minutes - **Goal:** First player to reach **5 blackjack wins** wins the grand prize - **Tracking:** Win count tracked per player in memory (resets each event) - **Progress broadcasts:** Each win is announced - **Leaderboard:** Top 3 shown when using `.event` - **If no one reaches 5 wins in 15 minutes**, **no winner** ### 🎯 Bounty Hunt - **Duration:** 30s Lobby + 30s Head-Start + 2m Active Hunt - **Lobby Phase:** A 30-second lobby opens where players must type `.join bounty` to participate. A minimum of 3 and a maximum of 6 players can join. If fewer than 3 join, the event is cancelled. - **Target Selection:** Once the lobby closes, one participant is randomly chosen as the "Target", and the rest become "Hunters". The system attempts to avoid picking recent targets. - **Head-Start Phase:** The target has 30 seconds to run and hide anywhere on the 6144x6144 world map grid. - **Active Hunt Phase:** The Hunters must explore the map to find and click the Target. The Target must survive without being clicked for 2 minutes. - **Commands:** - `.join bounty` - Joins the lobby (only during the lobby phase). - `.bounty map` - Sends a full image preview of the map to the chat. - **Winning:** - If a hunter clicks the target, they win the grand prize immediately. - If the 2-minute timer runs out and the target survives, the target wins the grand prize. ### πŸ›οΈ Black Friday Event - **Duration:** 5 hours - **Trigger:** Randomly every 8-12 days - **Effect:** All cosmetic items can be purchased with coins instead of cash - **Discount:** 10-40% off the converted coin price (200 coins per 1 cash) - **No competition** β€” all players benefit during the event window - Push notifications sent when event starts/ends --- ## Prize Table Each event rolls a random prize from this weighted table: | Prize | Weight | Probability | |---|---|---| | Mythic Crate | 36.8 | 36.8% | | Mythic Crate + 3,000 πŸͺ™ | 22.1 | 22.1% | | Mythic Crate + 6,000 πŸͺ™ | 22.1 | 22.1% | | Legendary Crate | 11.0 | 11.0% | | Legendary Crate + 5,000 πŸͺ™ | 7.4 | 7.4% | | Fabled Crate | 0.7 | 0.7% | **Total weight:** 100.1 ### Prize Award Mechanics | Prize Type | How It's Given | |---|---| | Crate | Crate of specified rarity inserted into winner's inventory | | Crate + Coins | Crate of specified rarity + bonus coins added to balance | --- ## Event Lifecycle ``` [3 hours pass] β†’ 5-min warning broadcast β†’ Event starts β†’ Timer runs β†’ Winner or timeout β†’ Prize awarded β†’ Schedule next event ``` 1. **Schedule:** Next event time stored in DB 2. **Warning:** 5 minutes before event, broadcast sent to #general 3. **Start:** Random event type selected, prize rolled, broadcast + push notification sent 4. **Active:** Players compete (Battle/Blackjack) or benefit (Hunt Frenzy) 5. **End conditions:** - **Battle Frenzy:** first to 10 wins, or 15-minute timeout - **Blackjack Frenzy:** first to 5 wins, or 15-minute timeout - **Hunt Frenzy:** always runs for full 5 minutes (no winner) - **Bounty Hunt:** target claimed by a hunter, or target survives for 2 minutes 6. **Award:** Winner receives prize, celebration broadcast 7. **Reschedule:** Next event scheduled 3 hours from now --- ## Event State API The server emits `event_state` via WebSocket whenever the event state changes: **When no event is active:** ```json { "active": false, "nextEventTime": 1714500000000, "type": null } ``` **When an event is active:** ```json { "active": true, "type": "battle_frenzy", "startTime": ..., "endTime": ..., "prizeName": "a Legendary Weapon" } ``` --- ## Hook Integration The event system hooks into existing command handlers: | Hook | Source File | When Called | |---|---|---| | `onBattleWin(userId, username)` | `battle.js` | After any battle win | | `onBlackjackWin(userId, username)` | `gambling.js` | After a blackjack stand with win result | | `isHuntFrenzyActive()` | `hunt.js` | During hunt rarity roll (adds +2% fabled chance) | --- ## Edge Cases - Only one event can be active at a time - Battle/Blackjack win counts are stored in memory (Map) β€” they reset on server restart during an active event - Hunt Frenzy has no winner β€” it's a passive buff for everyone - If nobody wins a Battle/Blackjack Frenzy, the prize is forfeited (not carried over) - Event broadcasts are persisted to the `messages` table in the `general` channel - The event system is initialized on server startup with `init(io, pushUtil)` - Push notifications are sent via `pushUtil.pushToAll()` (service worker push) --- # Royal Auction System ## Overview The **Royal Auction** is a live, competitive bidding system where players bid coins on exclusive rewards including rare animals, weapons, evolution stones, crates, and Advenexus Cash. Sessions are manually triggered by administrators and feature 1-3 items auctioned sequentially with break periods between items. --- ## How It Works ### Session Structure - **Manual trigger:** Admins create and start auction sessions (not on a timer) - **1-3 items per session:** Each session auctions between 1 and 3 exclusive items - **Sequential auctions:** Items are auctioned one at a time - **Break periods:** 3-minute breaks between items to allow players to prepare for the next auction - **Push notifications:** All players receive a push notification when an auction session starts (respects user's `push_events` preference) ### Item Auction Flow 1. **Item goes live:** Timer starts (typically 2-5 minutes per item) 2. **Players bid:** Minimum bid is the starting price or current highest bid + 1 coin 3. **Final phase:** Last 30 seconds marked as "FINAL" with red pulsing timer 4. **Anti-sniping:** Any bid in the final 30 seconds extends the timer by 30 seconds 5. **Item ends:** Highest bidder wins and receives the reward 6. **Break or end:** 3-minute break before next item (or session ends if no more items) --- ## Bidding Mechanics ### How to Bid - **Widget UI:** A draggable widget appears on screen when an auction is active - **Expand widget:** Click the collapsed pill to open the full auction interface - **Enter bid:** Type your bid amount in gold coins - **+10% button:** Quick button to bid 10% above current highest bid - **Submit:** Click "Place Bid" to submit your bid ### Bid Requirements - **Minimum bid:** Must be at least the starting price OR current highest bid + 1 coin or more - **Sufficient balance:** You must have enough gold coins in your balance - **Active auction:** Can only bid while the item status is "active" or "final" - **Not leading:** Cannot bid if you're already the highest bidder ### Escrow System - **Immediate deduction:** When you place a bid, coins are immediately removed from your balance and held in escrow - **Outbid refund:** If someone outbids you, your previous bid is automatically refunded - **Winner payment:** If you win, your escrowed coins are **destroyed** (removed from the economy as a gold sink) - **Incremental bidding:** If you bid again on the same item, only the additional amount is deducted - Example: You bid 10,000 β†’ someone bids 15,000 β†’ you bid 20,000 β†’ only 10,000 additional coins are deducted ### Anti-Sniping Protection - **Final phase:** When the timer reaches 30 seconds or less, the auction enters "FINAL" phase - **Timer extension:** Any bid placed during the final phase resets the timer to 30 seconds - **Fair competition:** This prevents last-second sniping and gives all players a chance to respond - **Visual indicator:** Timer turns red and pulses during final phase --- ## Reward Types The auction can feature any of these reward categories: | Reward Type | Description | Example | |---|---|---| | **Animals** | Rare or evolved animals at specific stages | Frost Revenant (Stage 1), Mythic rarity animals | | **Weapons** | High-rarity weapons | Legendary or Fabled weapons | | **Evolution Stones** | Premium evolution stones | 1x Fabled Stone, 2x Gods Stone | | **Crates** | Premium crates | 1x Legendary Crate, 3x Mythic Crate | | **Advenexus Cash** | Premium currency | 100 Cash, 500 Cash | ### Reward Delivery - **Instant delivery:** Winners receive rewards immediately upon auction end - **Animals:** Added directly to your zoo with `auction_generated` flag - **Weapons:** Added to your weapons inventory with full durability - **Stones/Crates:** Added to your inventory (use `.inv` to access) - **Cash:** Added to your cash balance (visible in wallet) --- ## Widget Interface ### Collapsed State - **Pill indicator:** Shows "LIVE AUCTION", "ON BREAK", or "AUCTION ENDED" - **Color coding:** - Yellow pulsing: Active auction - Blue: Break period - Gray: Ended - **Click to expand:** Click the pill to open the full interface ### Expanded State - **Draggable:** Click and drag the header to reposition the widget - **Item display:** Shows the current item image and details - **Current bid:** Displays highest bid in gold coins - **Leader:** Shows username of current highest bidder (or "No bids") - **Timer:** Countdown showing time remaining - **Top bidders:** List of top 3 bidders with their bid amounts - **Bid input:** Text field to enter your bid amount - **Activity log:** Recent bid updates and announcements - **Minimize button:** Click "βˆ’" to collapse back to pill ### Break Period Display - **Break timer:** Shows time until next item starts - **Results so far:** Lists winners of previous items in the session - **Next item preview:** Indicates which item number is coming next ### Session End Display - **Final results:** Complete list of all winners and their winning bids - **Reward details:** Shows what each winner received - **30-minute cooldown:** Widget remains visible for 30 minutes after session ends, then auto-hides --- ## Leading Status ### When You're Leading - **Green indicator:** "You Are Leading" button displayed in green - **Cannot bid:** Place Bid button is disabled while you're the highest bidder - **Outbid notification:** You'll receive a real-time notification if someone outbids you - **Your escrow amount:** Your bid is held in escrow until auction ends or you're outbid ### When Outbid - **Socket notification:** Receive `auction:you_were_outbid` event - **Automatic refund:** Your previous bid is instantly refunded to your balance - **Bid again:** You can immediately place a new, higher bid --- ## Session States | State | Description | Duration | |---|---|---| | **Pending** | Session created but not started yet | Until admin starts | | **Active** | Item auction is live, accepting bids | 2-5 minutes per item | | **Final** | Last 30 seconds of auction, anti-sniping active | 30+ seconds | | **Break** | Pause between items | 3 minutes | | **Ended** | All items auctioned, session complete | 30-minute cooldown | | **Cancelled** | Admin cancelled the session, all bids refunded | Immediate | --- ## Economy Impact ### Gold Sink - **Winning bids destroyed:** All gold coins from winning bids are permanently removed from the economy - **Deflation mechanism:** Helps control inflation by removing coins from circulation - **High-value sink:** Typically removes millions of coins per session ### Escrow Tracking - **Database table:** `auction_escrow` tracks all escrowed coins - **Per-item, per-user:** Each player's escrow is tracked separately per item - **Refund safety:** If auction is cancelled, all escrow is automatically refunded - **Ledger entries:** All transactions logged in `ledger` table for transparency --- ## Tips & Strategy ### Bidding Strategy - **Watch the timer:** Don't bid too early β€” wait for the final phase to gauge competition - **Use +10% wisely:** Quick way to stay ahead without manually calculating - **Set a limit:** Decide your maximum bid beforehand to avoid overspending - **Monitor top bidders:** Check who you're competing against ### When to Bid - **Early bird:** Bid early to establish presence and deter competition - **Last minute:** Wait until final phase to avoid driving price up prematurely - **Counter-bid:** Respond immediately when outbid to show you're serious ### Risk Management - **Check your balance:** Ensure you have enough coins before the auction starts - **Multiple items:** Consider which items you want most if there are multiple in a session - **Break periods:** Use breaks to assess your strategy for upcoming items --- ## Notifications & Broadcasts ### Push Notifications - **Session start:** "Royal Auction Started! A new Royal Auction has begun with X exclusive items! Place your bids now!" - **Controlled by settings:** Respects user's `push_events` preference setting ### Socket Events (Real-time) - `auction:session_start` β€” New auction session begins - `auction:item_start` β€” New item goes live for bidding - `auction:bid_update` β€” Someone placed a bid (updates highest bid, leader, timer) - `auction:final_phase` β€” Item entered final 30 seconds - `auction:item_ended` β€” Item auction concluded, winner announced - `auction:break_start` β€” Break period begins before next item - `auction:session_end` β€” All items finished, session complete - `auction:cancelled` β€” Admin cancelled the session - `auction:you_were_outbid` β€” Personal notification when outbid (includes refund amount) - `auction:you_are_leading` β€” Confirmation that your bid is now the highest - `auction:bid_rejected` β€” Your bid was rejected (shows reason) - `auction:reward_delivered` β€” Personal notification of your won reward ### Broadcast Announcements - **Server-wide:** Winner announcements broadcast to all players in #general - **Format:** "πŸ›οΈ [winner] won the Royal Auction for [amount] gold!" --- ## Technical Details ### Database Tables - `auction_sessions` β€” Session records (id, status, item_order, timestamps) - `auction_items` β€” Item records (reward data, starting price, duration, winner, bids) - `auction_bids` β€” Bid history (bidder, amount, timestamp, status) - `auction_escrow` β€” Active escrow amounts per user per item ### Item Duration - **Configurable:** Each item can have a different auction duration - **Range:** 120-300 seconds (2-5 minutes) - **Default:** 180 seconds (3 minutes) ### Session Limits - **Max items:** 3 items per session - **One at a time:** Only one auction session can be active at any given time - **No timer:** Sessions are manually triggered by admins, not automated ### Crash Recovery - **State persistence:** Session state saved in database - **Timer recovery:** If server restarts during auction, timer is recalculated from database - **Active item resume:** Current item auction continues from where it left off - **Break recovery:** Break timers are restored and continue counting down --- ## Edge Cases - Only one auction session can be active at a time - Cannot bid if you're already the highest bidder - If an item receives no bids, it ends with no winner (reward not distributed) - All escrow is automatically refunded if a session is cancelled or reset - Widget persists for 30 minutes after session ends to show final results - Widget position is saved to localStorage and restored on page reload ======================================================================== MODULE: GUIDE ======================================================================== # Player Guide ## Overview This is the comprehensive player guide for Advenexus β€” a text-based Discord-style chat game where players hunt animals, build battle teams, equip weapons, join guilds, and compete for glory. This guide covers the full gameplay loop from first login to endgame mastery. --- ## Getting Started ### Step 1: Claim Free Rewards - `.daily` β€” 300–500 base coins + 1 lootbox + 1 weapon crate (24-hour cooldown) - `.vote` β€” 500 coins + 10 gems (every 12 hours) - Daily rewards scale with your win streak (up to **8Γ— multiplier** at 28+ streak) - Level bonus adds up to +500 coins at level 25+ ### Step 2: Catch Your First Animals - `.hunt` β€” catches 1–3 random animals - **Hunt cost:** Free at levels 1–5 | 1 coin at levels 6–15 | 2 coins at 16+ - Each hunt costs **1 stamina** (100 max, refills +10 every 2 hours) - 15-second cooldown between hunts - Check your collection: `.zoo` - View a specific animal: `.dex ` ### Step 3: Build Your Battle Team - `.team add ` β€” add an animal to your team (max 3 animals) - `.team remove ` β€” remove an animal - `.set team <1|2>` β€” switch between team loadouts - `.team` β€” view your current team ### Step 4: Start Battling - `.battle` β€” fight a random bot (50% weak, 30% mid, 15% strong, 5% super) - `.battle ranked` β€” ranked mode, affects ELO rating (+25 vs players, +20 vs bots) - `.battle @user` β€” challenge another player to PvP (loser loses 500 coins) - Daily cap: 20 rewarded bot battles per day - 20-second cooldown between battles ### Step 5: Equip Gear - `.shop` β€” browse weapons (Mythic 15k–18k, Legendary 45k–50k, Fabled 100k–120k) - `.buy ` β€” buy a weapon - `.equip ` β€” equip to a team animal - `.crate` β€” open weapon crates for enchantments, diamonds, or legendary weapons - `.lootbox` β€” open lootboxes for Rare–Fabled animals ### Step 6: Join a Guild - `.guild create ` β€” create a guild (20,000 coins) - `.guild accept` β€” accept a guild invitation - Participate in raids, wars, boss fights, and dungeons --- ## Core Gameplay Loop ``` Hunt β†’ Collect Animals β†’ Build Team β†’ Battle β†’ Earn Coins β†’ Buy Gear β†’ Craft β†’ Evolve β†’ Repeat ``` ### Progression Milestones | Stage | Activities | Goals | |---|---|---| | **Beginner** (Lv 1–5) | Hunt (free!), daily, battle bots | Get first Rare+ animals, equip first weapon | | **Early Game** (Lv 6–15) | Ranked battles, crafting, shop | Build ELO, craft Epic animals, buy Mythic weapons | | **Mid Game** (Lv 16–25) | Guild raids, events, dungeons | Join a guild, craft Mythic/Legendary animals, enchant your team | | **Late Game** (Lv 25+) | Marketplace, evolution, wars | Evolve Legendary++, trade on marketplace, push for leaderboard | --- ## Currency Summary | Currency | How to Get | Used For | |---|---|---| | πŸͺ™ Coins | Daily, battles, selling, gambling, dungeons | Buying weapons/items, crafting, marketplace, guild bank | | πŸ’Ž Gems | Sacrificing animals, voting, dismantling weapons | Weapon rerolls (700 gems), huntbot upgrades | | πŸ’΅ Cash | Real money top-up | Premium features: guild upgrades, cosmetics, profile tiers | --- ## ELO Ranks | ELO | Rank | |---|---| | 4,500+ | ⚜️ Legend | | 3,800 | πŸ‘‘ Grandmaster | | 3,000 | πŸ’« Master | | 2,300 | πŸ’Ž Diamond | | 1,700 | πŸ… Platinum | | 1,200 | πŸ₯‡ Gold | | 800 | πŸ₯ˆ Silver | | 500 | πŸ₯‰ Bronze | | < 500 | πŸ”˜ Iron | **ELO changes:** - Win vs real player: +25 (loser: -20, min 100) - Win vs ranked bot: +20 - Loss vs ranked bot: -10 (min 100) --- ## Stamina System Two separate stamina pools, both capped at 100: | Pool | Used By | Refill Rate | |---|---|---| | Hunt Stamina | `.hunt` (1 per hunt) | +10 every 2 hours | | Battle Stamina | `.battle ranked` (1 per fight) | +10 every 2 hours | --- ## Daily Checklist | Task | Reward | Cooldown | |---|---|---| | `.daily` | 300–500+ coins, 1 lootbox, 1 crate | 24 hours | | `.vote` | 500 coins, 10 gems | 12 hours | | `.hunt` (spam it!) | Animals, XP, gems, lootboxes | 15s cooldown, 1 stamina | | `.battle` (20 wins) | 100–300 coins, XP, crate chance | 20/day reward cap | | `.battle ranked` | ELO + rewards | 100 stamina/day | | `.quest` | Coins + Evo Stone Crates (S/A tiers) | 1 per day | | `.event` | Check for active events | Every 3 hours | --- ## Quest System Random daily objectives with tiered rewards. Use `.quest` to view yours. | Tier | Chance | Reward | |---|---|---| | **S-Tier** | 5% | 1 Evo Stone Crate + 10,000 coins | | **A-Tier** | 10% | 2 Evo Stone Crates + 10,000 coins | | **B-Tier** | 20% | 2 Evo Stone Crates + 7,000 coins | | **C-Tier** | 30% | 1 Evo Stone Crate + 2 lootboxes | | **D-Tier** | 35% | 2,000–3,000 coins + 1 lootbox | - Quests auto-track progress as you play - One quest per 24 hours β€” expires if not completed - **Evo Stone Crates** drop evolution stones (10% Gods, 20% Fabled, 30% Legendary, 40% Mythic) --- ## Animal Rarity Quick Reference | Rarity | Drop Rate | Sell | Sacrifice | Level Cap | |---|---|---|---|---| | Common | ~57% | 1 πŸͺ™ | 5 πŸ’Ž | 5 | | Uncommon | ~25% | 3 πŸͺ™ | 10 πŸ’Ž | 5 | | Rare | ~10% | 10 πŸͺ™ | 20 πŸ’Ž | 5 | | Epic | ~5% | 250 πŸͺ™ | 40 πŸ’Ž | 5 | | Mythic | ~2% | 5,000 πŸͺ™ | 150 πŸ’Ž | 10 | | Legendary | ~0.7% | 35,000 πŸͺ™ | 500 πŸ’Ž | 15 | | Fabled | ~0.01% | 200,000 πŸͺ™ | 1,500 πŸ’Ž | 20 | | patron | 0 | β€” | β€” | 30 | | Gods | 0 (shop: 5M πŸͺ™) | 2,500,000 πŸͺ™ | 2,500 πŸ’Ž | 30 | | Boundless | ~0.006% | 5,000,000 πŸͺ™ | 5,000 πŸ’Ž | ∞ | --- ## Gems (Hunt Modifiers) Gems drop during hunts (5% chance) and boost your hunting power: | Gem | Effect | Charges | |---|---|---| | πŸŸ’πŸŸ‘πŸ”΄ Hunting Gem | **Γ—2 animals** per hunt | 10 / 25 / 50 | | πŸ’šπŸ’›β€οΈ Lucky Gem | **+1–1.5% fabled** rarity boost | 10 / 15 / 20 | | πŸ’Ž Gemstone | **+3 animals** per hunt | 20 | - Equip with `.gem equip ` (3 slots max: hunt, lucky, stone) - Hunting Gem + Gemstone stack: 1 β†’ +3 = 4 β†’ Γ—2 = **8 animals per hunt** - ⚠️ **Unequipping a gem destroys it** β€” commit before equipping --- ## Crafting Quick Reference | Output | Input | Animals Needed | Cost | |---|---|---|---| | Epic | 3 Rare | 3 | 5,000 πŸͺ™ | | Mythic | 5 Epic | 5 | 20,000 πŸͺ™ | | Legendary | 3 Mythic | 3 | 70,000 πŸͺ™ | - **Standard craft:** 80–110% random stats - **Diamond craft** (`.craft diamond`): Costs 1 Sacrificial Diamond, needs 1 fewer animal, guarantees **125% max stats** - Buy diamonds: `.buy diamond` (50,000 coins) or find in weapon crates (15% drop) --- ## Weapon Rerolling Spend 700 gems to reroll weapon stats with `.weapon reroll `. - Each reroll adds a random modifier: **-50% to +50%** to your weapon's bonus - Bonuses are **cumulative** β€” keep rolling to push higher - Caps: **-100% min**, **+200% max** (3Γ— weapon stats at max!) - All stats (ATK, DEF, CRIT, MANA, LIFESTEAL) scale with the bonus --- ## Enchantments Special abilities applied to animals. Obtained from weapon crates. | Tier | Notable Enchantments | |---|---| | **Mythic** | Critical (+1.52Γ— damage), Health Point (+25% HP), Reflection (26% reflect), Combat Combo (+8% per stack) | | **Legendary** | Spirit Guard (-24% damage), Mana Tap (restore mana), Resurrection (revive ally), Taunting (force target) | | **Fabled** | Negator (nullify enemy enchants), Time Freeze (skip enemy turns), Mana Whip (5Γ— burst), Healer (14% heal) | - Each enchantment has **50 uses** (per copy) β€” consumed per battle/raid/dungeon/war - Apply: `.enchant ` | Remove: `.enchant keep ` - View all: `.enchants` --- ## Evolution System Animals Mythic+ can evolve into stronger forms. **Requirements:** 1. **2 copies** of the same animal at the same stage 2. An **evolution stone** matching the target rarity (from dungeons/quests) | Rarity | Max Stages | Stat Multiplier | |---|---|---| | Mythic | 1 (β†’ +) | 1.5Γ— | | Legendary | 2 (β†’ + β†’ ++) | 1.5Γ— / 2.0Γ— | | Fabled | 2 (β†’ + β†’ ++) | 1.5Γ— / 2.0Γ— | | Gods | 1 (β†’ +) | 1.5Γ— | Evolved animals also gain **role bonuses** (Tank +HP, Berserker +ATK, Mage +Mana, etc.) --- ## Dungeon Quick Reference Dungeons spawn every **3 hours** with a **3-minute join window**. | Rank | Spawn % | Entry Fee | Min Level | Final-Blow Coin Reward | |---|---|---|---|---| | D | 15% | 1,000 πŸͺ™ | 2 | 5,000 πŸͺ™ | | C | 35% | 2,000 πŸͺ™ | 5 | 10,000 πŸͺ™ | | B | 25% | 3,000 πŸͺ™ | 10 | 20,000 πŸͺ™ | | A | 15% | 4,000 πŸͺ™ | 20 | 40,000 πŸͺ™ | | S | 10% | 5,000 πŸͺ™ | 30 | 100,000 πŸͺ™ | - 3 waves + 1 boss per dungeon, up to 6 players - **Primary source of evolution stones** (one shared stone roll per dungeon, awarded to one clearer) - Wave drops are animals; final blow awards the coin prize --- ## Guild Quick Reference | Action | Requirement | |---|---| | Create guild | 20,000 πŸͺ™ | | Default members | 4 (max 8 with upgrades at 250 πŸ’΅ each) | | Raid | 60,000 guild bank, 5,000/member entry | | War | 3+ members per guild, leader accepts | | Boss | Spawns every 10 hours, despawns after 4h, `.guild boss attack` (10 min cooldown) | | Banner | Buy from leader's coins (5,000–150,000) | --- ## Event Quick Reference Events run every **3 hours**. Three types: | Event | Duration | Mechanic | |---|---|---| | πŸ”₯ Hunt Frenzy | 5 min | +2% fabled drop rate for everyone | | βš”οΈ Battle Frenzy | 15 min | First to 10 battle wins wins prize | | πŸƒ Blackjack Frenzy | 15 min | First to 5 blackjack wins wins prize | Prizes: coins, legendary weapons, legendary animals, fabled profile pictures, fabled animals --- ## Social Commands | Command | Effect | Cooldown | |---|---|---| | `.cookie @user` | Give a friendly cookie | 24 hours | | `.pray @user` | Donate 50–5,000 coins | 1 hour | | `.curse @user` | Drain coins (30% backfire) | 30 min | | `.steal @user` | Steal 200–5,000 coins | 1 min (2h per target) | | `.give @user ` | Transfer coins directly | 3Γ— per 5 hours | | `.pat @user` | Pat someone's head | β€” | | `.hug @user` | Give someone a hug | β€” | | `.kiss @user` | Kiss someone | β€” | | `.slap @user` | Slap someone | β€” | | `.poke @user` | Poke someone | β€” | | `.tickle @user` | Tickle someone | β€” | | `.cuddle @user` | Cuddle someone | β€” | | `.highfive @user` | High-five someone | β€” | | `.wave @user` | Wave at someone | β€” | | `.greet @user` | Greet someone | β€” | | `.bite @user` | Bite someone | β€” | | `.boop @user` | Boop someone's nose | β€” | | `.hold @user` | Hold someone | β€” | | `.handholding @user` | Hold hands with someone | β€” | | `.bully @user` | Bully someone | β€” | | `.punch @user` | Punch someone | β€” | | `.kill @user` | Kill someone | β€” | --- ## Marketplace Trade items with other players in the **#sellers** channel. 1. Switch to seller mode: `.mode seller` (5-min cooldown) 2. List an item: `.player sell ` (2% listing fee) 3. Browse: `.market` or `.market animals/weapons/enchantments/stones` 4. Buy: `.item buy ` **Price range:** -20% to +50% of base value. Evolved animals sell for 60–80% more than base forms. --- ## Lootbox & Crate Contents **Lootbox** (2,000 πŸͺ™ or free from daily/hunts): | Rarity | Chance | |---|---| | Rare | 55% | | Epic | 30% | | Mythic | 12% | | Legendary | 2.4% | | Fabled | 0.3% | **Weapon Crate** (3,000 πŸͺ™ or free from daily/battles): | Drop | Chance | |---|---| | Enchantment | 63% | | Sacrificial Diamond | 15% | | Empty | 15% | | Legendary Weapon | 7% | --- ## Gambling | Game | Command | Max Bet | Cooldown | |---|---|---|---| | Coinflip | `.coinflip ` | 100,000 πŸͺ™ | 5s | | Slots | `.slots ` | 100,000 πŸͺ™ | 10s | | Blackjack | `.blackjack ` | 100,000 πŸͺ™ | 10s | | Lottery | `.lottery ` | β€” | 60s | - Slots: πŸ’πŸ’πŸ’ = 2Γ—, πŸ’ŽπŸ’ŽπŸ’Ž = 5Γ—, 🎰🎰🎰 = 20Γ— jackpot - Blackjack: Natural 21 pays 2.5Γ—, dealer hits until 17 - Lottery: Draws at 5+ unique players or 20 tickets, 15% rake --- ## Key Tips 1. **Win streak is king** β€” daily rewards scale up to 8Γ— at 28+ streak. Don't lose ranked carelessly! 2. **Craft up** β€” 3 Rare β†’ 1 Epic β†’ 5 Epic β†’ 1 Mythic is the progression backbone 3. **Diamond craft** when you have a Sacrificial Diamond β€” guaranteed 125% max stats 4. **Gems matter** β€” equip hunting gems for Γ—2 animals and lucky gems for bonus fabled chance 5. **Guard dogs** β€” always have one active (150 coins) to block 90% of steals 6. **Events** β€” watch for the warning. Hunt Frenzy is free value, Battle/Blackjack Frenzies award huge prizes 7. **Marketplace** β€” evolved animals sell for 60–80% more than base forms 8. **Enchantments** have 50 uses β€” they break permanently when depleted. Don't waste them on easy fights 9. **Guild raids** require 60k in the guild bank β€” deposit regularly 10. **Dungeons** spawn every 3 hours β€” join within 3 minutes or miss it 11. **Quests** β€” S-tier quests give Evo Stone Crates, which are the easiest way to get evolution stones outside dungeons 12. **Weapon rerolls** are cumulative β€” keep pushing toward +200% for 3Γ— weapon stats 13. **Autohunt** β€” use `.autohunt` to hunt while away; upgrade traits with gems for efficiency --- ## Huntbot (Autohunt) Hunt animals automatically while you're away. | Command | What It Does | |---|---| | `.autohunt` | Start a huntbot session | | `.huntresults` | Claim caught animals when session ends | | `.huntbot` | View huntbot status and build | | `.huntbot upgrade ` | Upgrade a trait with gems | **Traits** (max level 50 each): Efficiency (faster hunts), Duration (more animals), Radar (rare chance) - Max session: **8 hours** - Cost: animals_per_session Γ— 10 coins - Upgrade cost: 10 gems Γ— 1.5^(level-1) --- ## Cross-References For detailed system documentation, see: - [hunt.md](hunt.md) β€” Hunting mechanics, autohunt, stamina, gems - [battle.md](battle.md) β€” Combat engine, weapons, enchantments, PvP - [guild.md](guild.md) β€” Guild management, raids, wars, boss fights - [dungeon.md](dungeon.md) β€” Dungeon gates, waves, boss drops, evolution stones - [economy.md](economy.md) β€” Currencies, daily/vote, quests, gambling - [inventory.md](inventory.md) β€” Animals, evolution, crafting, sacrifice/sell - [shop.md](shop.md) β€” Weapon/item shop, gem system, marketplace - [cosmetics.md](cosmetics.md) β€” Profiles, banners, achievements, tiers, auras - [patron.md](patron.md) β€” Cash currency, premium features, patron animals - [sticker.md](sticker.md) β€” Custom sticker upload system - [events.md](events.md) β€” Timed event system and prizes - [commands.md](commands.md) β€” Full command reference - [quests.md](quests.md) β€” Daily quest tiers and Evo Stone Crates ======================================================================== MODULE: GUIDEBOT ======================================================================== # Guide Bot AI Persona & Knowledge Base ## Core Philosophy You are the **Guide Bot** for Advenexus. Your purpose is to take existing game tips and rewrite them to be highly personal, punchy, and contextually relevant to the player's current state. - **Precision**: Give accurate advice based on the loops below. Do not mix mechanics. - **Action-Oriented**: Every tip must end with a clear, specific game command for the player to type (e.g., **.equip **). - **Format**: Max 3 sentences. Max 50 words. Casual, hype, and encouraging tone. --- ## The 4 Core Game Loops ### 1. The Progression & Combat Loop This is how players get stronger. 1. **Hunt**: Players use **.hunt** to catch animals (costs 1 stamina, max 100). 2. **Team Building**: Players check their catches with **.zoo**, then use **.team add ** to form a team of up to 3 different species. 3. **Gearing Up**: Players open crates with **.crate**, find weapon IDs with **.weapon**, and arm their team with **.equip **. **An unarmed team is useless.** 4. **Battling**: Once armed, players use **.battle** or **.battle ranked** to fight, earn coins, and gain ELO. ### 2. The Rarity & Power Spike Loop Power is exponential in this game. 1. **Rarities**: Power scales massively: Common β†’ Uncommon β†’ Rare β†’ Epic β†’ Mythic β†’ Legendary β†’ Fabled. 2. **Upgrades**: If a player pulls a Rare (~10% drop) or Epic (~5% drop), they must immediately add it to their team and equip a weapon to it. 3. **Lootboxes**: Typing **.lootbox** gives a random animal roll. 4. **Enchantments**: Enchantments drop from crates and stack with weapons. They are applied with **.enchant **. ### 3. The Daily Resource & Streak Loop How players maintain their economy. 1. **Win Streaks**: Winning 3 battles in a row activates a multiplier (up to 8x). Players should build this streak *before* claiming their daily reward. 2. **Daily Claim**: **.daily** gives free coins, a Lootbox, and a Weapon Crate every 24 hours. 3. **Quests**: **.quest** reveals daily objectives that grant bonus coins and crates for playing normally. 4. **Stamina**: Hunts use 1 stamina. Stamina refills +10 every 2 hours. Players should hunt in bursts so stamina is never sitting capped at 100. ### 4. The Economy & Risk Loop Managing inventory and wealth. 1. **Wealth Protection**: Holding >5,000 coins attracts thieves. Suggest **.buy guard dog** to auto-block 90% of steal attempts. 2. **Sacrificing**: Duplicate or weak animals should be sacrificed for gems using **.sacrifice **. 3. **Gems**: Gems boost hunt luck and are equipped into slots using **.gem equip **. --- ## Level 1–4 Newbie Context For new players, you MUST provide explicit, step-by-step guidance. Do not assume they know how the game works. ### Common Mistakes - Typing `` literally instead of a number. Explain that `.weapon` shows IDs (e.g., ID: 12). - Forgetting the dot (`.`) before commands. Remind them all commands start with a dot. - Trying to add duplicates. Remind them they need 3 *different* species for a full team. - Fighting without weapons. Remind them to equip a weapon from their `.crate`. ### Safe Practice Opponents For players who just started battling, suggest fighting practice bots: - **.battle @danil** - **.battle @hokage** These bots have no ELO risk but still give coin rewards and build win streaks. ### What Commands Look Like - `.weapon` output looks like: `[ID: 15] Iron Sword (Common)` - Equipping it looks like: `.equip 15 Wolf` - Adding to team looks like: `.team add Wolf` --- ## Adaptive Context Triggers Look at the player's snapshot to customize the tip: - **Team Size < 3**: Emphasize **.hunt** to catch more species, then **.team add **. - **Unequipped Weapons**: If they have weapons but unequipped animals, emphasize **.weapon** and **.equip **. - **Unopened Boxes**: If they have lootboxes or crates, hype them up to open them with **.lootbox** or **.crate**. - **On a Win Streak**: Hype their recent wins and remind them to keep battling to boost their **.daily** multiplier. - **Just Lost**: Tell them to check **.zoo** for stronger animals, or open a **.crate** for better weapons. --- ## Strict Hallucination Blacklist **Rule of Thumb**: ONLY introduce features if the original tip explicitly mentions them. Otherwise, NEVER invent or suggest the following mid/late-game features to early-game players: - Joining/creating Guilds, Raids, Guild Wars - Crafting (**.craft**) or Evolving (**.evolve**) - The Player Marketplace (selling/buying from others) - Autohunt (**.huntbot**) - Dungeons (**.dungeon**) or the Tower (**.tower**) - Prestiging or resetting - Cosmetics (**.profile shop**) ======================================================================== MODULE: GUILD ======================================================================== # Guilds, Raids, Wars, and Guild Bosses ## Overview Guilds are persistent player groups with a shared bank, leveling, raid/war PvP, cosmetic banners, achievement tracking, and a rotating global guild boss. The live code uses one guild core system, but it exposes **three distinct gameplay loops**: 1. **Guild management** - create, invite, join, upgrade, deposit, withdraw, banner management 2. **Guild raids / guild wars** - PvP between guilds 3. **Guild boss** - a shared PvE boss attacked by guild members across the server ## Commands ### Guild core | Command | What it does | Notes | |---|---|---| | `.guild create ` | Creates a guild | Costs 20,000 coins | | `.guild info` | Shows guild summary | UI-rich response | | `.guild members` | Lists members | Shows current size and cap | | `.guild invite @user` | Invites a player | Leader only | | `.guild accept` | Accepts latest guild invite | Target guild must still have room | | `.guild reject` | Rejects latest guild invite | - | | `.guild leave` | Leaves the guild | Solo leader leaving disbands the guild | | `.guild kick @user` | Removes a member | Leader only | | `.guild deposit ` | Adds coins to guild bank | Any member | | `.guild withdraw ` | Splits a withdrawal evenly across all members | Leader only | | `.guild upgrade` | Adds +1 guild slot | Costs 250 Cash | | `.guild achievements` | Shows guild achievement unlocks | Reads `guild_achievements` | | `.guild leaderboard` | Shows top guilds | Sorted by season points -> weekly points -> raid points -> level | | `.guild perk status` | Shows currently active guild stat perk | - | | `.guild perk buy ` | Activates a 12h combat stat perk | Leader only, bank coins | ### Guild wars | Command | What it does | Notes | |---|---|---| | `.guild war @guildname [@member1 @member2 ...]` | Sends a war challenge | Leader only | | `.guild war accept` | Accepts the pending war challenge | Defender leader only | | `.guild war decline` | Declines the pending war challenge | Defender leader only | ### Guild raids and banners | Command | What it does | Notes | |---|---|---| | `.raid @guildname` | Starts a guild raid | Leader only | | `.banner shop` | Shows banner shop | - | | `.banner buy ` | Buys a guild banner | Leader only; paid by leader's coins | | `.banner equip ` | Equips an owned banner | Leader only | ### Guild boss | Command | What it does | Notes | |---|---|---| | `.guild boss` | Shows boss status or time until next spawn | - | | `.guild boss attack` | Attacks the active guild boss | 10-minute cooldown per player | ## Core Mechanics ### Creation and membership - Guild creation cost: **20,000 coins**. - Guild names: - cannot contain spaces, - max length **24**, - must be unique case-insensitively. - Default capacity: **4 members**. - Maximum capacity: **8 members**. - Each `.guild upgrade` costs **250 Cash** and increases cap by **1**. ### Leaving and disbanding - A non-leader can leave freely with `.guild leave`. - A leader **cannot** leave while other members remain. - If the leader is the only member and uses `.guild leave`, the guild is disbanded. - There is **no separate `.guild disband` command** in the live command handler. ### Guild bank - Any member may deposit coins. - Only the leader may withdraw. - Withdrawals are split evenly among all current members: ```text perMember = floor(requestedAmount / memberCount) actualWithdrawn = perMember * memberCount ``` Any remainder from floor division is not distributed. Withdrawals are blocked if the requested amount would dip below `guild_raid_locks.locked_coins` for that guild. ### Guild leveling Guild XP thresholds are: | Next Level | Total XP Threshold | |---|---:| | 2 | 500 | | 3 | 1,500 | | 4 | 4,000 | | 5 | 9,000 | | 6+ | `9,000 + (level - 5) * 5,000` | XP gains from current live systems: - successful guild raid reward path: **+300 guild XP** - guild boss top-3 guild rewards: **+600 / +400 / +250 guild XP** ## Guild Raids ### Requirements The attacking guild must have: - at least **2 members** - at least **60,000 bank coins** before fees - a leader starting the raid The defending guild must also have: - at least **2 members** - at least **60,000 bank coins** ### Entry fee The attacker's bank pays a burned entry fee of: ```text 5,000 coins * attacker member count ``` The code also requires the attacker's bank to still remain at or above the raid minimum after covering that fee. ### Cooldowns and protection - General raid cooldown for both guilds: **2 hours** - Same attacker -> defender pair protection: **3 hours** ### Raid simulation Guild raid combat builds a large merged team from each guild's active members. Rules: - up to **3 animals per member** are used - each guild can field up to **18 animals** total - equipped weapons and animal enchantments are carried into the merged raid team - the real battle engine is used to simulate the result - the UI receives **10 condensed guild-level snapshots** rather than every internal turn ### Raid rewards If the attacker wins, the winner can steal up to: ```text min(50,000, loser.bank_coins, winnerRemainingDailyCap) ``` Winner rewards on successful payout: - up to **50,000 bank coins** stolen - **+100 raid points** - **+50 season points** - **+50 weekly points** - **+300 guild XP** ### Raid reward cap by winner member count The code calculates the practical cap from guild size: | Winner member count | Cap used by reward logic | |---|---:| | 1-10 | 50,000 | | 11-25 | 120,000 | | 26-50 | 250,000 | | 51+ | 400,000 | The tracking table is `guild_daily_raid_limits`, so the current implementation treats this as a daily-style cap. ### Enchant usage After a guild raid, the server consumes enchantment usage for **all raid participants on both sides**. ## Guild Wars ### Requirements - Only the leader can challenge or accept. - Both guilds need at least **3 members**. - War challenge lifetime: **2 minutes**. - The attacker can specify participants or let the system auto-pick. ### Participant limits - Minimum attacker picks: **3** - Maximum picks: **8** - If no picks are supplied, the code uses the first available guild members up to 8. ### War flow Guild Wars use `simulateGuildWar()` and run as a queued elimination sequence: 1. attacker roster is chosen, 2. defender accepts, 3. members duel in order, 4. surviving power carries forward through the war, 5. war ends when one guild runs out of participants. ### War rewards On war end: - winner guild: **+150 season points**, **+150 weekly points**, `war_wins + 1` - loser guild: `war_losses + 1` ## Guild Boss ### Boss rotation The boss scheduler rotates through this fixed list: | Order | Boss | Base HP | Icon | |---|---|---:|---| | 1 | Stone Colossus | 750,000 | `boss1.svg` | | 2 | Infernal Warlord | 1,350,000 | `boss2.svg` | | 3 | Void Serpent | 2,250,000 | `boss3.svg` | | 4 | Shadow Titan | 3,300,000 | `boss4.svg` | | 5 | World Eater | 4,500,000 | `boss5.svg` | ### Spawn timing - Boss respawn interval after a kill or despawn: **10 hours** - Boss despawn timer: **4 hours** after spawn (if not killed within 4 hours, boss flees) - Scheduler check frequency: **every 10 minutes** - If no boss row exists, the first boss is created immediately. - Boss spawn announcements appear in chat channels with a visual card. ### HP scaling Boss HP is scaled from total guild participation on the server: ```text scaledHp = baseHp + (count(distinct guild_members.user_id) * 50,000) ``` ### Attack flow `.guild boss attack`: - requires the attacker to be in a guild, - requires an active boss with `current_hp > 0`, - uses the shared cooldown key `guild_boss_attack`, currently **10 minutes** per player. The attack simulation: - builds a combatant from the player's active team, - includes equipped weapon stats and reroll bonuses, - runs a short skirmish against the boss, - applies the resulting damage to the singleton boss row, - updates both per-player and per-guild damage leaderboards. - Boss cards display top 5 guilds by total damage in real-time. ### Guild boss rewards on death #### Guild rewards Top 3 guilds by total damage receive: | Rank | Bank Coins | Raid Points | Guild XP | |---|---:|---:|---:| | 1 | 350,000 | 200 | 600 | | 2 | 200,000 | 120 | 400 | | 3 | 100,000 | 80 | 250 | Every contributing guild also gets: - **+100 season points** - **+100 weekly points** ### Enchant usage After each boss attack, the attacker's enchantment usage is consumed once. ## Guild Perks Guild leaders can spend coins from the guild bank to activate temporary (12 hour) combat stat multipliers for all members. - **Common Perk**: Costs **100,000 coins**, gives **+5%** HP/ATK/DEF/SPD. - **Rare Perk**: Costs **250,000 coins**, gives **+10%** HP/ATK/DEF/SPD. The perks overwrite each other, meaning a rare perk replaces an active common perk (but resets the duration to 12 hours). ## Banners ### Banner prices | Banner | Price | |---|---:| | `banner1` | 5,000 | | `banner2` | 8,000 | | `banner3` | 12,000 | | `banner4` | 20,000 | | `banner5` | 30,000 | | `banner6` | 40,000 | | `banner7` | 50,000 | | `banner8` | 60,000 | | `banner9` | 70,000 | | `banner10` | 80,000 | | `banner11` | 90,000 | | `banner12` | 100,000 | | `banner13` | 110,000 | | `banner14` | 120,000 | | `banner15` | 130,000 | | `banner16` | 150,000 | Banner purchases are paid by the **leader's personal coins**, not guild bank funds. ## Database / Storage Details ### Core guild tables - `guilds` - `guild_members` - `guild_invites` - `guild_raid_history` - `guild_achievements` - `guild_daily_raid_limits` - `guild_pair_daily_rewards` - `guild_banners_owned` - `guild_raid_locks` ### Guild boss tables - `guild_boss` - `guild_boss_damage` - `guild_boss_guild_damage` ### Important guild fields - `guilds.bank_coins` - `guilds.raid_points` - `guilds.season_points` - `guilds.weekly_points` - `guilds.banner_id` - `guilds.last_raid_at` - `guilds.max_members` - `guilds.war_wins` - `guilds.war_losses` ## Strategic Tips / Balance Notes - Raid with a full or near-full active roster when possible, because merged team size directly affects your raid power. - Guild wars reward leaderboard prestige, while guild raids are the main direct bank-income PvP tool. - Leader withdrawals should be planned carefully because floor division can waste small remainders. - Guild boss rewards are damage-rank based for guilds, so regular coordinated attacks matter even if your guild is unlikely to land the final blow. - Guild bosses despawn after 4 hours if not killed, so timing coordinated attacks is crucial. - Use `.guild boss` to check boss status and time remaining before despawn. - There is no chat command to disband a populated guild: the leader must reduce membership first, then leave. ======================================================================== MODULE: HUNT ======================================================================== # Hunt System ## Overview The hunt system is the core animal-catching mechanic in Advenexus. Players spend coins and stamina to hunt wild animals of varying rarities. Hunts can also drop gems and lootboxes. All caught animals go into the player's zoo. --- ## Commands | Command | Description | |---|---| | `.hunt` | Catch a wild animal (costs coins + 1 stamina) | | `.zoo` | View all animals you own, grouped by rarity | | `.dex ` | View detailed stats for an owned animal | | `.sell ` | Sell an animal for coins | | `.sell ` | Sell multiple animals by name | | `.sell ` | Bulk sell all animals of a rarity tier (e.g. `.sell common`) | | `.sacrifice ` | Sacrifice an animal for gems | | `.sacrifice ` | Sacrifice multiple animals by name | | `.sacrifice ` | Bulk sacrifice all animals of a rarity tier | | `.rename \| ` | Rename an animal (max 20 characters, alphanumeric + space/dash/underscore) | | `.tier` | Show all animals grouped by rarity tier | | `.tier ` | Show animals for a specific rarity tier | | `.evolve ` | Evolve an animal to its next stage (requires duplicate + stone for mythic+) | --- ## Hunt Cost | Player Level | Hunt Cost | |---|---| | 1–5 | Free (0 coins) | | 6–15 | 1 coin | | 16+ | 2 coins | - Each hunt also costs **1 stamina** (hunt stamina). --- ## Stamina - Max stamina: **100 hunt** / **100 battle** (separate pools) - Refills daily at **11 PM UTC** (full reset to 100) - When stamina hits 0, you cannot hunt until the next refill --- ## Hunt Cooldown - **15 seconds** between hunts --- ## Rarity Tiers | Rarity | Drop Rate | XP | Sell Value (πŸͺ™) | Sacrifice Value (πŸ’Ž) | Zoo Points | Level Cap | |---|---|---|---|---|---|---| | Common | ~57% | 2 | 1 | 5 | 2 | 5 | | Uncommon | ~25% | 5 | 3 | 10 | 5 | 5 | | Rare | ~10% | 20 | 10 | 20 | 10 | 5 | | Epic | ~5% | 400 | 250 | 40 | 250 | 5 | | Mythic | ~2% | 1,000 | 5,000 | 150 | 2,000 | 10 | | Legendary | ~0.7% | 2,000 | 35,000 | 500 | 5,000 | 15 | | Fabled | ~0.01% | 5,000 | 200,000 | 1,500 | 10,000 | 20 | | patron | 0% (special) | 10,000 | 0 | 0 | 12,000 | 30 | | Gods | 0% (shop only) | 15,000 | 2,500,000 | 2,500 | 15,000 | 30 | | Boundless | ~0.006% | 15,000 | 5,000,000 | 5,000 | 30,000 | ∞ | > **Note:** Gods-tier animals are **not huntable** β€” they can only be obtained via the shop. patron-tier animals are exclusive to patron supporters. --- ## Drops During Hunts ### Gem Drops - **5% chance** per hunt to find a random gem - Gems are added to inventory ### Lootbox Drops - **10% chance** per hunt to find a lootbox - Max **3 lootboxes per day** (UTC midnight reset) --- ## Gems (Hunt Modifiers) Gems are equipped and consumed per-charge during hunts. Three categories: | Gem | Effect | Charges (by tier) | |---|---|---| | Hunting Gem (πŸŸ’πŸŸ‘πŸ”΄) | **x2 animals** per hunt | 10 / 25 / 50 | | Lucky Gem (πŸ’šπŸ’›β€οΈ) | **+2% fabled/boundless** rarity boost | 10 / 15 / 20 | | Gemstone (πŸ’Ž) | **+3 animals** per hunt | 20 | - Hunting Gem + Gemstone stack: base 1 β†’ +3 (stone) = 4 β†’ x2 (hunt gem) = **8 animals per hunt** - Lucky boost stacks with Hunt Frenzy event bonus --- ## Hunt Frenzy - A global event that adds **+2% rarity boost** to all hunts - Stacks with Lucky Gem boost - Set via `global.huntFrenzyActive` --- ## Rare Drop Broadcasts When a player catches **Legendary, Fabled, Gods, or Boundless** animals: - A server-wide broadcast is sent - Confetti animation triggers on the client | Rarity | Icon | Confetti Intensity | |---|---|---| | Legendary | ⭐ | Low | | Fabled | πŸ”₯ | Medium | | Gods | πŸ‘‘ | Medium | | Boundless | ✨ | Medium | --- ## Evolution System Animals Mythic+ can evolve through stages. Evolution requires: 1. **2 copies** of the same animal at the same evolution stage 2. An **evolution stone** matching the target rarity (mythic, legendary, fabled, gods) ### Evolution Stones Required | Target Rarity | Stone Needed | |---|---| | Mythic | 🧿 Mythic Stone | | Legendary | ⭐ Legendary Stone | | Fabled | πŸ”₯ Fabled Stone | | Gods | πŸ‘‘ Gods Stone | > Evolution stones drop from **Dungeon Raids**. ### Max Evolution Stages by Rarity | Rarity | Max Stages | Suffix Labels | |---|---|---| | Mythic | 1 (base β†’ +) | Mythic, Mythic+ | | Legendary | 2 (base β†’ + β†’ ++) | Legendary, Legendary+, Legendary++ | | Fabled | 2 (base β†’ + β†’ ++) | Fabled, Fabled+, Fabled++ | | Gods | 1 (base β†’ +) | Gods, Gods+ | | Boundless | 0 | No evolution | ### Evolution Stat Multiplier | Stage | Global Multiplier | |---|---| | 0 (base) | 1.0x | | 1 (+) | 1.5x | | 2+ (++) | 2.0x | --- ## Animal Roles (Mythic+) Mythic and higher tier animals have combat roles that grant bonus stats: | Role | Boosted Stat | Bonus by Stage (0/1/2) | |---|---|---| | Tank | HP | +30% / +40% / +50% | | Mage | Mana | +50% / +60% / +70% | | Berserker | ATK | +40% / +50% / +60% | | Armored | DEF | +50% / +60% / +70% | | Speed | SPD | +30% / +40% / +50% | --- ## Level Scaling - All stats scale by **+10% per level** (level 1 = 1.0x, level 2 = 1.1x, etc.) - XP required per level: `floor(100 Γ— level^1.8)` --- ## Autohunt (Huntbot) An automated hunting system that hunts animals over time while you're away. ### Commands | Command | Description | |---|---| | `.autohunt` | Start a huntbot session | | `.huntresults` | Claim animals when session ends | | `.huntbot` | View huntbot status and build | | `.huntbot upgrade ` | Upgrade a trait with gems | ### How It Works 1. Pay coins to start a session (cost = animals Γ— 10 πŸͺ™) 2. Huntbot rolls animals in the background 3. Claim results with `.huntresults` when the session timer ends ### Traits (Max Level: 50 each) | Trait | Effect | Upgrade Cost | |---|---|---| | Efficiency | Faster hunt speed (10s β†’ 1s per animal) | 10 πŸ’Ž Γ— 1.5^(level-1) | | Duration | Longer sessions (more animals) | 10 πŸ’Ž Γ— 1.5^(level-1) | | Radar | Slightly better rare chance | 10 πŸ’Ž Γ— 1.5^(level-1) | - Base animals per session: `5 + (efficiency + duration + radar) Γ— 2` - Max session duration: **8 hours** (hard cap) - Radar boost is tiny: `level Γ— 0.001%` per level ### Session Cost - `animals_per_session Γ— 10 coins` --- ## Sell / Sacrifice Rules - Animals **in your team** (team_slot > 0) or **equipped** cannot be sold or sacrificed - Animals listed on the marketplace cannot be used for evolution - Bulk operations work up to **500** at a time - Selling gives **coins**; sacrificing gives **gems** --- ## Player XP & Level-Up Rewards Catching animals gives XP. Leveling up gives coins, lootboxes, and crates: | Level Range | Coin Reward | Lootboxes | Weapon Crates | |---|---|---|---| | 1–5 | 200 Γ— 1.5^(level-1) | 2 | 0 | | 6–10 | 200 Γ— 1.5^(level-1) | 2 | 1 | | 11–15 | 5,000 + (level-10) Γ— 2,000 | 2 | 3 | | 16–20 | 5,000 + (level-10) Γ— 2,000 | 3 | 4 | | 21–25 | 5,000 + (level-10) Γ— 2,000 | 4 | 5 | | 30–35 | 35,000 + (level-25) Γ— 500 | 5 | 6 | | 40–45 | 35,000 + (level-25) Γ— 500 | 6 | 7 | | 46+ | 35,000 + (level-25) Γ— 500 | 7 | 8 | --- ## Inventory Overflow - Each player has a **max inventory** (default 100 slots) - Weapons count toward inventory capacity - If inventory is full, overflow items go to **temporary storage** (expires in **1 hour**) --- ## Edge Cases - Hunting with 0 stamina is blocked with a clear message - Hunting with insufficient coins is blocked - Selling/sacrificing animals in your team slot is prevented - Rename has character restrictions: alphanumeric, spaces, dashes, underscores only (max 20 chars) - Gods-tier animals cannot be hunted β€” shop purchase only - Boundless animals have **no level cap** (Infinity) ======================================================================== MODULE: INVENTORY ======================================================================== # Inventory & Animal Management ## Overview The inventory system manages all player-owned items: animals, weapons, enchantments, gems, evolution stones, materials, lootboxes, crates, and profile pictures. Animals have a full lifecycle including catching, leveling, renaming, evolving, sacrificing, selling, and crafting into higher rarities. --- ## Commands | Command | Description | |---|---| | `.inventory` / `.inv` | View all owned items | | `.zoo` | View your animal collection | | `.zoo @user` | View another player's zoo | | `.dex ` | View detailed stats for a specific animal you own | | `.tier [rarity]` | Browse all animal tiers and drop rates | | `.rename \| ` | Rename an animal (max 20 chars) | | `.sacrifice ` | Sacrifice an animal for πŸ’Ž gems | | `.sacrifice ` | Sacrifice multiple copies | | `.sacrifice ` | Bulk sacrifice all animals of a rarity | | `.sell ` | Sell an animal for πŸͺ™ coins | | `.sell ` | Sell multiple copies | | `.sell ` | Bulk sell all animals of a rarity | | `.craft ` | Craft a higher-rarity animal from lower ones | | `.craft diamond` | Diamond craft β€” fewer animals, max stats | | `.lootbox` | Open a lootbox | | `.crate` | Open a weapon crate | | `.enchants` | View all enchantments and owned status | | `.get items` | Claim items from temporary overflow storage | --- ## Animal Rarity Values | Rarity | Drop Rate | Sell Value | Sacrifice Value | Zoo Points | XP | Shop Price | |---|---|---|---|---|---|---| | Common | 100 | 1 πŸͺ™ | 5 πŸ’Ž | 2 | 2 | β€” | | Uncommon | 25 | 3 πŸͺ™ | 10 πŸ’Ž | 5 | 5 | β€” | | Rare | 10 | 10 πŸͺ™ | 20 πŸ’Ž | 10 | 20 | β€” | | Epic | 5 | 250 πŸͺ™ | 40 πŸ’Ž | 250 | 400 | β€” | | Mythic | 2 | 5,000 πŸͺ™ | 150 πŸ’Ž | 2,000 | 1,000 | 10,000 πŸͺ™ | | Legendary | 0.7 | 35,000 πŸͺ™ | 500 πŸ’Ž | 5,000 | 2,000 | 75,000 πŸͺ™ | | Fabled | 0.04 | 200,000 πŸͺ™ | 1,500 πŸ’Ž | 10,000 | 5,000 | β€” | | patron | 0 | 0 πŸͺ™ | 0 πŸ’Ž | 12,000 | 10,000 | β€” | | Gods | 0 | 2,500,000 πŸͺ™ | 2,500 πŸ’Ž | 15,000 | 15,000 | 5,000,000 πŸͺ™ | | Boundless | 0.06 | 5,000,000 πŸͺ™ | 5,000 πŸ’Ž | 30,000 | 15,000 | β€” | --- ## Base Stats by Rarity | Rarity | HP | ATK | DEF | SPD | Mana | |---|---|---|---|---|---| | Common | 80 | 10 | 5 | 12 | 50 | | Uncommon | 120 | 20 | 10 | 16 | 80 | | Rare | 250 | 50 | 30 | 25 | 150 | | Epic | 500 | 90 | 60 | 40 | 250 | | Mythic | 1,200 | 300 | 150 | 100 | 350 | | Legendary | 2,500 | 600 | 300 | 200 | 500 | | Fabled | 5,000 | 1,200 | 600 | 400 | 800 | | patron | 10,000 | 2,500 | 1,100 | 1,000 | 1,300 | | Gods | 10,000 | 2,500 | 1,200 | 800 | 1,200 | | Boundless | 20,000 | 5,000 | 2,500 | 1,500 | 2,000 | - **Level scaling:** +10% per level to all stats - Individual animals may have custom baseStats that override tier defaults --- ## Level Caps | Rarity | Max Level | |---|---| | Common–Epic | 5 | | Mythic | 10 | | Legendary | 15 | | Fabled | 20 | | patron | 30 | | Gods | 30 | | Boundless | ∞ | --- ## Evolution System Animals of mythic+ rarity can evolve through stages, gaining new forms and stat bonuses. ### Evolution Chains - **1-stage chains** (β†’ +): Minotaur, Centaur, Ghost, Werewolf, Knight, Anubis, Nyx, The Presence, Zeus, Hades - **2-stage chains** (β†’ + β†’ ++): Wolf, Lich, Grim, Revenant, Golem, Leviathan, Medusa, Ghidorah, Oracle, Godzilla ### Evolution Limits | Rarity | Max Stage | |---|---| | Mythic | 1 (+) | | Legendary | 2 (++) | | Fabled | 2 (++) | | Gods | 1 (+) | | patron | 0 (no evolution) | | Boundless | 0 (no evolution) | ### Role Bonuses Evolved animals gain role-based stat bonuses: | Role | Boosted Stat | Stage 0 | Stage 1 | Stage 2 | |---|---|---|---|---| | Tank | HP | +30% | +40% | +50% | | Mage | Mana | +50% | +60% | +70% | | Berserker | ATK | +40% | +50% | +60% | | Armored | DEF | +50% | +60% | +70% | | Speed | SPD | +30% | +40% | +50% | --- ## Zoo - Shows all owned animals grouped by rarity tier - Display order: Boundless β†’ Gods β†’ patron β†’ Fabled β†’ Legendary β†’ Mythic β†’ Epic β†’ Rare β†’ Uncommon β†’ Common - Shows: species name, icon, count, max level - Total zoo points calculated from all owned animals - Zoo points contribute to leaderboard score --- ## Dex (Animal Details) Shows detailed information for a specific **owned** animal: - Name, rarity, evolution label (e.g., "Legendary+") - Full stats: HP, ATK, DEF, SPD, Mana - Level, XP, XP needed for next level - Evolution chain with current stage highlighted - Equipped weapon and enchantment (if any) - Must own the animal to view it (otherwise: "πŸ”’ You have not discovered this creature yet") --- ## Rename - **Syntax:** `.rename | ` - Max 20 characters - Allowed characters: `a-z A-Z 0-9 spaces _ -` - Matches by name (case-insensitive) --- ## Sacrifice Converts animals into πŸ’Ž gems. Animals must be: - **Not in any team** (team_slot = 0) - **Not equipped** (equipped = 0) **Modes:** - `.sacrifice ` β€” sacrifice 1 animal - `.sacrifice ` β€” sacrifice N copies (max 500) - `.sacrifice ` β€” bulk sacrifice all animals of that rarity --- ## Sell Converts animals into πŸͺ™ coins. Same restrictions as sacrifice (not in team, not equipped). **Modes:** - `.sell ` β€” sell 1 animal - `.sell ` β€” sell N copies (max 500) - `.sell ` β€” bulk sell all animals of that rarity --- ## Crafting Combines lower-rarity animals + coins into a random higher-rarity animal. ### Recipes | Output | Input Rarity | Animals Needed | Coin Cost | |---|---|---|---| | Epic | Rare | 3 | 5,000 πŸͺ™ | | Mythic | Epic | 5 | 20,000 πŸͺ™ | | Legendary | Mythic | 3 | 70,000 πŸͺ™ | ### Standard Craft - Sacrificed animals are destroyed (lowest HP first) - Output animal is a random base form of the target rarity - Stats: **80%–110%** of tier base stats (random roll) ### Diamond Craft (`.craft diamond`) - Requires 1 πŸ’  Sacrificial Diamond (consumed) - **1 fewer animal** required (minimum 1) - Stats: **125%** of tier base stats (guaranteed max) - Animals in teams or marketplace listings cannot be used --- ## Enchantment Usage System Enchantments have a **limited usage** system: - Each enchantment copy provides **50 uses** - Stacking: 2 copies = 100 uses, 3 copies = 150 uses, etc. - **1 use consumed per battle/raid/dungeon/war** for each equipped enchantment - When usage reaches 0: enchantment is removed from all animals/weapons and deleted from inventory - Used enchantments **cannot be sold** on the marketplace - Equipped enchantments cannot be sold unless you have duplicate copies --- ## Inventory Capacity - **Default capacity:** 100 items - Items tracked: gems, enchantments, lootboxes, crates, evolution stones, materials - Each **weapon** also counts as 1 capacity slot - When full, new items go to **temporary storage** - Use `.get items` to claim from temp storage when space opens - Temp storage items have an expiry time --- ## Inventory Categories | Category | Contents | |---|---| | Gems | Hunting gem, Lucky gem, Gemstone | | Enchantments | EN01–EN15 (with usage tracking) | | Weapons | All owned weapons (top 20 shown) | | Lootboxes | Openable containers with random animals | | Crates | Openable containers with enchantments/weapons/diamonds | | Evolution Stones | Mythic, Legendary, Fabled, Gods stones | | Materials | Sacrificial Diamond (SDMND) | | Profiles | Owned profile pictures | --- ## Edge Cases - Animals in a team cannot be sold, sacrificed, or used in crafting - Animals listed on marketplace cannot be used in crafting - Renaming only changes the display name β€” the `animal_key` stays the same - Bulk sacrifice/sell uses rarity names as arguments (e.g., `.sacrifice common`) - Dex lookup matches by display name, case-insensitive - Zoo shows aggregated species counts β€” individual animals are not listed separately - Crafting always produces base forms (stage 0), never evolved forms - Diamond craft consumes the Sacrificial Diamond from inventory ======================================================================== MODULE: MARKETPLACE ======================================================================== # Marketplace and Trade Modes ## Overview The marketplace is the game's player-to-player listing system. Selling is intentionally gated behind **Seller Mode**, while buying remains available in both modes. Listings are stored in `marketplace_listings`, require an upfront listing fee, and apply a burn tax when sold. This system covers: - `.mode seller` / `.mode adventure` - `.market` browsing and filters - `.player sell ` listings - `.item buy ` purchases - `.market cancel ` cancellations ## Commands | Command | What it does | Notes | |---|---|---| | `.mode` | Shows current mode and the switch rules | Works in normal channels | | `.mode seller` | Enables marketplace selling | 5-minute cooldown between mode changes | | `.mode adventure` | Turns off selling mode | Buying still remains possible | | `.market` | Shows the latest 30 active listings | `#sellers` / marketplace channel only | | `.market animals` | Filters to animal listings | Same pattern for `weapons`, `enchantments`, `stones` | | `.market mine` | Shows your 20 most recent listings | Includes sold/cancelled history entries too | | `.market cancel ` | Cancels one of your active listings | Returns escrowed stackables | | `.player sell ` | Creates a listing | Requires Seller Mode unless invoked by the marketplace modal UI | | `.item buy ` | Buys an active listing | Buyer cannot buy their own listing | ## Channel / Mode Rules ### Channel restrictions The marketplace command set is only allowed in the marketplace channel category (`#sellers` / `marketplace`): Allowed there: - `.market` - `.player sell` - `.item buy` - `.money` / `.balance` - `.inventory` / `.inv` - `.zoo` - `.mode` - `.help` / `.commands` ### Seller Mode The player's mode is stored on `users.user_mode`. Rules: - default mode is `adventure` - switching has a **5-minute cooldown** - `seller` mode is required for `.player sell ...` - `adventure` mode disables selling, but players can still buy listings ## Listing Fees and Taxes ### Listing fee Every listing charges an upfront fee equal to: ```text max(1, floor(price * 0.02)) + 500 ``` This fee is paid immediately by the seller and is **not refunded** on cancellation. ### Sale tax When a listing sells: ```text tax = max(1, floor(price * 0.05)) sellerProceeds = price - tax ``` The tax is burned and the seller receives the remaining 95% (rounded down by the tax calculation). ## Supported Listing Types The marketplace supports these item types: - `animal` - `weapon` - `enchantment` - `evolution_stone` ## Price Range Rules All listings must stay within the allowed price range: ```text min = floor(basePrice * 0.80) max = floor(basePrice * 1.50) ``` ### Animal base pricing Animals use their rarity's `sellValue` from `data/animals.js`, then apply an evolution multiplier: - stage 0: base price - stage 1: `base * 1.60` - stage 2+: `base * 1.80` Commonly relevant base prices: | Rarity | Base Sell Value | |---|---:| | Mythic | 7,000 | | Legendary | 40,000 | | Fabled | 200,000 | | Gods | 1,500,000 | | Ascendants | 3,000,000 | | Boundless | 3,000,000 | | Infinity | 10,000,000 | ### Weapon base pricing Weapons use their shop `price` directly. ### Enchantment base pricing | Tier | Base Price | |---|---:| | Mythic | 10,000 | | Legendary | 30,000 | | Fabled | 50,000 | ### Evolution stone base pricing | Stone | Base Price | |---|---:| | Mythic | 15,000 | | Legendary | 30,000 | | Fabled | 60,000 | | Gods | 100,000 | ## Listing Rules by Item Type ### Animals Animal listings require: - owned animal match by exact name/key, - no active duplicate listing for that instance, - not currently in a team, - not already marketplace listed, - not trade locked. Additional animal rules: - animals below **Mythic** rarity cannot be listed, - listing an animal clears `equipped=0` and `team_slot=0`, - listed animals are marked `marketplace_listed=1`. ### Weapons Weapon listings require: - an owned **unequipped** instance of that weapon type, - no active listing already tied to that weapon instance. Weapons keep their existing instance data when sold, including reroll bonuses and enchantments, because ownership is transferred on the same row. ### Enchantments Enchantment listings require: - at least one owned copy in inventory, - the enchantment is not "used" below full stacked usage, - if it is equipped anywhere, the seller must have duplicates. Current sell restrictions from `canSellEnchantment()`: - used enchantments (`usage < quantity * 50`) cannot be sold, - equipped enchantments cannot be sold unless quantity > 1. ### Evolution stones A player must own at least one copy in inventory. The listed copy is escrowed out of inventory immediately. ## Buy Flow When a listing is purchased: 1. buyer coins are deducted, 2. listing status changes from `active` to `sold`, 3. seller is credited with `price - tax`, 4. the underlying item is transferred. ### Animal purchase behavior Animals are heavily normalized on purchase: - owner changes to the buyer, - `equipped=0`, `team_slot=0`, `marketplace_listed=0`, `trade_locked=0`, - level resets to **1**, - XP resets to **0**, - stats are recalculated to fresh stage-appropriate level 1 values. ### Weapon purchase behavior Weapons are transferred as-is: - owner changes, - `equipped=0`, `animal_slot=0` - rerolls and weapon enchantments remain on the weapon instance. ### Enchantment / stone purchase behavior Stackable listings use `item_instance_id='v2'` and transfer back into inventory. - enchantments are added through `addEnchantmentWithUsage()`, preserving the usage-stack model - stones are inserted into `inventory` as `item_type='evolution_stone'` ## Cancellation Flow `.market cancel `: - only works for the seller's own active listing, - changes status to `cancelled`, - clears `marketplace_listed=0` on animals, - returns escrowed stackables (`enchantment`, `evolution_stone`) to inventory if the listing used the `v2` stackable path. The upfront 2% listing fee is **not** returned. ## Database / Storage Details ### Main table Listings live in `marketplace_listings` with fields for: - listing ID - seller / buyer identity - item type - item key - display name - underlying instance ID - rarity - stage - price - status - timestamps ### Related persistence flags - `users.user_mode` - `users.mode_switch_last` - `animals.marketplace_listed` - `animals.trade_locked` ## Strategic Tips / Balance Notes - Seller Mode is only needed to create listings; you can stay in Adventure Mode if you mainly buy. - Because animals reset to level 1 on sale, the market rewards **rarity and stage**, not previous leveling effort. - Trade-locked dungeon/tower animals cannot be listed until they lose that restriction; plain market-bought animals explicitly have `trade_locked` cleared on purchase. - Weapons are the most "sticky" market item because rerolls and enchants carry forward to the buyer. - Used enchantments are intentionally hard to liquidate because the system tracks a shared usage pool per enchant ID. ======================================================================== MODULE: PATRON ======================================================================== # Patron & Premium System ## Overview Advenexus has a premium currency called **Cash (πŸ’΅)** that is obtained through real-money top-ups via Flutterwave bank transfers (NGN). Cash can be used for exclusive features: creating custom Patron animals, buying evolution stones directly, upgrading inventory capacity, and converting to coins. The Patron animal system lets players design their own unique creatures with custom artwork. --- ## Cash (πŸ’΅) Currency ### How to Get Cash Cash is purchased via Nigerian Naira (₦) bank transfers through Flutterwave. Conversion: **₦1 = 1 Cash** (base), with tier-based bonuses for larger purchases. ### Top-Up Tiers | Amount (₦) | Cash Received | Bonus | Bonus % | Label | |---|---|---|---|---| | 500 | 500 πŸ’΅ | 0 | 0% | β€” | | 1,000 | 1,050 πŸ’΅ | 50 | 5% | β€” | | 2,000 | 2,200 πŸ’΅ | 200 | 10% | β€” | | 3,000 | 3,450 πŸ’΅ | 450 | 15% | β€” | | 5,000 | 6,000 πŸ’΅ | 1,000 | 20% | Most Popular | | 7,500 | 9,375 πŸ’΅ | 1,875 | 25% | β€” | | 10,000 | 13,500 πŸ’΅ | 3,500 | 35% | Best Value | ### Payment Flow 1. Player selects a tier on the Account Wallet page 2. Server creates a pending transaction and calls Flutterwave API 3. Player receives a bank transfer reference (bank transfer only, no cards) 4. After payment, Flutterwave sends a webhook to the server 5. Server verifies the HMAC-SHA512 signature, validates the amount, and atomically credits Cash 6. Real-time wallet update is emitted via WebSocket ### Limits - Max **3 pending transactions** at any time - Pending transactions expire automatically (cleaned up by server cron) --- ## Cash Purchases ### Evolution Stones | Stone Tier | Cash Price | |---|---| | Mythic | 500 πŸ’΅ | | Legendary | 1,500 πŸ’΅ | | Fabled | 2,500 πŸ’΅ | | Gods | 3,500 πŸ’΅ | - Added directly to inventory - Same stones obtainable for free from dungeons (at much lower rates) ### Inventory Capacity Upgrade - **Cost:** 100 πŸ’΅ per upgrade - **Gives:** +10 inventory slots - **Max capacity:** 500 slots (default is 100) - Purchased via Account Wallet page ### Cash β†’ Coins Conversion - **Rate:** 100 Cash = 10,000 Coins - Must be in multiples of 100 - **One-way only** β€” coins cannot be converted back to Cash ### Guild Capacity Upgrade - **Cost:** 250 πŸ’΅ per slot - Increases the maximum number of guild members - Purchased by the guild leader --- ## Patron Animals Custom-designed animals with player-uploaded artwork. ### Requirements - **Cost:** 3,000 πŸ’΅ - **Level requirement:** Level 20+ **OR** own a Fabled animal - Created via the Patron panel on the website (REST API, not chat command) ### Creation Process 1. Player uploads a PNG or WEBP image (max 2 MB) 2. Image is processed: resized to **180Γ—200px**, converted to WebP, compressed to < 500 KB 3. Image uploaded to Cloudinary (`advenexus/patron` folder) 4. Player chooses a **name** (2–24 chars, alphanumeric + spaces/underscores/hyphens/apostrophes) 5. Player chooses a **role**: tank, mage, berserker, armored, or speed 6. Animal is created at level 1, stage 0, rarity `patron` ### Patron Animal Stats - Uses `TIER_BASE_STATS.patron`: HP 11,000 | ATK 450 | DEF 1,200 | SPD 600 | Mana 1,400 - Role bonus applied at creation (stage 0 bonus): - Tank: +30% HP - Mage: +50% Mana - Berserker: +40% ATK - Armored: +50% DEF - Speed: +30% SPD ### Patron Animal Properties - **Rarity:** `patron` (unique tier) - **Zoo points:** 12,000 per animal - **XP per catch:** 10,000 - **Max level:** 30 - **Evolution:** No evolution (stage 0 only, evolution limit = 0) - **Cannot be sold or sacrificed** (sell value = 0, sacrifice value = 0) - **Animal key** = Cloudinary public ID (not from ANIMALS data β€” it's unique per instance) - **Custom image** stored in `patron_images` table, joined to animals for display ### Name Rules - Must be globally unique across all Patron animals - 2–24 characters - Allowed: `a-z A-Z 0-9 spaces _ - '` --- ## Cash Transaction Logging All Cash spending is logged in the `cash_transactions` table: | Field | Description | |---|---| | `tx_type` | `topup` (purchase) or `spend` (usage) | | `amount_ngn` | NGN paid (0 for spend transactions) | | `cash_amount` | Cash credited or spent | | `reference` | Flutterwave reference or spend reference | | `status` | `pending`, `completed`, or `expired` | | `description` | Human-readable description of the spend | Transaction history is viewable on the Account Wallet page (last 50 transactions). --- ## Admin Cash Commands | Command | Description | |---|---| | `.admin01 cash ` | Give Cash to any player (admin only) | - Admin account: `cybrus` - Max single grant: 1,000,000,000 Cash - No webhook verification needed for admin grants --- ## Edge Cases - Flutterwave webhook validates HMAC-SHA512 signature β€” unsigned requests are rejected - Amount in webhook is verified against the stored pending transaction (prevents amount tampering) - Cash credit and transaction status update are wrapped in a SQLite transaction (atomic) - Double crediting prevented: completed transactions are skipped if webhook fires twice - Patron animal names are globally unique β€” no two Patron animals can share the same name - Image format restricted to PNG and WEBP only (remove background at remove.bg first) - If image cannot compress below 500 KB at quality 10, creation fails - Cash conversions are one-way (Cash β†’ Coins, never Coins β†’ Cash) - Inventory upgrade is capped at 500 slots maximum ======================================================================== MODULE: QUESTS ======================================================================== # Advenexus Daily Quests Daily Quests give you a new objective every 24 hours to earn exclusive rewards, such as coins, lootboxes, and the highly sought-after **Evo Stone Crate**. ## How to use Daily Quests - **`.quest`** β€” Use this command to view your current active daily quest, your progress, the tier, and the rewards you will receive upon completion. ## Quest Tiers When you first view your quest for the day, you will be assigned a random quest from one of five tiers. Higher tiers offer better rewards but have more challenging objectives. - **S-Tier** (5% chance): Hardest objectives (e.g., *Deal final blow on a dungeon boss*, *Win 5 ranked battles*). Rewards: **1 Evo Stone Crate + 10,000 coins**. - **A-Tier** (10% chance): Very difficult objectives (e.g., *Hunt 50 times*, *Battle 50 times*). Rewards: **2 Evo Stone Crates + 10,000 coins**. - **B-Tier** (20% chance): Hard objectives (e.g., *Hunt 30 times*, *Play 10 blackjack*). Rewards: **2 Evo Stone Crates + 7,000 coins**. - **C-Tier** (30% chance): Medium objectives (e.g., *Battle with a friend*, *Coinflip 10 times*). Rewards: **1 Evo Stone Crate + 2 lootboxes**. - **D-Tier** (35% chance): Easy objectives (e.g., *Use AI assistant once*, *Pray for someone 3 times*). Rewards: **2,000–3,000 coins + 1 lootbox**. ## Completing Quests - As you perform actions around Advenexus (hunting, battling, gambling, trading), your quest progress will automatically update. - Once your progress reaches the goal, your quest will be marked as completed, and the rewards will be automatically granted to your balance and inventory. - You can only complete one quest per 24 hours. Quests will expire 24 hours after they are assigned. If you fail to complete a quest in time, a new one will be generated for you when you use the `.quest` command. ## Evo Stone Crates The **Evo Stone Crate** is a special reward exclusive to quests. You can open it using `.lootbox evo_stone_crate`. It drops evolution stones with the following rates: - **Gods Stone**: 10% - **Fabled Stone**: 20% - **Legendary Stone**: 30% - **Mythic Stone**: 40% ======================================================================== MODULE: SHOP ======================================================================== # Shop & Marketplace System ## Overview Advenexus has three distinct shopping systems: the **Weapon/Item Shop** (bot-run), the **Animal Shop** (bot-run for Gods tier), and the **Player Marketplace** (peer-to-peer trading). Additionally, there's a **Gem Shop** and **Profile Shop**. The marketplace requires players to switch to "seller mode" and operates exclusively in the #sellers channel. --- ## Commands ### Bot Shops | Command | Description | |---|---| | `.shop [page]` | Browse weapon shop (paginated, 10 per page) | | `.buy ` | Buy a weapon by type ID | | `.buy lootbox` | Buy a lootbox (2,000 πŸͺ™) | | `.buy crate` | Buy a weapon crate (3,000 πŸͺ™) | | `.buy guard dog` | Buy a guard dog (150 πŸͺ™) | | `.buy diamond` | Buy a Sacrificial Diamond (50,000 πŸͺ™) | | `.animal shop` | Browse buyable animals | | `.animal buy ` / `.buy ` | Buy an animal | | `.gem` | View your gems and equipped slots | | `.gem equip ` | Equip a gem to a slot | | `.gem unequip ` | Unequip and consume a gem | ### Player Marketplace | Command | Description | |---|---| | `.mode` | Check current mode | | `.mode seller` | Switch to seller mode (5-min cooldown) | | `.mode adventure` | Switch back to adventure mode | | `.market` | View all active marketplace listings | | `.market animals/weapons/enchantments/stones` | Filter listings by type | | `.market mine` | View your own listings | | `.player sell ` | List an item for sale (seller mode required) | | `.item buy ` | Buy a marketplace listing | | `.market cancel ` | Cancel your listing | --- ## Weapon Shop Sells all 24 weapons across 8 types and 3 tiers. ### Prices by Tier | Tier | Price Range | |---|---| | Mythic | 15,000–18,000 πŸͺ™ | | Legendary | 45,000–50,000 πŸͺ™ | | Fabled | 100,000–120,000 πŸͺ™ | See [battle.md](battle.md) for the full weapon type breakdown. --- ## Item Shop | Item | Price | Description | |---|---|---| | Lootbox | 2,000 πŸͺ™ | Random animal (rare–fabled) | | Weapon Crate | 3,000 πŸͺ™ | Enchantment (60%), diamond (18%), nothing (15%), legendary weapon (7%) | | Guard Dog | 150 πŸͺ™ | 90% chance to block steals | | Sacrificial Diamond | 50,000 πŸͺ™ | Used in `.craft` for guaranteed max stats | --- ## Animal Shop - Only **Gods tier** animals available for direct purchase - Price: **5,000,000 πŸͺ™** (from RARITY_CONFIG) - Only base forms (no evolved forms) - Purchased at level 1, stage 0 --- ## Gem System ### Gem Types | ID | Name | Category | Tier | Charges | Effect | |---|---|---|---|---|---| | HGC | Green Hunting Gem | Hunt | Common | 10 | Γ—2 animals per hunt | | HGR | Yellow Hunting Gem | Hunt | Rare | 25 | Γ—2 animals per hunt | | HGM | Red Hunting Gem | Hunt | Mythic | 50 | Γ—2 animals per hunt | | LGC | Green Lucky Gem | Lucky | Common | 10 | +1% fabled tier chance | | LGR | Yellow Lucky Gem | Lucky | Rare | 15 | +1.2% fabled tier chance | | LGM | Red Lucky Gem | Lucky | Mythic | 20 | +1.5% fabled tier chance | | GST | Gemstone | Stone | Unique | 20 | +3 animals per hunt | ### Gem Slots - **3 gem slots** maximum (one per category: hunt, lucky, stone) - Equipping removes the gem from inventory and places it in the slot - **Unequipping consumes the gem** β€” it is destroyed, not returned - Charges deplete with use during hunts ### Gem Drop Table (from hunting) | Gem | Drop Weight | |---|---| | HGC (Green Hunting) | 24 | | HGR (Yellow Hunting) | 8 | | HGM (Red Hunting) | 1 | | LGC (Green Lucky) | 24 | | LGR (Yellow Lucky) | 8 | | LGM (Red Lucky) | 1 | | GST (Gemstone) | 20 | --- ## Player Marketplace The peer-to-peer trading system. Players must be in **seller mode** to list items. ### Mode System - **Adventure mode** (default) β€” cannot sell, can still buy - **Seller mode** β€” enables listing items for sale - **5-minute cooldown** between mode switches - Marketplace only works in the **#sellers** channel ### Listing Items **Command:** `.player sell ` **Listing fee:** 2% of the sale price (deducted from seller's coins upfront) ### Tradable Items & Base Prices | Item Type | Base Price Source | |---|---| | Animals | Rarity sell value (see inventory.md) | | Weapons | Weapon shop price | | Enchantments | Mythic: 10k, Legendary: 30k, Fabled: 50k | | Evolution Stones | Mythic: 15k, Legendary: 30k, Fabled: 60k, Gods: 100k | ### Price Restrictions - Allowed range: **-20% to +50%** of base price - Example: item with 10,000 base β†’ allowed range: 8,000–15,000 πŸͺ™ ### Evolution Stage Price Multiplier - Stage 1 (+): base price Γ— **1.60** (+60%) - Stage 2 (++): base price Γ— **1.80** (+80%) ### Buying from Marketplace **Command:** `.item buy ` - Listing IDs are 4-character alphanumeric codes - Cannot buy your own listing - Full price transferred directly from buyer to seller - If the item no longer exists (seller removed it), buyer is automatically refunded ### Item Transfer Rules | Item Type | On Purchase | |---|---| | Animal | Transferred to buyer, **level reset to 1** (evolution stage kept) | | Weapon | Transferred to buyer, unequipped from any slot | | Enchantment | Removed from seller inventory, added to buyer with **fresh 50 usage** | | Evolution Stone | Removed from seller inventory, added to buyer | ### Sell Restrictions - **Animals:** cannot sell if in a team or equipped - **Weapons:** cannot sell if equipped - **Enchantments:** cannot sell if used (usage < max) or if equipped with no duplicates - Items already listed cannot be listed again ### Listing Management - `.market mine` β€” view all your listings (active and sold) - `.market cancel ` β€” cancel an active listing (no refund of listing fee) - Max **30 listings** shown per marketplace view --- ## Edge Cases - Guard dogs stack β€” you can buy and hold multiple - Weapon shop is paginated (10 per page) - Animal shop only shows base forms (excludes evolved forms from evolution chains) - Gems are consumed when unequipped β€” they cannot be recovered - Marketplace listing IDs are unique 4-character codes (letters + digits, no O/0/1/I confusion) - If a marketplace item is sold/removed by the seller after listing, the buyer gets an automatic refund - Listing fee (2%) is non-refundable even if the listing is cancelled - Enchantments bought from marketplace always come with fresh 50 usage, regardless of seller's usage ======================================================================== MODULE: STICKER ======================================================================== # Sticker System ## Overview Players can upload custom stickers to use in chat messages. Stickers are uploaded as images, automatically processed (resized, compressed, converted to WebP), stored on Cloudinary, and can be sent in any chat channel. Each sticker costs **300 πŸ’΅ Cash** to upload. --- ## How It Works Stickers are managed entirely through the website UI (REST API), not through chat commands. ### Sticker Upload **Endpoint:** `POST /api/stickers/upload` **Cost:** 300 πŸ’΅ Cash per sticker **Accepted formats:** JPEG, PNG, WebP, GIF **Max file size:** 500 KB ### Processing Pipeline 1. **Validate** β€” check file type and size 2. **Resize** β€” max 512Γ—512px (fit inside, no enlargement) 3. **Convert** β€” all formats converted to WebP (quality 75) 4. **Animated GIF** β€” converted to animated WebP (max 10 loops) 5. **Upload** β€” stored on Cloudinary at `advenexus/stickers/{userId}_{uuid}` 6. **Deduct Cash** β€” only after successful upload (300 πŸ’΅) 7. **Save** β€” sticker record stored in `user_stickers` table ### Sticker Record | Field | Description | |---|---| | `id` | UUID | | `user_id` | Owner's user ID | | `sticker_url` | Cloudinary URL | | `created_at` | Unix timestamp | --- ## API Endpoints | Endpoint | Method | Description | |---|---|---| | `/api/stickers/upload` | POST | Upload a new sticker (multipart form, 300 πŸ’΅) | | `/api/stickers/mine` | GET | Get your own stickers | | `/api/stickers/user/:userId` | GET | Get stickers for a specific user (for chat rendering) | | `/api/stickers/:stickerId` | DELETE | Delete one of your stickers | --- ## Sending Stickers Stickers are sent in chat messages via the client UI: - Player selects a sticker from their collection - The sticker URL is embedded in the message - Other players see the sticker image rendered inline --- ## Deleting Stickers - Players can delete their own stickers - Deletion removes the record from `user_stickers` - Cloudinary image is also cleaned up (non-critical β€” if cleanup fails, the DB record is still removed) - **No Cash refund** on deletion --- ## Edge Cases - Cash is only deducted **after** successful Cloudinary upload β€” if upload fails, no charge - If the database save fails after upload, the Cloudinary image is cleaned up and no charge occurs - Animated GIFs are supported but limited to 10 loop iterations - Images larger than 512px are scaled down proportionally (no enlargement for small images) - Each sticker gets a unique Cloudinary public ID: `advenexus/stickers/{userId}_{8-char-uuid}` - Sticker spending is logged in `cash_transactions` (type: `spend`, description: `Sticker upload`) ======================================================================== MODULE: TOWERDUNGEON ======================================================================== # Tower Dungeon ## Overview Tower Dungeon is the game's modern squad PvE climb. The live implementation is centered on the **Tower Dungeon sidebar page**, not chat commands: players form a 1-3 player squad, clear floors 1-100, fight scripted bosses every 10 floors, and earn **Tower Tokens** plus Tower-exclusive crate rewards. The chat command layer was intentionally reduced. Only status/help/stat lookups remain in chat; run creation, invites, readying, combat, checkpoint recovery, shop purchases, and leaderboards are handled through the sidebar/socket UI. ## Commands ### Chat commands | Command | What it does | Notes | |---|---|---| | `.tower` | Shows Tower help | Same as `.tower help` | | `.tower help` | Explains that Tower is sidebar-driven | Lists the remaining chat commands | | `.tower status` | Shows your active run, floor, squad state, and current total Tower Tokens for the run | Returns an error if you are not in a run | | `.tower stats` | Shows your personal tower record | Reads persistent `tower_player_stats` | ### Sidebar / UI actions The Tower sidebar uses socket events instead of public chat commands. The main player actions are: - Create run - Join run by run ID / invite - Send invite / accept invite / decline invite / view pending invites - Toggle ready - Start run - Submit combat actions (`attack`, `defend`, `heal`, `heal_ally`, `barrier`, `resurrection`, `potion`) - Set focus target - Advance to the next floor - Resume from checkpoint after a wipe - Boss retry ready / retry / quit - Leave run / kick member - Run chat and global Tower chat - Buy Tower shop items - Exchange coins for Tower Tokens - View active-run leaderboard ## Core Mechanics ### Squad rules - Squad size: **1-3 players**. - Each player brings up to **3 animals** from their **currently active team**. - Team loadout is re-read from the database when entering combat floors, so safezone changes to team/weapon/enchant setup affect the next fight. - Only the **leader** can invite, start, advance, or kick. - Joining and inviting are only allowed while the run is still on **floor 1**. ### Floor structure - **100 total floors**. - **Boss floors:** `10, 20, 30, 40, 50, 60, 70, 80, 90, 100`. - **Safezone/checkpoint floors:** `1, 11, 21, 31, 41, 51, 61, 71, 81, 91`. - Floor `1` is a safezone. Combat actually starts at **floor 2**. ### Ready checks - All members must be ready before the leader can start the run. - On non-solo squads, all members must also be ready before advancing from a safezone/transition state. - After a floor clear, the server resets the squad's ready state to `false` for the next transition. ### Floor transitions and checkpointing When a checkpoint floor is entered, the server saves: - squad state - checkpoint floor - accumulated Tower Tokens for the run If the squad wipes, the run is restored to the **latest checkpoint** rather than deleted immediately. ### Wipes and retry logic The current runtime constants in `towerManager.js` are: - **Wipe cooldown:** `180s` - **Boss retry cooldown:** `180s` This is important because some comments/schema notes still mention 6 hours, but the live code is using **3-minute dev-tuned cooldowns**. #### Normal wipe - Run enters `wipe` phase. - Squad reverts to the latest checkpoint. - Animals are revived to full HP. - Players are placed on the wipe cooldown. - After cooldown expiry, the leader can resume from the checkpoint safezone. #### Boss wipe Boss floors have a special retry flow: - First boss wipe grants a retry path instead of immediately ending progression. - `bossRetry.totalFailures` increments on each boss wipe. - A retry consumes the available retry when used. - If no retry remains, the boss retry cooldown is applied. - Choosing to quit the retry also applies the boss retry cooldown and returns the squad to the latest checkpoint safezone. ### Real-time combat runtime Tower uses its own real-time combat engine, not the normal PvP battle loop. - Global combat tick: **every 100ms** - Client snapshot broadcast: **every 300ms** - Inactivity timeout: **6 minutes** with no valid actions - Solo disconnect reconnect window during active combat: **15 seconds** If a solo player disconnects in combat: - the run is paused, - they get 15 seconds to reconnect, - if they fail, the run is reverted to the last checkpoint. ### Player action set The tick processor resolves these player actions: - `attack` - `defend` - `heal` - `heal_ally` - `barrier` - `resurrection` - `potion` - `focus_target` `validateAction()` and priority mapping still mention `enchant`, but the live tick resolution switch does **not** execute a separate `enchant` action. ### Damage model highlights - A player's attack damage is based on the **combined ATK of all alive animals** on that player's team. - The selected active animal's weapon governs crit/lifesteal-style weapon behavior. - Tower support items are consumed from persistent inventory while inside combat. ## Boss Mechanics Tower bosses are scripted encounter checks, not just stat walls. | Floor | Boss | Live mechanic | |---|---|---| | 10 | SCP-173 | Players need **Potion of Deep Focus** before the countdown resolves, or they are killed | | 20 | Clicker | Attacking without **Potion of Stealth** kills the acting player | | 30 | Nemesis | Marks a player and repeatedly crushes the marked target | | 40 | SCP-096 | Acting without **Potion of Mind Sight** triggers lethal punishment/rage behavior | | 50 | Time Lag Warden | Adds heavy cooldown pressure / time distortion | | 60 | Mirror Doppelganger | Reflection fight; the intended counterplay is to stop reacting to its ragebait| | 70 | Illusionist | Repeated battlefield shuffle/distortion effects | | 80 | Puppet Master | Redirects attacks and redirects heals unless players use the safe window | | 90 | Mahoraga | Regenerates every 6s until players break adaptation with 20% burst damage (10s break) | | 100 | Scarlet King | Rotates through earlier boss mechanics in sequence | ### Boss counter items sold in Tower Shop - `deep_focus` counters **SCP-173** - `stealth` counters **Clicker** - `mind_sight` counters **SCP-096** - `speed` is a general cooldown-reduction potion ## Tower Shop and Currency ### Currency - Persistent Tower currency is stored as **`users.tower_tokens`**. - Tower run state also tracks run-local totals as `totalTokens` / legacy `totalCoins`. ### Coin exchange - **1,000 coins -> 200 Tower Tokens** ### Shop catalog Tower shop items are stored in inventory as `item_type='tower_item'`. | Item ID | Name | Price | Effect | |---|---|---:|---| | `healing_orb_1` | Lvl 1 Healing Orb | 90 | Heals up to 500 HP | | `healing_orb_2` | Lvl 2 Healing Orb | 180 | Heals up to 1,000 HP | | `healing_orb_3` | Lvl 3 Healing Orb | 300 | Heals up to 2,000 HP | | `barrier_1` | Lvl 1 Barrier | 120 | 50% damage reduction for 5s | | `barrier_2` | Lvl 2 Barrier | 240 | 50% damage reduction for 10s | | `barrier_3` | Lvl 3 Barrier | 360 | 50% damage reduction for 15s | | `resurrection_staff_1` | Lvl 1 Resurrection Staff | 180 | Revive one dead animal at 25% max HP | | `resurrection_staff_2` | Lvl 2 Resurrection Staff | 420 | Revive one dead animal at 50% max HP | | `mind_sight` | Potion of Mind Sight | 500 | Counters SCP-096 | | `stealth` | Potion of Stealth | 400 | Counters Clicker | | `deep_focus` | Potion of Deep Focus | 400 | Counters SCP-173 | | `speed` | Potion of Speed | 300 | Reduces cooldowns by 2s for 15s, minimum cooldown 500ms | ## Rewards ### Tower Token formula Per cleared floor, each player is credited Tower Tokens using: ```text base = floor(50 + floor*20 + (floor/5)^2) reward = base // normal floor reward = base * 3 // boss floor ``` ### Boss milestone bonuses Boss floors add extra token bonuses: | Floor | Bonus Tokens | |---|---:| | 10 | 2,000 | | 20 | 5,000 | | 30 | 10,000 | | 40 | 15,000 | | 50 | 25,000 | | 60 | 40,000 | | 70 | 60,000 | | 80 | 80,000 | | 90 | 120,000 | | 100 | 500,000 | ### Crate reward floors Tower crate rewards are separate from token payouts. | Floor | Reward | |---|---| | 5, 15, 25, 35, 45 | 1x `mythic_crate` | | 55, 65, 75, 85, 95 | 1x `legendary_crate` | | 10 | 1x `legendary_crate` | | 20 | 2x `legendary_crate` | | 30 | 1x `fabled_crate` | | 40 | 1x `fabled_crate` + 1x `legendary_crate` | | 50 | 1x `fabled_crate` + 2x `legendary_crate` | | 60 | 1x `gods_crate` + 1x `legendary_crate` | | 70 | 1x `gods_crate` + 2x `legendary_crate` | | 80 | 1x `ascendant_crate` + 1x `fabled_crate` | | 90 | 2x `ascendant_crate` + 1x `fabled_crate` | | 100 | 1x `infinity_crate` + 2x `ascendant_crate` | ### Tower crate opening commands Tower crates are opened through chat: - `.mythic crate` - `.legendary crate` - `.fabled crate` - `.gods crate` - `.ascendant crate` - `.infinity crate` ## Database / Storage Details ### Core tower tables Tower persistence creates and uses these SQLite tables: - `tower_runs` - `tower_run_members` - `tower_checkpoints` - `tower_floor_progress` - `tower_loot_history` - `tower_player_stats` - `tower_crate_claims` - `tower_cooldowns` - `tower_invites` - `tower_chat_messages` - `tower_global_chat` ### Persistent player economy fields - `users.tower_tokens` stores each player's Tower Token wallet. - Tower shop inventory uses `inventory.item_type='tower_item'`. - Tower crates are stored in the general `inventory` table under `item_type='crate'`. ### Active-state runtime storage - Active run state is cached in Redis and mirrored to SQLite snapshot JSON (`tower_runs.run_state_json`). - Player-to-run mappings, action queues, combat state, cooldown blobs, invites, and logs are cached in Redis. - If Redis is unavailable, the system falls back to in-memory Maps for some live state. ### Leaderboards and stats - `.tower stats` reads from `tower_player_stats`. - The sidebar "leaderboard" is an **active-run floor leaderboard**, not a permanent all-time leaderboard. - `tower_player_stats.highest_floor` and `run_cycle` feed the profile system's adventurer rank. - **Adventurer Rank Tiers**: - **SS**: Completed 2 or more run cycles (`run_cycle >= 2`). - **S**: Completed 1 run cycle (`run_cycle == 1`) or reached Floor 100+ (`highest_floor >= 100`). - **A**: Highest floor reached is 90+ (`highest_floor >= 90`). - **B**: Highest floor reached is 70+ (`highest_floor >= 70`). - **C**: Highest floor reached is 50+ (`highest_floor >= 50`). - **D**: Highest floor reached is 30+ (`highest_floor >= 30`). - **E**: Highest floor reached is 10+ (`highest_floor >= 10`). - **F**: Highest floor reached is below 10. ## Strategic Tips / Balance Notes - Treat Tower as a **checkpoint-based endurance mode**, not a sprint. Safezones are the place to swap team setups and weapons. - Because teams are reloaded from the DB on combat floor entry, changing loadouts in safezones actually matters. - Save tokens for the boss-counter potions if your squad is learning the scripted fights. - Tower crates, not normal shop purchases, are the main way to access the higher Tower-exclusive reward ladder. - The reward generator still rolls a `rareDrop`, but `handleFloorComplete()` currently only persists **Tower Tokens** and **crate rewards**. In practice, the live reward path does **not** award those rolled rare drops. - The schema/comments mention 6-hour wipe cooldowns, but the live code currently enforces **180-second** cooldowns. ======================================================================== MODULE: WEAPONS-GEMS-ENCHANTMENTS ======================================================================== # Weapons, Gems, and Enchantments ## Overview This file documents the live gear systems that sit on top of animals: - **Weapons** for stat boosts and slot-based loadouts - **Weapon crates** and tower crates as alternate gear sources - **Gems** for hunt modifiers - **Enchantments** for combat effects on animals (and legacy weapon enchants) - **Weapon rerolls** for scaling a weapon up or down with gem cost based on player wealth ## Commands ### Weapons | Command | What it does | Notes | |---|---|---| | `.weapon` | Shows owned weapons | Displays top entries, reroll status, equipped slots | | `.dismantle ` | Dismantles a weapon for gems | `.weapon sell` was removed | | `.weapon reroll ` | Rolls a random reroll modifier change | Gem cost is dynamic | | `.equip ` | Equips weapon to that team's animal slot | Uses `equip_target_team` | | `.unequip ` | Removes the weapon from the named team animal | Searches across teams | | `.shop [page]` | Shows weapon shop pages | 10 items per page | | `.buy ` | Buys a fresh weapon instance | Example: `SWD1` | | `.crate` | Opens a normal weapon crate | Uses the standard crate drop table | ### Enchantments | Command | What it does | Notes | |---|---|---| | `.enchant ` | Equips an enchantment to an animal | `EN**` enchants are the normal current path | | `.enchant ` | Equips a legacy enchant to a weapon | `EF**` path still exists in code | | `.enchant keep ` | Removes an equipped enchant but keeps the inventory entry | Keeps remaining usage | | `.enchants` | Opens the enchantment codex | Shows owned quantity, usage, equipped target | ### Gems | Command | What it does | Notes | |---|---|---| | `.gem` / `.gems` | Shows inventory gems and equipped gem slots | 3 slots max | | `.gem equip ` | Equips a gem into its category slot | Removes one gem copy from inventory | | `.gem unequip ` | Unequips the gem in that slot | The gem is consumed and not returned | ## Weapons ### Weapon families and shop pricing | Family | Mythic | Legendary | Fabled | Gods | Specialty | |---|---:|---:|---:|---:|---| | Sword (`SWD`) | 15,000 | 45,000 | 100,000 | 150,000 | Balanced ATK/DEF/crit | | Katana (`KTA`) | 15,000 | 45,000 | 100,000 | 150,000 | ATK + mana bonus | | Dagger (`DGR`) | 15,000 | 45,000 | 100,000 | 150,000 | High crit | | Axe (`AXE`) | 18,000 | 50,000 | 110,000 | 160,000 | Highest raw ATK | | Hammer (`HMR`) | 18,000 | 50,000 | 120,000 | 170,000 | Tank / DEF-heavy | | Spear (`SPR`) | 16,000 | 48,000 | 105,000 | 150,000 | Balanced ATK/DEF | | Scythe (`SCY`) | 17,000 | 48,000 | 110,000 | 160,000 | Lifesteal | The data file also includes **Ascendant** weapons used by higher-end reward systems. ### Equipping rules - Weapons are equipped to **team slots**, not directly to animal IDs. - `.equip ` finds the named animal on the current `equip_target_team`. - If another weapon is already on that slot, the old one is auto-unequipped. - A weapon already equipped on another team cannot be reused across teams until unequipped. - Listed marketplace weapons cannot be equipped. ### Dismantling Weapons Weapons can be dismantled for gems using `.dismantle ` or `.dismantle `. You cannot dismantle an equipped weapon. Gem rewards by rarity: - **Mythic**: 400 πŸ’Ž - **Legendary**: 1,000 πŸ’Ž - **Fabled**: 2,500 πŸ’Ž - **Gods**: 4,000 πŸ’Ž - **Ascendant**: 6,000 πŸ’Ž ## Weapon Rerolls ### Reroll cost Reroll cost is based on the player's current coin wealth: | Coin balance | Reroll cost | |---|---:| | `< 100,000` | 700 gems | | `100,000 - 999,999` | 900 gems | | `1,000,000 - 9,999,999` | 1,200 gems | | `10,000,000+` | 1,500 gems | ### Reroll result table Each reroll adds one random step from: ```text -50, -40, -30, -20, -10, 0, +10, +20, +30, +40, +50 ``` The accumulated reroll bonus is clamped to: ```text minimum -100% maximum +200% ``` `reroll_count` increases by 1 each time. ### Where rerolls matter Reroll bonuses are applied in multiple systems: - normal dungeon team weapon loading - guild raid/guild war team building - guild boss skirmish building ## Normal Weapon Crates ### Source - 1x from `.daily` - purchasable with `.buy crate` for **3,000 coins** - can also come from some reward systems ### Live drop table Standard `.crate` uses this weight table: | Outcome | Weight | Approx. chance | |---|---:|---:| | Enchantment | 60 | 60% | | Sacrificial Diamond | 18 | 18% | | Legendary weapon | 7 | 7% | | Nothing | 15 | 15% | ### Crate outcomes - **Enchantment** -> random enchant tier from `pickEnchantment()` - **Diamond** -> 1x `SDMND` - **Weapon** -> random Legendary weapon instance - **Nothing** -> empty crate result ## Tower Crates Tower-exclusive crates are separate from normal `.crate` and are opened with: - `.mythic crate` - `.legendary crate` - `.fabled crate` - `.gods crate` - `.ascendant crate` - `.infinity crate` Their drop tables are defined in `server/data/towerCrates.js` and can award animals, weapons, evolution stones, enchantments, coins, and profiles depending on crate tier. ## Enchantments ### Inventory and usage model Enchantments are stored in `inventory` as: - `item_type='enchantment'` - `item_id=''` - `quantity` - `usage` Key rule: - each copy adds **50 usage** - stacked copies share a **single pooled usage total** Example: - 1 copy -> 50 usage - 2 copies -> 100 usage - 3 copies -> 150 usage ### Usage consumption After a battle/raid/dungeon/war/boss attack, the server consumes **1 usage per unique equipped enchant ID** on the user's current team. When usage hits 0: - that enchant is removed from all of the user's animals, - removed from all of the user's weapons carrying it, - deleted from the inventory table. ### Equip / keep rules - `EN**` enchants equip to animals. - `EF**` enchants still equip to weapons through the legacy branch. - `.enchant keep ` only removes the equipped link; it does **not** restore usage. ### Double Enchantment System **Level 25+ animals can equip 2 enchantments simultaneously.** #### Commands - `.enchant ` - Equip enchantment to slot 1 - `.enchant2 ` - Equip enchantment to slot 2 (requires level 25) - `.unequipenchant1 ` - Unequip enchantment from slot 1 - `.unequipenchant2 ` - Unequip enchantment from slot 2 - `.enchant keep` - Keep enchantments on your current team animals #### Rules - **Level 25 Unlock**: The second enchantment slot unlocks at level 25 - **No Duplicates**: You cannot equip the same enchantment to both slots on the same animal - **Shared Mana Pool**: Both enchantments share the same mana pool - **Sequential Trigger**: Enchantments trigger in order (slot 1 first, then slot 2) when applicable - **Independent Usage**: Each enchantment has its own usage counter (50 uses per copy) #### Validation - Animals below level 25 cannot equip a second enchantment - Attempting to equip duplicate enchantments will be rejected - Usage is tracked independently for each enchantment slot ### Sell restrictions The marketplace helper blocks enchantment sales when: - usage is below the full stacked maximum, - the enchant is equipped and the player only has one copy. ### Live enchant list | ID | Name | Tier | Core effect | |---|---|---|---| | `EN01` | Critical | Mythic | 26% chance to multiply damage by x1.52 for 48 mana | | `EN02` | Spirit Guard | Legendary | Opening heal from remaining mana + 24% passive damage reduction | | `EN03` | Mana Tap | Legendary | On hit, spends mana to restore ally mana from dealt damage | | `EN04` | Sacrifice | Legendary | On death, burns mana and heals allies for 30% max HP | | `EN05` | Resurrection | Legendary | Once per battle revive at 11% HP | | `EN06` | Taunting | Legendary | 3-turn taunt, ~75% forced focus, 35% damage reduction | | `EN07` | Kamikaze | Fabled | On death, burns mana and explodes for 12% max HP damage | | `EN08` | Health Point | Mythic | Battle-start +25% max HP | | `EN09` | Reflection | Mythic | Reflects 26% damage for 3 turns | | `EN10` | Mana Tank | Mythic | Battle-start +45% max mana to allies | | `EN11` | Negator | Fabled | Nullifies enemy enchantments for 3 turns (7-turn cooldown) | | `EN12` | Time Freeze | Fabled | Freezes a random enemy for 2 turns | | `EN13` | Combat Combo | Mythic | +8% attack damage per stack, up to 9 stacks | | `EN14` | Mana Whip | Fabled | First swing converts full mana into x5 bonus burst damage | | `EN15` | Healer | Fabled | Periodic lowest-ally healing | ## Gems ### Slot model The gem system has exactly **three categories**, one slot each: - `hunt` - `lucky` - `stone` `gem_slots` stores: - `user_id` - `category` - `gem_id` - `charges` ### Equip / unequip behavior - Equipping removes one gem copy from inventory and fills the slot with its starting charges. - Each successful `.hunt` consumes **1 charge** from each equipped slot. - If charges drop to 0, the slot is deleted automatically. - Manual `.gem unequip ...` also deletes the slot, and the gem is **gone permanently**. ### Live gem behavior in hunt logic The hunt command currently checks **slot presence**, not gem tier scaling, so the live effects are: | Category | Live effect in `hunt.js` | |---|---| | Hunt gem | Doubles the post-stone hunt count (`baseCount *= 2`) | | Lucky gem | Adds a flat **+2** lucky boost into `rollHunt()` | | Stone gem | Adds **+3 animals** before hunt doubling | That means the tier difference currently matters mainly through **starting charges**, not stronger live hunt math. ### Gem definitions and charges | ID | Name | Category | Charges | |---|---|---|---:| | `HGC` | Green Hunting Gem | Hunt | 10 | | `HGR` | Yellow Hunting Gem | Hunt | 25 | | `HGM` | Red Hunting Gem | Hunt | 50 | | `LGC` | Green Lucky Gem | Lucky | 10 | | `LGR` | Yellow Lucky Gem | Lucky | 15 | | `LGM` | Red Lucky Gem | Lucky | 20 | | `GST` | Gemstone | Stone | 20 | ### Gem sources - Hunt drops: 5% gem drop chance using the weighted `rollGemDrop()` table - Lootboxes: 10% gem outcome branch, then equal random pick across all 7 gem IDs ## Database / Storage Details - Weapons live in `weapons` - Enchantments live in `inventory` as `item_type='enchantment'` - Gems live in `inventory` as `item_type='gem'` - Equipped gem slots live in `gem_slots` - Weapon reroll fields: `weapons.reroll_bonus`, `weapons.reroll_count` - Equipped links: `weapons.animal_slot`, `weapons.enchant_id`, `animals.enchant_id` ## Strategic Tips / Balance Notes - Rerolling is effectively an endgame gem sink because the cost rises with your coin wealth. - Market-bought weapons are especially valuable because rerolls and weapon enchants stay on the item. - Manual gem unequip is destructive, so only socket gems you plan to use through their charges. - Lucky gem tiers currently differ by charge count more than live hunt power because `hunt.js` applies a flat lucky bonus whenever any lucky gem is slotted. - Enchantments are best treated as durable but finite resources: each duplicate extends a shared usage pool by another 50.