CraftChallenge v1.0.0

CraftChallenge | Competitive Crafting Events Plugin

A feature-rich competitive crafting system with team and individual modes, real-time leaderboards, milestone celebrations, tiered rewards, challenge templates, countdown timers, and comprehensive tracking - turn crafting into an engaging community event that brings players together.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

What Does CraftChallenge Do?

CraftChallenge transforms the simple act of crafting into exciting community-wide events where players compete or cooperate to reach crafting goals. Whether racing individually to craft the most diamond swords or working together as a team to reach 10,000 iron ingots, CraftChallenge creates engaging events with real-time leaderboards, milestone celebrations, and generous rewards that keep your community active and motivated.

The Problem: Minecraft crafting is often a solitary, repetitive activity. Players craft items when needed but rarely engage with the crafting system as a community activity. Server owners struggle to create engaging events that encourage resource gathering, promote economy activity, and bring the community together. Traditional events require manual tracking, lack visual feedback, and offer no way to create recurring challenges.

The Solution: CraftChallenge provides a complete event system where admins create crafting challenges with specific items and target amounts (e.g., "Craft 1,000 Diamond Swords in 7 days"). Players participate by crafting normally, with automatic tracking, real-time leaderboards showing who's contributing most, milestone announcements celebrating progress, and automatic reward distribution when goals are reached. Two modes (Team vs Individual) support different playstyles, while template system allows recurring events, and comprehensive configuration makes every aspect customizable.

How It Works:
1. Admin creates challenge: /challenge create DIAMOND_SWORD 1000 team 7d
2. Optional countdown timer builds excitement (10...5...3...2...1...GO!)
3. Challenge starts - scoreboard appears showing progress and rankings
4. Players craft items normally - progress tracked automatically
5. Milestone announcements celebrate 25%, 50%, 75%, 90% completion
6. Real-time leaderboard updates showing top contributors
7. Goal reached - automatic reward distribution based on ranks/contribution
8. Challenge completes - final standings announced, rewards given

Perfect For:
[*]Survival servers creating community events
[*]Economy servers driving resource gathering
[*]Competitive servers with player rankings
[*]Skyblock servers with progression milestones
[*]Community servers building engagement
[*]Any server wanting recurring crafting events

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Core Features

Two Challenge Modes
[*]Team Mode: Everyone works together

• Collective goal (e.g., "Server crafts 10,000 Iron Ingots")
• All contributions count toward single target
• Progress shown as community achievement
• Milestone celebrations bring server together
• Rewards based on contribution percentage
• Perfect for building community spirit

[*]Individual Mode: Competitive racing

• Same goal, different winners (e.g., "First to craft 100 Enchanted Books")
• Players compete for top ranks
• Leaderboard shows who's ahead
• Top 3 get special rewards
• Rank-based reward distribution
• Perfect for competitive players

Example:

Real-Time Leaderboard System
[*]Live Scoreboard: Always visible progress

• Displays current challenge info (goal, time remaining)
• Shows server-wide progress (500/1000 crafted)
• Top 3 contributors with amounts
• Your personal progress and rank
• Updates every 30 seconds (configurable)
• Sidebar integration

[*]GUI Leaderboard: Detailed view

• Open with /challenge leaderboard
• Shows top 21 players with medals ()
• Challenge info display (goal, progress, time)
• Your stats highlighted ("← YOU")
• Your rank and contribution percentage
• Visual item display

[*]Tab List Integration: Optional display

• Show progress in tab list
• Configurable format
• Real-time updates

Example Scoreboard:

Comprehensive Reward System
[*]Rank-Based Rewards: Top performers

• 1st Place: Custom items + commands
• 2nd Place: Lesser tier rewards
• 3rd Place: Participation rewards
• Top 10: Configurable tiers
• Automatic distribution on completion

[*]Contribution-Based Rewards: Participation tiers

• High Contribution (30%+): Tier 1 rewards
• Medium Contribution (10-30%): Tier 2 rewards
• Low Contribution (1-10%): Tier 3 rewards
• Everyone who participates gets something
• Fair distribution system

[*]Custom Reward Items: Rich customization

• Custom display names
• Custom lore (multiple lines)
• Enchantments (any level)
• Multiple items per reward
• Amount configuration

[*]Command Rewards: Integration flexibility

