Rewards System

Overview

The Rewards Distribution System provides a scriptable, animated way to show XP and loot rewards earned by players after battles. It creates a spectacular visual experience that can be debugged and replayed.

Architecture

Components

• RewardsScene - The main scene that displays the rewards animation

• Rewards Script - JSON object containing all reward data and timing

• Database Storage - battle_rewards_scripts table for persistence

• API Endpoints - For saving and retrieving reward scripts

Flow

WrapUpScene → RewardsScene → JoinScene

Rewards Script Structure

{
  "battleId": "battle_2024_001",
  "timestamp": "2024-01-15T10:30:00Z",
  "players": [
    {
      "id": "player_1",
      "name": "HeroName",
      "level": 5,
      "isRealHero": true,
      "heroId": 123,
      "imageUrl": "/path/to/hero/image.png",
      "matchStats": {
        "kills": 3,
        "deaths": 1,
        "damageDealt": 450,
        "survivalTime": 120
      },
      "rewards": {
        "xpEarned": 150,
        "leveledUp": true,
        "newLevel": 6,
        "lootItems": [
          {
            "itemId": "sword_001",
            "itemName": "Iron Sword",
            "rarity": "common",
            "quantity": 1
          }
        ],
        "specialFinds": [
          {
            "type": "unique",
            "message": "Unique Discovered!",
            "itemId": "unique_sword_001"
          }
        ]
      }
    }
  ],
  "globalTiming": {
    "playerTransitionDelay": 500,
    "totalDuration": 45000
  }
}

Animation Sequence

1

Player Highlight

Player is highlighted in the top lineup.

2

Stats Display

Shows match statistics (kills, damage, etc.).

3

XP Count-up

XP earned counts up from 0 with animation.

4

Level Up

If applicable, shows "LEVEL UP!" animation.

5

Loot Reveal

Loot items appear one by one with delays.

6

Special Finds

Special discoveries get dramatic announcements.

Database Schema

battle_rewards_scripts Table

CREATE TABLE "battle_rewards_scripts" (
  "id" char(36) NOT NULL,
  "battle_id" varchar(100) NOT NULL,
  "battle_date" timestamp NOT NULL DEFAULT CURRENT_TIMESTAMP,
  "script_json" longtext NOT NULL,
  "total_players" int NOT NULL DEFAULT 0,
  "total_xp_awarded" int NOT NULL DEFAULT 0,
  "total_loot_items" int NOT NULL DEFAULT 0,
  "created_at" timestamp NOT NULL DEFAULT CURRENT_TIMESTAMP,
  "updated_at" timestamp NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
  PRIMARY KEY ("id"),
  UNIQUE KEY "uniq_battle_id" ("battle_id")
);

API Endpoints

Save Rewards Script

POST /api/battles/save-rewards-script

Body:

{
  "battleId": "battle_2024_001",
  "scriptJson": { /* rewards script object */ },
  "totalPlayers": 8,
  "totalXpAwarded": 1200,
  "totalLootItems": 15
}

Get Rewards Script

GET /api/battles/rewards-script/:battleId

Get Recent Scripts

GET /api/battles/recent-rewards-scripts?limit=10

Delete Script

DELETE /api/battles/rewards-script/:battleId

Features

Visual Effects

• Player Lineup - All players displayed across top of screen

• Scaling - Players automatically scaled to fit screen

• Highlighting - Current player gets glow and scale effects

• XP Animation - Smooth count-up with pop effect

• Level Up - Dramatic "LEVEL UP!" animation

• Loot Items - Color-coded by rarity with reveal animations

• Special Finds - Large animated messages for unique items

Rarity Colors

• Common - Gray (#808080)

• Uncommon - Green (#00FF00)

• Rare - Blue (#0080FF)

• Epic - Purple (#8000FF)

• Legendary - Orange (#FF8000)

• Unique - Red (#FF0000)

Timing Controls

• Player Transition - 500ms delay between players

• XP Count-up - ~2 seconds for count animation

• Level Up - 2 seconds display duration

• Loot Reveal - 800ms between items

• Special Finds - 2 seconds display duration

Debugging & Replay

Rewards scripts are automatically saved to the database and can be:

• Retrieved by battle ID for replay

• Listed in recent scripts for debugging

• Deleted if no longer needed

This allows developers to:

• Debug reward calculations

• Test different reward scenarios

• Replay specific battles

• Analyze reward distribution patterns

Integration

The system integrates with:

• BattleStateManager - Gets player data and battle info

• WrapUpScene - Generates rewards script and transitions

• GameScene - Provides match statistics (when implemented)

• Hero System - Uses real hero data for authentic rewards

Future Enhancements

• Real Match Stats - Integrate with GameScene for actual performance data

• Custom Animations - Allow theme-specific reward animations

• Sound Effects - Add audio feedback for rewards

• Particle Effects - Enhanced visual effects for special finds

• Reward History - Player-specific reward tracking

• Achievement System - Integration with achievement unlocks