From cd41bc2a48322decc20850f8d5e925ecec8d2d4c Mon Sep 17 00:00:00 2001 From: Rene Arumetsa Date: Mon, 20 Apr 2026 22:42:26 +0300 Subject: [PATCH] Remove DEV_NOTE3S in root directory --- DEV_NOTES.md | 257 --------------------------------------------------- 1 file changed, 257 deletions(-) delete mode 100644 DEV_NOTES.md diff --git a/DEV_NOTES.md b/DEV_NOTES.md deleted file mode 100644 index d8b6f12..0000000 --- a/DEV_NOTES.md +++ /dev/null @@ -1,257 +0,0 @@ -# TipiLAN Bot - Developer Reference - -## File Structure - -| File | Purpose | -|---|---| -| `bot.py` | All Discord commands, views (UI components), event handlers, reminder system | -| `economy.py` | All economy logic, data model, constants (SHOP, COOLDOWNS, LEVEL_ROLES, etc.) | -| `pb_client.py` | Async PocketBase REST client - auth token cache, CRUD on `economy_users` collection | -| `strings.py` | **Single source of truth for all user-facing text.** Edit here to change any message. | -| `sheets.py` | Google Sheets integration (member sync) | -| `member_sync.py` | Birthday/member sync background task | -| `config.py` | Environment variables (TOKEN, GUILD_ID, PB_URL, etc.) | - ---- - -## Adding a New Economy Command - -Checklist - do all of these, in order: - -1. **`economy.py`** - add the `do_` async function with cooldown check, logic, `_commit`, and `_txn` logging -2. **`economy.py`** - add the cooldown to `COOLDOWNS` dict if it has one -3. **`economy.py`** - add the EXP reward to `EXP_REWARDS` dict -4. **PocketBase** - if the function stores new fields, add them manually in the PB admin UI at `http://127.0.0.1:8090/_/`. Fields not in the PB schema are silently dropped on PATCH. -5. **`strings.py` `CMD`** - add the slash command description -6. **`strings.py` `OPT`** - add any parameter descriptions -7. **`strings.py` `TITLE`** - add embed title(s) for success/fail states -8. **`strings.py` `ERR`** - add any error messages (banned, cooldown uses `CD_MSG`, jailed uses `CD_MSG["jailed"]`) -9. **`strings.py` `CD_MSG`** - add cooldown message if command has a cooldown -10. **`strings.py` `HELP_CATEGORIES["tipibot"]["fields"]`** - add the command to the help embed -11. **`bot.py`** - implement the `cmd_` function, handle all `res["reason"]` cases -12. **`bot.py`** - call `_maybe_remind` if the command has a cooldown and reminders make sense -13. **`bot.py`** - call `_award_exp(interaction, economy.EXP_REWARDS[""])` on success -14. **`strings.py` `REMINDER_OPTS`** - add a reminder option if the command needs one -15. **`bot.py` `_maybe_remind`** and **`_restore_reminders`** - if item-modified cooldown, add `elif` branch -16. **`bot.py` `_REMINDER_COOLDOWN_KEYS`** - add `"cmd": "last_cmd"` mapping if reminder-capable - ---- - -## Adding a New Shop Item - -Checklist: - -1. **`economy.py` `SHOP`** - add the item dict `{name, emoji, cost, description: strings.ITEM_DESCRIPTIONS["key"]}` -2. **`economy.py` `SHOP_TIERS`** - add the key to the correct tier list (1/2/3) -3. **`economy.py` `SHOP_LEVEL_REQ`** - add minimum level if it is T2 (≥10) or T3 (≥20) -4. **`strings.py` `ITEM_DESCRIPTIONS`** - add the item description (Estonian flavour + English effect) -5. **`strings.py` `HELP_CATEGORIES["shop"]["fields"]`** - add display entry (sorted by cost) -6. If the item modifies a cooldown: - - **`economy.py`** - add the `if "item" in user["items"]` branch in the relevant `do_` function - - **`bot.py` `_maybe_remind`** - add `elif cmd == "" and "" in items:` branch with the new delay - - **`bot.py` `_restore_reminders`** - add the same `elif` branch - - **`bot.py` `cmd_cooldowns`** - add the item annotation to the relevant status line - ---- - -## Adding a New Level Role - -1. **`economy.py` `LEVEL_ROLES`** - add `(min_level, "RoleName")` in descending level order (highest first) -2. **`bot.py` `_ensure_level_role`** - no changes needed (uses `LEVEL_ROLES` dynamically) -3. Run **`/economysetup`** in the server to create the role and set its position - ---- - -## Adding a New Admin Command - -1. **`strings.py` `CMD`** - add `"[Admin] ..."` description -2. **`strings.py` `OPT`** - add parameter descriptions -3. **`strings.py` `ADMIN`** - add response and DM strings -4. **`strings.py` `HELP_CATEGORIES["admin"]["fields"]`** - add the entry -5. **`economy.py`** - add `do_admin_` function -6. **`bot.py`** - add command with `@app_commands.default_permissions(manage_guild=True)` and `@app_commands.guild_only()` - ---- - -## Economy System Design - -### Storage - -All economy state is stored in **PocketBase** (`economy_users` collection). `pb_client.py` owns all reads/writes. Each `do_*` function in `economy.py` calls `get_user()` → mutates the local dict → calls `_commit()`. `_commit` does a `PATCH` to PocketBase. - -### Currency & Income Sources - -| Command | Cooldown | Base Earn | Notes | -|---|---|---|---| -| `/daily` | 20h (18h w/ korvaklapid) | 150⬡ | ×streak multiplier, ×2 w/ lan_pass, +5% interest w/ gaming_laptop; prestige daily_plus adds +20% per level | -| `/work` | 1h (40min w/ monitor) | 15-75⬡ | ×1.5 w/ gaming_hiir, ×1.25 w/ reguleeritav_laud, ×3 30% chance w/ energiajook; prestige work_plus +20%/level | -| `/beg` | 5min (3min w/ hiirematt) | 10-40⬡ | ×2 w/ klaviatuur | -| `/crime` | 2h | 200-500⬡ win | 60% success (75% w/ cat6), +30% w/ mikrofon; fail = fine + jail | -| `/rob` | 2h | 10–25% of target | 45% success (60% w/ jellyfin); fail = fine; cannot rob TipiBOT directly | -| `/heist` | 4h personal + 1h global | 20–55% of house / n players | solo allowed, max 8; 35%+5%/player success (cap 65%); fail = 3h jail + ~15% balance fine | -| `/fish` | 2min (90s w/ ussipurk) | varies by fish rarity | Interactive minigame; catches go to inventory; sell with `/fishsell` | -| `/slots` | - | varies | pair=+0.5× bet; triple tiered; karikas jackpot ×25; ×1.5 w/ monitor_360; miss=lose bet | -| `/roulette` | - | 2× red/black, 14× green | 1/37 green chance | -| `/blackjack` | - | 1:1 win, 3:2 BJ, 2:1 double | Dealer stands on 17+; double down on first action only | - -### Fishing System - -- `/fish` - interactive minigame: cast → wait 5–15s for bite → press button within 2s (3s w/ echolood) → keep or sell -- Fish stored in `fish_inventory` (list of `{fish_id, weight, value}` objects) -- `/fishbook` - paginated fish collection showing caught species and inventory counts -- `/fishsell` - sell all fish from inventory at once -- `fish_inventory` and `fish_book` **survive prestige resets** -- `kalavork` (T3, 5000⬡): bumps all caught fish up one rarity tier -- `ussipurk` (T2, 3500⬡): cooldown 2min → 90s -- `echolood` (T3, 8000⬡): bite window 2s → 3s - -### Prestige System - -- Requires level 30 (9000 EXP) -- Resets: balance, EXP, items, cooldowns, jail -- Preserves: fish_book, fish_inventory, lifetime stats, prestige_points, season_total_exp, prestige_upgrades -- Awards prestige_points = max(1, exp ÷ 1000) at time of prestige -- Each prestige increments `prestige_level` counter -- Prestige coin/exp multipliers apply to all earned values - -**Prestige Shop** (`PRESTIGE_SHOP` in economy.py): - -| Upgrade | Max Level | Cost/level | Effect | -|---|---|---|---| -| `coin_mult` | 5 | 5 PP | +8% coin multiplier per level | -| `exp_mult` | 5 | 5 PP | +8% EXP multiplier per level | -| `daily_plus` | 3 | 7 PP | +20% daily base reward per level | -| `work_plus` | 3 | 7 PP | +20% work earnings per level | - -### "all" Keyword -Commands that accept a coin amount (`/give`, `/roulette`, `/rps`, `/slots`, `/blackjack`) accept `"all"` to mean the user's full current balance. Parsed by `_parse_amount(value, balance)` in `bot.py`. - -### Daily Streak Multipliers -- 1-2 days: ×1.0 (150⬡) -- 3-6 days: ×1.5 (225⬡) -- 7-13 days: ×2.0 (300⬡) -- 14+ days: ×3.0 (450⬡) -- `karikas` item: streak survives missed days - -### Jail -- Normal duration: 30 minutes (`JAIL_DURATION`) -- Heist fail duration: 3 hours (`HEIST_JAIL`) + fine 15% of balance (min 150⬡, max 1000⬡) -- `gaming_tool`: prevents jail on crime fail -- `/jailbreak`: 3 single-button dice rolls (both dice at once), need doubles to escape free. Animated reveal with TipiDICE emoji. On fail after 3 tries - bail = 20-30% of balance, min 350⬡. If balance < 350⬡, stay jailed until timer. - -### EXP Rewards (from `EXP_REWARDS` in economy.py) -EXP is awarded on every successful command use. Level formula: `floor(sqrt(exp / 10))`, so Level 5 = 250 EXP, Level 10 = 1000, Level 20 = 4000, Level 30 = 9000. - -Fish EXP is awarded per catch (varies by rarity, defined in `FISH_CATALOGUE`). Prestige `exp_mult` upgrade applies to fish EXP. - ---- - -## Admin Commands Reference - -| Command | What it does | -|---|---| -| `/pause` | Toggle maintenance mode - blocks all non-admin commands | -| `/admincoins @user ` | Give/take coins (positive/negative). DMs user. | -| `/adminexp @user ` | Give/take EXP (positive/negative). Auto-applies level roles on change. DMs user. | -| `/adminitem @user ` | Give or remove any shop item for free. DMs user. | -| `/adminjail @user ` | Manually jail a user. DMs user. | -| `/adminunjail @user` | Remove jail from a user. | -| `/adminban @user ` | Ban from all economy commands. DMs user. | -| `/adminunban @user` | Lift economy ban. | -| `/adminreset @user ` | Wipe balance, EXP, items, streak. DMs user. | -| `/adminview @user` | Full profile: balance, EXP/level, streak, prestige, fish stats, items, timestamps. | -| `/adminseason ` | End season: DM top N players, reset all EXP. | - -All admin commands require **Manage Guild** permission and work in any channel (bypass pause and channel restrictions). - ---- - -## Role Hierarchy (Discord) - -Order top to bottom in server roles: - -``` -[Bot managed role] ← bot's own role, always at top of our stack -ECONOMY ← given to everyone who uses any economy command -TipiLEGEND ← level 30+ -TipiCHAD ← level 20+ -TipiHUSTLER ← level 10+ -TipiGRINDER ← level 5+ -TipiNOOB ← level 1+ -``` - -Run `/economysetup` to auto-create all roles and set their positions. The command is idempotent - safe to run multiple times. - -Role assignment: -- **ECONOMY** role: given automatically on first EXP award (i.e. first successful economy command) -- **Level roles**: given/swapped automatically on level-up; synced on `/rank` -- **`/adminexp`**: automatically re-applies level roles if level changes - ---- - -## Shop Tiers & Level Requirements - -| Tier | Level Required | Items | -|---|---|---| -| T1 | 0 (any) | gaming_hiir, hiirematt, korvaklapid, lan_pass, anticheat, energiajook, gaming_laptop | -| T2 | 10 | reguleeritav_laud, jellyfin, mikrofon, klaviatuur, monitor, cat6, **ussipurk** | -| T3 | 20 | monitor_360, karikas, gaming_tool, **kalavork**, **echolood** | - -Shop display is sorted by cost (ascending) within each tier. -The `SHOP_LEVEL_REQ` dict in `economy.py` controls per-item lock thresholds. - ---- - -## strings.py Organisation - -| Section | Dict | Usage in bot.py | -|---|---|---| -| Flavour text | `WORK_JOBS`, `BEG_LINES`, `CRIME_WIN`, `CRIME_LOSE` | Randomised descriptions | -| Command descriptions | `CMD["key"]` | `@tree.command(description=S.CMD["key"])` | -| Parameter descriptions | `OPT["key"]` | `@app_commands.describe(param=S.OPT["key"])` | -| Help embed | `HELP_CATEGORIES["cat"]` | `cmd_help` | -| Banned message | `MSG_BANNED` | All banned checks | -| Reminder options | `REMINDER_OPTS` | `RemindersSelect` dropdown | -| Slots outcomes | `SLOTS_TIERS["tier"]` → `(title, color)` | `cmd_slots` | -| Embed titles | `TITLE["key"]` | `discord.Embed(title=S.TITLE["key"])` | -| Error messages | `ERR["key"]` | `send_message(S.ERR["key"])` - use `.format(**kwargs)` for dynamic parts | -| Cooldown messages | `CD_MSG["cmd"].format(ts=_cd_ts(...))` | Cooldown responses | -| Shop UI | `SHOP_UI["key"]` | `_shop_embed` | -| Item descriptions | `ITEM_DESCRIPTIONS["item_key"]` | `economy.SHOP[key]["description"]` | -| Fish UI | `FISH_UI["key"]` | `/fish`, `/fishbook`, `/fishsell` | -| Fish names | `FISH_NAMES["fish_id"]` | Fish display name | -| Admin responses | `ADMIN["key"]` | Admin command success/DM messages | - ---- - -## Constants Location Quick-Reference - -| Constant | File | Description | -|---|---|---| -| `SHOP` | `economy.py` | All shop items (name, emoji, cost, description) | -| `SHOP_TIERS` | `economy.py` | Which items are in T1/T2/T3 | -| `SHOP_LEVEL_REQ` | `economy.py` | Min level per item | -| `COOLDOWNS` | `economy.py` | Base cooldown per command | -| `JAIL_DURATION` | `economy.py` | How long jail lasts | -| `LEVEL_ROLES` | `economy.py` | `[(min_level, "RoleName"), ...]` highest first | -| `ECONOMY_ROLE` | `economy.py` | Name of the base economy participation role | -| `EXP_REWARDS` | `economy.py` | EXP per command | -| `FISH_CATALOGUE` | `economy.py` | All fish species (rarity, weight, coins, exp) | -| `PRESTIGE_SHOP` | `economy.py` | Prestige upgrade definitions | -| `HOUSE_ID` | `economy.py` | Bot's user ID (house account for /rob) | -| `MIN_BAIL` | `economy.py` | Minimum bail payment (350⬡) | -| `COIN` | `economy.py` | The coin emoji string | - ---- - -## Balance Notes (as of current version) - -- **Beg** is most efficient for active players (3min cooldown + 2× multiplier w/ `klaviatuur` = high ⬡/hr) -- **Work** is best for passive players (1h cooldown, fire and forget) -- **Crime** is high risk/reward - best with `cat6` + `mikrofon` -- **`lan_pass`** (1200⬡) doubles daily - good long-term investment -- **`gaming_laptop`** (1500⬡) 5% interest, capped 500⬡/day - snowballs with large balance -- `anticheat` is consumable (2 uses) - only item that can be re-bought -- `karikas` (T3) is the only item that preserves a daily streak across missed days -- `reguleeritav_laud` (T2) stacks with `gaming_hiir`: combined ×1.5 × ×1.25 = ×1.875 -- **Fishing** is a steady passive income; `kalavork` (T3) dramatically increases fish value by bumping rarity