NexaKits Documentation

What is NexaKits?#

A kit platform for servers that need persistent player loadout layouts, not only one static kit inventory.

Who is it for?#

Crystal, Practice, FFA, Lifesteal, BoxPvP and SMP owners who need configurable PvP gear workflows.

Generated files#

config.yml, messages.yml, categories.yml, kits/, ender-chests/, premades/ and menus/.

Main systems#

• Kit creation, saving, claiming and previewing
• Personal layout editor with staff modes
• Ender Chest profile editor
• Premade kit library
• Dynamic Kit Room
• Auto kit rules
• Backup, restore and migration commands
• Public API and Bukkit events

Dependencies#

• Java 21
• Paper-style server runtime
• License key in config.yml
• PlaceholderAPI optional
• WorldGuard optional
• Vault, LuckPerms, SkinsRestorer and combat hooks optional

Setup checklist#

1. Set license and storage.
2. Review kits.default-cooldown-seconds and permission mode.
3. Create categories in categories.yml.
4. Use /kit save <name> for each staff-defined kit.
5. Use /eceditor 1 to prepare common Crystal EC layouts.
6. Create premades with /premadekit save <id>.
7. Open /kitroom and verify locked, available and cooldown states.

Production notes#

• Use LuckPerms or another permission manager for nexakits.kit.<kit> and profile nodes.
• Keep a backup before changing storage type.
• Do not claim Folia support unless the full setup is tested for region-thread safety.
• WorldGuard and combat hooks are optional; missing hooks should not block startup.

Message structure#

Most message keys are objects with enabled, type and either text, title fields or sound fields. This keeps player-facing output configurable.

Format examples#

<green>Loaded kit <white><kit></white>.
<red>You do not have permission.
type: "actionbar"
sound: "UI_BUTTON_CLICK"

Main Menu#

Entry point for Kit Room, layout editor, Ender Chest editor and premade kits.

• File: menus/main-menu.yml
• Size: 27 slots
• Actions: [open] kit-room, [open] premade-kits

Kit Room#

Static category template plus dynamic rendering for kit pages, favorites, recent, search and sort.

• File: menus/kit-room.yml
• Size: 54 slots
• Dynamic command: /kitroom

Kit Preview#

Read-only kit inspection before claiming a kit.

• File: menus/kit-preview.yml
• Command: /kit preview <name>

Kit Editor#

Personal, staff and legacy layout editing with protected controls.

• File: menus/kit-editor.yml
• Command: /kiteditor <kit>

Ender Chest Editor#

Profile selection and direct EC layout editing.

• File: menus/ender-chest-editor.yml
• Profiles: 1-3

Premade Kits#

Premade library entry menu for load, clone, favorites and recent workflows.

• File: menus/premade-kits.yml
• Size: 45 slots

Kit claim order#

1. Find kit by id.
2. Check permission unless bypassed.
3. Check cooldown and fire cooldown event.
4. Check world and optional region rules.
5. Fire claim event.
6. Clear inventory/armor if configured.
7. Apply saved player layout or base kit items.
8. Load Ender Chest if enabled.
9. Apply potion effects and cooldown.

Editor protections#

• Number key and shift-click handling
• Top/bottom inventory movement control
• Drag, drop, swap-hand and creative clone protection
• Filler item lock
• Armor slot validation
• Offhand whitelist validation
• Unsaved close warning and save confirmation

Storage modes#

• yaml: readable local files under data/.
• sqlite: default local SQL database under storage/nexakits.db.
• mysql: external database configuration for larger deployments.

Data surfaces#

