TrajCakeWars

A complete, production-ready Cake Wars 1v1 minigame engine for Spigot, Paper, Purpur, and all Spigot-based forks. Built for performance, customization, and seamless integration.

Requirements

Installation

Quick Start

1. Prepare the template

# Manual copy or in-game:
/cw savetemplate desert

2. Configure the arena

/cw create desert
/cw tp desert                   # TP into the template
/cw set desert spawn1            # Stand at player 1 spawn
/cw set desert spawn2            # Stand at player 2 spawn
/cw set desert cake1             # Stand on cake block 1
/cw set desert cake2             # Stand on cake block 2
/cw set desert gen1              # Iron generator island 1
/cw set desert gen2              # Iron generator island 2
/cw set desert diamond           # Diamond gen (repeat for each)
/cw set desert lobby             # In-arena spectator point
/cw setname desert §6§lDesert
/cw settemplate desert desert
/cw back                         # Return to lobby
/cw setlobby                     # Set exact lobby return point
/cw enable desert
/cw save

Creating a Template

A template is a world folder in cw_templates/ at the server root. Each game clones it into a temporary world. The original is never modified.

Method 1: Manual copy

server/cw_templates/desert/   ← full world folder

Method 2: In-game

/cw savetemplate desert

Configuring an Arena

Use /cw tp <arena> to teleport into the template world. Use /cw back to return.

Additional settings

/cw setname <arena> <name>          # Display name (supports §)
/cw seticon <arena> <MATERIAL>     # GUI icon
/cw settemplate <arena> <name>     # Link to cw_templates/ folder
/cw set <arena> diamond clear     # Remove all diamond gens

Shop NPCs

The plugin detects interactions with existing entities via configurable name keywords. Works with any NPC plugin or vanilla renamed mobs.

Setup

1. Place NPCs in your template world using any method
2. Name them with a keyword (e.g. "Items Shop", "Blocks Shop")
3. Save the template — NPCs are cloned with the world for every game

Default keywords

Using vanilla villagers

# Spawn a villager
/summon villager ~ ~ ~

# Rename with a name tag at an anvil ("Items Shop" or "Blocks Shop")

# Make it stay still and invincible
/data merge entity @e[type=villager,sort=nearest,limit=1] {NoAI:1b,Invulnerable:1b,Silent:1b}

# Rotate it (0=South, 90=West, 180=North, 270=East)
/data merge entity @e[type=villager,sort=nearest,limit=1] {Rotation:[180f,0f]}

Generators

Generators stop spawning when the ground cap is reached within a 3-block radius.

Lobby Point

The lobby point is where players are teleported after every game. Independent of world spawn.

/cw setlobby   # Saves your exact position (x, y, z, yaw, pitch, world)

Game Flow

/cw → GUI Menu → Play / Private
→ 2 players matched → Clone template world
→ Save inventories → TP players → Freeze 5s
→ GO! Generators active, shops open
→ PvP + Eat enemy cake (7 slices, 1s cooldown)
→ Cake destroyed → next death = eliminated
→ Winner → Rewards executed
→ Restore inventories → TP to lobby → Delete temp world

Matchmaking

Cross-queue matching: a random-queue player can be matched with a map-specific player if the arena is available.

Private Sessions

/cw private desert     # Creates session → Code: K4HN7P
/cw join K4HN7P        # Friend joins → Game starts

The host stays in the main lobby while waiting. Open sessions are visible in the GUI.

Cake Mechanic

When a cake is fully eaten, the owner can no longer respawn. Next death is permanent elimination.

Shops

Fully driven by config.yml. Two default shops: Items and Blocks.

Tier hierarchy: Leather (0) → Chainmail (1) → Iron (2) → Diamond (3)

Death System

• Fatal damage is intercepted and cancelled — no vanilla death screen
• Player is set to Spectator with a title countdown on screen
• Respawn at island with starter sword after countdown
• If cake is destroyed → permanent elimination, opponent wins
• Safety net: if the player somehow dies anyway, instant forced respawn
• Anti-double guard: ignored if player is already in Spectator mode

TNT & Explosions

Explosions (TNT, fireballs) only destroy blocks placed by players during the game. The original template terrain is always protected and never modified.

Freeze Phase

During the pre-game countdown (default 5 seconds), players are frozen in place via continuous teleportation. They can look around but cannot move, break blocks, place blocks, or take damage. Game mode is set to Adventure during freeze.

Inventory Save & Restore New in v2.2

Critical for SMP and survival servers. When enabled, the plugin saves the player's complete state before each game and restores it after.

What is saved:

• Full inventory contents (every slot, exact position)
• Armor (helmet, chestplate, leggings, boots)
• Off-hand item
• XP level and progress
• Health and food level
• Game mode

game:
  save-inventory: true   # Enable inventory save/restore

Command Blocking New in v2.2

During a game, all commands are blocked except those in the whitelist. This prevents players from using /rtp, /tpa, /spawn, /home, or any other command that could break the game flow.

game:
  allowed-commands:    # Only these commands work during a game
    - "cw"
    - "cakewars"
    - "cake"
    - "msg"
    - "r"
    - "reply"

Players with the cakewars.admin permission bypass this restriction.

Unbreakable Items New in v2.2

All items given during a game (swords, armor, pickaxes, bows, shears, etc.) are flagged as Unbreakable. No durability loss, no tool breaking mid-fight. Applies to shop purchases and the starter wooden sword on respawn.

