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

1. Open the admin/editor menu.

2. Create at least one Kit and one Crate.

3. Set up permissions for staff and players.

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

5. (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

1. Open the admin/editor menu.

2. Go to Crates → Create.

3. 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)

4. 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.

5. 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