MysteryCrates configuration editor

Set everything with sliders and toggles, then export the files. This covers the whole config folder: config.json for how the plugin behaves, one file per crate for the loot, the shared pools they draw from, and the language file players read. Your progress saves in this browser as you go. See the docs for what each setting does.

Ready to edit

Templates

Save every file you have changed as one named set, then load it any time. Stored in this browser.

No templates yet.

Settings

Crates

No crate files yet.

Shared pools

No shared pools yet.

Language

No language file published.

config.json

How the plugin behaves. Settings only, never loot.

General

Language

Language: which text file I read for every player line and every command reply. It points at a file in the lang folder next to this config, so "en" loads lang/en.json. Want German? Copy lang/en.json to lang/de.json, change the words on the right of each line, keep every key and every {} spot exactly as it is, then set this to "de". Pick a code with no matching file and I fall back to English, so it is safe to try. Example: "de"

LangAutoFill

LangAutoFill: fills in the language lines a new build adds. Your file keeps its own order and its own wording. I only append the keys you do not have yet, in English, ready for you to translate when you feel like it. I write a .bak of your old file first, every time I change anything. A missing line already falls back to my built in English, so this saves you the hunt for what changed, it does not keep the server running. Set it to false to have your files left completely alone.

SenderName

SenderName: the name shown at the front of my chat lines. The default is empty (""), which leaves the game's built in "(SERVER):" prefix alone. Fill it in to brand your messages, so "Mystery Crates" reads "Mystery Crates: ...". Colour is kept, so a red warning stays red. Supports {map} for the map name and {server} for the server name. {server} takes the ServerName from discord.json when you set one there, and otherwise the name I work out for this server myself, see the Server block right below. Only chat lines use it. The pop up box shows no sender at all. Example: "Mystery Crates"

Server

Server: how I figure out which server I am running on. Matters most on a cluster, where one copy of this config goes to every map and each one still needs its own name in Discord posts and in the {server} tag. Most owners can leave this whole block alone, because the launch line already carries the answer.

Name

Name: a name typed here wins over everything else. I stop looking and use it as given. Leave it empty on a cluster, since every map would end up with the same one. Example: "NordBots PvP"

NameFromParams

NameFromParams: with Name empty, I walk your server's launch line and take the first of these pieces that has something after it. The list ships covering the usual launchers. Your host passes the name some other way? Add that piece to the front of the list.

UseSessionName

UseSessionName: true lets me also try the session name the game reports in the browser when the launch line gave me nothing. Off by default, because plenty of hosts stuff that field with ads and long text nobody wants in an embed. When everything comes up empty I simply use the map name, so I always end up with something readable.

Id: a short machine tag for this server, made of small letters, digits and hyphens. Leave it empty and I squeeze one out of the name on my own. Set it by hand only when two of your servers resolve to the same name and you need to tell them apart. Example: "island-pvp"

General

Debug

Debug: true writes the detail behind every decision to ArkApi.log. Which crate loaded, what a roll produced, what the points bridge answered, what went into the database. Keep it false for a quiet log. Turn it on when you are chasing something odd, or when support asks for it. It is chatty on a busy server, so turn it back off afterwards.

License

License: the block that switches Mystery Crates on. This is a paid plugin, so I check your key with the shop before I do anything at all. Read the next few lines even if you skip the rest of this file. Nothing works without them.

Key

Key: the license key you got when you bought Mystery Crates. It looks like NB-XXXXX-XXXXX-XXXXX-XXXXX. Copy it in whole, between the quotes, with no spaces on either end. Keep it to yourself, it belongs to you and one key runs one server box. What happens with no key, or with a key that is empty, wrong, expired, or turned off: I do nothing. Not a smaller version of me, nothing. The /crate command goes away, so does every admin command except the reload one, all my hooks come off, my crates unload and my storage shuts down. Your server itself is completely fine and every other plugin carries on. I write one plain line in ArkApi.log telling you what I found, and that is my whole day. A player who types /crate is told crates are switched off right now, nothing more. They do not see anything about keys or money, because that side is yours, not theirs. Fixing it never needs a restart. Paste your key in here, save the file, then run MysteryCrates.Reload from the server console or from RCON. That one command is always listening, even while I am switched off, on purpose, so you are never stuck. I pick the new key up, check it, and everything comes straight back with players still online. The first check is a quick call out to the shop when the server starts. I do not sit and wait on it, so a good key never slows your boot down by even a moment. If the shop is unreachable later, say your host has a network wobble, I keep running on the last good answer for up to 72 hours before I switch off, so a blip in the night costs you nothing. Moving to a new machine? Free the seat from your account on the website first, then start the plugin on the new box and it takes the seat there. Lost your key or need a hand? Get support at NordBots.cc. Example: "NB-A1B2C-D3E4F-G5H6I-J7K8L"

