ShaiBot/COOKIE_LOGIC.md

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:

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:

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.