MysteryCrates

A lootbox that stops and asks. Bank the prize, or climb one more rung?

MysteryCrates hands your players loot crates they earn by playing, then lets them bank the prize or climb one rung higher on odds they can check themselves.

Most lootboxes open themselves. You click, you get a thing, you shrug. MysteryCrates makes the player decide. Every crate is a ladder, each rung rolls a real named prize, and before they choose I print the honest chance of the next rung landing. Crates are earned from kills, tames, login streaks and hours played, never handed out for cash, and every single roll comes with a receipt the player can check line by line.

Supported Features

• The climb: every crate is a ladder of rungs, and each rung rolls a real prize you can walk away with.
• Bank it or push it: take keeps what is in hand, climb risks it for the rung above, and I print the true odds before the choice.
• Sealed doors: the top rungs deal face down doors, the player picks one, then I turn all of them over so they see what they missed.
• Earned, never sold: crates drop from wild kills, boss kills, tames, first joins, login streaks, hours played and PvP kills, each with its own switch, cooldown and daily cap.
• A receipt for every roll: I publish the hash of a secret seed before play starts, so verify can walk a player through the whole sum afterwards, pity climbs included.
• Shards soften the misses: a failed climb or a repeat prize pays shards, and shards buy insurance, a reroll, or a whole crate forged from scratch.
• Nothing to place, nothing to lose: a crate is a row in a database, not a box in the world, so no game mod, no lost loot to a stasis bug, and no build limit trouble.
• Your loot, your files: one plain JSON file per crate holds items, creatures, engrams, shop points, XP, shards and console rewards, with weights you set.
• One bad file breaks one crate: fat finger a crate file and I switch off that crate alone, then tell you the file, the line and the column to look at.
• Bring your old boxes: point me at another lootbox plugin's config file and I turn its boxes into crate files for you.
• Runs on what you already have: shop points, permissions, Discord and MySQL are all optional, and the built in SQLite needs no setup at all.
• Speak your players' language: set the language in the config and every line I say in game and in the console follows, and the file is plain text you can edit or hand to a friend who runs a server in another tongue.

Console & RCON Commands

Command	What It Does	Where
MysteryCrates.Reload	Read the config, the language file and every crate file again, with no restart.	Both
MysteryCrates.Check	Test every crate file and list the problems, without touching the crates players are using.	Both
MysteryCrates.Crates	List every crate that loaded so you can see what your server is really offering.	Both
MysteryCrates.Export	Write one crate back out to a file so you can copy it, share it, or keep a spare.	Both
MysteryCrates.Import	Turn another lootbox plugin's config file into crate files.	Both
MysteryCrates.Give	Hand a player one or more of any crate. Takes an online name or a player id.	Both
MysteryCrates.Shards	Add shards to a player, or take them away with a minus number.	Both
MysteryCrates.Reseed	Roll a player a fresh secret seal, which starts their fairness trail over.	Both
MysteryCrates.Book	Print a player's recent opens, or just the ones from a crate you name.	Both
MysteryCrates.Verify	Print the full receipt for any past open by its number.	Both
MysteryCrates.TestDiscord	Send a test post so you can check your webhook before a big night.	Both

Player Commands

One chat word does the lot. The word lives in config.json, so rename /crate to whatever suits your server.

Command	What It Does
/crate	Show what is in the player's pocket: crates waiting, shards held, and what to type next.
/crate open <crate>	Start a climb on one of their crates.
/crate take	Bank the prize sitting on the current rung and end the climb.
/crate climb	Risk the prize for a shot at the rung above.
/crate pick <n>	Pick one of the sealed doors on a door rung.
/crate insure	Spend shards so a failed climb does not cost them everything.
/crate reroll	Spend shards to roll the current rung again.
/crate forge <crate>	Spend shards to build a whole new crate out of thin air.
/crate odds <crate>	Read the real rung by rung odds of a crate before spending it.
/crate book [crate]	Look back over their own recent opens.
/crate fair	Show the published hash of their sealed seed, before any of it is spent.
/crate seed <text>	Add their own words to the seed, so the server alone cannot pick the outcome.
/crate verify [n]	Print the receipt for one of their opens and check the maths.
/crate claim	Pick up a prize that was held back because their inventory was full.

