Skip to main content

Wallet & Coin System

Learn how the economy works in La Légende des Trois Gardiens and manage your hard-earned coins.

Overview​

The Wallet System is your personal economy manager, tracking coins earned through gameplay and managing future spending.

Key Features:

  • 💰 Server-backed balance (persistent across devices)
  • 📊 Transaction history (immutable ledger)
  • 🔄 Real-time updates
  • 📴 Offline fallback display

What Are Coins?​

Coins are the primary currency in La Légende des Trois Gardiens.

How to Earn Coins​

Primary Method: Complete Challenges

Your Score = Coins Earned

Examples:

  • Score 1000 points → Earn 1000 coins
  • Score 5432 points → Earn 5432 coins
  • Score 0 points (fail) → Earn 0 coins

Earning Factors:

  • Challenge difficulty (harder = higher potential)
  • Your performance (score-based)
  • Bonus objectives (perfect runs, time bonuses)
  • No random chance - pure skill-based

Success vs. Failure​

Success (Challenge Completed):

  • ✅ Score recorded
  • ✅ Coins awarded (score amount)
  • ✅ Progress tracked
  • ✅ Can replay for improvement

Failure (Challenge Not Completed):

  • ❌ No coins awarded
  • ❌ Score not saved
  • ✅ Can retry immediately
  • ✅ No penalty or cost

Key Point: Failing doesn't cost you anything - just try again!

Wallet Interface​

Viewing Your Balance​

Quick View: Bottom Navigation

  • 💰 Coin icon with number
  • Always visible
  • Updates in real-time
  • Tap for details

Detailed View: Inventory Page

  • Full balance display
  • Transaction history
  • Earning statistics
  • Recent activity

Balance Display States​

Normal:

  • Shows current balance
  • Updated after each challenge
  • Exact coin count

Loading:

  • Small spinner or animation
  • During server sync
  • Brief (< 1 second normally)

Offline:

  • Shows cached balance
  • "(Offline)" indicator
  • Syncs when connection restored

Error:

  • Last known balance
  • Error message if critical
  • Retry option

Transaction System​

Transaction Types​

EARN - Challenge Completion​

Source: Game challenges
Amount: Equal to score
Recorded: Immutable ledger entry
Linked to: Specific attempt ID

Details Stored:

  • Challenge ID
  • Score achieved
  • Timestamp
  • Attempt reference

SPEND - Future Features​

Purpose: Shop, upgrades, etc.
Status: Planned
Validation: Sufficient balance required

BONUS - Special Awards​

Sources:

  • Achievements
  • Events (future)
  • Special milestones
  • Daily login rewards (planned)

Transaction History​

Accessing History:

  1. Go to Inventory page
  2. Scroll to transaction section
  3. View recent activity
  4. Paginated for performance

Information Displayed:

  • Transaction type (EARN/SPEND/BONUS)
  • Amount (+/- coins)
  • Source (challenge name)
  • Date and time
  • Running balance

Features:

  • Immutable records (never deleted)
  • Complete audit trail
  • Filter by type (future)
  • Export option (planned)

Server-Backed System​

Why Server-Based?​

Benefits:

  1. Persistence - Never lose progress
  2. Sync - Same balance on all devices
  3. Security - Prevents cheating
  4. Reliability - Authoritative source of truth

Technical Details:

  • Database transaction for each earn
  • Idempotency protection (no double-awards)
  • Real-time balance calculation
  • Automatic conflict resolution

How It Works​

When You Complete a Challenge:

1. Game completes on your device
   ↓
2. Score submitted to server (POST /api/v1/scores)
   ↓
3. Server validates score
   ↓
4. Server creates attempt record
   ↓
5. Server awards coins (transaction created)
   ↓
6. Server updates user balance
   ↓
7. Response sent to your device
   ↓
8. UI updates with new balance

Guaranteed Once:

  • Unique constraint on attempt ID
  • Even if you submit twice, coins awarded once
  • Database-level protection

Synchronization​

Cross-Device Sync:

  • Play on phone, see balance on tablet
  • Instant synchronization
  • No manual sync required
  • Works when online

Offline → Online:

  • Play offline (if cached)
  • Scores stored locally
  • Sync when connection returns
  • Seamless experience

Coin Management​

Current Balance​

Viewing:

  • Bottom menu: Quick glance
  • Inventory page: Full detail
  • Profile page: Progress context

Updating:

  • Automatic after challenges
  • Manual refresh option
  • Real-time event system

Maximizing Earnings​

Strategies:

1. Replay for Higher Scores

  • Replay any challenge
  • New score = new coins (if higher)
  • Previous best still counts
  • No limit on attempts

2. Target High-Difficulty Challenges

  • Harder challenges = higher score potential
  • Practice to master them
  • Risk vs. reward balance

3. Perfect Runs

  • Bonus points for perfection
  • Time bonuses
  • No-damage runs
  • Combo multipliers

4. Daily Play

  • Consistent practice improves skills
  • Better skills = higher scores
  • Future: Daily bonuses (planned)

5. Multiplayer Bonuses

  • Team challenges (future)
  • Cooperative bonuses
  • Social play rewards

Spending (Future Features)​

Planned Uses:

  • Cosmetic items
  • Power-ups
  • Character customization
  • Special challenge unlocks
  • Hints or helps

Not Planned:

  • Pay-to-win mechanics
  • Required purchases for progression
  • Consumable advantages

Philosophy:

  • Coins enhance, don't gate
  • All content accessible via play
  • Optional spending only

Wallet Statistics​

Tracking Your Earnings​

Available Stats:

  • Total coins earned (lifetime)
  • Average coins per challenge
  • Best single-challenge earnings
  • Earning rate trends
  • Coins by challenge type

Future Analytics:

  • Daily earning charts
  • Weekly/monthly summaries
  • Comparison with average players
  • Personal records

Potential Milestones:

  • First 1,000 coins
  • First 10,000 coins
  • 100,000 coins earned
  • Specific earning rates
  • Consecutive high-score challenges

Troubleshooting​

Balance Not Updating​

Check:

  1. Internet connection active?
  2. Challenge completed (not failed)?
  3. Result screen showed coins?
  4. Wait a few seconds for sync

Solutions:

  • Refresh the page
  • Check Inventory page for update
  • Verify transaction history
  • Contact support if missing

Coins Disappeared​

Unlikely but check:

  1. Review transaction history
  2. Check all devices (maybe different account?)
  3. Verify you completed challenge
  4. Server maintenance? (rare)

Reality:

  • Coins never disappear
  • Immutable ledger
  • Server-backed security
  • Transaction history proves earning

Offline Play Concerns​

What Happens:

  • Balance displays last known amount
  • Can still play cached challenges
  • Scores stored locally
  • Sync when online

After Reconnecting:

  • Local scores submitted
  • Coins awarded for successes
  • Balance updates
  • Full sync completes

Best Practices​

Maximizing Your Wallet​

Do:

  • ✅ Complete challenges successfully
  • ✅ Replay for higher scores
  • ✅ Master motion controls
  • ✅ Try all challenge types
  • ✅ Stay online when possible

Don't:

  • ❌ Worry about losing coins
  • ❌ Rush through challenges
  • ❌ Ignore practice opportunities
  • ❌ Focus only on one challenge type

Long-Term Strategy​

Early Game:

  • Build initial coin reserves
  • Try all challenges
  • Find your strengths
  • Don't worry about optimal play

Mid Game:

  • Replay favorites for higher scores
  • Target high-value challenges
  • Balance variety and mastery
  • Save for future features

Late Game:

  • Perfect remaining challenges
  • Chase high scores
  • Help others in multiplayer
  • Maintain healthy balance

Security & Fairness​

Anti-Cheat​

Protections:

  • Server validates all scores
  • Reasonable score ranges
  • Rate limiting
  • Anomaly detection

Fair Play:

  • Everyone earns the same way
  • Skill determines earnings
  • No shortcuts
  • Transparent system

Privacy​

Your Data:

  • Balance is private (yours only)
  • Transaction history private
  • Optional leaderboards (future)
  • No selling of data

Future Enhancements​

Planned Features:

  • Spending marketplace
  • Gift coins to friends
  • Team wallet (multiplayer)
  • Coin-based challenges
  • Trading system (maybe)
  • Seasonal bonuses

Under Consideration:

  • Multiple currencies
  • Premium currency (no pay-to-win)
  • Conversion systems
  • External rewards (merchandise?)

API Reference (Technical)​

For developers interested in the wallet system:

Endpoints:

  • GET /api/v1/wallet - View balance and history
  • POST /api/v1/scores - Submit score, earn coins
  • POST /api/v1/wallet/spend - Spend coins (future)

Events:

  • wallet:invalidate - Triggers UI refresh

Next Steps​

Learn more about the game economy:

Pro Tip: Don't hoard coins waiting for future features - mastering challenges is the real goal. Coins are just a bonus reward for your skills!