Commands

Crate

Crate: the one word players type. Everything else is a sub action of it, so renaming this renames my whole chat surface in one edit and I never collide with another plugin. /crate what you are holding, your shards, one hint line /crate open <name> spend one crate and start a ladder /crate take keep the prize on the rung you are standing on /crate climb roll once for the next rung /crate pick <n> pick a sealed door on a doors rung /crate insure spend shards so your next miss does not drop you /crate reroll spend shards to reroll this rung's prize /crate forge <name> spend shards to mint one sealed crate /crate odds <name> the whole ladder with the real percentages /crate book [set] your collection /crate fair your seed hash, your client seed, your nonce /crate seed <text> set your client seed and reveal the old server seed /crate verify <id> the full receipt for one open /crate claim take anything I am holding for you Keep the leading slash. Example: "/box"

AllowCommandRewards

AllowCommandRewards: the main switch for command prizes. Read this whole block before you touch it. A crate reward of Type "command" runs a real console command on your server, so turning this on hands me the power to run console commands. That is why it starts off. While this is false I will not run a command prize, no matter what any crate file asks for. I hold the prize for the player instead, and if I cannot even do that I write a warning with the player and the reason so you can sort it out by hand. Nothing else in a crate changes. Turning it on does NOT let crates run whatever they like. The Allowlist below still decides. With this true and the Allowlist empty, the answer is still no to every command. Example: true

Allowlist

Allowlist: the only console commands a crate file is ever allowed to run. Empty ([]) means no crate can run any command at all. That is the safe default and the one I recommend. Put a command here only if you are happy for a crate to run it for a player. I look at the FIRST word of the command and nothing else. If that word is not on this list I refuse the reward, both when I load the crate file and again the moment it would have run. I name the crate file in the log when I refuse one, so you always know what asked for what. Write the first word on its own. Upper and lower case do not matter. Do not add arguments. Tokens: just before I run a command I swap in {eos} for the player's EOS id, and {name} or {player} for their character name. A character name is text the player picked, so I treat it that way. I drop control characters and double quotes from it, cut it to 64 characters, and then I check the first word one more time. A name can never change WHICH command runs, but remember a name can hold spaces, so only allow a command that is safe with an extra word. A longer list is more power for a crate file and less safety in a crate somebody sent you. Example: ["addpoints", "giveexptoplayer"]

LendStaffPowers

LendStaffPowers: whether I lend the player staff rights for the moment a command prize runs. A command runs through the player's own console, and the useful ones (handing out points or experience) are refused for a normal player, so most command prizes need this to work. When this is true I note the player's own admin and cheat flags, switch both on, run the one command, then set their flags back to exactly what they were. I put them back even when the command fails. The player never gets to type anything while the rights are up and they never keep them, but for that instant the command is running with full rights, so only ever allow a command you would be happy to run yourself. Set it to false if every command on your Allowlist is one a normal player could already run. A command that needs staff rights will then just do nothing. Default is true. Example: false

Ladder

Ladder: the take it or climb it loop. This is the heart of the plugin.

DecideSeconds

DecideSeconds: how long a player has to answer take or climb before I decide for them. When the clock runs out I always TAKE. I will never gamble for somebody who walked away. 45 is relaxed. A smaller number is snappier and tenser. A bigger number is kinder to players who are often mid fight when a crate opens. A crate file can set its own with "Decide". Example: 20

StepSeconds

