Medal System v1.0

Setup & Asset Placement
Getting started is entirely plug-and-play. Just drop the assets into these specific locations:

• ReplicatedStorage: Move the "Medals" (image assets) and "Events" (RemoteEvents) folders here.
• ServerScriptService: Move the main "Medal System" script and the "SETUP" here.
• StarterGui: Place the "Medal UI" ScreenGui here to handle client-side rendering.

Centralized Configuration​

You can easily fine-tune the game balance and visual layout directly at the top of the scripts:

• The Combo Engine (Server Module):
  • MAX_DURATION (Default: 15s) – The time window a player gets after their first kill.
  • MIN_DURATION (Default: 3s) – The absolute tightest the time window shrinks to at a high kill spree.
  • SHORTEN_AMOUNT (Default: 0.5s) – How many seconds get shaved off the timer window with each consecutive kill.
• The Interface Engine (Client Script):
  • TWEEN_DURATION – Sets the animation speed for pop-ups and sliding transitions.
  • MEDAL_LIFESPAN – Controls how long a medal stays on screen before destroying itself.
  • SHIFT_OFFSET_X – Controls pixel spacing between active badges to prevent UI overlapping during fast multi-kills.

Developer API Reference​

Integrating this into your custom weapon or combat scripts takes only a few server-side lines:

1. Initialize Profile: Run MedalService.SetupPlayer(Player) inside your PlayerAdded event to open their session data tracking.
2. Standard Kill: Call MedalService.AwardMedal(Player) on an enemy's defeat to automatically step up their combo count and fire the UI.
3. Special Achievements: Pass an extra string like MedalService.AwardMedal(Player, "HEADSHOT") to grant specific, conditional badges simultaneously.
4. Data Cleanup: Call MedalService.RemovePlayer(Player) inside your PlayerRemoving event to purge data vectors and safely prevent server memory leaks.

Important: You must wrap this inside your weapon/damage script's health check (e.g., checking if Humanoid.Health <= 0) to ensure the medal is only awarded exactly when the target player dies.

Modular Scalability​

Adding custom achievements is completely streamlined. If you want to add a new reward type (such as "WALLBANG"), you only need to run MedalService.AwardMedal(Player, "WALLBANG") in your script and drop an image asset named "WALLBANG" right into ReplicatedStorage.Medals. The client-side UI handles the layout rendering automatically.

Questions or Suggestions? Let me know!