📄
pasted-code-1789747507868.txt
txt
2198 lines
▶
אני רוצה שתבנה עבורי MiniGame מלא, מקצועי ומוכן לשרת Minecraft ציבורי בשם:
# 🛒 MARKET MAYHEM
זהו MiniGame תחרותי ומהיר שמתרחש בתוך סופרמרקט ענק.
המשחק צריך להיות **מקורי**, ולא העתק של MiniGame קיים.
הקונספט המרכזי:
השחקנים נכנסים לסופרמרקט, מקבלים רשימת קניות אישית, אוספים מוצרים, מתמודדים על מוצרים נדירים, מגיבים לאירועים שמשנים את הסופר, ומנסים להשיג את כמות הנקודות הגבוהה ביותר לפני שהזמן נגמר.
המשחק צריך להרגיש כמו שילוב של:
* Fast-paced collection
* Strategy
* Risk / Reward
* Random Events
* Shopping
* Competition
* Exploration
אבל בלי להפוך אותו למשחק PvP רגיל.
---
# 🎮 GAME OVERVIEW
שם:
`Market Mayhem`
מינימום שחקנים:
`2`
מקסימום שחקנים:
`16`
זמן משחק ברירת מחדל:
`4 דקות`
אפשר להגדיר בקונפיג.
Flow:
```text
LOBBY
↓
QUEUE
↓
COUNTDOWN
↓
TELEPORT TO MARKET
↓
ROLE / SHOPPING LIST ASSIGNMENT
↓
GAME START
↓
SHOPPING
↓
RANDOM EVENTS
↓
SPECIAL EVENTS
↓
FINAL 30 SECONDS
↓
GAME END
↓
RESULTS
↓
REWARDS
↓
RETURN TO LOBBY
```
---
# 🛒 CORE GAMEPLAY
בתחילת המשחק כל שחקן מקבל:
1. Shopping List
2. Shopping Cart
3. Starting Score
4. מספר Slots מוגבל לעגלה
5. משימות/Bonuses אישיים
לדוגמה:
```text
🛒 YOUR SHOPPING LIST
☐ 2x Apple
☐ 1x Bread
☐ 2x Milk
☐ 1x Cookie
☐ 1x Chicken
BONUS:
Complete the entire list:
+50 points
```
המטרה היא לאסוף מוצרים.
אבל חשוב:
לא כל המוצרים שווים אותו דבר.
---
# 🍎 PRODUCT SYSTEM
צור מערכת Products מודולרית.
כל Product צריך לכלול:
* ID
* Display Name
* Material / Custom Item
* Category
* Base Points
* Rarity
* Spawn Weight
* Shopping List Weight
* Stack Size
* Special Effects
* Sound
* Pickup Effect
* Optional Icon
* Optional ItemsAdder integration
דוגמאות:
```text
apple
bread
milk
cookie
carrot
potato
beef
chicken
cake
melon
golden_apple
diamond_chocolate
mystery_box
```
אל תשתמש רק ב־Vanilla Items אם יש צורך במוצרים מותאמים.
תכנן abstraction שמאפשר בעתיד:
* Vanilla Item
* ItemsAdder Item
* Oraxen Item
* CustomModelData
---
# ⭐ PRODUCT RARITY
צור Rarity System:
```text
COMMON
UNCOMMON
RARE
EPIC
LEGENDARY
MYTHIC
```
דוגמה:
```text
Apple
COMMON
+5
Cake
UNCOMMON
+10
Golden Apple
RARE
+25
Mystery Box
EPIC
+50
Golden Product
LEGENDARY
+100
```
הערכים צריכים להיות configurable.
---
# 🎯 SHOPPING LIST SYSTEM
זו מערכת מרכזית.
לכל שחקן נוצרת רשימת קניות.
לא ליצור לכולם אותה רשימה.
המערכת צריכה לבחור רשימה באופן דינמי.
לדוגמה:
Player A:
```text
2 Apple
1 Milk
1 Bread
2 Cookie
```
Player B:
```text
1 Chicken
2 Potato
1 Cake
1 Milk
```
Player C:
```text
3 Apple
1 Bread
1 Golden Product
```
---
# 🧠 SMART LIST GENERATION
צור מערכת שמונעת מצב שבו Shopping List בלתי אפשרית.
לפני תחילת משחק:
המערכת צריכה לבדוק:
* האם המוצרים קיימים?
* האם יש מספיק Spawn Points?
* האם קיימת כמות מספקת?
* האם המשחק יכול להשלים את הרשימה?
* האם יש Products נדירים מדי?
אל תגרום לשחקן לקבל משימה שאין דרך להשלים.
---
# 🛒 SHOPPING CART
לכל שחקן יש Shopping Cart.
העגלה מוגבלת.
לדוגמה:
```text
Cart Capacity: 12
```
אם השחקן מגיע ל־12 פריטים:
```text
🛒 CART FULL!
Return to checkout!
```
אפשר לשדרג Capacity באמצעות Power-Up.
לדוגמה:
```text
Small Cart: 8
Medium Cart: 12
Large Cart: 16
Mega Cart: 20
```
---
# 🧾 CHECKOUT SYSTEM
השחקן לא מקבל את כל הנקודות מיד.
כאשר הוא מגיע ל־Checkout:
העגלה נסרקת.
```text
🧾 CHECKOUT
Products:
Apple x2 +10
Milk x1 +8
Bread x1 +12
Shopping Bonus +25
TOTAL:
55 POINTS
```
לאחר Checkout:
העגלה מתרוקנת.
זה יוצר החלטה:
האם להמשיך לאסוף?
או לחזור לקופה לפני ששחקן אחר לוקח מוצרים?
---
# 🏪 MULTIPLE CHECKOUTS
במפה יכולים להיות מספר Checkouts.
לדוגמה:
```text
Checkout 1
Checkout 2
Checkout 3
Checkout 4
```
אבל כל Checkout יכול לקבל מצב:
```text
OPEN
BUSY
BROKEN
SALE
DOUBLE_POINTS
```
---
# 💰 SCORING SYSTEM
צור מערכת ניקוד ברורה.
דוגמה:
```text
Common Product +5
Uncommon Product +10
Rare Product +25
Epic Product +50
Legendary Product +100
Shopping List Item +10
Complete List +50
Perfect Checkout +25
Golden Product +100
```
אבל כל הערכים צריכים להיות configurable.
---
# 🎯 BONUS SYSTEM
צור Bonuses נוספים.
לדוגמה:
## PERFECT SHOPPER
השחקן השלים את כל הרשימה:
`+50`
## SPEED SHOPPER
השלים רשימה לפני 60 שניות:
`+75`
## RARE FIND
אסף 3 Rare Products:
`+30`
## CLEAN CART
ביצע Checkout ללא פריטים שלא היו ברשימה:
`+25`
---
# ⚠️ PENALTIES
אפשר להגדיר Penalties.
לדוגמה:
מוצר שלא היה ברשימה:
`-2`
אבל לא להעניש יותר מדי.
השחקן צריך להיות מסוגל לשחק גם אם הוא טועה.
---
# 🎲 RANDOM SPAWNING
מוצרים צריכים להופיע באופן דינמי ברחבי הסופר.
לא פשוט להניח את כל הפריטים בתחילת המשחק.
צור:
`ProductSpawner`
ששולט ב:
* Spawn Rate
* Max Active Products
* Spawn Areas
* Product Rarity
* Spawn Weights
* Minimum Distance
* Maximum Distance
* Respawn Delay
---
# 📍 SPAWN ZONES
למפה יהיו Zones.
לדוגמה:
```text
FRUIT_SECTION
BAKERY
MEAT_SECTION
DRINKS
FREEZER
CANDY
CHECKOUT
WAREHOUSE
```
לכל Zone ניתן להגדיר אילו Products יכולים להופיע.
לדוגמה:
```yaml
fruit_section:
products:
- apple
- melon
- carrot
```
---
# 🎯 PRODUCT SPAWN LOGIC
אל תאפשר ל־Products להופיע:
* בתוך קירות
* בתוך שחקנים
* מחוץ למפה
* בתוך Lava
* ב־Void
* בתוך אזורים חסומים
* במקום שאי אפשר להגיע אליו
המערכת צריכה לבצע Validation למיקום.
---
# ✨ PICKUP SYSTEM
כאשר שחקן אוסף Product:
להציג:
```text
+10
🍎 Apple
```
עם:
* Sound
* Particle
* ActionBar
* Optional floating text
אל תיצור Spam מוגזם.
---
# 🔥 GOLDEN PRODUCTS
במהלך המשחק יכולים להופיע מוצרים מיוחדים.
לדוגמה:
```text
✨ GOLDEN PRODUCT!
Find it before someone else!
```
Golden Product:
`+100`
אפשר להגדיר Spawn נדיר.
---
# 🎁 MYSTERY BOX
אפשר להוסיף Mystery Box.
כאשר שחקן אוסף אותו:
הוא מקבל Reward אקראי.
לדוגמה:
```text
🎁 MYSTERY BOX
You received:
+50 Points
```
או:
```text
🛒 +5 Cart Capacity
```
או:
```text
⚡ Speed II for 10 seconds
```
או:
```text
💰 Double Score for next Checkout
```
---
# ⚡ POWER-UPS
צור Power-Up System.
Power-Ups אפשריים:
## SPEED BOOST
Speed למשך 10 שניות.
## BIG CART
+5 Cart Capacity.
## DOUBLE POINTS
ה־Checkout הבא שווה ×2.
## MAGNET
Products בטווח מסוים נמשכים לשחקן.
## PRODUCT RADAR
מראה Products נדירים בקרבת מקום.
## FREE CHECKOUT
ה־Checkout הבא לא דורש לחזור לקופה רגילה.
כל Power-Up:
* configurable
* cooldown
* duration
* sound
* particles
* permission/config support
---
# 🛍️ SPECIAL EVENTS
המערכת צריכה להפעיל Events במהלך המשחק.
Events צריכים להיות אקראיים או מתוזמנים.
---
# 🔥 EVENT: SALE
```text
🔥 FLASH SALE!
All products in:
BAKERY
are worth ×2 points!
```
משך:
30 שניות.
---
# 💰 EVENT: GOLDEN PRODUCT
מוצר Legendary מופיע במפה.
```text
✨ GOLDEN PRODUCT SPAWNED!
Find it!
```
---
# 🧊 EVENT: FREEZER FAILURE
אזור המקפיא משתנה:
* Slowness
* Ice
* Special Products
---
# 🚨 EVENT: STORE CHAOS
למשך 15 שניות:
* Products spawn faster
* Movement speed increases
* More rare products
* Special music
---
# 🛑 EVENT: CHECKOUT FAILURE
Checkout אחד מפסיק לעבוד.
```text
🚨 CHECKOUT 2 OFFLINE
Find another checkout!
```
---
# 🌟 EVENT: DOUBLE POINTS
למשך זמן קצר:
כל המוצרים שווים פי 2.
---
# 🧹 EVENT: STORE RESET
כל ה־Products הפעילים נמחקים.
מיד לאחר מכן:
Spawn Wave חדש.
---
# 📦 EVENT WAVES
אפשר ליצור Waves.
לדוגמה:
```text
Wave 1:
Common products
Wave 2:
Common + Uncommon
Wave 3:
Rare
Wave 4:
Epic + Legendary
```
ככל שהמשחק מתקדם:
המשחק נהיה מהיר יותר.
---
# 🏃 MOVEMENT
השחקנים צריכים להיות בתנועה.
אפשר להשתמש:
* Speed
* Slowness Zones
* Doors
* Escalators
* Shortcuts
* Warehouse
* Freezer
* Staff-only areas
---
# 🚪 MAP INTERACTIONS
המפה צריכה להיות Interactive.
דוגמאות:
* Automatic doors
* Buttons
* Elevators
* Freezer doors
* Warehouse doors
* Checkout scanners
* Shopping carts
* Shelves
---
# 🛒 SHOPPING CART ENTITY
אפשרות ליצור Shopping Cart visual.
העגלה יכולה:
* Follow player
* Have custom model
* Show capacity
* Play sounds
אם שימוש ב־Entity מורכב מדי או פוגע בביצועים:
צור fallback באמצעות Item/Visual בלבד.
---
# 🗺️ MAP SYSTEM
המערכת צריכה לתמוך במספר מפות.
דוגמאות:
```text
MegaMart
SuperStore
DowntownMarket
NightMarket
LuxuryMall
```
כל Map צריכה להיות עצמאית.
---
# 🏪 MAP STRUCTURE
כל מפה יכולה להכיל:
```text
Lobby
Fruit Section
Bakery
Meat Section
Drinks
Freezer
Candy
Warehouse
Checkout
Staff Room
Secret Area
```
---
# 📍 MAP SETUP
Admin צריך להיות מסוגל להגדיר:
* Player Spawns
* Spectator Spawn
* Product Zones
* Product Spawn Points
* Checkout Points
* Event Zones
* Power-Up Points
* Golden Product Points
* Lobby Spawn
---
# 🧑💼 OPTIONAL NPC SYSTEM
אם יש NPC System:
אפשר NPC:
```text
Shop Manager
Cashier
Security
```
אבל אל תיצור dependency חובה על NPC plugin.
---
# 🏆 LEADERBOARD
בסיום המשחק:
```text
━━━━━━━━━━━━━━━━━━━━
🛒 MARKET MAYHEM
━━━━━━━━━━━━━━━━━━━━
🥇 Noam 485
🥈 Player2 420
🥉 Player3 365
4. Player4 310
5. Player5 280
Products Collected: 47
Shopping Lists: 6
Golden Products: 1
━━━━━━━━━━━━━━━━━━━━
```
---
# 🎉 WINNER EFFECT
המנצח מקבל:
* Title
* Sound
* Fireworks
* Particles
* Winner animation
אבל לא להציף את השרת באפקטים.
---
# 🎁 REWARDS
Rewards configurable.
לדוגמה:
```text
Coins
XP
Tokens
Cosmetics
```
אפשרות Vault integration.
---
# 📊 PLAYER STATISTICS
שמור:
```text
Games Played
Games Won
Products Collected
Products Delivered
Shopping Lists Completed
Perfect Checkouts
Golden Products Found
Mystery Boxes Opened
Power Ups Used
Highest Score
Best Game
```
המערכת צריכה להיות מוכנה ל־PlaceholderAPI.
---
# 📈 LEADERBOARDS
אפשר Leaderboards:
```text
Most Wins
Highest Score
Most Products
Most Golden Products
Most Perfect Checkouts
```
---
# 🧠 ANTI-CAMPING
המשחק לא צריך לעודד שחקן לעמוד בפינה.
אם שחקן לא זז במשך זמן רב:
```text
⚠ MOVE!
You haven't collected anything recently.
```
לאחר זמן:
המערכת יכולה להפעיל:
* Product nearby
* Temporary Speed
* Objective update
לא להעניש בצורה מעצבנת.
---
# 🚫 ANTI-EXPLOIT
טפל ב:
* Double pickup
* Item duplication
* Shift-click exploits
* Inventory exploits
* Dropped item duplication
* Disconnect during checkout
* Disconnect with cart items
* Reconnect abuse
* Teleport exploits
* Movement exploits
* Illegal locations
* Command abuse
כל Product צריך UUID/Unique ID פנימי כדי למנוע Double Collection.
---
# 🔌 COMMANDS
Main command:
```text
/marketmayhem
```
Alias:
```text
/mm
```
---
# 👤 PLAYER COMMANDS
## `/mm join `
הצטרפות למשחק.
## `/mm leave`
יציאה מהמשחק.
## `/mm list`
רשימת Arenas.
## `/mm stats`
Statistics של השחקן.
## `/mm top`
Leaderboard.
## `/mm help`
Help.
---
# 🛠️ ADMIN COMMANDS
## `/mmadmin`
או:
```text
/mm admin
```
---
## Arena Management
```text
/mm admin create
/mm admin delete
/mm admin list
/mm admin info
/mm admin enable
/mm admin disable
```
Delete צריך Confirmation:
```text
/mm admin delete megamart confirm
```
---
# 🎮 GAME CONTROL
```text
/mm admin start
/mm admin stop
/mm admin restart
/mm admin pause
/mm admin resume
/mm admin forceend
```
---
# 👥 PLAYER ADMIN
```text
/mm admin join
/mm admin leave
/mm admin spectate
/mm admin reset
```
---
# 📦 PRODUCT ADMIN
```text
/mm admin product list
/mm admin product give
/mm admin product spawn
/mm admin product clear
/mm admin product reload
```
---
# 🎁 POWER-UP ADMIN
```text
/mm admin powerup list
/mm admin powerup give
/mm admin powerup spawn
/mm admin powerup clear
```
---
# ⚡ EVENT ADMIN
```text
/mm admin event list
/mm admin event
/mm admin event stop
```
Examples:
```text
/mm admin event megamart sale
/mm admin event megamart golden_product
/mm admin event megamart store_chaos
/mm admin event megamart freezer_failure
```
---
# 🗺️ MAP SETUP
Create a proper Setup system.
```text
/mm admin setup
```
פתח GUI:
```text
MARKET MAYHEM SETUP
[ Player Spawns ]
[ Spectator Spawn ]
[ Product Zones ]
[ Product Spawns ]
[ Checkouts ]
[ Power-Up Spawns ]
[ Event Zones ]
[ Lobby Spawn ]
[ Validate Arena ]
```
---
# 📍 SETUP COMMANDS
```text
/mm admin setspawn
/mm admin setspectator
/mm admin setlobby
```
Product Zone:
```text
/mm admin zone create
/mm admin zone delete
/mm admin zone list
```
Product Spawn:
```text
/mm admin productpoint add
/mm admin productpoint remove
/mm admin productpoint list
```
Checkout:
```text
/mm admin checkout add
/mm admin checkout remove
/mm admin checkout list
```
Power-Up:
```text
/mm admin powerpoint add
/mm admin powerpoint remove
```
---
# 🧪 TESTING
Create testing commands.
```text
/mm admin test start
/mm admin test product
/mm admin test event
/mm admin test powerup
/mm admin test checkout
```
Example:
```text
/mm admin test event sale
```
---
# 🔍 DEBUG
```text
/mm admin debug
/mm admin debug arena
/mm admin debug player
/mm admin debug products
/mm admin debug zones
```
Debug should show:
* Active products
* Spawn points
* Players
* Cart capacity
* Score
* Active events
* Checkouts
* Timers
* Tasks
* Performance data
---
# 🩺 VALIDATION
Command:
```text
/mm admin validate
```
Example:
```text
VALIDATING MARKET: megamart
✓ Lobby Spawn
✓ 16 Player Spawns
✓ Spectator Spawn
✓ 24 Product Points
✓ 6 Product Zones
✓ 4 Checkouts
✓ 8 Power-Up Points
✓ 6 Event Zones
✓ Product Configuration
✓ Shopping Lists
✓ Rewards
Arena is READY!
```
If something is missing:
```text
✗ Missing Spectator Spawn
✗ Only 3 Checkouts
✗ No Product Spawn Points in FREEZER
```
---
# 📊 STATUS
```text
/mm admin status
```
Display:
```text
MARKET MAYHEM STATUS
Plugin: ENABLED
Version: 1.0.0
Arenas: 4
Active Games: 2
Players: 24
Products Active: 71
Power Ups Active: 8
Events Active: 2
Database: CONNECTED
```
---
# 💾 RELOAD
```text
/mm admin reload
```
Reload configuration safely.
Do NOT restart active games unnecessarily.
If a configuration cannot be changed during an active game:
```text
⚠ This configuration can only be changed when the arena is inactive.
```
---
# 🔐 PERMISSIONS
Create:
```text
marketmayhem.admin
marketmayhem.admin.arena
marketmayhem.admin.game
marketmayhem.admin.player
marketmayhem.admin.product
marketmayhem.admin.powerup
marketmayhem.admin.event
marketmayhem.admin.setup
marketmayhem.admin.debug
marketmayhem.admin.testing
marketmayhem.admin.reload
marketmayhem.command.join
marketmayhem.command.leave
marketmayhem.command.stats
marketmayhem.command.top
```
Permissions must be granular.
Do not give every Admin permission automatically if unnecessary.
---
# 📝 ADMIN AUDIT LOG
Every dangerous Admin action must be logged.
Example:
```text
[18:32:10]
Admin: Noam
Action: FORCE_END
Arena: megamart
```
Another:
```text
[18:34:21]
Admin: Noam
Action: SPAWN_PRODUCT
Product: golden_apple
Location: megamart
```
Save to:
```text
logs/admin.log
```
Optional Discord Webhook support can be implemented later.
---
# 📱 SCOREBOARD
During game:
```text
🛒 MARKET MAYHEM
Time: 02:31
Score: 185
Cart: 7/12
List:
✓ Apple x2
✓ Milk x1
✗ Bread x1
✓ Cookie x2
Next Bonus:
+25
Event:
🔥 BAKERY SALE
```
The scoreboard must be configurable.
---
# 🎯 BOSSBAR
Use BossBar for important temporary information.
Examples:
```text
🛒 GAME ENDS IN 00:30
```
or:
```text
🔥 FLASH SALE — 00:12
```
---
# 💬 ACTIONBAR
Use ActionBar for small events:
```text
🍎 Apple +5
```
```text
🛒 Cart: 8/12
```
```text
🔥 DOUBLE POINTS!
```
---
# 🔊 SOUND SYSTEM
Create configurable sounds for:
* Game Start
* Countdown
* Product Pickup
* Rare Product
* Legendary Product
* Checkout
* Shopping List Completed
* Event Start
* Event End
* Winner
* Game End
Never hardcode sounds where configuration makes sense.
---
# ✨ PARTICLE SYSTEM
Particles for:
* Product spawn
* Product pickup
* Legendary product
* Checkout
* Winner
* Special Events
Effects must be optimized.
Do not spawn thousands of particles every tick.
---
# 📁 CONFIGURATION
Create:
```text
config.yml
messages.yml
products.yml
shopping-lists.yml
events.yml
powerups.yml
maps.yml
rewards.yml
sounds.yml
```
Everything possible should be configurable.
---
# products.yml
Example:
```yaml
products:
apple:
display-name: "Apple"
material: APPLE
category: fruit
rarity: common
points: 5
spawn-weight: 40
golden_apple:
display-name: "Golden Apple"
material: GOLDEN_APPLE
category: special
rarity: legendary
points: 100
spawn-weight: 1
```
---
# events.yml
Example:
```yaml
events:
sale:
enabled: true
duration: 30
multiplier: 2.0
golden_product:
enabled: true
duration: 20
store_chaos:
enabled: true
duration: 15
spawn-multiplier: 2.0
```
---
# shopping-lists.yml
Example:
```yaml
lists:
beginner:
- apple: 2
- bread: 1
- milk: 1
medium:
- chicken: 1
- cookie: 2
- potato: 2
- cake: 1
hard:
- golden_apple: 1
- cake: 2
- chicken: 2
```
---
# DATABASE
Create a proper database abstraction.
Support:
```text
SQLite
MySQL
PostgreSQL
```
Do not couple the entire plugin to one database.
Store:
* Player statistics
* Wins
* Scores
* Products
* Shopping lists
* Leaderboard data
Use asynchronous database operations where appropriate.
Never block the main server thread with slow database queries.
---
# 🔌 INTEGRATIONS
Design optional integrations for:
* Paper
* Vault
* LuckPerms
* PlaceholderAPI
* ItemsAdder
* Oraxen
Dependencies should be optional whenever possible.
The plugin must still work without ItemsAdder/Oraxen.
---
# 🧩 PLACEHOLDERAPI
Create placeholders such as:
```text
%marketmayhem_score%
%marketmayhem_wins%
%marketmayhem_games%
%marketmayhem_products%
%marketmayhem_best_score%
%marketmayhem_cart%
%marketmayhem_cart_capacity%
%marketmayhem_time%
%marketmayhem_arena%
%marketmayhem_event%
```
---
# 🏗️ CODE ARCHITECTURE
Build a modular architecture.
Suggested:
```text
marketmayhem/
│
├── MarketMayhemPlugin
│
├── game/
│ ├── GameManager
│ ├── Game
│ ├── GameSession
│ ├── GameState
│ └── GameTimer
│
├── arena/
│ ├── Arena
│ ├── ArenaManager
│ ├── ArenaValidator
│ └── ArenaSetup
│
├── player/
│ ├── MarketPlayer
│ ├── PlayerManager
│ └── PlayerSession
│
├── products/
│ ├── Product
│ ├── ProductManager
│ ├── ProductSpawner
│ └── ProductRarity
│
├── shopping/
│ ├── ShoppingList
│ ├── ShoppingListGenerator
│ ├── ShoppingCart
│ └── CheckoutManager
│
├── events/
│ ├── MarketEvent
│ ├── EventManager
│ ├── SaleEvent
│ ├── ChaosEvent
│ └── GoldenProductEvent
│
├── powerups/
│ ├── PowerUp
│ ├── PowerUpManager
│ └── PowerUpType
│
├── rewards/
│ └── RewardManager
│
├── statistics/
│ └── StatisticsManager
│
├── commands/
│
├── listeners/
│
├── gui/
│
├── database/
│
├── integrations/
│
├── config/
│
└── utils/
```
You may change the architecture if you have a better professional design.
Do NOT create one enormous Java class.
---
# ⚙️ PERFORMANCE
This plugin must be designed for a real Minecraft server.
Avoid:
* Unnecessary repeating tasks
* Huge entity counts
* Excessive particles
* Synchronous database operations
* Scanning huge areas every tick
* Creating thousands of temporary objects
* Memory leaks
* Unremoved listeners
* Timers that survive after games end
All game sessions must clean themselves up.
When a game ends:
```text
Players restored
Inventories restored
Effects removed
Scoreboards removed
BossBars removed
Items removed
Entities removed
Tasks cancelled
Events cancelled
Temporary data cleared
```
---
# 🔄 PLAYER DISCONNECT
If a player disconnects:
During Lobby:
Remove normally.
During Game:
* Remove player from game.
* Preserve game state.
* Do not crash the game.
* Their cart is deleted.
* Their products are returned to the spawn system if appropriate.
If the player reconnects:
Do NOT automatically exploit-rejoin unless configured.
---
# 🧹 GAME CLEANUP
Every Arena must have a reliable cleanup method.
No matter how the game ends:
* Normal End
* Admin Stop
* Server Shutdown
* Player Disconnect
* Exception
The cleanup must execute safely.
Use defensive cleanup.
---
# 🛡️ SERVER RESTART
If server restarts while a game is running:
Do not save a broken active game as permanent state.
On startup:
All Arenas return to:
`WAITING`
All active sessions are cleared.
---
# 🧪 TESTING REQUIREMENTS
Before considering the plugin complete, test:
### Lobby
* Join
* Leave
* Countdown
* Minimum players
### Gameplay
* Product spawning
* Product pickup
* Cart capacity
* Checkout
* Shopping List
* Score
### Events
* Sale
* Golden Product
* Store Chaos
* Freezer Failure
* Checkout Failure
* Double Points
### Power-Ups
* Speed
* Big Cart
* Double Points
* Magnet
* Radar
* Free Checkout
### End Game
* Timer
* Winner
* Results
* Rewards
* Statistics
* Cleanup
### Admin
* Arena creation
* Arena validation
* Start
* Stop
* Restart
* Product spawn
* Event trigger
* Debug
* Reload
---
# 🧪 EDGE CASES
Handle:
* Two players picking up same Product simultaneously
* Player disconnects during Checkout
* Player disconnects with full Cart
* Game starts with exactly minimum players
* Player joins at last second
* Admin stops game during event
* Event ends at same moment as game
* Product spawns after game ends
* Checkout used at exact game end
* Server shutdown during game
* Database unavailable
* Invalid Product configuration
* Invalid arena
* Missing spawn points
* Empty Shopping List
* Shopping List containing impossible Product
* Product spawn point inside invalid block
* Full inventory
* Player attempting commands outside game
Never allow an exception to break the entire plugin.
---
# 🚨 ERROR HANDLING
Use meaningful logs.
Bad:
```text
Error!
```
Good:
```text
[MarketMayhem] Failed to spawn product 'golden_apple'
Arena: megamart
SpawnPoint: 24
Reason: Invalid location
```
Use appropriate log levels:
* INFO
* WARNING
* SEVERE
* DEBUG
---
# 📖 README
Create a complete README containing:
1. Installation
2. Requirements
3. Supported Minecraft versions
4. Dependencies
5. Commands
6. Permissions
7. Configuration
8. Creating an Arena
9. Creating Product Zones
10. Creating Checkouts
11. Creating Power-Up Points
12. Creating Events
13. Creating Shopping Lists
14. PlaceholderAPI
15. Vault
16. ItemsAdder
17. Oraxen
18. Database
19. Troubleshooting
---
# 🎨 DESIGN PHILOSOPHY
Market Mayhem should feel:
🛒 Fun
⚡ Fast
🎯 Competitive
✨ Colorful
🏪 Immersive
🧠 Strategic
Do not make it feel like a generic Minecraft plugin.
The supermarket should feel alive.
The player should constantly think:
> "Should I keep collecting?"
> "Should I go to checkout?"
> "Someone just took the Legendary Product!"
> "There's a Flash Sale in Bakery!"
> "My cart is almost full!"
That decision-making is a central part of the gameplay.
---
# ❌ DO NOT DO
Do NOT make this:
* Spleef
* TNT Run
* BedWars clone
* Murder Mystery clone
* Simple item collection plugin
* Basic scavenger hunt
* AFK minigame
The core identity must remain:
**Competitive Supermarket Shopping.**
---
# ⭐ MOST IMPORTANT GAMEPLAY PRINCIPLE
The player should constantly have meaningful choices.
Example:
The player has:
```text
Cart: 10/12
Score: 220
```
They see a Legendary Product worth 100 points.
But their Shopping List is missing:
```text
Milk x1
Bread x1
Cookie x2
```
The Bakery currently has:
```text
🔥 FLASH SALE
×2 POINTS
```
The player has to decide:
1. Take Legendary Product.
2. Finish Shopping List.
3. Go to Checkout.
4. Search for another bonus.
5. Use a Power-Up.
There should not be one obvious optimal action every time.
---
# 🏁 END GAME
At the end:
Stop all spawning.
Display:
```text
━━━━━━━━━━━━━━━━━━━━
🛒 MARKET MAYHEM
TIME'S UP!
━━━━━━━━━━━━━━━━━━━━
🥇 Noam
485 POINTS
🥈 Player2
420 POINTS
🥉 Player3
365 POINTS
━━━━━━━━━━━━━━━━━━━━
🍎 Products Collected: 32
🧾 Lists Completed: 4
✨ Golden Products: 1
🔥 Perfect Checkouts: 3
━━━━━━━━━━━━━━━━━━━━
🏆 WINNER:
NOAM
━━━━━━━━━━━━━━━━━━━━
```
Then give Rewards.
Wait a configurable amount of time.
Return all players to Lobby.
---
# 📦 FINAL DELIVERABLES
I expect a complete production-ready project.
Provide:
1. Full Java source code.
2. Gradle or Maven configuration.
3. plugin.yml.
4. All YAML configuration files.
5. README.
6. Commands.
7. Permissions.
8. Database implementation.
9. PlaceholderAPI integration.
10. Vault integration.
11. Optional ItemsAdder integration.
12. Optional Oraxen integration.
13. Arena setup system.
14. Admin system.
15. Game system.
16. Product system.
17. Shopping List system.
18. Cart system.
19. Checkout system.
20. Event system.
21. Power-Up system.
22. Rewards.
23. Statistics.
24. Leaderboards.
25. Debug system.
26. Validation system.
27. Cleanup system.
28. Error handling.
29. Performance optimization.
---
# 🚨 FINAL DEVELOPMENT INSTRUCTION
Do not rush into generating random classes.
First internally design:
1. Architecture
2. Data model
3. Game state machine
4. Product system
5. Shopping List system
6. Cart system
7. Checkout system
8. Event system
9. Power-Up system
10. Arena system
11. Admin system
12. Database abstraction
13. Integrations
14. Cleanup
15. Error handling
Then implement the project.
Do not create fake functionality.
If a feature is listed, it must actually work.
Do not create buttons, commands or configuration options that do nothing.
Do not use placeholder implementations such as:
```java
// TODO
// implement later
return null;
```
for core functionality.
If a requested feature cannot be implemented exactly as described, explain the limitation and implement the closest stable solution.
The final result must be a **real Minecraft MiniGame plugin**, not a concept, mockup, prototype or collection of disconnected classes.
The architecture must allow me to add more supermarket maps, Products, Shopping Lists, Events, Power-Ups and game mechanics later without rewriting the entire plugin.
The most important goal is:
**Make Market Mayhem feel like its own recognizable Minecraft game.**
Create the Gradle/Paper project, plugin metadata, and all configurable YAML resources.
Implement the modular arena, game, product, shopping, event, power-up, statistics, and integration layers.
Add player/admin commands, listeners, validation, cleanup, database persistence, placeholders, rewards, and documentation.
Created the complete Gradle/Paper project structure with plugin metadata, permissions, configurable YAML files, SQLite dependency manifest, and README.
Implemented modular products, rarities, weighted spawning, custom ItemsAdder/Oraxen item support, shopping lists, carts, checkout scoring, bonuses, penalties, and product UUID protection.
Added arena management, arena persistence/validation, game lifecycle, countdowns, spawning, events, scoreboards, cleanup, disconnect handling, and statistics persistence.
Added player/admin commands, event and power-up services, pickup/checkout protection listeners, PlaceholderAPI placeholders, and optional integration handling.
Added configuration for products, lists, events, power-ups, sounds, rewards, maps, database, messages, and gameplay settings.
package com.kodari.marketmayhem;
import org.bukkit.NamespacedKey;
import org.bukkit.plugin.java.JavaPlugin;
public final class MarketMayhemPlugin extends JavaPlugin {
private ConfigManager configManager;
private ProductManager productManager;
private ShoppingListGenerator listGenerator;
private ArenaManager arenaManager;
private PlayerManager playerManager;
private GameManager gameManager;
private StatisticsManager statisticsManager;
private PowerUpManager powerUpManager;
private NamespacedKey productKey;
@Override public void onEnable() {
saveDefaultConfig();
for (String file : new String[]{"messages.yml", "products.yml", "shopping-lists.yml", "events.yml", "powerups.yml", "maps.yml", "rewards.yml", "sounds.yml"}) saveResource(file, false);
productKey = new NamespacedKey(this, "product");
configManager = new ConfigManager(this);
playerManager = new PlayerManager();
productManager = new ProductManager(this);
listGenerator = new ShoppingListGenerator(this);
arenaManager = new ArenaManager(this);
statisticsManager = new StatisticsManager(this);
powerUpManager = new PowerUpManager(this);
gameManager = new GameManager(this);
getCommand("marketmayhem").setExecutor(new MarketCommand(this));
getCommand("marketmayhem").setTabCompleter(new MarketCommand(this));
getCommand("mmadmin").setExecutor(new AdminCommand(this));
getCommand("mmadmin").setTabCompleter(new AdminCommand(this));
getServer().getPluginManager().registerEvents(new MarketListener(this), this);
if (getServer().getPluginManager().getPlugin("PlaceholderAPI") != null) new MarketPlaceholderExpansion(this).register();
getServer().getScheduler().runTaskTimer(this, gameManager::tick, 20L, 20L);
getLogger().info("Market Mayhem enabled with " + productManager.all().size() + " products and " + arenaManager.all().size() + " arenas.");
}
@Override public void onDisable() { if (gameManager != null) gameManager.shutdown(); if (statisticsManager != null) statisticsManager.close(); }
public ConfigManager config() { return configManager; }
public ProductManager products() { return productManager; }
public ShoppingListGenerator listGenerator() { return listGenerator; }
public ArenaManager arenas() { return arenaManager; }
public PlayerManager players() { return playerManager; }
public GameManager games() { return gameManager; }
public StatisticsManager statistics() { return statisticsManager; }
public PowerUpManager powerups() { return powerUpManager; }
public NamespacedKey productKey() { return productKey; }
}