Permissions

Node	What It Unlocks
Permissions.UsePermission	The node you set here controls opening crates at all. Left blank, which is the default, everybody may open them.
Permission	The node you set on this key inside a crate's own file controls that one crate. This is how a VIP only crate is built.

Permissions is optional. With no node set, or with Permissions.Enabled false, every player may open their crates. If the Permissions plugin is missing or will not answer, I let the player through on purpose, so a broken permissions install can never lock your server out of its own loot.

Config

To see every configuration option, visit our docs. To edit your config files the easy way, open our configuration editor.

Requirements

• AsaApi v2.01 or newer
• A Windows server running ArkAscendedServer through the AsaApi loader
• A licence key, which you paste into config.json under License and then Key
• ArkShop or WShop (optional, only needed when a prize pays shop points)
• Permissions (optional, works without it, only needed to gate crates by group)
• MySQL (optional, works without it, since SQLite is built in and needs no setup)
• A Discord webhook (optional, works without it)

Installation

1. Unzip the download and put the MysteryCrates folder inside ArkApi/Plugins/. Leave the folder name alone, because it has to match the DLL inside it.
2. Open MysteryCrates/config.json and paste your licence key under License and then Key.
3. Look through Configs/crates/ and set up the loot. Bronze, Silver and Gold are there to copy from.
4. Pick which ways players earn crates in the Earn block, and turn off the ones you do not want.
5. Start the server through AsaApiLoader.exe.
6. Check ArkApi.log for the line that says the plugin loaded, then run MysteryCrates.Check to see your crate files got read cleanly.

Support & Help

Stuck on a crate file, or want a hand planning your loot before you go live? Come and find me on Discord and I will walk you through it: https://discord.gg/8GGaEzWk9p

Frequently Asked Questions

What does MysteryCrates do?

MysteryCrates gives your players loot crates they earn by playing, and turns opening one into a decision instead of a click. Each crate is a ladder of rungs holding real named prizes. At every rung the player sees the honest chance of climbing and chooses to bank what they have or push for more.

How do I install MysteryCrates?

Unzip the download and drop the whole MysteryCrates folder into ArkApi/Plugins/, keeping the folder name as it is so it matches the DLL. Paste your licence key into config.json, set up the crate files in Configs/crates/, then restart the server through the AsaApi loader. Watch ArkApi.log for the loaded line.

How can a player be sure the odds are real?

Before any of it is spent, MysteryCrates seals a secret seed and publishes its hash with /crate fair, and a player may mix their own words into it with /crate seed. After an open, /crate verify prints every step of the sum so anyone can redo it by hand. When a pity rule forced a climb, the receipt says so out loud, because hiding it would make the numbers stop adding up.

Does it need ArkShop or a MySQL server?

No, neither. MysteryCrates only knocks on a points shop when a prize pays shop points, and it is happy with ArkShop or with WShop, so keep the one you already have. Everything else lives in a SQLite file on your own server with no setup from you. Point it at MySQL only if you want several servers sharing one set of crates and shards.

Will a crate go missing if my server stops badly?

A crate is a row in a database, never a box standing in the world, so nothing rots, nothing sinks through the floor, and nothing vanishes on a bad restart. If a player's inventory is full when a prize lands, I hold the prize back rather than dropping it, and they pick it up later with /crate claim.

Was any AI content used in the making of this?

The source code itself was fully created by myself. I do use ChatGPT occasionally to generate product images, and I do use ChatGPT to generate the website descriptions. I do this because I don't speak native English perfectly. I am natively from Sweden, so I use GPT to help translate and write product descriptions. I also will sometimes use GPT to write better English logs. Majority of my Free plugins are open source, so you can review the code yourself and freely fork and edit it to your liking.