StepSeconds: the forced quiet between a reveal and the next prompt, in seconds. 1.5 gives a player time to read the prize before the question lands. A bigger number makes the reveal slower and more dramatic. Do NOT go under 1.1, because the game drops any chat line sent within one second of that player's last one, so a smaller number quietly eats my own text and players see half a reveal. Example: 2.5

MaxLiveOpens

MaxLiveOpens: how many ladders may be running at the same time, server wide. 40 is generous for a 70 player server. Past this an open is refused with a plain message and the crate is NOT spent. A smaller number is a harder ceiling on the chat noise. A bigger one suits a busy cluster map. Each live ladder is a few dozen bytes, so this is about noise, not about memory. Example: 15

Reveal

Reveal: how a prize is shown.

Style

Style: "full" paces the reveal, uses the pop up box and lets the moment breathe. "quick" is chat only with no pacing, which suits a server that wants the loot and not the show. A crate file can override this for itself with its own "Reveal" key. Example: "quick"

AnnounceFromRung

AnnounceFromRung: reaching this rung or higher shouts to the whole server and earns its own Discord post. 3 means the top of a four rung crate is special and the bottom two stay quiet. A bigger number makes the shout rarer and louder. Set it to 99 to never shout at all. A crate file can override this with its own "Announce" block, and the shipped crates do. Example: 4

Fairness

Fairness: every player has a secret server seed whose SHA-256 hash I publish before their first open, a client seed they choose, and a nonce that counts up. Every roll is an HMAC of those three, so /crate verify can rebuild any open by hand.

ReseedAfterOpens

ReseedAfterOpens: after this many opens I retire a player's server seed, show it next to the hash I already published, and mint a fresh one. That is what turns their past opens from "trust me" into "check it yourself". 500 is a good balance. A smaller number reveals sooner and proves faster. A bigger number means a heavy player waits longer before their history becomes checkable. Set it to 0 to never rotate on my own. Players can still rotate whenever they like with /crate seed, so 0 is not the same as never proving anything. Example: 100

AllowClientSeed

AllowClientSeed: true lets a player set their own client seed with /crate seed <text>, which is the part that proves I could not have picked the seed pair to suit myself. false locks every client seed to the player's EOS id. The proof still works, it is just weaker, so leave this true unless you have a reason not to.

Shards

Shards: my own little currency. It exists so the whole economy still runs on a server with no ArkShop installed.

PerMiss

PerMiss: shards paid when a climb fails. This is the fallback a crate file uses when it does not set its own. 15 makes a bad night still worth something. A bigger number makes failing feel fine, which makes players climb more. A smaller number makes a miss really sting. Example: 5

PerDuplicate

PerDuplicate: shards paid when a player pulls a Card they already own, instead of handing them the same card twice. Again a crate file may set its own. 25 keeps a collection from turning into a punishment. Raise it on a crate with a small card pool, because duplicates come fast there. Example: 50

InsureCost

InsureCost: shards to make your NEXT miss this open not drop you. Once per open. 120 is roughly eight failed climbs of saving up. Cheaper means players always insure and the ladder loses its teeth. Dearer means insurance is a real decision. Example: 250

RerollCost

RerollCost: shards to reroll the prize on the rung you are standing on, keeping the rung. 80 is about five misses. Each reroll gets its own step in the fairness receipt, so it can never be used to hide anything. A bigger number makes rerolling a treat. Example: 150

MaxRerollsPerOpen

MaxRerollsPerOpen: how many times one open may be rerolled. 2 keeps a run moving. 0 turns rerolling off completely. A big number lets a rich player fish for the one prize they want, which usually reads as pay to win. Example: 0

Inventory

Inventory: what happens when a payout will not fit in a bag. This matters more than it sounds. The game silently creates NOTHING when a bag is at its cap, so a plugin that does not count first can void a top roll and never tell anybody. I count your free slots before I create a single item.

WhenFull

WhenFull: pick one of three. "refuse" I do not resolve the open, your crate is NOT spent, and I tell you how many slots you need. This is the default and the one that never loses anything. "partial" I pay what fits and hold the rest for /crate claim. "hold" I pay nothing now and hold the whole lot for /crate claim. A player who is offline when something is owed to them always takes the hold path, whatever this says, so nothing is ever dropped on the floor. Example: "hold"