game:
  unbreakable-items: true

Configuration — General

settings:
  prefix: "&d&lCakeWars &r&7» &r"   # Chat message prefix
  lobby-world: "world"               # Lobby world name (fallback)
  lobby-location:                     # Set by /cw setlobby
    world: "world"
    x/y/z/yaw/pitch: ...

Configuration — Game Settings

game:
  countdown: 5              # Pre-game freeze duration (seconds)
  respawn-time: 5            # Respawn countdown when cake is alive
  max-duration: 600          # Max game length in seconds (0 = infinite)
  save-inventory: true       # Save/restore player inventory
  unbreakable-items: true    # All game items are unbreakable
  allowed-commands:          # Whitelisted commands during games
    - "cw"
    - "cakewars"
    - "msg"
    - "r"
    - "reply"

Configuration — Generators

generators:
  iron:
    interval: 40     # Ticks between spawns (20 = 1 second)
    max: 32          # Max items on ground per generator
  diamond:
    interval: 600
    max: 4

Configuration — Rewards

rewards:
  enabled: true
  winner:
    commands:                   # Console commands on win
      - "give %winner% diamond 5"
      - "eco give %winner% 100"    # Works with Vault
    message: "&6⭐ VICTORY! &a+5 Diamonds"
  loser:
    commands: []
    message: "&cDefeat. Try again!"

Variables: %winner%, %loser%, %arena%

Configuration — Shop Items

Both shops are fully defined in config.yml.

items-shop:
  title: "&d&lItems Shop"
  size: 45                     # 9, 18, 27, 36, 45, 54
  items:
    my-item:                   # Unique key (any name)
      slot: 10                  # Inventory position
      type: normal              # sword | armor-set | armor-piece | normal
      material: GOLDEN_APPLE
      name: "&6Golden Apple"     # Supports color codes
      amount: 1
      price: 2
      currency: DIAMOND         # IRON_INGOT or DIAMOND
      lore: ["&7Description"]

For armor-set type, use chest and legs instead of material.

Configuration — NPC Detection

shop-detection:
  items-keywords: ["Items", "Item", "Combat", "Weapons"]
  blocks-keywords: ["Blocks", "Block", "Build", "Construction"]

Case-insensitive, substring matching. Works on any living entity. Color codes stripped before comparison.

Player Commands

Admin Commands

All require cakewars.admin permission.

Arena Management

Setup

Teleportation

Permissions

Compatibility

Server Software

Compatible with Spigot, Paper, Purpur, Pufferfish, and all Spigot-based forks. Not compatible with Folia, Fabric, Forge, or Sponge.

NPC Plugins

Recommended Companion Plugins

Architecture

cw_templates/desert/     ← immutable template
    → File copy → cw_game_<uuid>/  ← temporary clone
    → WorldCreator → Game plays → Unload → Deleted

Auto gamerules: no mobs, no daylight cycle, no weather, fixed noon, no fire, no advancements.

Plugin Structure (~2400 lines)

fr.trajstudio.cakewars/
├── CakeWarsPlugin          ├── gui/MainMenuGUI
├── arena/Arena             ├── gui/MapSelectGUI
├── arena/ArenaManager      ├── gui/AdminGUI
├── arena/ArenaState        ├── gui/GUIListener
├── commands/CakeWarsCmd    ├── listeners/GameListener
├── game/GameInstance       ├── listeners/ShopListener
├── matchmaking/Manager     ├── listeners/ConnectionListener
├── shop/ShopGUI            ├── utils/AutoEquip
                            └── utils/WorldManager

FAQ

How many concurrent games?

10-20 with 4 GB RAM. Limited by RAM and disk speed.

Does TNT damage the map?

No. Only player-placed blocks are destroyed.

Server crash during a game?

Temporary world folders (cw_game_*) remain on disk. Delete them manually when the server is stopped.

2v2 / 4v4 support?

Current version is 1v1 only.

Empty shop?

Delete plugins/TrajCakeWars/config.yml and restart to regenerate with full shop configuration.

Players fall into void after game?

Run /cw setlobby at the correct position in your lobby.

Player lost inventory?

Enable game.save-inventory: true in config.yml. Essential for SMP servers.

How to add a new map?

Build map → copy to cw_templates/ → /cw create → /cw tp → /cw set all points → /cw enable → /cw save

How to update?

Replace the JAR and restart. arenas.yml is preserved. Delete config.yml to regenerate if new config sections were added.

Changelog

v2.2.2

Added

• Inventory save and restore system for SMP servers. Saves full player state before game, restores after.
• All game items are now unbreakable (no durability loss).
• Command blocking during games with configurable whitelist.
• /cw tp <arena> — teleport into template for setup.
• /cw back — return to lobby.
• /cw setlobby — set precise lobby return point.
• /cw delete <arena> — delete arena with confirmation.
• Full English translation of all player-facing strings.

Changed

• Lobby teleportation uses saved location instead of world spawn.
• Private session hosts stay in lobby while waiting.
• Death system uses gamemode check instead of UUID set, fixing double-kill bug.

Fixed

• Second kill after cake destruction healing instead of eliminating.
• GUI arena detection failing due to missing ID in lore.
• Private session teleporting to wrong coordinates.
• Empty shop when config.yml was from older version.