🎁 ARCADIA LOOTBOX — KEYS, CRATES & REWARDS 🎁

⚡ The lootbox system your server actually deserves ⚡

Data-driven crates, 50 themed keys, free timers, multi-draw — and a polished Hub UI players will love.

[EN] Built for Real Servers

Arcadia Lootbox is a production-grade crate system. Thread-safe managers, async config reload, atomic map swaps, anti-autoclicker, per-lootbox cooldowns, usage caps, soft LuckPerms integration. No client-only references leak into common code — safe on dedicated servers from day one.

[FR] Conçu pour les vrais serveurs

Arcadia Lootbox est un système de crates de qualité production. Managers thread-safe, rechargement de config asynchrone, swap atomique des maps, anti-autoclicker, cooldowns par lootbox, limites d'utilisations, intégration LuckPerms souple. Aucune classe client ne fuit dans le code commun — sûr sur serveur dédié dès le premier lancement.

🔌 DROP-IN & DATA-DRIVEN

Drop the jar in mods/ and you get 50 themed keys, a steampunk Hub UI, and 14 admin commands out of the box. Define new lootboxes with simple JSON files — no Java, no KubeJS scripts, no datapacks.

✅ Works in singleplayer and on dedicated servers. Reload live with /arcadia_lootbox reload — async, no tick freeze.

🔌 PRÊT À L'EMPLOI & DATA-DRIVEN

Posez le jar dans mods/ et vous avez 50 clés thématiques, une UI Hub steampunk et 14 commandes admin d'office. Définissez de nouvelles lootbox avec de simples fichiers JSON — pas de Java, pas de scripts KubeJS, pas de datapacks.

✅ Fonctionne en solo et sur serveur dédié. Rechargement à chaud via /arcadia_lootbox reload — asynchrone, sans freeze de tick.

🇺🇸 Description (English) 🇺🇸

🌟 Reward your players without writing a single line of code. 🌟

🤔 Why Arcadia Lootbox?

🗝️ 50 Themed Keys Six categories — Dungeon, Shop, Vote, Lootable, Event, Boss — with up to 10 tiers each (Common → Transcendent / Bronze → Overlord). Custom 16×16 textures and JSON-defined item models, all bundled.	📦 Data-Driven Lootboxes Define a lootbox by writing a JSON file. 35+ tunable parameters: weighted or guaranteed drops, per-item chance, min/max counts, rarities, broadcast triggers, free timers, permissions, particles, sounds, animations, command rewards.
🎨 Steampunk Hub UI A polished client-side browser screen with copper-glass styling. Categories collapse and expand on click; expand-all / collapse-all controls keep things tidy when you have dozens of lootboxes.	🎯 Smart Preview Menu Single clickable action row, 28 items per page, rarity filter chips, multi-draw (left = 1, right = all keys, shift = 10). Right-click a key in air to open its matching lootbox preview directly.
⏰ Free Lootbox Timers Per-lootbox free claims with configurable cooldown (72 h default, 48 h with permission). Persistent across restarts via `free_claims.json`. Auto-save every 5 minutes.	🛡️ Hardened & Optimized Anti-autoclicker, per-lootbox cooldowns, usage caps, strict slot bounds, click anti-spam, null-safe registry lookups, input sanitization. Frame cached, rarity counts cached, ordered lists immutable.
🌐 100% Bilingual EN/FR Every user-facing string goes through `LanguageHelper` with both English and French translations. Language is detected per-player via client info — no manual switch needed.	🔑 Soft LuckPerms Integration Permission nodes on every lootbox and free-reduced-cooldown perk. LuckPerms is optional — the mod gracefully falls back to vanilla OP checks when LP isn't installed.

🎮 How to Use

It really is this simple:

1️⃣ Drop the jar in `mods/` and start the server.	2️⃣ Edit JSON files in `config/arcadialootbox/` to define your lootboxes.
3️⃣ Run `/arcadia_lootbox give` to spawn a crate, or `/arcadia_lootbox hub` to open the UI.	4️⃣ Right-click the placed crate with the correct key. Watch the rewards fly. Done.

🛠️ Creating a Lootbox (JSON)

Every lootbox is a single JSON file in config/arcadia/arcadialootbox/. The file name becomes the lootbox ID. Two examples are generated on first launch — example_weighted.json and example_guaranteed.json — alongside a README.txt cheat sheet.

🎲 Weighted Mode

Each item in lootTable rolls independently against its chance (0.0 to 1.0). Multiple items can drop on the same open, or none at all if you set low chances.