ReserveSlots

ReserveSlots: free slots I leave alone, so a payout never fills a bag right to the brim. 1 is polite. A bigger number suits a server where people live at their slot cap and complain. 0 means I will happily fill the last slot. This only bites on a bag that has a real slot cap, like a vault or a dino. A normal player pack fills up by weight and has no slot cap at all, so there is nothing for me to hold back and this setting is skipped. Example: 5

Crates

Crates: how I read the crates folder. The loot itself lives in those files, not here. I read the folder at start up and again on MysteryCrates.Reload.

MaxRungs

MaxRungs: the most rungs I will accept in one crate file. 8 is already a long ladder. A crate with more rungs than this is refused by name and every other crate still loads. A bigger number lets you build a twelve rung monster, but remember a player has to sit through every single prompt. A smaller number keeps every crate short. Example: 4

Rewards

=========================================================================================== Rewards: the one setting a crate reward needs from you rather than from its own file. Everything else about a prize is written in the crate file itself, so a crate you download brings its own loot and can never reach anything in here. The full guide with a worked example of every key is in crates/_example.jsonc. Here is the short list of what a prize can now do, so you know what is on offer before you open that file: A CREATURE PRIZE can say Male, Female or Random, can arrive neutered so it is a pet and not a breeding line, can come as a matched breeding pair, can be born with the wild stat points you choose, can arrive already wearing a saddle with its own quality, armor, durability and damage, and can be packed into a cryopod with the pod's clock set to as long as you like, up to thirty days. AN ITEM PRIZE can have its armor, durability, damage and quality word pinned to exact numbers, so a headline prize reads the same for every player who wins it, or rolled inside a range. ANY NUMBER a prize takes can be written as one exact number, or as two numbers in square brackets for a range, like "Level": [120, 180]. That works the same way everywhere, on the amount, the quality, the level, and on every saddle and item stat. ===========================================================================================

CryopodBlueprint

CryopodBlueprint: the cryopod item I put a creature into when a crate reward asks for one. A crate reward of Type "dino" can say "Cryopod": true. When it does, I spawn the creature, set its stats, pack it into one of these, and drop the pod straight into the player's bag. Nothing appears in the world, so nobody loses a prize to a full base or a bad spawn spot. The value below is the normal game cryopod, the one every map already has since Extinction. Leave it exactly as it is and everything works. You only ever touch this line if your server runs a cryopod MOD and you would rather hand out the mod's pod, because that is the one your players already have a terminal or a fridge for. To point it at a mod pod, copy the mod item's blueprint path in whole, quotes and all. A mod path always starts with /Game/Mods/ and ends with the item name written twice, so it looks like this shape: Example: "Blueprint'/Game/Mods/<ModFolder>/<PodItem>.<PodItem>'" The mod's own store page, its spawn code list, or its item list gives you the real one. Get it wrong and nothing breaks and nobody loses a prize. I try to load the path, it does not load, so I set the creature down next to the player instead, tell them plainly that their creature is standing there, and write one warning in ArkApi.log naming the path I tried. Fix the line, run MysteryCrates.Reload, and the next pod works. Blank ("") is treated the same as leaving it alone, so I fall back to the game cryopod. How long a reward pod lasts is set in the crate file, not here, with "CryopodMinutes" next to the "Cryopod": true line. Leave that out and the pod keeps whatever clock the game gives a fresh one. Put a number on it and the player gets that many minutes to throw the creature out, so 43200 is thirty days and 60 is one hour of real time. Thirty days is the longest I will set. A short clock is a nice touch on a prize you want used rather than hoarded, and a long one is kinder to a player who wins something at three in the morning.

Paste it straight from the wiki or your spawn code list, quotes and all.

Season

Season: an optional label stamped on every wallet row, receipt and book entry I write.

Current

Current: your season tag, up to 16 characters. Blank ("") means no season, which is right for almost everybody. Change it when you wipe and start again, and old rows keep the old tag, so you can still look back at last season without mixing the two. Example: "S3"

Permissions

Permissions: gate who may use the crate commands. Needs Permissions.dll, and everything here is optional. The staff commands are console and RCON only, so they need no node at all. Whoever is holding the console already owns the server.

