TribeCraft Wiki · Release 2026.09.8
Wiki Release: 2026.09.8 · UltimateRaids: 0.12.0 · Documentation branch: 1

Kits and player loadouts#

Loadout mode controls whether UltimateRaids treats the player's normal inventory as part of the raid or temporarily replaces it with a controlled kit.

PLAYER mode#

loadout:
  mode: PLAYER

Use PLAYER when:

  • RPG/progression gear should matter;
  • players bring their own food/arrows/items;
  • the raid is part of the normal survival/economy loop.

Environment rules still decide whether item drop/pickup and other actions are allowed.

KIT mode#

loadout:
  mode: KIT
  kit: crypt

Use KIT when:

  • all players should have equal gear;
  • the raid is a minigame;
  • you want role-specific curated equipment;
  • normal inventory should not affect difficulty.

Create a kit in-game#

A practical workflow:

  1. Prepare your inventory exactly as the raid player should receive it.
  2. Equip the intended armor.
  3. Apply any effects/state you want represented by the kit configuration.
  4. Run:
/uraid kit create crypt
  1. Save/update from the prepared player state:
/uraid kit save crypt
  1. Inspect it:
/uraid kit view crypt
  1. Give a normal test copy without entering a raid:
/uraid kit give crypt
/uraid kit give crypt <player>
  1. Reload after manual file edits:
/uraid kit reload
  1. Delete when no raid references it:
/uraid kit delete crypt

Kit file structure#

The bundled example demonstrates:

id: example
name: '<primary>Example Raider Kit</primary>'
clear-effects: true
health: 20
food: 20
saturation: 8

inventory:
  '0':
    item: IRON_SWORD
    amount: 1

armor:
  helmet:
    item: IRON_HELMET
    amount: 1

effects: []

Inventory keys correspond to inventory slots. Armor is separated into helmet/chestplate/leggings/boots.

Item providers#

Kit/reward/item systems can use the registered item implementations. The default provider handles normal Bukkit materials; optional integrations can resolve custom items.

Before using an external item provider:

/uraid debug implementations

and verify it is actually active. A provider name in modules.yml is only a preference, not proof that the external plugin/extension loaded successfully.

Inventory escrow and restoration#

KIT mode is not simply “clear inventory and give items”. UltimateRaids keeps the original player state so it can be restored when the managed raid/lobby flow ends. Pending loadout state is designed to survive normal recovery paths rather than relying only on memory.

That is why administrators should not manually delete storage while players have active/pending raid state.

What to test before production KIT use#

Test all of these:

  • join lobby → leave before start;
  • join → start → complete;
  • join → fail;
  • join → administrator stop;
  • death/elimination;
  • disconnect/reconnect within grace time;
  • full inventory before/after raid;
  • staging-server restart/recovery.

The original inventory should not be duplicated or lost.

KIT with MINIGAME#

KIT is a strong fit for MINIGAME because the lobby and match lifecycle is fully managed. Make sure the player does not receive/lose the raid kit repeatedly during queue transitions.

Use the player/lobby GUI and normal leave flow rather than external teleport plugins to end participation.

Common mistakes#

Raid says kit is missing#

The raid references an ID that does not exist/failed to load. Verify the file under kits/ and reload kits.

Kit contains wrong items#

Re-prepare the player inventory and run /uraid kit save <id>, or edit the kit YAML carefully.

Custom item becomes normal/invalid item#

Check the item provider ID and /uraid debug implementations.

Original inventory did not restore#

Do not “fix” by deleting storage. Check pending recovery/loadout state and the console first. See Troubleshooting.

Wiki Release 2026.09.8 · Canonical TribeCraft documentation.