{
  "displayName": "Treasure Chest",
  "color": "yellow",
  "keyItem": "arcadialootbox:shop_key_rare",
  "rarity": "rare",
  "type": "weighted",
  "broadcastRare": true,
  "lootTable": [
    { "item": "minecraft:diamond",
      "minCount": 1, "maxCount": 3,
      "chance": 0.3, "rarity": "rare",
      "displayName": "Diamond",
      "broadcast": true },
    { "item": "minecraft:gold_ingot",
      "minCount": 2, "maxCount": 5,
      "chance": 0.6, "rarity": "uncommon",
      "displayName": "Gold Ingot" },
    { "item": "minecraft:iron_ingot",
      "minCount": 5, "maxCount": 10,
      "chance": 1.0, "rarity": "common",
      "displayName": "Iron Ingot" }
  ],
  "particles": ["minecraft:flame"],
  "openSound": "minecraft:block.chest.open",
  "openMessage": "§aLootbox opened!"
}

🎯 Guaranteed Mode

The player always receives guaranteedItem and exactly one entry from lootTable, picked using chance as a weight (higher = more likely).

{
  "displayName": "Lucky Box",
  "color": "lime",
  "keyItem": "arcadialootbox:vote_key_common",
  "rarity": "uncommon",
  "type": "guaranteed",
  "guaranteedItem": "minecraft:bread",
  "guaranteedMinCount": 1,
  "guaranteedMaxCount": 3,
  "lootTable": [
    { "item": "minecraft:diamond",
      "minCount": 1, "maxCount": 1,
      "chance": 0.05, "rarity": "legendary" },
    { "item": "minecraft:emerald",
      "minCount": 1, "maxCount": 3,
      "chance": 0.15, "rarity": "rare" },
    { "item": "minecraft:gold_ingot",
      "minCount": 2, "maxCount": 5,
      "chance": 0.30, "rarity": "uncommon" },
    { "item": "minecraft:iron_ingot",
      "minCount": 3, "maxCount": 8,
      "chance": 0.50, "rarity": "common" }
  ],
  "freeEnabled": true,
  "freeCooldownHours": 72,
  "freeReducedCooldownHours": 48,
  "freeReducedPermission": "arcadialootbox.free.reduced",
  "experienceReward": 5
}

🧩 Key fields you'll use most

Field	What it does
`keyItem`	The item the player must hold to open. Pick one of the 50 registered keys (e.g. `arcadialootbox:dungeon_key_rare`) or any vanilla item id.
`type`	`"weighted"` or `"guaranteed"` — chooses the drop algorithm above.
`rarity`	`common, uncommon, rare, epic, legendary, mythic`. Drives color, broadcast threshold, sort order.
`permission`	LuckPerms node required to open. Empty = no check.
`cooldownTicks`	Per-player cooldown between two opens (20 = 1 second).
`maxUses`	Hard cap of opens per placed block. `-1` = unlimited.
`freeEnabled`	Allow the player to claim this lootbox for free every `freeCooldownHours` hours.
`broadcastRare` / `broadcast` per entry	Auto-broadcast drops above the global rarity threshold, or force a broadcast on a specific item.
`commandRewards`	Array of `{ command, chance, asConsole }` — runs as console or player, `{player}` is replaced safely.
`displayNameFR`, `openMessageFR`, `openTitleFR`	Optional French overrides. Fall back to the English fields when empty.

Full field reference (35+ parameters) is documented in the project README.md. After editing any JSON, run /arcadia_lootbox reload — the reload is async, so the tick loop never stalls.

📦 Requirements

Dependency	Version
Minecraft	1.21.1
NeoForge	21.1.42+
Java	21
Arcadia Lib	bundled in the jar
LuckPerms	optional (soft integration)

Arcadia Lib is shipped inside the jar — no separate download. LuckPerms is fully optional; the mod falls back to vanilla OP checks when it's absent.

🐛 Bug Reports & Support

Found a crash or unexpected behavior? We'd love to hear about it.

Please include your full crash log, your Arcadia Lootbox and NeoForge versions, the JSON config of the relevant lootbox if any, and clear steps to reproduce.

🤝 Contribute

Issues, suggestions and bug reports are welcome on the public tracker.

🤝 Official Hosting Partner

Want to run your own modded server with Arcadia Lootbox? Our official US/international partner offers high-performance Minecraft hosting optimized for modpacks.

🇫🇷 Description (Français) 🇫🇷

🌟 Récompensez vos joueurs sans écrire une seule ligne de code. 🌟

🤔 Pourquoi Arcadia Lootbox ?

