SeasonalShop

SeasonalShop is a seasonal cosmetics shop for Paper 1.21.9 (Java 21). Players can purchase cosmetic rewards using your server's economy through Vault, while the plugin automatically switches between seasons based on the current month.

✨ Features

• Automatic season detection based on the current month.
  
  
• Seasonal GUI shop.
  
  
• Uses your server economy through Vault.
  
  
• Cosmetic rewards:
  
  • Titles
  • Particles
  • Trails
  • Custom cosmetics
• ✨ Equip and unequip purchased cosmetics at any time.
  
  
• Configurable purchase broadcast messages.
  
  
• Optional chat title formatting.
  
  
• Automatic season switching.
  
  
• Spending leaderboard.
  
  
• Full PlaceholderAPI support.
  
  
• ⚙️ Fully configurable through config.yml.
  

Requirements

• Paper 1.21.9
• Java 21
• Vault
• EssentialsX (economy provider)
• PlaceholderAPI

These dependencies are required for the plugin to load.

Commands
Command Description
/shop Opens the current season shop.
/shop reload Reloads the configuration.
/shop season <id|auto> Forces a season or enables automatic detection.
/shop give <player> <item> Gives a shop item without charging.
/shop equip <item> Equips or unequips a purchased cosmetic.
/shop list Lists all items available in the current season.
Seasons
Each season is configured inside config.yml using a list of active months.

Example:

spring:
active-months: [3,4,5]

The plugin checks the current month automatically and activates the corresponding season. If no season matches, the configured default season is used.

Cosmetics
Supported cosmetic types:

• TITLE
• PARTICLE
• TRAIL
• COSMETIC

Purchased cosmetics can be equipped or unequipped whenever the player wants.

PlaceholderAPI
Global placeholders

• %seasonalshop_season%
• %seasonalshop_season_display%
• %seasonalshop_season_item_count%
• %seasonalshop_auto_detection%
• %seasonalshop_next_season%
• %seasonalshop_days_left_in_month%
• %seasonalshop_top_spender%
• %seasonalshop_top_spender_amount%
• %seasonalshop_rank_<n>%
• %seasonalshop_price_<item>%
• %seasonalshop_name_<item>%

Player placeholders

• %seasonalshop_active_title%
• %seasonalshop_active_particle%
• %seasonalshop_active_trail%
• %seasonalshop_purchase_count%
• %seasonalshop_total_spent%
• %seasonalshop_balance%
• %seasonalshop_my_rank%
• %seasonalshop_owns_<item>%

⚙️ Configuration
Everything can be customized from config.yml, including:

• Seasons
• Shop items
• Prices
• Broadcast messages
• Chat title format
• GUI appearance
• Automatic season detection

SeasonalShop is designed to be lightweight, easy to configure, and simple to integrate into any Paper server using Vault and PlaceholderAPI.

⚠️ Important: Make sure Vault, EssentialsX, PlaceholderAPI, and LuckPerms are installed before starting the server. SeasonalShop depends on these plugins and will not load correctly if any of them are missing.