ShaiBot/docs/PROGRESSION.md

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:

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:

game_start
game_result
cookie_gain
cookies_given
steal_success
stolen_from_me

New wager metadata should prefer:

wager

Compatibility reads for older bet/previousBet fields may remain intentionally.

Activity

Profile activity uses a configured timezone.

Default:

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:

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:

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:

/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.