DeSqBlocki
201 lines
4.0 KiB
Markdown
201 lines
4.0 KiB
Markdown
# ShaiBot Profiles, Achievements & Badges
|
|
|
|
ShaiBot's profile system is the permanent progression layer behind the
|
|
economy and games.
|
|
|
|
## Central Profile System
|
|
|
|
`utils/profileSystem.js` owns the main profile/progression behavior.
|
|
|
|
Important collections:
|
|
|
|
``` text
|
|
stats_profiles
|
|
items_achievements
|
|
guild_badges
|
|
config_achievements
|
|
```
|
|
|
|
Game modules should integrate with this system instead of creating
|
|
separate progression databases.
|
|
|
|
## Profiles
|
|
|
|
Profiles can track:
|
|
|
|
- Overall game totals
|
|
- Per-game statistics
|
|
- Cookie gains and losses
|
|
- Giving and stealing
|
|
- Daily activity
|
|
- Win/loss streaks
|
|
- Weekday/time-of-day activity
|
|
- Social relationships
|
|
- Run It Back progression
|
|
- Poker history
|
|
- Achievement progress
|
|
- Badge ownership
|
|
|
|
Profiles are intended to preserve meaningful long-term history.
|
|
|
|
## Profile Events
|
|
|
|
Prefer extending established event metadata rather than inventing
|
|
parallel event systems.
|
|
|
|
Common concepts include:
|
|
|
|
``` text
|
|
game_start
|
|
game_result
|
|
cookie_gain
|
|
cookies_given
|
|
steal_success
|
|
stolen_from_me
|
|
```
|
|
|
|
New wager metadata should prefer:
|
|
|
|
``` text
|
|
wager
|
|
```
|
|
|
|
Compatibility reads for older `bet`/`previousBet` fields may remain
|
|
intentionally.
|
|
|
|
## Activity
|
|
|
|
Profile activity uses a configured timezone.
|
|
|
|
Default:
|
|
|
|
``` text
|
|
Europe/Berlin
|
|
```
|
|
|
|
Activity supports daily streaks, weekly participation, weekday counts,
|
|
and broad time buckets.
|
|
|
|
Avoid making ordinary progression depend on excessively narrow
|
|
late-night windows.
|
|
|
|
## Social Progression
|
|
|
|
Profiles can store unique relationship sets for gifting and stealing.
|
|
|
|
Use set-style updates for unique users rather than appending duplicates.
|
|
|
|
Current social progression is intentionally scaled for a relatively
|
|
small community.
|
|
|
|
## Achievements
|
|
|
|
Achievements are personal: multiple players can earn the same
|
|
achievement.
|
|
|
|
Supported models include:
|
|
|
|
### Stat-backed
|
|
|
|
Best for durable lifetime milestones and reconciliation.
|
|
|
|
### Composite
|
|
|
|
Combines multiple durable conditions.
|
|
|
|
### Event-only
|
|
|
|
Used when the accomplishment depends on exact event context that cannot
|
|
reliably be reconstructed later.
|
|
|
|
### Hidden
|
|
|
|
Used for secret/special challenges.
|
|
|
|
Event-only achievements should not be treated as historically
|
|
backfillable when the necessary event was never stored.
|
|
|
|
## Achievement Notifications
|
|
|
|
Unlock notification is centralized.
|
|
|
|
Individual games should not create competing achievement announcement
|
|
systems.
|
|
|
|
## Global Badges
|
|
|
|
Global badges are guild-unique distinctions.
|
|
|
|
The common pattern is an atomic claim against an unowned badge:
|
|
|
|
``` text
|
|
guildId
|
|
badgeId
|
|
ownerId: null
|
|
```
|
|
|
|
then setting the winner.
|
|
|
|
This prevents simultaneous candidates from both owning the same
|
|
guild-first badge.
|
|
|
|
Achievements and badges are intentionally different:
|
|
|
|
``` text
|
|
Achievement → personal; many owners
|
|
Global badge → guild-unique; one owner
|
|
```
|
|
|
|
## ID Stability
|
|
|
|
Once achievement or badge IDs may exist in MongoDB, treat them as
|
|
persistent database identifiers.
|
|
|
|
Prefer retiring an old definition over renaming/deleting an ID that
|
|
players may already own.
|
|
|
|
## Reconciliation & Audit
|
|
|
|
Administrative tooling includes:
|
|
|
|
``` text
|
|
/profileadmin audit
|
|
/profileadmin reconcile dry-run:true
|
|
```
|
|
|
|
Reconciliation can backfill durable/stat-backed accomplishments.
|
|
|
|
Event-only achievements may be skipped because historical event context
|
|
cannot be invented safely.
|
|
|
|
When changing progression schemas:
|
|
|
|
- use idempotent migrations
|
|
- preserve existing values
|
|
- preserve historical IDs
|
|
- dry-run reconciliation first
|
|
- do not fabricate data that was never tracked
|
|
|
|
## Poker History
|
|
|
|
Poker stores permanent statistics in the profile system rather than
|
|
retaining completed raw table documents.
|
|
|
|
Examples include:
|
|
|
|
- hands played/won/lost
|
|
- Cookies won/lost
|
|
- largest pot
|
|
- All-Ins
|
|
- showdowns
|
|
- action counts
|
|
- streaks
|
|
- hand-rank counters
|
|
- pocket Aces wins
|
|
- 7-2 wins
|
|
- fold wins
|
|
- full-table wins
|
|
|
|
Poker profile tracking occurs after authoritative game state succeeds. A
|
|
profile failure must never corrupt a valid pot/economy settlement.
|