נועם זבישינסקי
📎 1 file 28,462 chars
📄
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.**
Kodari AI
KodariSep 18 at 4:19 pm 4
MarketMayhem
A competitive multiplayer Minecraft minigame plugin where players race through a supermarket collecting products from dynamic shopping lists. Players manage limited cart capacity, strategically decide when to checkout for points, and react to random events like flash sales, golden product spawns, and store chaos. Features include a modular product system with rarity tiers, smart shopping list generation that validates feasibility, multiple checkout stations with statuses, power-ups (speed boost, magnet, double points), configurable events, arena setup system with validation, database abstraction (SQLite/MySQL/PostgreSQL), PlaceholderAPI and Vault integrations, player statistics, leaderboards, and comprehensive admin commands with audit logging. Designed for 2-16 players with fast-paced, risk-reward gameplay emphasizing meaningful strategic choices.
  1. Create the Gradle/Paper project, plugin metadata, and all configurable YAML resources.

  2. Implement the modular arena, game, product, shopping, event, power-up, statistics, and integration layers.

  3. Add player/admin commands, listeners, validation, cleanup, database persistence, placeholders, rewards, and documentation.

  1. Created the complete Gradle/Paper project structure with plugin metadata, permissions, configurable YAML files, SQLite dependency manifest, and README.

  2. Implemented modular products, rarities, weighted spawning, custom ItemsAdder/Oraxen item support, shopping lists, carts, checkout scoring, bonuses, penalties, and product UUID protection.

  3. Added arena management, arena persistence/validation, game lifecycle, countdowns, spawning, events, scoreboards, cleanup, disconnect handling, and statistics persistence.

  4. Added player/admin commands, event and power-up services, pickup/checkout protection listeners, PlaceholderAPI placeholders, and optional integration handling.

  5. Added configuration for products, lists, events, power-ups, sounds, rewards, maps, database, messages, and gameplay settings.

Kodari can make mistakes. Review important code before using.
Files
src
build.gradle
manifest.kod
README.md
settings.gradle
Code
41 1,210
src/main/java/com/kodari/marketmayhem/MarketMayhemPlugin.java
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; }
}