• Player layouts: data/player_layouts or SQL table
• Ender Chest layouts: data/ender_chests or SQL table
• Premades: premades/*.yml and provider storage
• Backups: backups/backup-yyyyMMdd-HHmmss

Provider entry point#

NexaKitsAPI api = NexaKitsProvider.get();
api.kit("crystal").ifPresent(kit -> {
    player.sendMessage("Found " + kit.id());
});

boolean loaded = api.claimKit(player, "crystal");

Common events#

• KitClaimEvent
• KitPreviewEvent
• KitCooldownCheckEvent
• KitEditorOpenEvent, menu, save and reset events
• EnderChestEditorOpenEvent, save and reset events
• KitRoomOpenEvent, render and select events
• PremadeKitLoadEvent, create, clone and publish events
• PlayerAutoKitApplyEvent
• NexaKitsReloadEvent

Bootstrap checklist#

1. Install the supported Paper/Spigot API 1.20+ server and Java runtime.
2. Copy the generated plugins/NexaKits/ directory before editing YAML.
3. Set license-key and confirm LicenseGate validation before gameplay services register.
4. Choose SQLite for a small server or MySQL for a network, then restart to create the schema.
5. Grant only the kit permissions needed by a test group and verify with a non-op account.

Core baseline#

storage:
 type: "sqlite"
 async-save: true
kits:
 permission-mode: "EXPLICIT"
 preview-enabled: true
editor:
 enabled: true
ender-chest:
 enabled: true
kit-room:
 enabled: true
regear:
 enabled: true

Use /nexakits reload or /kit reload for runtime YAML changes. Treat storage and license changes as maintenance-window changes.

Default kit configuration#

kits:
 default-cooldown-seconds: 0
 permission-mode: "EXPLICIT"
 clear-inventory-default: true
 clear-armor-default: true
 load-ender-chest-default: false
 default-kits: kit-1 ... kit-7

Each entry has an id, display name and category. Gate access with nexakits.kit.<kit> or nexakits.kit.*.

Player claim workflow#

1. Use /kit list or /kitroom to discover available kits.
2. Preview with /kit preview <kit> before claiming.
3. Claim with /kit <kit>, /k1–/k7 or readable aliases.
4. Verify cooldown, kit permission, blocked/allowed world and optional WorldGuard region.
5. Confirm inventory/armor clearing, Ender Chest injection and potion effects with a test account.

Editor entry points#

1. Open /kit edit <kit> or /kiteditor <kit>.
2. Use /kiteditor legacy <kit> only when the legacy flow is intentionally required.
3. Arrange slots 0–35, armor and offhand through the 54-slot editor.
4. Use Save, Reset, Share, Import Shared Kit, Rename, Help and Back controls.
5. Close and reopen the editor to verify the SQL layout was saved.

Protection and sharing#

• editor.save-confirmation and unsaved-close-warning protect unfinished changes.
• Drop, number-key, hand-swap, creative-pickup and disabled-command protections remain active while editing.
• Helmet, armor and offhand placement is validated by slot.
• Sharing uses temporary UUID snapshots, nearby visibility and expiration.
• Use nexakits.editor.share and nexakits.editor.import as separate permissions.

Item editing flow#

1. Hold an item and run /edit-item, /itemeditor or /ei.
2. Edit the title through AnvilGUI and adjust amount where allowed.
3. Open enchantment, flags or trims menus and verify max-level/registry values.
4. Open a shulker to transition into menus/shulker-editor.yml.
5. Save and inspect serialized item metadata before using it in a kit.

Safety boundaries#

• item-editor.enabled controls the feature; nexakits.itemeditor controls player access.
• nexakits.itemeditor.admin is reserved for staff-level editing.
• Nested shulker exploit protection prevents unsafe recursive content mutations.
• Trim materials/patterns can use registry defaults or configured overrides.
• Test enchantment caps and invalid material fallback after reload.

Player profile flow#

1. Open /eceditor for profile 1 or /eceditor <profile> for a specific profile.
2. Arrange and save the profile through the Ender Chest editor.
3. Use /eceditor import <uuid> for a shared snapshot when permitted.
4. Claim a kit with kits.load-ender-chest-default enabled only after testing replacement behavior.
5. Restart and verify each profile remains independent.

Profile permissions#

ender-chest.enabled: true
ender-chest.default-profiles: 7
ender-chest.max-profiles: 7
ender-chest.permission-prefix: "nexakits.ec.slots."

Use nexakits.ec.slots.<number>, nexakits.ec.edit, nexakits.ec.share and nexakits.ec.import. Staff uses /ecadmin view|edit|reset <player> [profile].

Player browsing flow#

1. Open /kitroom or /kroom.
2. Choose a category or use /kitroom category <category>.
3. Search with /kitroom search <query> across kit names, descriptors and materials.
4. Use favorites, recents and /kitroom sort <mode> to refine results.
5. Left-click load, right-click preview, shift-right-click favorite and middle-click edit when permitted.

Staff category workflow#

1. Configure category slots and item content in kitroom.yml.
2. Open the category and verify potions, arrows, equipment and PvP materials.
3. Edit in memory with /kitroom edit <category>.
4. Persist a reviewed category with /kitroom save <category>.
5. Reopen the room and confirm pagination/search/favorite state.

Staff workflow#

1. Create/save with /premadekit create <id> or /premadekit save <id>.
2. Edit with /premadekit edit <id> and verify item metadata.
3. Publish with /premadekit publish <id> after review.
4. Delete only with /premadekit delete <id> after checking references.
5. Keep the premades/ backup when sharing between servers.

Player workflow#

1. Open /premadekit, /premadekits or /pkits.
2. Use /premadekit list, recent and favorites to find a loadout.
3. Load with /premadekit load <id> or clone with /premadekit clone <premade> <kit>.
4. Verify clone overwrites only the selected personal layout.

Trigger configuration#

auto-kit.enabled: true
auto-kit.kit: ""
auto-kit.on-join: false
auto-kit.on-respawn: false
auto-kit.on-world-change: false
auto-kit.on-kill: false
auto-kit.delay-ticks: 5
auto-kit.block-in-combat: true
auto-kit.ignore-combat-on-kill: true

Rollout checklist#

1. Set an explicit kit id or use the first definition with auto-give: true.
2. Configure allowed/blocked worlds and WorldGuard regions.
3. Test join, respawn, world change and kill independently.
4. Enter combat through CombatLogX/PvPManager and verify the block rule.
5. Test broadcast radius and ensure the kit is not duplicated after reconnect.

Player flow#

1. Grant nexakits.regear and run /regear.
2. Place and right-click the configured shulker.
3. Wait for the configured combat-clear period, then choose Regear.
4. Verify only missing items are filled and occupied slots are preserved.
5. Break the shulker and confirm the configured drop behavior.

Safety configuration#

regear.enabled: true
regear.owner-only: true
regear.drop-on-break: true
regear.combat-clear-seconds: 3
regear.fallback-to-empty-slots: true
regear.excluded-materials:
 - "TOTEM_OF_UNDYING"

Test with CombatLogX/PvPManager states, full inventories, occupied original slots and a missing last-kit record.

Provider setup#

• SQLite uses storage/nexakits.db with WAL enabled by default.
• MySQL uses HikariCP pool settings for network deployments.
• Player tables include layouts, Ender Chest profiles, cooldowns, favorites and audit log.
• Premades remain human-readable YAML rather than thousands of player files.
• Async save/debounce reduces synchronous disk work; verify flush on shutdown.

Maintenance workflow#

1. Run /nexakits storage and record provider health/counts.
2. Run /nexakits backup before changing storage.
3. Use /nexakits migrate sqlite mysql only on a tested copy first.
4. Restore with /nexakits restore <backup> during maintenance.
5. Reopen an existing kit/editor/Ender Chest profile and verify data after migration.

Gameplay hooks#

WorldGuard controls region restrictions. CombatLogX and PvPManager protect auto-kit/regear timing. NexaCombat can participate in the local PvP ecosystem.

Account hooks#

LuckPerms metadata can scale Ender Chest profile access. Vault is available for economy-aware integrations. Skript exposes a bridge surface for server automation.

Cosmetic hooks#

SkinsRestorer and PlaceholderAPI provide optional display/integration surfaces. Missing plugins should skip registration safely and appear in the hook report.

Developer surface#

• Access NexaKitsAPI through NexaKitsProvider.get().
• Observe kit claim, preview and cooldown checks.
• Observe editor open/save/reset and Ender Chest open/save/reset events.
• Observe Kit Room open/render/select and premade load/create/clone/publish events.
• Use the API for custom menus, stats, claim gates and addon integrations.

Placeholder setup#

1. Enable integrations.placeholderapi.
2. Use total/available kit placeholders in scoreboards and menus.
3. Use selected/last kit values to connect Regear and player profile displays.
4. Use per-kit cooldown and layout status placeholders for feedback.
5. Test unknown kit ids and offline players before publishing the display.

Admin command workflow#

/nexakits reload
/nexakits hooks
/nexakits storage
/nexakits backup
/nexakits restore <backup>
/kit give <player> <kit>
/kiteditor staff <player> <kit>
/ecadmin view|edit|reset <player> [profile]

Permission boundaries#

• Player access: nexakits.kit.<kit>, nexakits.editor, nexakits.ec.edit, nexakits.kitroom.open, nexakits.regear.
• Staff layout: nexakits.editor.staff, nexakits.ec.admin, nexakits.itemeditor.admin.
• Publishing: nexakits.premade.admin, nexakits.premade.publish, nexakits.kit.delete.
• Maintenance: nexakits.reload, backup, restore, migrate.

Stage 1 — sandbox#

• Use SQLite and kit-1/kit-2 only.
• Test claim, preview, cooldown and personal editor.
• Confirm no item duplication on close, reset or reconnect.

Stage 2 — pilot#

• Add categories, premades, Ender Chest profiles and Kit Room search.
• Test multiple ranks, worlds, regions and combat states.
• Measure async saves, SQL health and backup restore time.

Stage 3 — live#

• Enable auto-kit/regear only after combat tests.
• Restrict staff/global editor and restore permissions.
• Record plugin, server, storage, hook and premade versions.

Staff: publish a kit#

1. Create the kit/category and choose its permission id.
2. Load the intended items, armor and offhand into the editor.
3. Save with /kit save <name> or the configured premade workflow, then preview it from /kitroom.
4. Test claim, cooldown, disabled world and item restoration with a normal player.
5. Publish only after the kit icon, lore, category and permission are correct.

Player: claim and customize#

1. Open /kitroom, search/favorite a kit and use preview before claiming.
2. Claim with /kit <name> or the configured shortcut.
3. Use /kiteditor <kit> for the personal inventory/armor/offhand layout.
4. Use /eceditor [profile] for a kit-linked Ender Chest profile.
5. Reopen the kit after a restart to verify saved layout persistence.

Safe editor settings#

editor:
  enabled: true
  save-confirmation: true
  unsaved-close-warning: true
  prevent-number-key: true
ender-chest:
  max-profiles: 3
kit-room:
  search-enabled: true
  show-locked-kits: true

Ranked/PvP rollout#

Gate kits with nexakits.kit.<kit>, give each mode a category, and keep cooldowns/world restrictions consistent with the practice plugin. Use approved premades for staff loadouts so player edits never mutate the shared source.

Crystal PvP#

Use crystal category kits, EC profile 1, premade aggressive/defensive loadouts and no cooldowns for arena servers.

Practice / FFA#

Use Kit Room categories and personal layouts so players can repeatedly claim consistent loadouts between fights.

SMP PvP#

Use permissions, world restrictions, region checks and cooldowns to keep kits controlled outside PvP arenas.

Ranked kits#

Gate kit ids behind nexakits.kit.<kit> and EC profiles behind nexakits.ec.slots.<n>.

Staff loadout library#

Create approved premades and let players clone them into personal layouts instead of editing global kits.

SQL deployment#

Use SQLite for one server, MySQL for larger deployments, and backup before migrating from YAML.

Normal jar#

& 'C:\Program Files\Apache\maven\bin\mvn.cmd' -DskipTests package

The normal release jar is written to target/NexaKits-1.0.0.jar.

Obfuscated jar#

$env:JAVA_HOME='C:\Program Files\Java\jdk-21'
$env:Path="$env:JAVA_HOME\bin;$env:Path"
& 'C:\Program Files\Apache\maven\bin\mvn.cmd' -Pobfuscate -DskipTests package

The obfuscated jar is written to target/NexaKits-1.0.0-obfuscated.jar.

Before asking for support#

• Test the latest available jar.
• Check Java and server versions.
• Run /nexakits hooks and /nexakits storage.
• Attach changed YAML files when config is involved.
• Include the first console error after startup.