rr3-server/DAILY_REWARDS_FEATURE.md

RR3 Community Server - Daily Rewards & Time Trials Feature

✅ New Features Added

Based on user feedback, the server now includes essential single-player progression features:

🎁 Daily Rewards System

• Daily login rewards with Gold and Cash
• Streak tracking - consecutive days increase rewards
• 24-hour cooldown - one reward per day
• Auto-reset - new reward available each day
• Web panel management - view all claims and statistics

⏱️ Daily Time Trials

• Racing events with target times
• Gold and Cash rewards for beating targets
• Multiple active events at once
• Custom tracks and cars - fully configurable
• Leaderboard-ready - results are stored
• Web panel management - create, edit, activate/deactivate events

💰 Gold Purchase System

• FREE gold purchases in community server (no real money)
• Multiple denominations: 100, 500, 1000, 5000 Gold
• Instant delivery - added immediately to account
• Purchase history - all transactions logged
• Perfect for offline play - no microtransactions needed

📦 What's NOT Included

As requested, the following features are NOT implemented:

• ❌ Race teams / crews
• ❌ Multiplayer racing
• ❌ Social features
• ❌ Online leaderboards (could be added later)

🔧 Technical Implementation

New API Endpoints

Rewards Controller (/synergy/rewards)

GET  /synergy/rewards/daily/{synergyId}              - Get daily reward status
POST /synergy/rewards/daily/{synergyId}/claim        - Claim daily reward
POST /synergy/rewards/gold/purchase                  - Purchase gold (FREE)
GET  /synergy/rewards/timetrials                     - Get active time trials
POST /synergy/rewards/timetrials/{id}/submit         - Submit time trial result

New Database Tables

DailyReward

• UserId, RewardDate, GoldAmount, CashAmount
• Claimed, ClaimedAt, Streak

TimeTrial

• Name, TrackName, CarName
• StartDate, EndDate, TargetTime
• GoldReward, CashReward, Active

TimeTrialResult

• UserId, TimeTrialId, TimeSeconds
• SubmittedAt, BeatTarget
• GoldEarned, CashEarned

User (Updated)

• Added Gold and Cash fields
• Tracks player currency

New Web Panel Pages

/admin/rewards

• View daily reward statistics
• Manage time trial events
• Create new racing challenges
• Activate/deactivate events
• View recent reward claims
• See trial completion statistics

🎮 How It Works

Daily Rewards Flow

1. Player opens game → Calls /rewards/daily/{synergyId}
2. Server checks if reward available today
3. If available → Player claims via /rewards/daily/{synergyId}/claim
4. Gold & Cash added to account immediately
5. Streak counter incremented
6. Next reward available in 24 hours

Time Trial Flow

1. Game fetches active events → /rewards/timetrials
2. Player completes race with recorded time
3. Time submitted → /rewards/timetrials/{id}/submit
4. Server checks if beat target time
5. Rewards granted based on performance:
   • Beat target: Full gold + cash reward
   • Didn't beat: Half cash (participation reward)

Gold Purchase Flow

1. Player opens store → Views gold packages (catalog)
2. Player "purchases" gold → /rewards/gold/purchase
3. Server adds gold to account for FREE
4. Transaction logged in purchase history
5. Instant delivery - no payment processing

📊 Default Configuration

Daily Rewards (Default)

• Gold: 50 per day
• Cash: 5,000 per day
• Streak bonus: +10 gold per consecutive day (potential feature)

Seeded Time Trials

1. Daily Sprint Challenge

   • Track: Silverstone National
   • Target: 90.5 seconds
   • Rewards: 50 Gold, $10,000 Cash

2. Speed Demon Trial

   • Track: Dubai Autodrome
   • Target: 120.0 seconds
   • Rewards: 100 Gold, $25,000 Cash

Gold Packages (Catalog)

• 100 Gold - FREE
• 500 Gold - FREE
• 1,000 Gold - FREE
• 5,000 Gold - FREE

🌐 Web Panel Features

Rewards Dashboard