• Execute commands on reward
• Economy integration (Vault)
• Permission grants
• Title/rank upgrades
• Multiple commands per reward
• Placeholders: {player}, {rank}, {amount}

Example:

Challenge Template System
[*]Preset Challenges: Recurring events

• Define templates with all settings
• Quick start: /challenge start weekly-diamond-sword
• Save common challenges
• Consistent events
• Easy management

[*]Template Configuration: Complete presets

• Item type
• Target amount
• Mode (team/individual)
• Duration
• Reward presets
• All settings saved

[*]Common Templates: Examples

• Weekly Diamond Sword (1000 swords, 7 days, team)
• Daily Iron Rush (5000 ingots, 24h, team)
• Race to 100 Books (100 books, unlimited, individual)
• Custom templates unlimited

Example:

Smart Countdown System
[*]Pre-Challenge Countdown: Build excitement

• Configurable duration (default: 10 seconds)
• Broadcast at specific intervals (10, 5, 3, 2, 1)
• "GO!" message on start
• Optional feature (enable/disable)
• Perfect for scheduled events

[*]Custom Messages: Your branding

• Countdown messages customizable
• Plural handling ("1 second" vs "5 seconds")
• Color coding
• Title/subtitle support (optional)

Example:

Milestone Celebration System
[*]Progress Milestones: Celebrate achievements

• Configurable percentages (25%, 50%, 75%, 90%, 100%)
• Server-wide broadcast announcements
• Shows current progress vs target
• Keeps players motivated
• Creates excitement

[*]Personal Milestones: Individual tracking

• Notify every X items crafted (default: 10)
• Shows your total contribution
• Displays your current rank
• Private messages
• Encourages continued participation

[*]Time Warnings: Urgency creation

• Warnings at specific times (60min, 30min, 10min, 5min, 1min)
• "Time running out!" messages
• Broadcast to all players
• Increases activity near deadline
• Configurable warning times

Example:

Time Management Features
[*]Flexible Duration: Time limits

• Time-limited: 1h, 6h, 24h, 7d, 30d (any duration)
• Unlimited: No time limit (first to goal wins)
• Format: XdXhXm (e.g., "7d" = 7 days, "2h30m" = 2.5 hours)
• Real-time countdown display
• Automatic expiration

[*]Pause/Resume: Event control

• /challenge pause - Temporarily stop tracking
• /challenge resume - Continue challenge
• Maintains all progress
• Time freezes during pause
• Perfect for maintenance or issues

[*]Time Display: Clear information

• Days/hours format: "2d 5h"
• Hours/minutes format: "5h 30m"
• Minutes/seconds format: "45m 20s"
• Seconds format: "30s"
• "Unlimited" for no time limit

Comprehensive Management Commands
[*]Creation Commands: Start events

• /challenge create <item> <amount> <mode> [duration]
• /challenge start [template]
• /challenge stop
• /challenge cancel

[*]Control Commands: Event management

• /challenge pause
• /challenge resume
• /challenge info
• /challenge setreward <placement> <preset>

[*]Player Commands: Participation

• /challenge leaderboard (GUI)
• /challenge info
• /challenge top

[*]Admin Commands: Configuration

• /challenge reload
• /challenge template <create|load|save>
• /challenge debug

Smart Progress Tracking
[*]Automatic Detection: No player action needed

• Tracks all crafting automatically
• Shift-click support (mass crafting)
• Calculates exact amounts
• Updates instantly
• No manual claims

[*]Rank System: Dynamic rankings

• Real-time rank calculation
• Rank-up notifications
• Rank-down alerts
• Shows rank in all displays
• Competitive motivation

[*]Contribution Tracking: Detailed stats

• Individual amount crafted
• Percentage of total
• Personal vs team progress
• Historical data
• Persistent across sessions

[*]Safety Features: Fair tracking

• Creative mode prevention (optional)
• Goal cap (no over-counting after completion)
• Remaining calculation (only count needed amount)
• Duplicate prevention

Persistent Data Storage
[*]Storage Options: Reliable saving

• YAML (flat-file, simple)
• MySQL (database, scalable) - coming soon
• Auto-save intervals (default: 5 minutes)
• Manual save on stop/complete

[*]Data Saved: Complete state

• Active challenge details
• All player progress
• Challenge state (active/paused/completed)
• Time remaining
• Milestone announcements (prevents repeat)
• Warning announcements

[*]Crash Recovery: Data protection

