Kits & Crates +

1) Requirements

• 

  Minecraft: 1.21.x (recommended: Paper)

• 

  Java: Java 21

• 

  Permissions plugin (optional): LuckPerms or similar (recommended for kit/crate access control)

2) Installation

1. Drop the jar into: /plugins

2. Start the server once to generate files.

3. Stop the server (optional but recommended) and review configs.

4. Start the server again.

Tip: If you’re upgrading from an older build, back up your plugin folder first:
/plugins/i

3) First-Time Setup Checklist

• 

  Open the admin/editor menu.

• 

  Create at least one Kit and one Crate.

• 

  Set up permissions for staff and players.

• 

  Test a full crate opening flow (animation + reveal + rewards + actions).

• 

  (Optional) If you’re using world crates: place/register a block crate + verify counter display + key behavior.

Kits

• 

  A kit is a saved loadout (items + meta) that can be redeemed via GUI/command.

• 

  Kits can be public, permission-gated, or admin-only depending on your setup.

• 

  Kits can be “inventory style” (slot-specific) OR layered/container style (rollable pools).

Crates

• 

  A crate is a reward pool with entries that can be rolled, typically with an opening animation + reveal.

• 

  Each reward entry can include items AND optional “Reward Actions” (commands/sounds/particles).

• 

  Crate opening sessions are protected to avoid interruption mid-animation.

• 

  Crates support layered containers (nest pools inside pools so crates aren’t flat).

Reveal Styles / Themes / Effects

• Reveal Style controls the motion/showcase style (example: ORBIT / HELIX / FRONT_LINE / POP_UP / etc.)

• Reveal Theme layers a “vibe” on top (example: DEFAULT / FIRE / ICE / VOID / ELECTRIC / etc.)

• Reveal Effect is a separate effect selection used by the editor (example: ground_break_fire style effects depending on your build)

Block Crates + Keys

• 

  Block crates are physical world crate blocks that can be placed/registered for openings.

• 

  Block crates can show an optional uses counter display above the block (readable for players).

• 

  Block crates can require keys (key can be checked in-hand or anywhere in inventory depending on settings).

• 

  Block crates can run ambient particles and opening FX for a premium idle/open feel.

Reward Actions (Optional per reward entry)

• Player Command — command runs as the player (permissions apply).

• Console Command — command runs as console (use with care).

• Sound — sound played on win (or during the flow depending on settings).

• Particles — particle effect on win (or during the flow depending on settings).

5.1 Create a Kit

1. Open the admin/editor menu.

2. Go to Kits → Create.

3. Set:

   • Name (internal id + display name)

   • Icon (what shows in the GUI)

   • Description/Lore (optional)

   • Permission (optional but recommended)

4. Add items:

   • Use the editor’s Add Item tools (or drag items in, depending on your build).

   • Save when finished.

5.2 Create a Crate

• 

  Open the admin/editor menu.

• 

  Go to Crates → Create.

• 

  Set:

  • 

    Name (internal id + display name)

  • 

    Icon

  • 

    Tier (if your build uses tiered crates)

  • 

    Reveal Style (controls motion/showcase style)

  • 

    Reveal Effect (selectable effect option used by the editor)

  • 

    Open rules (who can open, where, etc. depending on config)

• 

  Add reward entries:

  • Add an item reward (or a “virtual reward” if supported).

  • Set the % chance for that entry.

  • (Optional) Add Reward Actions: player/console commands, sounds, particles.

  • (Optional) Add nested containers for layered “roll inside roll” behavior.

  • Repeat for each reward.

• 

  Save the crate.

5.3 Editing Chances (Best Practices)

• Keep common rewards in higher ranges (ex: 30–60%), rare rewards lower (ex: 0.5–5%).

• Avoid “impossible math” where total chances don’t make sense for your roll system.

• If your build uses weighted selection rather than strict percentage totals, treat “%” as relative weight.

Important: If your crate system runs an animation, do not force-close the inventory or reload the plugin mid-opening. The system is designed to protect active openings.

5.4 Block Crates + Key Settings (Crate Access)

• 

  For each crate, open its access/settings GUI (the “Crate Access” style menu depending on your build).

• 

  Configure:

  • 

    Default block uses (limited-use crates)

  • 

    Key requirement behavior (required/consume; key check in-hand vs anywhere depending on server settings)

  • 

    Admin bypass behavior (if enabled/disabled)

  • 

    Deplete effect style (when uses hits 0)

6) Player Usage

• 

  Players can redeem kits via:

  • Kit GUI (if enabled)

  • Kit commands (if enabled)

• 

  Players can open crates via:

  • 

    Crate GUI / opening menu (common setup)

  • 

    Block crates in-world (if enabled on your server)

  • 

    Other access methods depending on your server’s flow (keys/commands/etc.)

• 

  If a crate requires a key, the player must have a valid key based on your key settings.

• 

  If a block crate is limited-use, the uses counter display (if enabled) shows remaining uses.

Common per-id patterns (recommended):

• 

  mcwar.kits.use. (example: mcwar.kits.use.mega_example)

• 

  mcwar.crates.use. (example: mcwar.crates.use.tier6_example)

Common files you may see (names vary by build):

• 

  config.yml — global settings (reveal defaults, block crates + keys, menus/themes, picker libraries)

• 

  messages.yml — user-facing messages (MiniMessage formatting)

• 

  theme-packs.yml — /kits menu theme packs (applied in-game)

• 

  kit-menu.yml — kit menu icon/name/description data (if separated)

• 

  kits/ — saved kits (inventory kits + container kits)

• 

  crates/ — saved crates + reward pools + animations/settings

If you edit files manually, restart or use the plugin’s reload option (if provided) to apply changes safely.

9.1 Menu Theme Packs (/kits)

• The /kits GUI is fully themeable (title, border, fill, buttons, lore templates, etc.)

• Theme packs can be applied in-game (Menu Themes) and saved as the active theme.

• Common packs included in builds like this: Premium / Minimal / Dark / Neon (depending on your file pack).

9.2 Block Crates + Keys (Config)

• 

  Global block crate system is controlled under a crateBlocks section (enabled/protect/persistent behavior).

• 

  Uses counter display can be enabled/disabled, with formatting + gradient coloring.

• 

  Ambient and opening FX can be toggled/tuned (premium idle feel).

• 

  Key defaults and key item templates are configurable (required/consume + lore templates).

9.3 Reveal Defaults + Picker Libraries

• 

  Reveal defaults (style/theme) can be set server-wide so crates look good out of the box.

• 

  Sound + Particle picker libraries are included so admins can pick effects quickly and consistently.

• 

  Some builds also support particle “preset” tags shown in example content (ex: PRESET:HALO / PRESET:SPIRAL / PRESET:EXPLOSION).

11) Support
When reporting an issue, include:

• 

  Server software + version (Paper/Spigot + build)

• 

  Plugin version

• 

  Exact steps to reproduce

• 

  Console errors (full stack trace)

• 

  Your kit/crate file(s) if the bug is content-specific

Test Server: mcwar.co