• Statistics cards: Today's claims, active events, gold distributed, completions
• Time Trial management: Create, edit, activate, deactivate, delete events
• Reward history: View all daily reward claims with streaks
• Quick actions: All management in one place

Create Time Trial Event

Modal form with fields:

• Event name
• Track name
• Car requirement
• Start/end dates
• Target time
• Gold reward
• Cash reward
• Active status

Statistics Tracking

• Total gold distributed
• Daily claim counts
• Time trial completion rates
• User streak tracking

💾 Database Migration

The database schema has been updated with new tables. On first run with the new code:

1. Automatic migration - EF Core will create new tables
2. Seed data - 2 time trials and 4 gold packages created
3. Existing data preserved - All users, sessions, purchases intact
4. Backward compatible - Old functionality unchanged

If you encounter issues, reset database via Settings page.

🚀 Usage Examples

Get Daily Reward (API)

# Check reward status
curl http://localhost:5000/synergy/rewards/daily/USER123

# Response:
{
  "available": true,
  "gold": 50,
  "cash": 5000,
  "streak": 3,
  "nextRewardIn": 0
}

# Claim reward
curl -X POST http://localhost:5000/synergy/rewards/daily/USER123/claim

# Response:
{
  "success": true,
  "goldEarned": 50,
  "cashEarned": 5000,
  "totalGold": 150,
  "totalCash": 25000,
  "streak": 4
}

Purchase Gold (API)

curl -X POST http://localhost:5000/synergy/rewards/gold/purchase \
  -H "Content-Type: application/json" \
  -d '{
    "synergyId": "USER123",
    "goldAmount": 1000,
    "sku": "com.ea.rr3.gold_1000"
  }'

# Response:
{
  "success": true,
  "goldPurchased": 1000,
  "totalGold": 1150,
  "orderId": "abc-123-def",
  "message": "Gold added to your account (FREE in community server!)"
}

Submit Time Trial (API)

curl -X POST http://localhost:5000/synergy/rewards/timetrials/1/submit \
  -H "Content-Type: application/json" \
  -d '{
    "synergyId": "USER123",
    "timeSeconds": 88.5
  }'

# Response:
{
  "success": true,
  "beatTarget": true,
  "timeSeconds": 88.5,
  "targetTime": 90.5,
  "goldEarned": 50,
  "cashEarned": 10000,
  "totalGold": 1200,
  "totalCash": 35000,
  "message": "🏆 Target time beaten!"
}

📝 Configuration Options

Adjust Daily Rewards

Edit RewardsController.cs line 35-36:

GoldAmount = 50,     // Change gold amount
CashAmount = 5000,   // Change cash amount

Add More Time Trials

Use web panel at /admin/rewards or seed data in RR3DbContext.cs

Change Gold Packages

Edit catalog items in web panel /admin/catalog

🎯 Perfect For

• ✅ Offline play - All rewards work without internet
• ✅ Solo progression - Focus on single-player experience
• ✅ No microtransactions - Everything is free
• ✅ Game preservation - Keep progression features working
• ✅ Testing - Give yourself gold for testing purposes
• ✅ Fair gameplay - No pay-to-win mechanics

🔮 Future Enhancements (Optional)

• Weekly challenges with bigger rewards
• Achievement system
• Car collection tracking
• Progressive streak bonuses
• Special event time trials
• Season pass simulation
• VIP rewards
• Bonus weekend events

📚 Related Files

New Files

• Controllers/RewardsController.cs - API endpoints
• Pages/Rewards.cshtml - Web panel page
• Pages/Rewards.cshtml.cs - Page logic
• Data/RR3DbContext.cs - Updated with new entities

Modified Files

• Pages/_Layout.cshtml - Added Rewards link
• Pages/Admin.cshtml - Added Rewards button
• Controllers/DirectorController.cs - Added rewards service URL

✅ Summary

Your friend can now enjoy:

• Daily login rewards for Gold and Cash
• Time trial events to earn more currency
• FREE gold purchases - no real money needed
• Clean single-player focus - no teams, no multiplayer

All features are fully functional, web-managed, and ready to use! 🏎️💨

---

Built for the RR3 community - focused on what matters: racing and progression!