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

PreviousMarquee SystemNextTaunt System