🗝️ 50 clés thématiques Six catégories — Donjon, Boutique, Vote, Trouvable, Événement, Boss — avec jusqu'à 10 paliers chacune (Commune → Transcendante / Bronze → Suzerain). Textures custom 16×16 et modèles d'objet en JSON, tout est inclus.	📦 Lootbox data-driven Définissez une lootbox en écrivant un fichier JSON. 35+ paramètres réglables : drops pondérés ou garantis, chance par item, min/max, raretés, déclencheurs de broadcast, timers gratuits, permissions, particules, sons, animations, récompenses par commande.
🎨 UI Hub steampunk Un écran navigateur côté client soigné avec style cuivre-verre. Les catégories se replient et se déploient au clic ; les boutons Tout déployer / Tout replier gardent l'écran propre quand vous avez des dizaines de lootbox.	🎯 Menu Preview intelligent Une seule rangée d'action cliquable, 28 objets par page, puces de filtre par rareté, multi-tirage (gauche = 1, droit = toutes les clés, shift = 10). Clic-droit avec une clé dans le vide pour ouvrir directement la lootbox correspondante.
⏰ Timers de lootbox gratuites Réclamations gratuites par lootbox avec cooldown configurable (72 h par défaut, 48 h avec permission). Persistantes entre redémarrages via `free_claims.json`. Sauvegarde auto toutes les 5 minutes.	🛡️ Durci & optimisé Anti-autoclicker, cooldowns par lootbox, limites d'utilisations, bornes strictes sur les slots, anti-spam de clic, lookups de registry null-safe, sanitization des entrées. Cadre en cache, comptes de rareté en cache, listes immuables.
🌐 100 % bilingue EN/FR Chaque texte visible passe par `LanguageHelper` avec traductions anglaise et française. La langue est détectée par joueur via le client info — aucun switch manuel.	🔑 Intégration LuckPerms souple Nodes de permission sur chaque lootbox et perk de cooldown réduit. LuckPerms est optionnel — le mod retombe gracieusement sur les checks OP vanilla quand LP n'est pas installé.

🎮 Comment l'utiliser

C'est vraiment aussi simple que ça :

1️⃣ Posez le jar dans `mods/` et démarrez le serveur.	2️⃣ Éditez les fichiers JSON dans `config/arcadialootbox/` pour définir vos lootbox.
3️⃣ Lancez `/arcadia_lootbox give` pour spawn une crate, ou `/arcadia_lootbox hub` pour ouvrir l'UI.	4️⃣ Clic-droit la crate posée avec la bonne clé. Regardez les récompenses voler. Terminé.

🛠️ Créer une lootbox (JSON)

Chaque lootbox est un unique fichier JSON dans config/arcadia/arcadialootbox/. Le nom du fichier devient l'ID de la lootbox. Deux exemples sont générés au premier lancement — example_weighted.json et example_guaranteed.json — accompagnés d'une feuille de triche README.txt.

🎲 Mode Weighted

Chaque item dans lootTable tire indépendamment contre son chance (0.0 à 1.0). Plusieurs items peuvent drop sur la même ouverture, ou aucun si vous mettez des chances faibles.

{
  "displayName": "Coffre au Trésor",
  "color": "yellow",
  "keyItem": "arcadialootbox:shop_key_rare",
  "rarity": "rare",
  "type": "weighted",
  "broadcastRare": true,
  "lootTable": [
    { "item": "minecraft:diamond",
      "minCount": 1, "maxCount": 3,
      "chance": 0.3, "rarity": "rare",
      "displayName": "Diamant",
      "broadcast": true },
    { "item": "minecraft:gold_ingot",
      "minCount": 2, "maxCount": 5,
      "chance": 0.6, "rarity": "uncommon",
      "displayName": "Lingot d'or" },
    { "item": "minecraft:iron_ingot",
      "minCount": 5, "maxCount": 10,
      "chance": 1.0, "rarity": "common",
      "displayName": "Lingot de fer" }
  ],
  "particles": ["minecraft:flame"],
  "openSound": "minecraft:block.chest.open",
  "openMessage": "§aLootbox ouverte !"
}

🎯 Mode Guaranteed

Le joueur reçoit toujours guaranteedItem et exactement une entrée du lootTable, choisie avec chance utilisé comme poids (plus élevé = plus probable).

{
  "displayName": "Boîte Chanceuse",
  "color": "lime",
  "keyItem": "arcadialootbox:vote_key_common",
  "rarity": "uncommon",
  "type": "guaranteed",
  "guaranteedItem": "minecraft:bread",
  "guaranteedMinCount": 1,
  "guaranteedMaxCount": 3,
  "lootTable": [
    { "item": "minecraft:diamond",
      "minCount": 1, "maxCount": 1,
      "chance": 0.05, "rarity": "legendary" },
    { "item": "minecraft:emerald",
      "minCount": 1, "maxCount": 3,
      "chance": 0.15, "rarity": "rare" },
    { "item": "minecraft:gold_ingot",
      "minCount": 2, "maxCount": 5,
      "chance": 0.30, "rarity": "uncommon" },
    { "item": "minecraft:iron_ingot",
      "minCount": 3, "maxCount": 8,
      "chance": 0.50, "rarity": "common" }
  ],
  "freeEnabled": true,
  "freeCooldownHours": 72,
  "freeReducedCooldownHours": 48,
  "freeReducedPermission": "arcadialootbox.free.reduced",
  "experienceReward": 5
}