Enabled

Enabled: true runs the permission checks. false skips them and treats everyone as a normal player who may open crates.

UsePermission

UsePermission: leave "" so everyone can open crates. Set a node like "MysteryCrates.Use" to limit crates to the groups that hold it. A single crate can also demand its own node with the "Permission" key inside its own crate file, which is how you build a VIP only crate. If Permissions.dll is missing or will not answer, I let the player through, so a broken permissions install never locks your server out of its own crates. Example: "MysteryCrates.Use"

ArkShop

ArkShop: the points economy. Only used for rewards of Type "points" inside a crate file. Either shop plugin works here, ArkShop or WShop. The plugin runs perfectly with no shop at all, which is what shards are for.

Enabled

Enabled: true and I look for a points shop at start up and use it when it is there. false and I never touch it, so a crate reward of Type "points" pays nothing and says so.

Provider

Provider: which shop plugin holds the points. "Auto" I knock on ArkShop first, then WShop, and use the one that answers. "ArkShop" only ArkShop.dll. "WShop" only WShop.dll. Auto suits nearly everyone. Name one if both shops live on this server.

Database

Database: where wallets, shards, seeds, receipts and the book live.

Enabled

Enabled: true and I keep records. false and I do not start at all, which switches crates off, because a crate ladder with nothing to write to would lose a prize on the first restart. Leave this true unless you are testing something.

UseMySQL

UseMySQL: false is SQLite, a single file at data/MysteryCrates.db, with no setup of any kind. true is MySQL, which is what you want when several maps in a cluster should share one wallet, one shard balance and one book. Everything below TablePrefix is for MySQL only.

TablePrefix

TablePrefix: the front of my five table names, so "mc_" gives mc_players, mc_wallet, mc_opens, mc_book and mc_hold. Change it if you run two instances against one database. Changing it after the fact makes fresh empty tables, it does not rename your old ones. Example: "crates2_"

Host

Host, Port, User, Password, Database: your MySQL details. All ignored when UseMySQL is false. Example: "10.0.0.5"

Port

Example: 3307

User

Example: "arkuser"

Password

Example: "a long password"

Database

Example: "ark_cluster"

MysqlSSLMode

MysqlSSLMode: -1 leaves the client default alone, which is right unless your host told you otherwise. A bigger number asks for a stricter connection, and your host will tell you which one they want. Example: 1

MysqlTLSVersion

MysqlTLSVersion: blank ("") means the client default. Only fill this in if your host asked. Example: "TLSv1.2"

RecentOpensKept

RecentOpensKept: how many receipts I keep per player before the oldest are pruned. 500 is plenty for any argument about a roll, and /crate verify reads from these. A bigger number keeps a longer history and a slightly bigger file. A smaller number keeps the table tidy and makes an old /crate verify come up empty. I clamp this between 50 and 20000, so anything outside that is pulled back inside. Example: 2000

MaxQueuedWrites

MaxQueuedWrites: how many pending saves I will hold before I start dropping the oldest and counting them in the log. 20000 is far more than a busy server ever queues. It only matters when a remote MySQL goes slow, and it stops that turning into runaway memory. A bigger number survives a longer database hiccup and uses more memory doing it. I clamp this between 500 and 200000. Example: 5000

Panel

Panel: the clickable crate window, drawn by the NordBots Companion UI mod. With the mod on your server, players get a window listing every crate they hold, each with its own Open button, plus a Top Openers board and the take or climb choice as buttons on the ladder. Every button press runs the very same code the typed command runs, so nothing can be done through the window that the chat command would refuse. No mod on the server? Nothing changes and this whole block sleeps. The mod is a nice extra, never a must have.

Enabled

Enabled: true means I look for the mod and offer the window. false means I never go looking at all, and crates stay chat only. Turn it off if you do not run the NordBots UI mod and want me doing nothing extra.

RowsPerPage

RowsPerPage: how many crate rows fit on one page of the window. A player holding more kinds than this gets page buttons under the list. 12 is the most the window can carry, and I quietly trim anything higher. Example: 8

TopCount

TopCount: how many players show on one page of the Top Openers board. Also capped at 12 so the window stays small enough to send. Example: 5

