# 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 <animal>` | View one owned animal |
| `.tier [rarity]` | View rarity pages / drop info |
| `.rename <old> \| <new>` | Rename an animal |
| `.sell <name>` / `.sell <count> <name>` / `.sell <rarity>` | Sell animals for coins |
| `.sacrifice <name>` / `.sacrifice <count> <name>` / `.sacrifice <rarity>` | Sacrifice animals for gems |
| `.craft <rarity>` | Craft upward by rarity |
| `.craft <rarity> diamond` | Diamond craft with a Sacrificial Diamond |
| `.evolve <animal>` | 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 <animal>` | Add to active team |
| `.team remove <animal>` | 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 <pictureId>` | Equip owned profile picture |
| `.profile unequip` | Remove equipped profile picture |
| `.give @user <amount>` | 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 <weaponTypeId>` | 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<N>` | Buy profile picture |
| `.animal shop` | Animal shop UI |
| `.animal buy <name>` | 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 <weaponId>` | Dynamic reroll cost: 700/900/1200/1500 gems depending on coin wealth |
| `.equip <weaponId> <animal>` | Equip weapon to named team animal |
| `.unequip <animal>` | Unequip that slot's weapon |
| `.enchant <target> <enchId>` | Equip enchant to animal or legacy weapon target |
| `.enchant keep <enchId>` | Remove enchant but keep remaining usage |
| `.enchants` | Enchantment codex |
| `.gem` / `.gems` | Gem inventory / slots |
| `.gem equip <gemId>` | Equip a gem |
| `.gem unequip <hunt|lucky|stone>` | Unequip and consume that gem |
| `.dismantle <weaponId or name>` | 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 <listingId>` | Cancel one of your active listings |
| `.player sell <item> <price>` | Create a listing (seller mode required) |
| `.item buy <listingId>` | Buy a listing |

## Guilds, Raids, Banners, and Guild Boss

| Command | Notes |
|---|---|
| `.guild create <name>` | 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 <amount>` | Deposit to guild bank |
| `.guild withdraw <amount>` | 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 <common|rare>` | Leader buys a guild stat perk |
| `.raid @guildname` | Start guild raid |
| `.banner shop` | Banner shop |
| `.banner buy <bannerId>` | Buy banner |
| `.banner equip <bannerId>` | 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 <animalName>` | Feed cookie to animal to restore +10 energy |
| `.duel @user <amount>` | 1v1 PvP duel for coins. 5% house rake |
| `.coinflip <bet> <heads|tails>` | Gambling channel allowed |
| `.slots <bet>` | Gambling channel allowed |
| `.blackjack <bet>` | Gambling channel allowed |
| `.hit` / `.stand` | Active blackjack only |
| `.lottery <bet>` | Gambling channel allowed |

## Weather

| Command | Notes |
|---|---|
| `.activate <effect>` | 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 <user>` | Admin only |
| `.admin01 unsuspend <user>` | Admin only |
| `.admin01 stats` | Admin only |
| `.admin01 dungeon open` | Force-spawn a dungeon gate |
| `.admin01 <amount> cash @user` | Grant Cash |
| `.add coin admin01 <amount>` | 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.