🧩 Les champs que vous utiliserez le plus

Champ	Effet
`keyItem`	L'item que le joueur doit tenir pour ouvrir. Choisissez une des 50 clés intégrées (ex. `arcadialootbox:dungeon_key_rare`) ou n'importe quel id d'item vanilla.
`type`	`"weighted"` ou `"guaranteed"` — choisit l'algorithme de drop ci-dessus.
`rarity`	`common, uncommon, rare, epic, legendary, mythic`. Pilote couleur, seuil broadcast, ordre de tri.
`permission`	Node LuckPerms requis pour ouvrir. Vide = pas de check.
`cooldownTicks`	Cooldown par joueur entre deux ouvertures (20 = 1 seconde).
`maxUses`	Plafond d'ouvertures par bloc posé. `-1` = illimité.
`freeEnabled`	Autorise le joueur à réclamer cette lootbox gratuitement toutes les `freeCooldownHours` heures.
`broadcastRare` / `broadcast` par entrée	Annonce auto les drops au-dessus du seuil global, ou force un broadcast sur un item précis.
`commandRewards`	Tableau de `{ command, chance, asConsole }` — exécute en console ou joueur, `{player}` est remplacé de manière sûre.
`displayNameFR`, `openMessageFR`, `openTitleFR`	Overrides français optionnels. Retombent sur les champs anglais si vides.

La référence complète des champs (35+ paramètres) est documentée dans le README.md du projet. Après chaque édition de JSON, lancez /arcadia_lootbox reload — le rechargement est asynchrone, donc le tick loop ne bloque jamais.

📦 Prérequis

Dépendance	Version
Minecraft	1.21.1
NeoForge	21.1.42+
Java	21
Arcadia Lib	inclus dans le jar
LuckPerms	optionnel (intégration souple)

Arcadia Lib est livrée à l'intérieur du jar — aucun téléchargement séparé. LuckPerms est totalement optionnel ; le mod retombe sur les checks OP vanilla en son absence.

🐛 Bugs & Support

Vous avez un crash ou un comportement inattendu ? On veut bien le savoir.

Merci d'inclure votre log de crash complet, vos versions d'Arcadia Lootbox et NeoForge, le JSON de la lootbox concernée le cas échéant, ainsi que des étapes claires pour reproduire.

🤝 Contribuer

Issues, suggestions et signalements de bugs sont les bienvenus sur le tracker public.

🤝 Hébergeur Officiel Partenaire

Vous souhaitez héberger votre propre serveur moddé avec Arcadia Lootbox ? Notre partenaire officiel français propose un hébergement Minecraft haute performance optimisé pour les modpacks.

🌟 PLAY ARCADIA V2 — ECHOES OF POWER 🌟

⚡ Where Magic Meets Machinery ⚡

The flagship modpack Arcadia Lootbox was built for — and ships in by default.

🔗 True Cross-Mod Progression Tech and magic don't live in separate silos. Late-game crafts need both ecosystems. 4 custom bridge items (Arcane Circuit, Ethereal Alloy, Industrial Heart, Rune Matrix) tie everything together.	🌐 100% Bilingual EN/FR 25,000+ translation entries across the entire pack. Quests, items, custom UIs — fully translated. Zero franglais.
🎮 Curated Server Experience In-house mods built for Arcadia: Arcadia Lootbox, Arcadia Pets (collectibles + PvP duels + ELO ladder), Arcadia Guard moderation, Prestige progression, Heart of Arcadia. Not mods bolted together — a tailored ecosystem.	📜 3,000+ Quest-Guided Journey 31 chapters of FTB Quests covering every mod's progression path. Whether you're fresh or a 1000-hour veteran, you always know what to do next.

🎮 JOIN THE ADVENTURE — 490 MODS, ONE EPIC JOURNEY 🎮

🇫🇷 Découvrez Arcadia V2 : Echoes of Power
Le modpack phare pour lequel Arcadia Lootbox a été conçu — et qui l'inclut par défaut. 490+ mods, 3 000+ quêtes, 5 serveurs actifs, 100 % bilingue EN/FR. Industrie + Magie + Exploration, comptez 150 à 300 heures pour atteindre l'endgame.

❤️ Support the Project / Soutenir le Projet

Your support helps us keep Arcadia alive and evolving!
Votre soutien nous aide à faire vivre et évoluer Arcadia !

Arcadia LootBox