• Challenges reload on restart
• Progress persists
• Time tracking continues
• No data loss

Vault Integration
[*]Economy Rewards: Money prizes

• Give money commands in rewards
• Configurable amounts per tier
• Placeholder support
• Automatic distribution

Example:

PlaceholderAPI Support
[*]Available Placeholders:

• %craftchallenge_active% - Is challenge active?
• %craftchallenge_item% - Challenge item name
• %craftchallenge_target% - Target amount
• %craftchallenge_current% - Current progress
• %craftchallenge_percentage% - Progress percentage
• %craftchallenge_time_remaining% - Time left
• %craftchallenge_player_amount% - Your contribution
• %craftchallenge_player_rank% - Your rank
• %craftchallenge_top1_player% - 1st place player
• %craftchallenge_top1_amount% - 1st place amount

[*]Use Cases: Integration everywhere

• Scoreboard displays
• Tab lists
• Chat prefixes
• Holograms
• GUIs from other plugins

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Commands

Admin Commands

Player Commands

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Permissions


━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Configuration

Main Config (config.yml)

Templates (templates.yml)

Rewards (rewards.yml)

Messages (messages.yml)

Leaderboard Display (leaderboard.yml)

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Use Case Examples

Weekly Community Event
Use Case: Weekly event builds community. 7-day duration lets everyone participate. Team mode means everyone contributes to single goal. Top 3 get rank rewards, high contributors get participation rewards. Countdown builds excitement on launch day.

Daily Iron Rush
Use Case: Daily event keeps server active. 5,000 iron is achievable in 24 hours. Simple milestone announcements (50%, 100%). Everyone who participates gets $100. Drives economy activity and resource gathering.

Competitive Race
Use Case: Weekend competition creates excitement. Individual mode means players compete directly. 100 swords is challenging but achievable. Fast leaderboard updates show who's winning. VIP permission for 1st place is strong motivation.

Resource Dump Event
Use Case: Unlimited duration means no pressure. 50,000 iron absorbs excess server resources. More milestone announcements keep motivation. Contribution tiers reward active participants proportionally.

Skyblock Progression
Use Case: Challenging item (Enchanted Golden Apples) fits Skyblock difficulty. Small target (10) but hard to achieve. Frequent milestones maintain engagement. Island level rewards integrate with Skyblock progression.

PvP Server - Weapon Supply
Use Case: 12-hour event fits PvP server schedule. 500 swords supplies server arsenal. 1-minute countdown alerts players event is starting. Top contributors get free enchanted weapons. Supports faction wars.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Event Flow

1. Challenge Creation

• Admin types /challenge create DIAMOND_SWORD 1000 team 7d
• System validates item exists and is craftable
• Challenge created with ID (challenge_timestamp)
• Display name formatted (Diamond Sword)
• Target amount set (1,000 swords)
• Mode set (TEAM)
• Duration calculated (7 days from start)
• State set to CREATED (not started yet)
• Challenge saved to active.yml

2. Pre-Start Countdown

• Admin types /challenge start
• If countdown enabled: Countdown begins (default: 10 seconds)
• Broadcast at intervals: "Starting in 10 seconds..."
• Broadcast at 5, 3, 2, 1 seconds
• Final message: "GO! Challenge has started!"
• If countdown disabled: Starts immediately

3. Challenge Activation

• Start time recorded (System.currentTimeMillis())
• End time calculated (start + 7 days)
• State changed to ACTIVE
• Progress cleared (0/1000)
• Milestone flags cleared
• Warning flags cleared
• Broadcast: "Challenge started! Goal: Diamond Sword x1000"
• Scoreboard appears for all players
• Tracking begins

4. Player Participation

• Player crafts Diamond Sword normally
• CraftListener detects crafting event
• Checks: Is challenge active? Is correct item? Is creative mode?
• Calculates amount (handles shift-click mass crafting)
• Caps amount at remaining target (no over-counting)
• Adds progress to player's individual count
• Updates total challenge progress
• Recalculates ranks (old rank vs new rank)
• Updates scoreboard for that player

5. Personal Notifications

• Every 10 items crafted (configurable)
• Player receives message: "+1 Diamond Sword | Total: 45 | Rank: #3"
• Rank-up notification if rank improved: "Congratulations! You're now rank #2"
• Private messages (not broadcast)
• Keeps player motivated

6. Milestone Celebrations