BuffTag

BuffTag: the tag on the buff the mod puts on every player. That buff is how my windows reach a player's screen, and the tag is how I spot it. Only change this if the mod itself changes.

BuffPath

BuffPath: where inside the mod that buff lives. My backup way of finding it when the tag is missing. Leave it be unless the mod moves things around.

SingletonPath

SingletonPath: where the mod's main actor sits. I read the mod's version number off it before I send anything. Leave it be unless the mod moves.

RequireHandshake

RequireHandshake: what I do when I cannot find a version number on the mod at all. false sends the window anyway and lets the mod skip anything it does not understand, which suits nearly every server. true holds every window back until I can read a matching version. A version that reads as the wrong number always stops the window, whatever this says.

ApiUtilsMod

ApiUtilsMod: shows my messages in a box on screen instead of plain chat, so a reveal actually lands. It needs the free "ASA API Utils" mod running on your server. Download it here: https://www.curseforge.com/ark-survival-ascended/mods/asa-api-utils Add mod id 955333 to your mod list, restart, and you are set. Optional. Crates work exactly the same without it, the reveals just show as plain text, and the log mentions once that the mod is missing.

Enabled

Enabled: true and I hand my messages to the mod. false and I keep using plain game text, even on a server that has the mod loaded.

BackdropColor

BackdropColor: what the box behind the text looks like. Four numbers, [red, green, blue, how solid], each one from 0.0 to 1.0. A bigger last number is a heavier box, a smaller one lets the game show through. Set the last number to 0.0 and you get bare text with no box at all. Example: [0.1, 0.0, 0.15, 0.65] gives a dark purple box

How solid0.55

ScreenPosition

ScreenPosition: the spot on screen the box appears in. Choose "Left", "Center" or "Right". Center works for almost everybody. Example: "Right"

TextAlign

TextAlign: how the words are lined up inside the box. Choose "Left", "Center" or "Right". Example: "Left"

TextScale

TextScale: how large the text is drawn. 1.0 is the normal size. A bigger number makes a message shout. A smaller number makes it quiet and small. Above about 2.2 the text starts running off the sides on smaller screens. Example: 1.6

MessageSeconds

MessageSeconds: how many seconds a box holds on screen before it fades. 6.0 gives a player time to read one line. A bigger number keeps it up longer, a smaller one clears it faster. Example: 10.0

AlsoShowInChat

AlsoShowInChat: leave true and every message goes out twice on purpose, once as the pop up box and once as an ordinary chat line that stays in the log. That matters here, because a player wants to scroll back and read what door three was holding. Set it false when you would rather have just the box and a tidy chat window.

MapName

MapName: how the map is written in player facing text and in the {map} tag. What the game hands me is a level file name such as "TheIsland_WP", which I clean up to "The Island" so it reads properly.

Pretty

Pretty: true takes off the "_WP" and puts the missing spaces back, so "ScorchedEarth_WP" comes out as "Scorched Earth". false keeps the raw name exactly as the game gives it.

Overrides

Overrides: your own label for a given map, handy for mod maps whose file name is nothing like the name people use. Raw name on the left, your name on the right, and it wins over Pretty. Example: { "TheCenter_WP": "Center", "Svartalfheim_WP": "Svartalfheim" }

Earn

Earn: how players get crates by playing. Four of these are on out of the box, so the plugin starts paying out from the first wild rex somebody kills and you never type a give command. Each trigger has its own cooldown and its own daily cap, and each one switches itself off on its own if a game update ever renames the thing it watches. Every "Crate" value here is a crate FILE NAME, lowercased, with no .json on the end. crates/Bronze.json is "bronze".

WildKill

WildKill: killing a wild creature. This is the busiest thing I watch and it is built to be cheap. A boss pays the BossCrate at BossChance. A creature whose name tag is in Tags pays the normal Crate at Chance. Everything else pays nothing at all.

Enabled

Enabled: false and I stop watching creature deaths completely, which is one less hook.

Crate

Crate: the crate a tagged kill pays. Example: "silver"

BossCrate

BossCrate: what a boss kill pays. Blank ("") means bosses pay the normal Crate instead. Example: ""