updated steal logic

COOKIE_LOGIC.md

@@ -0,0 +1,99 @@
+# Cookie Economy Command
+
+`cookies.js` implements the `/cookies` command and its five subcommands: `collect`, `steal`, `check`, `give`, and `leaderboard`.
+
+## Commands
+
+- `/cookies collect` delegates collection logic to `collectCookies()`, then displays the amount collected, updated vault, and next collection time.
+- `/cookies check [target]` shows a user's current Cookie balance. Without a target it checks the invoking user.
+- `/cookies give <target> <amount>` transfers Cookies to another non-bot user and records sender/recipient profile statistics.
+- `/cookies leaderboard` reads `items_cookies`, sorts by balance, excludes the bot, and displays the ten richest users.
+- `/cookies steal <target>` runs the PvP robbery system described below.
+
+## Steal balance
+
+| Setting | Value |
+|---|---:|
+| Cooldown | 15 minutes |
+| Base/equal-wealth success chance | 55% |
+| Success range | 30%–80% |
+| Wealth scaling | 12.5 percentage points per 10x balance difference |
+| Heat per recent attempt | 7.5 percentage points |
+| Heat lifetime | 1 hour, linear decay |
+| Victim hourly loss budget | 15% of balance when the window starts |
+| Per-robbery hard cap | 25,000 Cookies |
+| Base loot tiers | 1–3%, 3–5%, 5–8%, 8–10% |
+| Loot multiplier | 0.75x–1.25x based on final robbery difficulty |
+| Base failure penalty | 2%–10% of thief balance |
+| Failure multiplier | 0.75x–1.50x based on final success chance |
+
+### Wealth chance curve
+
+Before heat is applied, relative wealth determines the success chance. Absolute economy size does not matter.
+
+| Attacker compared with target | Base chance |
+|---|---:|
+| 100x poorer | 80% |
+| 10x poorer | 67.5% |
+| Equal | 55% |
+| 10x richer | 42.5% |
+| 100x richer | 30% |
+
+### Heat protection (`stats_profile`)
+
+Each valid robbery attempt adds an entry without modifying existing achievement/profile fields:
+
+```js
+stealProtection: {
+    attempts: [
+        {
+            userId: "attacker-id",
+            timestamp: Date
+        }
+    ]
+}
+```
+
+All attackers contribute to the same victim heat. Each attempt starts at a 7.5-point success penalty and fades linearly to zero over one hour. Expired entries are removed whenever the victim is targeted again. The current attempt is appended atomically while MongoDB returns the immediately previous profile state, so simultaneous attacks see newly-created heat while an attempt never penalizes itself.
+
+### Hourly victim-loss budget (`items_cookies`)
+
+Each Cookie record may contain:
+
+```js
+stealable: {
+    amount: 15000,
+    windowStartedAt: Date
+}
+```
+
+When no active window exists, the first valid robbery attempt after the attacker's cooldown check initializes the allowance to 15% of the victim's current balance. That first attempt is treated as breaching the Vault and adds a short `🔓 Vault Breached!` flavor message to the robbery embed. Attempts rejected by the attacker's cooldown do not open a new victim window.
+
+The exposed amount is shown in steal result embeds as **Vault Exposed**. The window lasts a fixed hour; successful robberies decrement `amount` without moving `windowStartedAt`. Failed robberies leave the exposed budget unchanged. When the hour expires, the next valid attempt recalculates the allowance from the victim's then-current balance and opens a new exposure window.
+
+A successful robbery reserves its amount from this budget with an atomic MongoDB update before calling `transferCookies()`. This prevents concurrent robberies from spending the same allowance. If the Cookie transfer fails, the reservation is refunded.
+
+When the allowance reaches zero, the Vault is no longer exposed. Further steal attempts are rejected without consuming the attacker's steal cooldown until the fixed window expires and can be breached again.
+
+### Loot and penalties
+
+The original weighted loot tiers remain:
+
+- 50% of successful steals roll 1–3%.
+- 30% roll 3–5%.
+- 15% roll 5–8%.
+- 5% roll 8–10%.
+
+Those ranges are multiplied by a difficulty factor: easy/high-chance robberies pay less, while difficult/low-chance robberies can pay more. The final amount is also capped by the victim balance, the remaining hourly stealable budget, and the 25,000-Cookie per-hit cap.
+
+Failure penalties work in the opposite direction. Easy/high-chance robberies carry a larger penalty when they fail; difficult robberies carry a smaller one. The resulting range moves from roughly 1.5–7.5% at a 30% success chance to 3–15% at an 80% success chance.
+
+## Collections and utilities
+
+The file expects `getCollections()` to expose:
+
+- `items_cookies` as `cookies`, `itemsCookies`, or `items_cookies`.
+- `stats_profile` as `statsProfile`, `statsProfiles`, or `stats_profile`.
+- Alternatively, `getCollections()` may expose a `db`/`database` handle from which those raw MongoDB collection names can be opened.
+
+Existing shared utilities remain responsible for Cookie balances, transfers, cooldown claims, random helpers, profile event tracking, and collection logic.