• Progress reaches 25% (250/1000)
• System checks if 25% milestone already announced
• If not announced: Broadcast server-wide
• Message: "Milestone! 25% complete (250/1000)"
• Milestone marked as announced (prevents repeat)
• Repeats for 50%, 75%, 90%, 100%

7. Time Warnings

• Every 30 seconds, system checks time remaining
• 60 minutes remaining: "Only 60 minutes remaining!"
• 30 minutes: Warning broadcast
• 10 minutes: Warning broadcast
• 5 minutes: Warning broadcast
• 1 minute: Final warning broadcast
• Creates urgency, increases activity

8. Leaderboard Updates

• Every 30 seconds (configurable)
• For each online player: Update scoreboard
• Fetch top 3 players with amounts
• Calculate player's rank and amount
• Update scoreboard lines with new data
• Shows real-time competition

9. Goal Completion

• Progress reaches 1000/1000 (target achieved)
• State changed to COMPLETED
• Broadcast: "GOAL REACHED! Diamond Sword x1000 crafted!"
• Reward distribution begins automatically
• Top 3 ranked players get rank rewards
• All participants checked for contribution tiers
• High contributors (30%+): Tier 1 rewards
• Medium contributors (10-30%): Tier 2 rewards
• Low contributors (1%+): Tier 3 rewards
• Rewards given (items + commands executed)
• Messages sent: "You received a reward for 2nd place"

10. Challenge End

• Final standings announced
• Scoreboard cleared
• Challenge saved to history (if enabled)
• Data persisted to storage
• System ready for next challenge
• Statistics available for review

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Performance Features

Optimized & Lightweight
[*]Efficient progress tracking (HashMap lookups)
[*]Scheduled tasks for updates (30-second intervals)
[*]Smart scoreboard updates (only for online players)
[*]Cached rank calculations
[*]Minimal event listener overhead
[*]Optimized shift-click calculations
[*]No database queries during crafting (in-memory)

Smart Data Management
[*]In-memory progress tracking (fast access)
[*]Auto-save intervals (default: 5 minutes)
[*]Manual save on important events (stop, complete)
[*]Persistent storage (YAML files)
[*]Crash recovery (reload on restart)
[*]Data validation on load
[*]Minimal disk I/O

Fair Competition
[*]Creative mode prevention (optional)
[*]Goal cap (no over-counting after completion)
[*]Remaining calculation (only needed crafts count)
[*]Shift-click support (accurate mass crafting)
[*]Duplicate prevention
[*]Rank recalculation after each craft

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

FAQ

Q: What's the difference between Team and Individual mode?
A: Team mode = everyone works together toward one goal, rewards based on contribution percentage. Individual mode = players compete for top ranks, rewards based on placement (1st, 2nd, 3rd). Both track individual amounts.

Q: Can players see the leaderboard?
A: Yes! Sidebar scoreboard shows real-time info, and /challenge leaderboard opens a GUI with detailed rankings. Both update automatically every 30 seconds (configurable).

Q: What happens if the goal isn't reached before time expires?
A: Challenge expires, rewards are still distributed to top contributors based on participation/rank. You can configure whether expired challenges give rewards or not.

Q: Can I create challenges without time limits?
A: Yes! Use duration: 0 or omit duration parameter. Challenge runs until goal is reached or manually stopped. Perfect for "first to X" races.

Q: Do rewards work with Vault economy plugins?
A: Yes! Use commands like "eco give {player} 10000" in reward configurations. Works with any economy plugin that supports Vault.

Q: What items can be challenged?
A: Any craftable Minecraft item. Use exact material names (DIAMOND_SWORD, IRON_INGOT, ENCHANTED_BOOK, etc.). Plugin validates items on creation.

Q: Does shift-clicking work for mass crafting?
A: Yes! Plugin accurately calculates shift-click amounts based on available materials in the crafting grid. Counts all items crafted.

Q: Can I prevent creative mode players from participating?
A: Yes! Enable "prevent-creative: true" in config.yml. Creative mode crafts will be ignored (no progress added).

Q: What happens if the server crashes during a challenge?
A: All data is auto-saved every 5 minutes and on important events. Challenge reloads on restart with all progress intact. Time tracking continues accurately.

Q: Can I have multiple challenges active at once?
A: No, only one challenge can be active at a time. This keeps things focused and prevents confusion. Complete or cancel current challenge before starting new one.

