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)
```bash
# 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)
```bash
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)
```bash
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:
```csharp
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!*