Kits & Crates + — Documentation
Author: Duq_ • Native: 1.21 • Test Server: mcwar.co
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/(your plugin folder name)

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 + rewards + actions).

4) Core Concepts
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.

Crates

• A crate is a reward pool with entries that can be rolled, typically with an opening animation.
• Each reward entry can include items AND optional “Reward Actions” (commands/sounds/particles).
• Crate opening sessions are protected to avoid interruption mid-animation.

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) Using the Admin GUI (Editor)
Note: Menu labels can vary slightly depending on your build. The flow below matches the standard editor structure.
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
     
   • Animation style (if your build supports multiple)
     
   • 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.
     
   • 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.

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)
    
  • Other access methods depending on your server’s flow (keys, commands, etc. if enabled)
    

7) Commands
Update these to match your exact plugin.yml. These are standard defaults.
Command Purpose
/kcp Open main menu
/kcp admin Open admin/editor tools
/kit Kit browser / redeem (if enabled)
/crate Crate browser / open (if enabled)
8) Permissions
Update these to match your exact permission nodes. These are common patterns.
Permission Purpose
kitscratesplus.use Use player menus/features
kitscratesplus.admin Full editor/admin access
kitscratesplus.kit.* (Optional) Kit access pattern
kitscratesplus.crate.* (Optional) Crate access pattern
9) Files & Configuration
After first run, the plugin creates a folder in:
/plugins/(plugin folder name)
Common files you may see (names vary by build):

• config.yml — global settings (GUI options, animation toggles, etc.)
• kits/ — saved kits
• crates/ — saved crates + reward pools
• messages.yml — user-facing messages (if separated)

If you edit files manually, restart or use the plugin’s reload option (if provided) to apply changes safely.
[HR][/HR]
10) Troubleshooting
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