Q: How do contribution tiers work?
A: Contribution = (your amount / total amount) × 100. If you crafted 300 out of 1000 total, that's 30% contribution. High tier (30%+), Medium (10-30%), Low (1-10%). Configure thresholds in rewards.yml.

Q: Can rewards have custom enchanted items?
A: Yes! Reward items support: custom names, custom lore (multi-line), enchantments (any type + level), any amount. See rewards.yml for examples.

Q: What's the template system for?
A: Templates save complete challenge configurations (item, amount, mode, duration, rewards). Perfect for recurring events. Create once, start with /challenge start template-name.

Q: Can I customize all messages?
A: Yes! Every message is in messages.yml with placeholder support. Change colors, wording, format. Supports &color codes.

Q: Does this work with PlaceholderAPI?
A: Yes! Use placeholders in other plugins (holograms, scoreboards, tab lists). Shows challenge info, player stats, rankings.

Q: Can I give permissions as rewards?
A: Yes! Use commands: "lp user {player} permission set vip.true" (LuckPerms) or equivalent for your permissions plugin.

Q: What happens if a player leaves during a challenge?
A: Progress is saved. When they rejoin, their contribution is still counted. They're still ranked and eligible for rewards based on their crafted amount.

Q: Can I cancel a challenge without giving rewards?
A: Yes! Use /challenge cancel instead of /challenge stop. Cancelling clears all progress and gives no rewards. Stopping completes the challenge normally.

Q: How many players can participate?
A: Unlimited! Plugin tracks everyone who crafts at least one item. Leaderboard shows top 21 in GUI, top 3 on scoreboard.

Q: Can I test challenges without affecting my server?
A: Yes! Create test challenges with small amounts, short durations. Use /challenge cancel to clean up tests without rewards.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Dependencies & Requirements

Required
[*]Minecraft: 1.20+ (Spigot, Paper, or Purpur - Paper recommended)
[*]Java: 17+ (required for Minecraft 1.20+)

Optional
[*]Vault: For economy rewards (eco give commands)
[*]PlaceholderAPI: For placeholder integration with other plugins

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Installation

1. Download CraftChallenge.jar
2. Place in your server's /plugins folder
3. (Optional) Install Vault for economy integration
4. (Optional) Install PlaceholderAPI for placeholders
5. Restart your server
6. Plugin generates all configuration files
7. Edit configs in /plugins/CraftChallenge/
8. Create templates in templates.yml
9. Configure rewards in rewards.yml
10. Customize messages in messages.yml
11. Use /challenge reload to apply changes
12. Create your first challenge: /challenge create DIAMOND_SWORD 100 team 1h
13. Start it: /challenge start
14. Done! Players can now participate by crafting

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Advanced Configuration

Scenario: High-Stakes Competition

Scenario: Community Building Event

Scenario: Speed Race

Scenario: Marathon Event

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Why Choose CraftChallenge?

Complete Event System
[*]Everything included: tracking, leaderboards, rewards, announcements
[*]Two modes for different playstyles (team vs individual)
[*]Template system for recurring events
[*]No manual tracking required
[*]Automatic reward distribution

Engaging Experience
[*]Real-time leaderboards keep competition exciting
[*]Milestone celebrations maintain motivation
[*]Personal notifications show individual progress
[*]Rank system creates competitive drive
[*]Time warnings build urgency

Highly Configurable
[*]Every message customizable
[*]Flexible reward system (items + commands)
[*]Template presets for common events
[*]Adjustable timings and thresholds
[*]Complete control over notifications

Professional Quality
[*]Persistent data storage (crash recovery)
[*]Shift-click support (accurate counting)
[*]Creative mode prevention
[*]Performance optimized
[*]GUI and scoreboard integration

Easy to Use
[*]Simple commands (/challenge create)
[*]Quick start with templates
[*]Automatic tracking (no player action needed)
[*]Clear documentation
[*]Intuitive configuration

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Support

Need help? Have suggestions? Found a bug?

Contact: moessoe97 on BuiltByBit
Discord: https://discord.gg/jsyct6TW9x
Documentation: Complete setup guide included
Bug Reports: Open a ticket in our Discord
Feature Requests: Always welcome!

If you enjoy this plugin, please leave a review!

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Turn crafting into community events with CraftChallenge - compete, cooperate, celebrate!