DeSqBlocki
169 lines
3.4 KiB
Markdown
169 lines
3.4 KiB
Markdown
# ShaiBot Cookie Economy
|
|
|
|
This manual describes the shared Cookie economy and the rules
|
|
maintainers should preserve.
|
|
|
|
## Source of Truth
|
|
|
|
`utils/cookieEconomy.js` is the shared economy utility.
|
|
|
|
Game and command modules should not perform independent ad-hoc balance
|
|
mutations when the shared economy already provides the required
|
|
operation.
|
|
|
|
## Balances
|
|
|
|
Cookie balances live in:
|
|
|
|
``` text
|
|
items_cookies
|
|
```
|
|
|
|
Conceptually:
|
|
|
|
``` js
|
|
{
|
|
userId: "...",
|
|
cookies: 2500
|
|
}
|
|
```
|
|
|
|
Negative changes use an atomic balance filter so a player cannot spend
|
|
more Cookies than are available.
|
|
|
|
Expected insufficient-balance failures use:
|
|
|
|
``` text
|
|
INSUFFICIENT_COOKIES
|
|
```
|
|
|
|
Some subsystems carry expected error identifiers in `error.message`,
|
|
while others may also use `error.code`. User-facing formatters should
|
|
account for the convention used by that subsystem.
|
|
|
|
## Transfers
|
|
|
|
Player-to-player transfers do not require MongoDB transactions.
|
|
|
|
The safe conceptual sequence is:
|
|
|
|
``` text
|
|
atomic debit source
|
|
→ credit destination
|
|
→ compensate source if destination credit fails
|
|
```
|
|
|
|
A critical compensation failure must remain visible in logs.
|
|
|
|
## Cooldowns
|
|
|
|
Cooldowns live in:
|
|
|
|
``` text
|
|
cooldown_cookies
|
|
```
|
|
|
|
Use the shared cooldown helpers, especially atomic cooldown claiming
|
|
when double-clicks or simultaneous requests must not both succeed.
|
|
|
|
## House Vault
|
|
|
|
ShaiBot acts as the general house Cookie vault for supported games.
|
|
|
|
Gambling losses and penalties may feed the vault, while wins, heists,
|
|
and rewards may pay out from it.
|
|
|
|
House-funded features should respect their existing liquidity rules.
|
|
|
|
## Cookie Collection
|
|
|
|
`/cookies collect` and the Crumb Saucer Bakery share
|
|
`utils/crumbCollect.js`.
|
|
|
|
They must share:
|
|
|
|
- the same cooldown
|
|
- the same reward generation
|
|
- the same balance mutation
|
|
- the same profile tracking
|
|
|
|
Do not create separate collection behavior for the two interfaces.
|
|
|
|
## PvP Stealing
|
|
|
|
Normal player-to-player stealing is separate from Vault Heist.
|
|
|
|
Detailed robbery balancing lives in:
|
|
|
|
``` text
|
|
COOKIE_LOGIC.md
|
|
```
|
|
|
|
The current model includes wealth scaling, victim heat, percentage-based
|
|
loot, a hard per-hit cap, and an hourly victim exposure budget.
|
|
|
|
## Persistent Game Settlement
|
|
|
|
For simple house games, settlement should still be protected against
|
|
repeated resolution.
|
|
|
|
For lifecycle-heavy multiplayer games such as Poker, Cookie movement is
|
|
separated from internal chip movement.
|
|
|
|
Poker only crosses the Cookie economy boundary for:
|
|
|
|
``` text
|
|
buy-in
|
|
cash-out / refund
|
|
```
|
|
|
|
Ordinary Poker betting modifies the table's internal stack state, not
|
|
`items_cookies`.
|
|
|
|
## Idempotent Operations
|
|
|
|
Recovery-sensitive economy flows can use operation IDs.
|
|
|
|
Poker temporarily stores markers such as:
|
|
|
|
``` js
|
|
appliedCookieOperations: [
|
|
"poker_buyin:...",
|
|
"poker_cashout:..."
|
|
]
|
|
```
|
|
|
|
The purpose is to prevent a retry after a crash from moving money twice.
|
|
|
|
Safe lifecycle:
|
|
|
|
``` text
|
|
apply Cookie operation once
|
|
→ persist authoritative game state
|
|
→ confirm operation is durably represented
|
|
→ remove temporary marker
|
|
```
|
|
|
|
Never remove a recovery marker before the surrounding state is safe.
|
|
|
|
When the final marker is removed, unset the empty field instead of
|
|
leaving:
|
|
|
|
``` js
|
|
appliedCookieOperations: []
|
|
```
|
|
|
|
## Economy Invariants
|
|
|
|
Every economy change should preserve:
|
|
|
|
``` text
|
|
No Cookie duplication.
|
|
No unexplained Cookie loss.
|
|
No duplicate debit.
|
|
No duplicate payout.
|
|
No spending below zero.
|
|
```
|
|
|
|
Correctness and recoverability take priority over cosmetic cleanup.
|