Skip to content
ShadowMC

Configuration

ShadowEssentials

The heart of the suite: homes, warps, kits, VIP, chat and the everyday commands.

Free v1.0.4

Where the files are

plugins/ShadowEssentials/

The plugin creates them on first start and updates them by itself on new versions, keeping your changes.

Applying changes

/shadowessentials reload

Reloads the files without restarting the server.

What’s inside

64 files · 968 settings

Start with: config.yml

Settings

The files that decide how the plugin behaves. Start here.

config.yml

General settings
86 settings
plugins/ShadowEssentials/config.yml
File notes

Core settings only. Everything else lives in its own file:

modules/<module>.yml   module settings
kits/<kit>.yml         one file per kit
vips/<tier>.yml        one file per VIP tier
menus/<menu>.yml       GUI layouts
lang/<locale>.yml      translations

COLOURS - write them the Minecraft way, with &

&0-&9 &a-&f  colours        &l bold   &o italic   &n underline
&#ff8800     an exact colour            &r  back to normal
&&           a literal ampersand

This works in every file of the plugin: configs, languages, kits, VIP ranks, holograms, signs and menus.

The richer tags are still there for the things & cannot do:

<gradient:#FFD700:#FFA500>GOLD</gradient>
<click:open_url:'https://...'>site</click>
<hover:show_text:'...'>hover me</hover>

Mixing the two on the same line is fine.

config-version1
core6 keys
server-id"server-1"

Identifier of this server, used when several servers share one database.

profile-linger"5m"

How long an offline player's profile stays cached in memory.

autosave"5m"

How often online profiles are written to the database.

audit-logtrue

Records administrative actions (bans, VIP grants, warp changes) in sb_audit_log.

auto-update-filestrue

On update, your files are moved to the new version automatically.

Keep reading

Each file is rebuilt from the new one inside the plugin (new settings, new messages, corrected defaults, new comments) and every value you had changed or added is carried into it; a key you deleted stays deleted. The old files are kept in backup/<date>/. If something could not be carried over - an option that no longer exists, a value of the wrong kind - PORTING-<version>.txt in this folder tells you what to fix. Kits (kits/) are never touched.

false: your files are never touched. New settings and messages still work, read from the plugin itself, but they do not appear in your files.

core.update-check3 keys
enabledtrue
notify-consoletrue
notify-playerstrue

Messages and translations

The engine supports ANY language: drop a <locale>.yml file into lang/ and it is picked up automatically. Missing keys fall back per key, so a partial translation is usable from day one.

messages4 keys
default-locale"en_US"

Used when the player has no preference and the client locale is unknown. Ships with en_US and it_IT. Set "it_IT" here for an Italian server.

follow-client-localetrue

Follow the language the Minecraft client is set to.

allow-player-choicetrue

Allow players to pick their language with /lang.

obfuscatedbars

What &k does, everywhere: chat, tab list, holograms, rank tags.

Keep reading

&k never draws the letter you wrote. Sixty times a second the client throws it away and draws a random glyph of "the same width" - and it decides what counts as the same width by rounding up to a whole pixel. The unicode font is loaded on top of the normal one at half scale, so its glyphs are 1.5, 2.5, 3.5 px wide: the group for a 2 px letter like i holds 624 glyphs 2 px wide and 376 that are 1.5. That half pixel is redrawn every frame, so everything after the tag slides left and right - and since the tab list is centred, one shaking rank tag shakes every name on the screen. A tag such as "&b&ki&5Founder&b&ki &f" does exactly that, at both ends. In the normal font every width from 2 to 9 px is mixed like this, so there is no safe character to roll on.

The way out is a different font. "minecraft:alt" has no unicode in it at all, so every width in it is a whole number of pixels and a group cannot hold two: the bars roll through every shape of exactly one width and push nothing. That is what "bars" does.

bars      the bars move, the line does not. THE DEFAULT.
bars:X    the same on the letter X, which is how you pick the width:
             i  2 px, 4 shapes   (as wide as the usual i - default)
             C  3 px, 4 shapes
             G  4 px, 8 shapes
             N  5 px, 6 shapes
             A  6 px, 30 shapes  (the loudest)
stop      take &k out and keep the colours. Nothing is random any
          more, so nothing can move - and the filler letters under
          the tag go with it, or the tag would read iFounderi.
keep      leave &k exactly as it was written, shaking included.
any char  roll on that character in the normal font. The old
          behaviour: it shakes unless the character is 10 px wide.

A player's own words get the bars too - nickname, tab, the name over the head, the chat line. They are parsed with the reduced set of tags plus <font> and nothing else, and any <font> THEY wrote is broken up first, so the only font that can reach the screen is this one.

/se obfuscated shows them side by side so you can pick by eye.

bars is the default, and keep is the setting that shakes. The two were the wrong way round in the builds up to here: the note under keep said it "never moves the rest of the line", which is what the game promises and not what it does. A nickname of &ki shook the whole chat line, the whole tab list and the name over the head, and the setting that fixes it was right there switched off. Whoever changes this back: that is what you are turning on.

Storage

AUTO  -> YAML files inside this plugin folder (the default).
         Nothing to install, nothing to configure, every file readable
         and editable by hand. If you fill in the MySQL host below,
         AUTO switches to that database instead.
YAML  -> always use files, even if MySQL credentials are present
MYSQL -> always use the database below
Keep reading

Moving to a database later loses nothing: create an empty database, fill in the five fields, then run /se storage migrate ShadowEssentials creates every table and index by itself on first connect.

storage6 keys
typeAUTO

Where the YAML files live, relative to this plugin folder:

data/players/<uuid>.yml   one file per player: profile, homes,
                          kit claims and pending kit deliveries
data/players-index.yml    name -> uuid, so offline lookups are instant
data/warps.yml            every warp on the server
data/vip-grants.yml       who has which rank and until when
data/audit.log            administrative actions
flush-interval"30s"

How often buffered player data is written to disk. Changes are also flushed when a player logs out and on shutdown, so this only decides how much a hard crash could cost you.

table-prefix"sb_"

Table prefix, used only by the database backend. Handy when several servers share one database.

storage.mysql6 keys
host""

Leave the host empty to stay on YAML files.

port3306
database"shadowessentials"
username""
password""
storage.mysql.properties3 keys
useSSLfalse
characterEncoding"utf8mb4"
serverTimezone"UTC"
storage.pool6 keys
maximum-size10

Database only. Rule of thumb: (cpu cores * 2) + 1, never above 20.

minimum-idle2
connection-timeout"10s"
idle-timeout"10m"
max-lifetime"30m"
leak-detection"0s"

Set above 0 to log connections that are never returned to the pool.

storage
fail-safetrue
true  -> if storage fails, keep running with the modules that do not need it
false -> if storage fails, shut the plugin down

Economy

ShadowEssentials does NOT implement an economy. Money belongs to the ShadowEconomy plugin. This section only says where to ask for it. With no provider installed, every cost is simply zero.

economy3 keys
providerAUTO

AUTO | SHADOW | VAULT | NONE

currency"default"

Currency used for ShadowEssentials costs (kits, warps, homes, teleports).

free-when-missingtrue
true  -> no provider means everything is free
false -> no provider means commands with a cost are refused

Talking to the outside

Everything here is OFF by default: the code is present and ready, but nothing leaves the server and nothing can reach it until you turn it on yourself.

web2 keys

Outbound: events sent to a website or to Discord

web.webhooks5 keys

Each event below sends to its own address (url); an empty url means that event is not sent. "format" says what is sent:

DISCORD  a message for a Discord channel. In Discord: channel
         settings, Integrations, Webhooks, create one and paste
         its address as the url.
JSON     an ordinary JSON body, for a website of your own:
           { "event": "...", "timestamp": 0, "data": { ... } }

The format here counts for every event. One event can have its own,

next to its url:   join: { url: "...", format: JSON }
enabledfalse
formatDISCORD
rate-limit20

Most sends per minute, so Discord does not rate-limit you.

max-retries3
web.webhooks.events4 keys
web.webhooks.events.punishments1 key
url""
web.webhooks.events.join1 key
url""
web.webhooks.events.vip1 key
url""
web.webhooks.events.audit1 key
url""

Inbound: an HTTP endpoint your website can call

web.api5 keys

For granting a rank the moment a payment clears, or for showing live statistics on the site.

It does NOT start if the token is empty or shorter than 16 characters. Leave bind on 127.0.0.1 and put a reverse proxy (nginx, Caddy) in front of it if the site is on another machine.

enabledfalse
bind"127.0.0.1"
port8123
token""

Generate something long and random. Send it with every request:

Authorization: Bearer <token>
rate-limit60

Available endpoints:

GET  /status                                  version, online, modules
GET  /players                                 who is online
GET  /player?name=X                           profile, playtime, VIP tier
POST /vip/grant?player=X&tier=gold&duration=30d
POST /command?run=say%20ciao

Modules

Listing a module here overrides the "enabled" value inside its own file. A disabled module registers no commands, no listeners and no tables: it costs nothing.

modules33 keys
coretrue

Each module also has its own "enabled" at the top of modules/<id>.yml. Either switch is enough to turn a module off, so whichever one you find first does what you expect. This list is the place to switch things off from one file; it cannot force on a module its own file disabled.

teleporttrue
homestrue
warpstrue
spawntrue
kitstrue
viptrue
playertrue
moderationtrue
chattrue
afktrue
mailtrue
rewardtrue
vouchertrue
leaderboardtrue
tablisttrue
hologramtrue
worldtrue
custom-commandtrue
signtrue
portaltrue
motdtrue
command-rulestrue
teamstrue
rulestrue
spawnertrue
particlestrue
npctrue
armorstandtrue
elevatortrue
autotooltrue
locktrue
skintrue

Migration

migration1 key
coexistfalse

Gradual migration from EssentialsX or CMI.

With this on, ShadowEssentials does NOT register a command that another plugin already provides. Keep the old plugin installed, then move one feature at a time by disabling the matching module over there: the command switches over on the next restart, on its own.

The console lists every command left alone at startup.

bStats - anonymous usage statistics (https://bstats.org)

metrics1 key
enabledtrue

What is sent, every 30 minutes: that this server runs ShadowEssentials, the plugin, Minecraft/Paper and Java versions, the operating system, the number of CPU cores, how many players are online (a number, nothing else), a random serverUuid that identifies nothing, and whether storage is YAML or MySQL. No player data leaves the server: no names, no UUIDs, no addresses.

Keep reading

false switches it off for this plugin only. enabled: false in plugins/bStats/config.yml switches it off for every plugin on this server at once.

Diagnostics

debug4 keys
enabledfalse
watchdogfalse

Logs a stack trace whenever something does file or database I/O on the main thread. Development aid, keep it off in production.

profilertrue
levelINFO

armorstand-poses.yml

Armorstand poses
28 settings
plugins/ShadowEssentials/armorstand-poses.yml
File notes

The ready poses of the armor stand editor: the "Poses" screen and /armorstand pose <name>. They are yours: add as many as you like, change them, delete the ones you do not want. The order here is the order on screen.

One pose:

my-pose:                      a-z, 0-9, _ and -; used in the command
  name: "<gold>My pose"       MiniMessage, or "lang:<key>" to take it
                              from the language files (translated)
  icon: GOLDEN_SWORD          the item shown in the list
  permission: "my.perm"       optional: who may use it
  head:      [x, y, z]
  body:      [x, y, z]
  left-arm:  [x, y, z]
  right-arm: [x, y, z]
  left-leg:  [x, y, z]
  right-leg: [x, y, z]

Angles are in degrees, exactly as the game writes them in /summon (a pose copied from a generator site works as it is, "10f" included). A part you leave out stays as a fresh armor stand has it.

What the numbers do, on arms and legs:

x  negative swings forward, positive backward (-90 = straight ahead,
   -180 = straight up)
z  opens it sideways: positive on the right limbs, negative on the
   left ones
y  turns it around the vertical axis

On the head: x positive looks down, y turns it, z tilts it.

The pose editor shows the three numbers of every part, so the easiest way to make a new one is: pose a stand in game, read the numbers (or /armorstand info), write them here.

config-version1
poses18 keys
poses.default8 keys
name"lang:armorstand.preset.default"
iconARMOR_STAND
head[0, 0, 0]
body[0, 0, 0]
left-arm[-10, 0, -10]
right-arm[-15, 0, 10]
left-leg[-1, 0, -1]
right-leg[1, 0, 1]
14 more entries shaped like default: salute, wave, t-pose, walk, run, point, think, facepalm, shrug, dance, cheer, zombie, hero, bow
poses.sit6 keys

The legs go straight ahead: lower the stand (Move, or carry it onto a stair) so it sits on something instead of floating.

name"lang:armorstand.preset.sit"
iconOAK_STAIRS
right-arm[-40, 0, 5]
left-arm[-40, 0, -5]
right-leg[-90, 10, 0]
left-leg[-90, -10, 0]
poses.archer6 keys

Put the bow in its main hand (the right one).

name"lang:armorstand.preset.archer"
iconBOW
right-arm[-90, 0, 0]
left-arm[-90, 35, 0]
right-leg[-10, 0, 3]
left-leg[10, 0, -3]
poses.guard7 keys

A sword in the main hand, a shield in the other.

name"lang:armorstand.preset.guard"
iconSHIELD
head[5, 0, 0]
right-arm[-70, 0, 10]
left-arm[-80, 30, 0]
right-leg[10, 0, 3]
left-leg[-15, 0, -3]

blocked-words.yml

Words blocked in chat
26 settings
plugins/ShadowEssentials/blocked-words.yml
File notes

The words you do not want to read on your server.

Write them plainly, in lower case, the way you would say them. The filter takes care of the rest: it recognises by itself the twists people use to get through, so you do not have to list them.

merda        caught
m3rda        caught   (leetspeak)
m.e.r.d.a    caught   (separators)
m e r d a    caught   (separators)
meeeerda     caught   (repeated letters)
mErDa        caught   (capitals)
mèrda        caught   (accents)
мerda        caught   (Cyrillic letters drawn like Latin ones)

/se filter <sentence> tells you what would happen to that sentence, without having to type it in public chat to find out.

config-version1
enabledtrue
censor-char"*"

The character the word is covered with.

Recognising a word written crooked

smart5 keys

Turn one off only if it is getting in your way: each of them closes a different way out.

leettrue

m3rda, c4zzo, $tronzo

separatorstrue
m.e.r.d.a, m-e-r-d-a, m e r d a   (at most 3 characters in between:

past that it is no longer a word anybody reads)

repeatstrue

meeeerda, mmmerda

accentstrue

mèrda, merdà

lookalikestrue

Cyrillic and Greek letters drawn identically to Latin ones

Words

words
[merd, stronz, vaffancul, cazz, coglion, puttan, troia, troie, bastard, fottit, figa, fica, "figo di", minchia, mignotta, zoccola, sborr, pompin, inculat, inculare, "cesso di", schifos, deficient, idiota, imbecill, cret …+82

The ordinary list, the one you will use for 90% of things.

Caught when they START where a word starts, and they may carry on. That is what most languages need: write "merda" and it also catches "merdaio" and "merdata", without you having to list them.

It does not catch a word that merely contains one in the middle: "merda" does not touch "camerda" (were it a word), because no word starts there.

Whole words

whole-word
[ass, cul, figa, sega, seghe, fag, cum, dick, cock, tits, wtf]+8

Caught ONLY when they stand as a word of their own.

THIS IS WHERE SHORT WORDS GO. "ass" written here does not touch "passage", "class", "assassin" or "bass". Written in the list above it would catch nearly all of them.

Rule of thumb: under 4 letters, put it here.

Anywhere

anywhere[ ]

Caught even in the middle of another word. For long, unmistakable strings, such as a cheat client's domain.

A short word here does damage. When in doubt, use one of the two lists above.

Blocked

blocked
["negro di merda", "sporco negro", "torna al tuo paese", "froci di merda", "ti ammazzo", "ti vengo a casa", "so dove abiti", "ti stupro", "kill yourself", "kys yourself", "hang yourself", "gas the", "heil hitler", "sieg …+17

The message is not sent at all, rather than censored. For the things you do not want arriving even in disguise: serious abuse, threats, links to cheats.

Replacements

replacements5 keys

The word is swapped for another one instead of for asterisks. Often this works better: the writer does not realise they were filtered, and stops trying.

stupido"simpatico"
scemo"adorabile"
noob"campione"
loser"campione"
trash"fenomeno"

Regular expressions

patterns[ ]

For whoever knows what they are doing. Applied exactly as written, without any of the tolerances above.

pattern: the expression
action:  CENSOR | BLOCK | REPLACE | WARN
with:    what to replace it with, only for REPLACE
- pattern: "(?i)\\bcompra\\s+oro\\b"
  action: BLOCK

Where it applies

apply-to8 keys

The filter is worth nothing if it covers public chat only and then the same word arrives in a private message or on a sign.

chattrue
private-messagestrue
nicknamestrue
signstrue
anviltrue
booksfalse
team-chattrue

Team chat and staff chat. Staff usually should not be filtered, but team chat is chat between players in every sense that matters.

staff-chatfalse

Who skips all of it: shadowessentials.chat.bypass-filter

npcs.yml

The NPCs
2 settings
plugins/ShadowEssentials/npcs.yml
File notes

The NPCs created with /npc. THIS FILE IS WRITTEN BY THE PLUGIN.

You can read it, and correct it with the server stopped. Edits made while the server is running are overwritten at the first change.

The settings live in modules/npc.yml.

config-version1
npcs{ }

rules.yml

The server rules
17 settings
plugins/ShadowEssentials/rules.yml
File notes

Italian texts (testi in italiano): esempi/it_IT/rules.yml - copy it over this file.

Your server's rules, written by you.

They come out two ways, from the very same texts:

/rules        opens the GUI, one entry per rule
/rules chat   prints them in chat, for whoever prefers reading there

Colours are written with &, the way Minecraft has always done it.

config-version1
enabledtrue
default-viewGUI

What /rules does with no arguments: GUI or CHAT.

gui5 keys
title"&5&lRules"
rows6
gui.entry3 keys

The shape of one rule in the GUI. Values: <number>, <title>, <short>, <text> (all the lines of the rule, one after the other). A line naming a value the rule does not have disappears.

glowfalse
name"<title>"
lore[<text>, <empty>]
gui
default-iconPAPER

The item used for a rule that does not name one of its own.

fillerBLACK_STAINED_GLASS_PANE
chat3 keys
header"&8&m &r &5&lRules &8&m "
numberedtrue

Numbers the rules automatically: 1. 2. 3.

The rules

rules10 keys

Each has a title and a description over several lines.

icon:   the item in the GUI (optional)
short:  the line printed in chat (optional: without it, the title is
        used)
rules.respect4 keys
title"&e1. Respect"
iconPLAYER_HEAD
short"&7Treat others the way you want to be treated."
lines
["&7No insults, harassment or discrimination.", "&7In public chat, in private, on signs", "&7and in the names of items, pets and builds."]+2
9 more entries shaped like respect: cheat, grief, exploit, spam, ads, scam, accounts, content, staff

teams.yml

Teams
2 settings
plugins/ShadowEssentials/teams.yml
File notes

The teams players created. THIS FILE IS WRITTEN BY THE PLUGIN.

You can read it to see what is there, and correct it with the server stopped if something went wrong. Edits made while the server is running are overwritten at the first change.

The settings - how many members, how long invitations last - live in modules/teams.yml instead.

config-version1
teams{ }

modules/afk.yml

Module: afk
13 settings
plugins/ShadowEssentials/modules/afk.yml
config-version1
enabledtrue
commands1 key
afk{ enabled: true, aliases: [ ] }
detection2 keys
timeout"5m"

How long without activity before somebody is marked AFK.

ignore-rotationtrue

When true, turning the head without moving does NOT count as activity: the simplest way to stop trivial anti-AFK macros.

while-afk2 keys

AFK time does not count as playtime, so it earns no hourly rewards: idling with the client running does not pay.

count-playtimefalse
tag"&7[AFK] "
kick4 keys
enabledfalse
after"30m"
bypass-permission"shadowessentials.afk.no-kick"
min-players30

Kick nobody while the server is below this many players.

broadcast2 keys
on-afktrue
on-returntrue

modules/armorstand.yml

Module: armorstand
24 settings
plugins/ShadowEssentials/modules/armorstand.yml
File notes

Armor stands and mannequins, posed and dressed from a GUI.

How it works in game:

/armorstand          look at a stand and open its editor
/armorstand tool     the tool: right click a stand to select it,
                     sneak + right click to open the editor

Both ARMOR STANDS (six limbs posed one by one, arms, base plate, small, marker) and MANNEQUINS (the player-shaped entity: skin, the game's poses, the line under the name) can be edited. NPC mannequins made with /npc are left alone: /npc owns them.

The poses everybody can pick are in armorstand-poses.yml. The poses players save for themselves are written by the plugin in data/armorstand-poses.yml.

Permissions: shadowessentials.command.armorstand opens the door (ops only by default); behind it, see docs/10-PERMESSI.md.

config-version1
enabledtrue
commands1 key
armorstand{ enabled: true, aliases: [ "ast" ] }

The tool

tool1 key
materialBREEZE_ROD

Any item. It is recognised by a hidden mark, not by its type, so a normal item of the same kind does nothing.

Picking a stand

selection2 keys
range8.0

How far away a stand can be picked by looking at it (blocks). Marker stands, which have no hit box, are found as well.

edit-distance16.0

How far you may walk away from the stand while editing it.

Moving and turning

move3 keys
steps[0.05, 0.25, 1]

The nudges offered in the move screen, in blocks.

max-step1.0

The biggest nudge one click may make: steps above this are cut down. Every move also asks the protection plugins about the place it goes TO, not only the place it leaves.

rotate-steps[5, 15, 45, 90]

The turns offered in the move screen, in degrees.

carry3 keys

"Carry": the stand follows where you look until you click.

distance3.0

How far in front of you it floats when you are not looking at a block.

reach6.0

How far a block you look at can be to put it on top of it.

timeout"60s"

After this long without a click it goes back where it was.

Posing

pose1 key
steps[1, 5, 15, 45]

The steps of the pose editor, in degrees.

saved-poses2 keys

Poses players can save for themselves (/armorstand savepose, or the pose screen). How many, by permission, like homes:

shadowessentials.limit.armorstand-poses.<n>
shadowessentials.limit.armorstand-poses.unlimited
default-limit5

For whoever has no numeric permission.

hard-cap54

Never more than this, whatever the permissions say. -1 = no cap.

Undo

history2 keys
size15

Steps per player. 0 turns undo off.

merge-within"3s"

Clicks on the same part of the same stand closer than this become ONE undo step: twenty clicks to place an arm are undone with one.

Size

scale3 keys

The scale of a stand or a mannequin (the game's own scale attribute).

min0.5
max2.0
step0.1

Names

names1 key
max-length48

Longest custom name, counted without colours. Names are typed in chat and follow the same rules as any text a player writes: colours and styles yes (& codes and colour tags), click and hover no. The blocked words of blocked-words.yml apply too.

Survival

survival1 key
consume-stand-itemtrue

Placing a new stand from the menu, cloning one, or making a "ready stand" item costs one armor stand from the inventory - so the menu is not a way to get free armor stands. Creative mode and shadowessentials.armorstand.free do not pay.

Protection

protection1 key
check-regionstrue

true: before any change, ask the protection plugins (WorldGuard, GriefPrevention, Lands, ShadowRegions...) if you could change an armor stand there by hand. It fires the same events the game fires when a player swaps an item on an armor stand, on an invisible probe stand - never a fake block break, so no logger records anything. false: only permissions, locks and the worlds below count.

disabled-worlds[ ]

Worlds where the tools do nothing (except for shadowessentials.armorstand.bypass). Example: [ "spawn", "pvp_arena" ]

modules/autotool.yml

Module: autotool
30 settings
plugins/ShadowEssentials/modules/autotool.yml
File notes

The best tool in your hand when you start digging, the best weapon after you hit something. Each player switches it on for themselves with /autotool, like /autopickup.

It is silent on purpose: no message and no sound when it swaps. /autotool why tells a player why it picked the last tool or weapon.

config-version1
enabledtrue
commands1 key
autotool{ enabled: true, aliases: [ "besttool" ] }
default-onfalse

A tool that jumps into your hand by itself surprises whoever did not ask for it: off for new players, /autotool turns it on.

defaults4 keys

What a player gets until they choose. They can change each one with /autotool <weapons|source|ores|swapback>.

weaponstrue
sourceHOTBAR

HOTBAR | INVENTORY (INVENTORY needs shadowessentials.autotool.inventory)

oresFORTUNE

FORTUNE | SILK_TOUCH | ANY

swap-backfalse
disabled-worlds[ ]

Worlds where it never does anything.

disable-while-sneakingtrue

Crouching = "leave me alone, I dig with what I hold".

disable-in-minigamestrue

Not during a ShadowGames match: kits are laid out on purpose.

mining5 keys
enabledtrue
skip-if-instanttrue

The tool in hand already breaks the block in one hit: do nothing. (Tall grass, flowers: a swap there would only be noise.)

min-durability-left5

Never pick a tool with fewer uses left than this, so the good pickaxe does not break on the last hit.

prefer-cheapest-when-instanttrue

Several tools break it in one hit: take the cheapest one, and keep the netherite pickaxe for what needs it.

rules
[{ blocks: […], prefer: SILK_TOUCH, mode: PREFER }, { blocks: […], prefer: SILK_TOUCH, mode: REQUIRE }, { blocks: […], prefer: PLAYER, mode: PREFER }, { blocks: […], prefer: FORTUNE, mode: PREFER, even-if-instant: true …+4

Per-block preferences. "blocks" takes materials and tags (#name). The first rule that names a block is the one that counts.

prefer:  SILK_TOUCH | FORTUNE | PLAYER (the player's /autotool ores)
mode:    PREFER  (a bonus: without such a tool, the fastest one)
         REQUIRE (without such a tool, do not swap at all)
avoid:   tool kinds never used on these blocks (SHEARS, HOE, ...)
even-if-instant: true = apply even when anything breaks it at once
blocks

Without Silk Touch these blocks are lost.

blocks

Without Silk Touch an ender chest becomes eight obsidian: no swap at all rather than the wrong one.

blocks

The most personal choice of all: whoever builds with ore blocks wants Silk Touch. Each player picks with /autotool ores.

blocks

Fortune gives more seeds, carrots and potatoes.

blocks

Shears give the leaf block and take away saplings and apples.

weapons8 keys
enabledtrue
against-playerstrue

In PvP some call it an advantage: switch it off here without switching off the rest.

metricDPS

DPS = damage x attack speed (a sword beats a slow axe); DAMAGE = one hit.

axe-vs-shieldtrue

An axe hit disables a raised shield.

mace-min-fall1.5

The mace only while falling at least this far (blocks).

min-gain-percent10

Swap only for a real gain, and not more often than this: two almost equal swords must not make the hotbar dance.

swap-cooldown"1s"
pre-swap-on-aimfalse

The swap happens on the tick AFTER a hit: that hit's charge is already spent, so it costs nothing. With this on, a left click in the air while looking at a mob swaps before the first hit too. Costs one click; off by default.

actions2 keys
shears-on-entitiestrue

Right click a sheep, a mooshroom, a snow golem, a bogged or a copper golem: the shears come into your hand for that click.

brush-on-suspicious-blocksfalse

Brushing is a "hold the button" action started by the game client: swapping from the server may need a second press. Try it with a real client before switching it on.

swap-back1 key
after"3s"

For players who turned on /autotool swapback: how long without digging or hitting before going back to the slot of before. Items moved from the inventory go back only if nobody moved them since.

never-use3 keys

Items AutoTool never takes and never leaves. Players can mark an item themselves with /autotool ignore (the mark travels with the item).

materials[ ]
customizer-items[ ]

Item ids of ShadowCustomizer.

lore-contains[ ]

Any lore line containing one of these (not case sensitive), for the "Soulbound" items of other plugins.

modules/chat.yml

Module: chat
47 settings
plugins/ShadowEssentials/modules/chat.yml
File notes

Italian texts (testi in italiano): esempi/it_IT/modules/chat.yml - copy it over this file. Format, channels, private messages, filters, mentions. Turn it off entirely if you run a dedicated chat plugin.

config-version1
enabledtrue
commands8 keys
msg
{ enabled: true, aliases: [ "tell", "w", "whisper", "pm" ] }+1
reply{ enabled: true, aliases: [ "r" ] }
ignore{ enabled: true, aliases: [ ] }
unignore{ enabled: true, aliases: [ ] }
ignorelist{ enabled: true, aliases: [ ] }
socialspy{ enabled: true, aliases: [ ] }
broadcast{ enabled: true, aliases: [ "bc" ] }
chat{ enabled: true, aliases: [ ] }

Message format

Placeholders available here:

<name>          nickname, or name when they have none
<player>        the real name, always
<message>       what they wrote
<rank_prefix>   rank prefix, from the permission plugin
<rank_suffix>   rank suffix
<rank_group>    name of the permission group
<channel>       the channel they are speaking in
<world>         the world they are in
Keep reading

CAREFUL: <prefix> is NOT the rank prefix. It is the prefix of ShadowEssentials' own messages. For the rank, use <rank_prefix>.

Prefix and suffix come from ShadowPermissions (or LuckPerms, or Vault: whichever is there). With no permission plugin, or with a group that has no prefix, those two placeholders stay empty and the line stays clean.

/perm group vip meta setprefix 100 "<gold>[VIP] "
format4 keys
default"<rank_prefix><name><rank_suffix><dark_gray>: <gray><message>"
format.by-group1 key

Per permission group. You already have the rank ladder written down in ShadowPermissions: the group name is enough here, there is no need to write it out again as a list of permissions.

staff"<dark_gray>[<red>STAFF<dark_gray>] <rank_prefix><name><rank_suffix><dark_gray>: <white><message>"
format
by-permission
[{ permission: shadowessentials.chat.format.owner, format: "<gradient:#FF4E50:#F9D423>[OWNER]</gradient> <rank_prefix><name><rank_suffix><dark_gray>: <white><message>" }, { permission: shadowessentials.vip.epic, format: …+1

Per permission: the first one held wins, from the top. Beats by-group.

allow-formatting-permission"shadowessentials.chat.colors"

Who may use MiniMessage inside their own messages. Without this permission the text is inserted literally: an ordinary player cannot inject tags into the format.

The name inside the message

Hovering shows the tooltip, clicking opens a private message. Set interactive: false for a plain name and nothing else.

Who joins and who leaves

Replaces the game's own line ("So-and-so joined the game"), which is the only thing in chat that does not look like the rest of the server: no rank, no nickname, and the real name even for someone who picked another one.

Keep reading

The same placeholders as the chat apply: <name> (the nickname if they have one), <player> (the real name), <rank_prefix>, <rank_suffix>, <rank_group>, <world>.

Leaving one of the two lines empty = say nothing in that case. Someone who is invisible never shows up, whatever is written here.

announce3 keys
enabledtrue
join"<gray>[<green><bold>+</bold></green><gray>] <name>"

The brackets stay grey: the colour comes from the symbol, not the box. The <name> is clickable as in chat - hover for the rank, click to message them privately - and keeps the colours of their rank or nickname.

quit"<gray>[<red><bold>-</bold></red><gray>] <name>"
name3 keys
interactivetrue
hover
[<rank_prefix><name><rank_suffix>, "<dark_gray>rank: <gray><rank_group>", "", "<yellow>Click <gray>to message them in private"]+3
click"/msg <player> "

<player> is replaced with the real name. Empty = no click action.

default-channel"global"

Channels radius: -1 = the whole server, otherwise a radius in blocks.

channels2 keys
channels.global5 keys
display-name"Globale"
prefix""
command"g"
radius-1
cross-worldtrue
channels.local6 keys
display-name"Locale"
prefix"&8[&aL&8] "
command"l"
radius100
cross-worldfalse
empty-warning"&7Nessuno ti ha sentito. Usa &f/chat global."

Filters

Whoever has shadowessentials.chat.bypass-filter skips all of them.

filters5 keys
filters.cooldown2 keys
enabledtrue
duration"2s"
filters.repeat2 keys

Blocks the same message repeated (or near enough).

enabledtrue
similarity0.85
filters.caps3 keys
enabledtrue
threshold0.6

Share of capitals above which the message is lower-cased.

min-length8
filters.advertising3 keys
enabledtrue
whitelist[ ]

Domains and IPs allowed through: put YOUR server and YOUR Discord here, otherwise your own links are blocked along with the others.

whitelist: [ "discord.gg/iltuoinvito", "example.com" ]
actionBLOCK

ALLOW | CENSOR | BLOCK | WARN

filters.words3 keys
actionCENSOR

CENSOR swaps the letters for asterisks, BLOCK refuses the message.

normalizetrue

Normalises leetspeak and lookalike Cyrillic characters before comparing, so a disguised spelling is recognised all the same.

list[ ]

Write the words in lower case, without accents.

Mentions

mentions2 keys
enabledtrue
format"&e&l@<name>"

modules/command-rules.yml

Module: command-rules
22 settings
plugins/ShadowEssentials/modules/command-rules.yml
File notes

Waits and prices on commands. A rule sits in front of a command and decides whether it may run: how long since the last time, and what it costs to run it again.

It works on any command, not only the ones this plugin owns, so a rule can cover /repair from here, a command from another plugin, or a vanilla one. The command itself does not have to know about it.

Waits survive a restart. They are written to the same storage as kit claims the moment a command is used, so stopping the server does not hand everybody a free go.

config-version1
enabledtrue

Rules

rules3 keys

The name of each block is up to you. It is what /cooldowns shows and what the wait is stored under, so renaming one forgets its waits.

rules.repair-all6 keys
enabledtrue
commands["repair all", "fix all"]

Which commands this covers. Written the way a player types them, without the slash. The namespace is ignored, so listing "repair" also covers "/shadowessentials:repair".

repair all     exactly that, nothing more
repair *       /repair with any arguments, or none
repair         /repair on its own

List the aliases too if you want them covered: "fix all".

cooldown"24h"

How long between uses. A plain time, or one of:

daily    once per day, resets at midnight
weekly   once per week
once     one time, ever
rules.repair-all.cost3 keys

What it costs. Any combination; all of them are taken. Money needs an economy plugin - without one it is simply free.

money500.0
xp-levels10
xp-points0
rules.repair-all
bypass-permission"shadowessentials.bypass.rule.repair-all"

Who the rule does not apply to. Defaults to shadowessentials.bypass.rule.<name> when left out.

message""

A language key to answer with instead of the standard wait message. Leave empty for the standard one.

rules.repair-hand4 keys

A second example: the same command, no price, a short wait, so a single repair is not a way to spam the server.

enabledtrue
commands[repair, fix]
cooldown"30m"
rules.repair-hand.cost3 keys
money50.0
xp-levels0
xp-points0
rules.daily-crate4 keys

Turned off by default: an example of covering another plugin's command, and of a wait that only lets it happen twice a week.

enabledfalse
commands["crate daily"]
cooldown"daily"
rules.daily-crate.cost3 keys
money0.0
xp-levels0
xp-points0

modules/custom-command.yml

Module: custom-command
23 settings
plugins/ShadowEssentials/modules/custom-command.yml
File notes

Italian texts (testi in italiano): esempi/it_IT/modules/custom-command.yml - copy it over this file. Commands defined entirely in this file.

Every entry becomes a real Brigadier command: it shows up in the client tab completion with the right argument types, and a wrong argument is refused before a single action runs.

Action language: docs/moduli/kits.md (same syntax everywhere)

config-version1
enabledtrue

NOTE: Minecraft only accepts new commands while the server is starting, so a command ADDED here appears after a restart. Changing the body of an existing command (its actions, cost, cooldown) works with /se reload.

commands7 keys

Where a new player starts

commands.guide4 keys

The card that answers "and now what do I do", with the commands this plugin already gives every player. On from the first start.

enabledtrue
aliases[howtoplay]
description"How to play here"
actions
["message:&8&m ", "message:<gradient:#8A2BE2:#00BFFF>&lHOW TO PLAY HERE</gradient>", "message:&7", "message:&e/kits &8- &7your kits, starting with the starter", "message: …+13

The rules, under a second name

commands.serverrules4 keys

The name a player types when /rules does not come to mind. The Italian example (esempi/it_IT) calls it /regolamento.

enabledtrue
aliases[regulations]
description"The rules of the server"
actions["command:/rules"]

The simplest possible one

commands.discord4 keys

Off, because only you know your own invite: write it in and turn it on. It is the one thing in this file nobody can write for you.

enabledfalse
aliases[dc]
description"Discord invite"
actions["message:&9Discord: &f<click:open_url:'https:…]
1 more entry shaped like guide: fixall

Typed arguments

commands.reward4 keys

The types below drive the tab completion the player sees. STRING · GREEDY_STRING · INTEGER · DOUBLE · BOOLEAN · PLAYER · OFFLINE_PLAYER · WORLD · MATERIAL · MONEY · DURATION · KIT · WARP · VIP_TIER · CHOICE (with a "values:" list)

enabledfalse
permission"server.reward"
arguments
[{ name: target, type: PLAYER, required: true }, { name: amount, type: MONEY, required: true }, { name: reason, type: GREEDY_STRING, required: false, default: "Well played" }]+2
actions
["console:eco give <target> <amount>", "message:&aYou rewarded <target> with <amount>.", "console:mail send <target> <reason>"]+2

Branching

commands.myvip2 keys

if:<condition> ? <action> : <action>

Conditions: permission · has-vip · world · gamemode · sneaking ·
            flying · op · level · money · playtime · health ·
            item-in-hand. A leading ! negates.
enabledfalse
actions["if:has-vip:any ? message:&6You are VIP. : me…]

Console only, for automation

commands.restartwarn3 keys

"sleep:" hands the rest of the chain to the scheduler, it does not block the server.

enabledfalse
console-onlytrue
actions
["broadcast:&cRestart in 5 minutes!", "sleep:4m", "broadcast:&cRestart in 1 minute!"]+2

modules/elevator.yml

Module: elevator
23 settings
plugins/ShadowEssentials/modules/elevator.yml
File notes

Elevators, as in CMI: stand on an elevator block and press JUMP to go up to the next one straight above you, or SNEAK to go down to the next one below.

Build one:

1. Place an elevator block (WHITE_WOOL, with the levels below).
2. Higher up, in the SAME column, place another block of the SAME
   level, within that level's max-distance, with 2 free blocks on
   top of it.
3. Stand on the lower one and jump. Sneak on the upper one to come
   back down.

Whatever is in between does not matter - floors, ceilings, walls: the ride goes straight through.

/elevator lists the levels as the plugin understood them, and which ones you can ride (shadowessentials.command.elevator, ops only). /se reload applies changes to this file.

config-version1
enabledtrue
commands1 key
elevator{ enabled: true, aliases: [ ] }

Levels

levels3 keys

A level is a kind of elevator: which blocks, how far apart, and who may ride it. Add, remove and rename levels as you like - the names (level-1, level-2...) are yours.

Keep reading
blocks        one or more Minecraft blocks: WHITE_WOOL, EMERALD_BLOCK,
              minecraft:lime_wool... They must be SOLID blocks you can
              stand on (carpets, flowers, signs, rails are refused).
              A wrong name is skipped and the console says why.
              A block belongs to ONE level only: when two levels list
              the same block, the first one keeps it.
max-distance  the biggest height difference, in blocks, between one
              elevator block and the next one of the same level.
              10 = the next floor can be at most 10 blocks higher (or
              lower). One further away is not found.
permission    "" = everybody can ride it. Otherwise the node a player
              needs. Invent the one you like and give it to your ranks
              with ShadowPermissions or LuckPerms, e.g.
                /lp group vip permission set shadowessentials.elevator.level.2

Only blocks of the SAME level connect: a level-1 block never takes you to a level-2 one. Every player also needs shadowessentials.elevator.use, which everybody has unless you take it away.

levels.level-13 keys
blocks[WHITE_WOOL]
max-distance10
permission""
levels.level-23 keys
blocks[LIGHT_BLUE_WOOL]
max-distance25
permission"shadowessentials.elevator.level.2"
levels.level-33 keys
blocks[LIME_WOOL, EMERALD_BLOCK]
max-distance50
permission"shadowessentials.elevator.level.3"
disabled-worlds[ ]

Worlds where elevators do nothing (the blocks are just blocks there).

cooldown"0.5s"

The wait between two rides of the same player. Decimals work: "0.5s", "1.5s", "250ms". "0" for no wait. The teleport module's warm-up, cooldown and price never apply here: an elevator has to feel instant.

center-playertrue

true: land in the middle of the destination block. false: land at the same spot of the block you left from. Where you look is always kept.

record-backfalse

false: /back ignores elevator rides, so it still takes you back to where you last teleported from. true: a ride counts like a teleport.

Protection

protectionenter

If every white wool is an elevator, a player could put one under somebody else's base and jump in. What stops it:

Keep reading
enter  (default) the ride is checked like a teleport: region and claim
       plugins that watch teleports (the entry flags of ShadowRegions,
       WorldGuard...) can refuse it, and so can any teleport blocker
       registered with ShadowEssentials. Enough when your protected
       areas refuse entry to strangers.
build  "enter", and the player must also be allowed to BUILD where
       they land - the same question the armor stand editor asks the
       protection plugins. The safe choice for claims that let anybody
       walk in: nobody rides into a place they could not build in.
       The price: in a shared building where guests may enter but not
       build, guests cannot use its elevators either.
none   no check of ours. The server still announces the ride as a
       teleport, so a plugin that refuses teleports can still refuse
       it.

shadowessentials.elevator.bypass (ops) skips these checks.

Feedback

messageactionbar

Where the short messages go ("no elevator above within 10 blocks", "the elevator above is blocked"...): actionbar, chat, title, subtitle or none. The texts are in lang/*.yml under "elevator:"; a text left empty there is not sent. The same message is repeated to the same player at most every 2 seconds.

sound3 keys

Played to the player on arrival. name: "" for silence.

name"ENTITY_ENDERMAN_TELEPORT"
volume0.5
pitch1.6
particles2 keys

Shown where the player lands. type: NONE (or count: 0) for none.

typePORTAL
count20

modules/hologram.yml

Module: hologram
23 settings
plugins/ShadowEssentials/modules/hologram.yml
File notes

Floating text built on the game's own display entities: no invisible armour stands, no packet library, no dependency.

The holograms themselves live at the bottom of this file. Build them in game with /hologram, or write them here by hand - both work, and the file is always the source of truth.

Colours with &, as everywhere else: &6 gold, &l bold, &#ff8800 for an exact colour. Gradients still use <gradient:...>.

config-version1
enabledtrue
commands1 key
hologram{ enabled: true, aliases: [ "holo", "hd" ] }

Living next to another hologram plugin

conflict2 keys
auto-disabletrue

If DecentHolograms, HolographicDisplays, FancyHolograms or a similar plugin is installed, this module steps aside on its own: it spawns nothing and /hologram says why. Turn this off to run both.

include-cmifalse

CMI is a whole essentials plugin, so its presence does not by itself mean it is drawing holograms. Set this to true if you use CMI's.

Defaults

defaults12 keys

Every hologram inherits these and can override any of them.

billboardCENTER

CENTER always faces you. FIXED never turns. VERTICAL and HORIZONTAL turn on one axis only.

scale1.0
view-range40.0

Distance in blocks past which the text stops being sent at all.

background"transparent"

ARGB, so the first pair is the opacity. "transparent" for none.

default-backgroundfalse

true uses the vanilla dark box instead of the colour above.

text-shadowfalse
see-throughfalse
alignmentCENTER

CENTER | LEFT | RIGHT

line-spacing0.28

Vertical gap between lines, in blocks.

line-width200

Wrap width in pixels for a very long line.

item-spintrue

Whether icon lines turn and bob in place. false: they hang still.

update-interval"1s"

How often a hologram with placeholders is redrawn. A hologram with nothing dynamic in it is never redrawn at all, whatever this says.

Distance

visibility1 key
spawn-distance32

A hologram exists only while a player is within this many blocks of it. Further away its entities are removed - nothing to tick, nothing to send - and put back the moment somebody comes near. Every plugin of the suite that draws through ShadowEssentials gets this for free. 0 = always spawned.

Animations

animations2 keys

Use one from a line with: animation:<name>

animations.arrow2 keys
interval"250ms"
frames
["&e>>> &7CLICK &e ", "&e >>> &7CLICK &e ", "&e >>> &7CLICK &e ", "&e >>> &7CLICK &e "]+3
animations.rainbow2 keys
interval"150ms"
frames
["&c&lWELCOME", "&6&lWELCOME", "&e&lWELCOME", "&a&lWELCOME", "&b&lWELCOME", "&d&lWELCOME"]+3

The holograms

holograms{ }

Line kinds:

plain text                       colours with &
""                               a blank spacer line
icon:DIAMOND                     an item that floats, turns and bobs
animation:<name>                 cycles the frames defined above
leaderboard:<board>:<1-10>:<fmt> one line per rank, from the
                                 leaderboard module
Keep reading
Placeholders:
  %online% %max_players% %tps%     the same for everybody
  %player% <player> %world%        this viewer's own values
  %shadowessentials_...%               and any PlaceholderAPI placeholder

A hologram whose text differs per viewer is drawn once per viewer, automatically, and only for the players close enough to read it.

Example, copy it outside the { } above to use it:

holograms:
  spawn:
    world: "world"
    x: 0.5
    y: 66.0
    z: 0.5
    lines:
      - "<gradient:#8A2BE2:#00BFFF>&lWELCOME</gradient>"
      - "&7Online: &f%online%&7/&f%max_players%"
      - ""
      - "icon:DIAMOND"
      - "&eClick for the kits"
    click:
      actions: [ "command:/kits" ]
      radius: 1.5
top-playtime:
  world: "world"
  x: 10.5
  y: 66.0
  z: 0.5
  update-interval: "60s"
  lines:
    - "&6&lMOST HOURS PLAYED"
    - "leaderboard:playtime:1-10:&7<rank>. &f<name> &8- &e<value>"
vip-only:
  world: "world"
  x: 20.5
  y: 66.0
  z: 0.5
  # Only shown to whoever passes the condition. Same conditions as
  # everywhere else: permission, has-vip, world, playtime, level...
  show-if: "has-vip:any"
  lines:
    - "&6Welcome back, &f%player%&6!"

modules/homes.yml

Module: homes
20 settings
plugins/ShadowEssentials/modules/homes.yml
config-version1
enabledtrue
commands4 keys
home{ enabled: true, aliases: [ "h" ] }
homes{ enabled: true, aliases: [ "listhomes" ] }
sethome{ enabled: true, aliases: [ "sh" ] }
delhome{ enabled: true, aliases: [ "dh", "removehome" ] }
limits3 keys
default1

For players without any specific permission.

permission-basedtrue

Reads shadowessentials.limit.homes.<n> - the highest value wins. shadowessentials.limit.homes.unlimited removes the limit.

hard-cap50

Absolute ceiling, even with permissions. -1 = no ceiling.

naming4 keys
default-name"home"

Name used by /sethome with no argument.

max-length16
pattern"[a-zA-Z0-9_-]+"
blacklist[list, help, set, del, icon]
placement1 key
blacklist-worlds[ ]

Worlds where homes cannot be created.

teleport3 keys
warmup"3s"

Leave empty to inherit from modules/teleport.yml.

cooldown"10s"
teleport.cost1 key
amount0
gui3 keys
allow-custom-icontrue

Players can choose the icon of each home with /home icon <name> while holding the item they want.

right-click-deletetrue

Right clicking a home in the menu offers to delete it. The question is asked in chat with the two buttons, never on the click itself, and it still needs shadowessentials.command.delhome.

sortNAME

NAME | DATE | WORLD

modules/inventory.yml

Module: inventory
15 settings
plugins/ShadowEssentials/modules/inventory.yml
File notes
/chestorder on   every chest, barrel, shulker box or ender chest the
                 player opens is tidied first: half-empty stacks of the
                 same thing are merged, and the stacks are sorted.
/autopickup on   what the player breaks or kills goes straight into
                 the inventory; what does not fit falls as usual.

Both are ON for a new player (default-on below) and remembered per player once they change them.

config-version1
enabledtrue
commands2 keys
chestorder
{ enabled: true, aliases: [ "chestsort", "sortchest" ] }+1
autopickup{ enabled: true, aliases: [ "autopick" ] }
chest-order4 keys
enabledtrue
default-ontrue

On for every player until they turn it off with /chestorder off.

shulker-boxestrue

Shulker boxes are sorted too. Off if your players keep them as organised kits and would rather they stayed exactly as packed.

ender-chesttrue
auto-pickup7 keys
enabledtrue
default-ontrue

On for every player until they turn it off with /autopickup off.

mob-dropstrue

Also the drops of a mob the player kills.

experiencetrue

Experience: from the blocks the player breaks and the mobs they kill.

The experience that would drop is set to zero and the same amount is given to the player, so the total is identical: the only difference is that there are no orbs to chase. Furnace experience is left alone - it is collected by opening them, and taking it from a distance would mean emptying them without looking at them.

experience-default-ontrue

On for everyone until they turn it off with /autopickupxp off.

creative-toofalse

In creative mode the drops normally do not matter; on if you want it anyway.

never-collect[ ]

Materials that always fall to the ground even with auto pickup on.

modules/kits.yml

Module: kits
17 settings
plugins/ShadowEssentials/modules/kits.yml
File notes

GLOBAL kit settings. Each kit is its own file in kits/<name>.yml

config-version1
enabledtrue
commands2 keys
kit{ enabled: true, aliases: [ "k" ] }
kits{ enabled: true, aliases: [ "kitlist" ] }
menu"kits"

GUI layout file: menus/kits.yml

defaults4 keys

Defaults applied to kits that do not define their own value.

cooldown"24h"
full-inventoryQUEUE
DROP   = drop the extra items on the ground
QUEUE  = keep them until the player has room (recommended)
CANCEL = refuse the claim if the inventory is full
cooldown-modeDURATION
respect-vip-multipliertrue

Delivery queue

When the inventory is full the leftover items are stored instead of being dropped on the ground. They survive relogs, deaths and restarts. Claim them with /kit claim.

queue3 keys
enabledtrue
max-items200

Maximum stored items per player. -1 = unlimited.

notify-on-jointrue

Tell the player at login that something is waiting.

first-join2 keys

Kits handed out automatically the first time a player joins.

enabledtrue
kits[starter]
timezone"Europe/Rome"

Timezone used by cooldown-mode DAILY / WEEKLY / MONTHLY. DAILY resets at midnight in this zone, which is what players expect, instead of 24 hours after the last claim.

preview2 keys
enabledtrue
allow-lockedtrue

Let players preview kits they cannot claim yet: seeing what is behind a rank sells it better than any description.

modules/leaderboard.yml

Module: leaderboard
16 settings
plugins/ShadowEssentials/modules/leaderboard.yml
File notes

Italian texts (testi in italiano): esempi/it_IT/modules/leaderboard.yml - copy it over this file. Leaderboards. Recalculated in the background and served from cache: /leaderboard never touches storage. The other Shadow plugins can register their own leaderboards through the API, and those appear here on their own.

config-version1
enabledtrue
commands1 key
leaderboard{ enabled: true, aliases: [ "top10", "lb" ] }
refresh"5m"

How often every leaderboard is recalculated.

boards3 keys
boards.playtime4 keys
display-name"&bMost hours played"
stat"playtime"

"playtime" and "first-join" come from the profile, the rest from the vanilla statistics.

size10
format"&7<rank>. &f<name> &8- &b<value>"
boards.kills4 keys
display-name"&cPiu uccisioni"
stat"kills"
size10
format"&7<rank>. &f<name> &8- &c<value>"
boards.deaths4 keys
display-name"&4Piu morti"
stat"deaths"
size10
format"&7<rank>. &f<name> &8- &4<value>"

modules/lock.yml

Module: lock
39 settings
plugins/ShadowEssentials/modules/lock.yml
File notes

Lock a chest, barrel, furnace or door for yourself: hang a sign on it with [Lock] on the first line. Right-click the sign to choose who else may open it.

Where the locks live: in the world itself (the chunk data), not in a database. A world backup brings its locks back with it, a deleted world takes them away. data/locks.yml (or the sb_lock table) is only an index for counting and listing: losing it loses no lock.

A lock adds a refusal, it never grants anything: if a region or an island keeps a chest closed to somebody, being on the lock does not open it for them.

config-version1
enabledtrue
commands1 key
lock{ enabled: true, aliases: [ "chestlock" ] }
sign-tags[Lock, Private, Privato]

First line of a lock sign. Case does not matter; both sides count. These tags are reserved: a sign type in modules/sign.yml with the same tag is ignored, and the console says so.

quick-locktrue

Right-click a container holding a sign: the sign hangs itself on a free side and the container is locked. With no free side it is locked without a sign.

lockable15 keys

What can be locked. Copper chests and decorated pots are off until copper golems and arrows are handled (see the manual). Iron doors never: only redstone opens them.

cheststrue

chest, trapped chest

copper-chestsfalse
barrelstrue
shulker-boxestrue
furnacestrue

furnace, smoker, blast furnace

hopperstrue
droppers-dispenserstrue
brewing-standstrue
crafterstrue
doorstrue

wooden doors, trapdoors, fence gates

shelvesfalse
lecternsfalse
jukeboxesfalse
decorated-potsfalse
chiseled-bookshelvesfalse
connected-doorstrue

Double doors open and close together, and one lock covers both.

disabled-worlds[ ]

Worlds where no lock can be made (existing ones there still hold).

command-range5

How far /lock reaches for the block you look at.

notice-cooldown"2s"

The same "this chest is locked" is said to the same player at most this often: a held right click repeats the click.

limits1 key
default25

Locks per player. shadowessentials.lock.limit.<n> raises it (the highest node wins), shadowessentials.lock.limit.unlimited removes it. A double chest counts one. The count comes from the index.

hoppers1 key
auto-lock-own-hopperstrue

A hopper the owner places against their own locked container is locked to them too, so their own hopper chains keep working. Those hoppers do not count against the limit.

modes1 key
deposittrue

DEPOSIT: everybody puts things in, only the members take them out.

groups1 key
permission-groups[ ]

Extra groups offered in the menu, next to team, island and region. "vip" here means: whoever has shadowessentials.lock.group.vip (give it to a group in ShadowPermissions or LuckPerms).

land-owner2 keys

Who owns the land may take a lock off it (never open it silently).

islandstrue
regionsfalse

Off: the regions of the spawn belong to the staff, who has bypass.

orphan-on-island-leavetrue

A member who left the island: their locks there count as expired for the island owner, who may open them and take them off.

expiry4 keys
after-days0

0 = locks never expire. Otherwise: owner not seen for this many days.

actionBREAKABLE
UNLOCK    anybody opens it

BREAKABLE still closed, but anybody may break it

NOTHING   only /lock info says so
purgefalse

Take the locks of expired owners off by themselves, every so often.

purge-every"24h"
import4 keys
signsfalse

Convert [Private] signs of Lockette, LockettePro and BlockLocker as their chunks load. Only while those plugins are NOT installed.

private-tags[Private, Privato]

The first line of those signs.

more-users-tags["More Users", "Altri Utenti"]
lwc-table"lwc_protections"

/lock admin import lwc mysql reads this table in the database ShadowEssentials uses.

modules/mail.yml

Module: mail
9 settings
plugins/ShadowEssentials/modules/mail.yml
config-version1
enabledtrue
commands1 key
mail{ enabled: true, aliases: [ "inbox" ] }
limits2 keys
max-messages50

Most messages an inbox may hold.

max-length256
expiry2 keys
unread"30d"

Unread messages expire after...

read"7d"

Read messages are deleted after...

notify2 keys
on-jointrue

A notice at login when there are unread messages.

delay"2s"

modules/moderation.yml

Module: moderation
61 settings
plugins/ShadowEssentials/modules/moderation.yml
File notes

Italian texts (testi in italiano): esempi/it_IT/modules/moderation.yml - copy it over this file. Ban, mute, kick, warn, jail, freeze, vanish. All of it in storage: it works offline and across several servers.

config-version1
enabledtrue
commands15 keys
ban{ enabled: true, aliases: [ ] }
tempban{ enabled: true, aliases: [ "tban" ] }
unban{ enabled: true, aliases: [ "pardon" ] }
kick{ enabled: true, aliases: [ ] }
mute{ enabled: true, aliases: [ ] }
tempmute{ enabled: true, aliases: [ "tmute" ] }
unmute{ enabled: true, aliases: [ ] }
warn{ enabled: true, aliases: [ ] }
jail{ enabled: true, aliases: [ ] }
unjail{ enabled: true, aliases: [ ] }
freeze{ enabled: true, aliases: [ ] }
history{ enabled: true, aliases: [ "punishments" ] }
alts{ enabled: true, aliases: [ ] }
vanish{ enabled: true, aliases: [ "v" ] }
staffchat{ enabled: true, aliases: [ "sc" ] }

Punishment templates

Preset reasons with the durations already decided:

/ban SomePlayer #cheating

Which duration is picked depends on how many times that player has already had the same template, so two different moderators hand out the same penalty for the same thing without having to remember it.

templates4 keys
templates.spam3 keys
display"Spam in chat"
typeMUTE
durations[10m, 1h, 12h, 7d]
templates.insults3 keys
display"Offensive language"
typeMUTE
durations[30m, 3h, 1d, 7d]
templates.cheating4 keys
display"Cheating clients"
typeBAN
durations[30d, perm]
broadcasttrue
templates.griefing3 keys
display"Griefing"
typeBAN
durations[3d, 14d, perm]

Warnings

warns2 keys
expire"30d"

How long before a warning stops counting towards the ladder.

warns.ladder3 keys

Automatic actions once N active warnings are reached. Only the exact rung fires, not every rung below it.

warns.ladder.33 keys
actionMUTE
duration"1h"
reason"3 warnings"
warns.ladder.53 keys
actionBAN
duration"1d"
reason"5 warnings"
warns.ladder.83 keys
actionBAN
duration"perm"
reason"8 warnings"

Ban

ban2 keys
screen
["&c&lYOU ARE BANNED", "", "&7Reason: &f<reason>", "&7By: &f<actor>", "&7Expires: &f<expires>", "", "&eIf you think this is a mistake, write on Discord."]+5

The screen shown to a banned player. MiniMessage works here. Placeholders: <reason> <actor> <expires>

broadcasttrue
kick1 key
screen
["&c&lYOU WERE KICKED", "", "&7Reason: &f<reason>"]+1

Mute

mute2 keys
blocked-commands[msg, tell, w, r, reply, mail, me, sc]

Commands blocked while muted, so a mute is not walked around by writing in private instead.

shadow-mutetrue

Shadow mute: the player sees their own messages, nobody else does. Far more effective than a plain mute against somebody baiting.

Jail

Cells are made with /jail create <name> while standing in the right spot, or written here by hand.

jail2 keys
cells{ }
contain-radius20

A player who walks away from the cell is put back inside.

Alt account detection

alts3 keys
enabledtrue
notify-on-jointrue

Tells the staff at login when the address is already known for other accounts.

only-if-punishedfalse

true = only warn when one of the other accounts is banned

Vanish

/vanish hides the player's entity from the other clients entirely: no model, no armour, no name, no potion particles, no line in the tab list. As far as they are concerned the player is not there.

The settings below are for every other way somebody invisible gives themselves away regardless.

vanish10 keys
silent-join-quittrue

No join and quit message while you are invisible.

block-pickuptrue

An item flying off the ground towards nothing gets noticed.

block-mob-targetingtrue

So does a zombie chasing an empty corridor.

block-pressure-platestrue

And a pressure plate going down on its own, even more so.

invulnerabletrue

No damage while invisible: you cannot die during an investigation.

freeze-hungertrue

Hunger stays where it is.

remindertrue

A reminder in the action bar, because forgetting you are invisible is the classic way to ruin an investigation.

hide-from-player-counttrue

The player count - server list, tab list, holograms, placeholders - leaves out whoever is invisible.

hide-from-listtrue

Vanilla's /list would name everybody anyway, so we answer it ourselves, in the same words and without whoever cannot be seen.

auto-on-joinfalse

Whoever has shadowessentials.vanish.auto joins already invisible.

notify1 key
permission"shadowessentials.moderation.notify"

Who receives the moderation notifications.

modules/motd.yml

Module: motd
24 settings
plugins/ShadowEssentials/modules/motd.yml
File notes

Italian texts (testi in italiano): esempi/it_IT/modules/motd.yml - copy it over this file.

What your server looks like in the multiplayer list: the two lines of text, the picture next to them, the player count and the little list that appears when you hover the count.

It is the first thing anybody sees of your server, and usually the only thing they compare it on.

COLOURS with &, as everywhere else:

&6 gold  &c red  &l bold  &#ff8800 exact colour  &r reset

Gradients use the tag, because & cannot do them:

<gradient:#8A2BE2:#00BFFF>SHADOW</gradient>
config-version1
enabledtrue
commands1 key
motd{ enabled: true, aliases: [ ] }

The two lines

motd4 keys
enabledtrue
modeRANDOM
RANDOM  = a different one at every refresh of the server list
ORDERED = one after the other, in the order written here

A single entry means it never changes, which is also fine.

centertrue

Pads each line with spaces so it sits in the middle of the panel. The width is measured character by character, because Minecraft's font is not monospaced and "just count the letters" looks wrong.

motd.messages3 keys

Placeholders that work here:

%online%  %max_players%  %tps%  %version%
and every PlaceholderAPI placeholder, if it is installed.
motd.messages.default1 key
lines
["<gradient:#8A2BE2:#00BFFF>&lSHADOW &fNETWORK</gradient>", "&7Survival &8| &7SkyBlock &8| &7Events every weekend"]+1
motd.messages.second1 key
lines
["<gradient:#8A2BE2:#00BFFF>&lSHADOW &fNETWORK</gradient>", "&e&lNEW &8| &7A new SkyBlock season is out"]+1
motd.messages.third1 key
lines
["<gradient:#8A2BE2:#00BFFF>&lSHADOW &fNETWORK</gradient>", "&7Online now: &a%online%&7/&f%max_players%"]+1

The picture

icon3 keys
enabledtrue
folder"icons"

Drop your PNG files in plugins/ShadowEssentials/<folder>/. Minecraft wants exactly 64x64: anything else is resized for you at startup, so you can drop in the logo you already have.

modeRANDOM

RANDOM | ORDERED | FIRST

The list under the player count

hover2 keys

Hovering the count shows this. Colours with & work here too, hex included. An empty line "" leaves a gap. Keep the lines short: the box is only as wide as the longest one.

enabledtrue
lines
["&7Welcome to", "&#8A2BE2SHADOW", "", "&7Online: &f%online%"]+1

Player count

players5 keys
hidefalse

Hides the count and the list entirely.

count-modeREAL
REAL            = the truth
ADD             = the truth plus "add" below
FIXED           = always "fixed" below
ALWAYS_ONE_MORE = slots always show one free, so it never looks full
add0
fixed0
max-slots0

0 = leave the slots from server.properties alone.

Version line

version1 key

Shown in red next to the count when the player's client version does not match, which is exactly the moment to tell them what to use. null = leave the real one.

textnull

Example: "&cRequires 1.26.2"

Maintenance

maintenance4 keys

Switch it with /motd maintenance on|off. It only changes what the server list shows: it does not close the server to anybody.

enabledfalse
lines
["&c&lMAINTENANCE", "&7Back soon. Thank you for your patience!"]+1
iconnull

A PNG from the same icons folder, without the extension.

hover["&cUnder maintenance", "&7Back soon"]

modules/npc.yml

Module: npc
4 settings
plugins/ShadowEssentials/modules/npc.yml
File notes

NPCs you can walk up to and click.

They are built on the MANNEQUIN, the player-shaped entity the game itself provides. That matters more than it sounds: every other plugin that puts a skinned player in the world does it by sending fake packets, which means one more library, one more dependency, and one more thing that breaks at the next update. A mannequin is an ordinary entity with an ordinary API.

The NPCs live in npcs.yml. The plugin writes that file.

config-version1
enabledtrue
commands1 key
npc{ enabled: true, aliases: [ ] }
look-range6.0

Within how many blocks an NPC turns its head towards a passer-by.

modules/particles.yml

Module: particles
16 settings
plugins/ShadowEssentials/modules/particles.yml
File notes

Italian texts (testi in italiano): esempi/it_IT/modules/particles.yml - copy it over this file.

Particles: the ones players wear, and the ones pinned to a fixed spot - an altar, a fountain, a crate.

An effect is two separate things: the SHAPE, where they are drawn, and the PARTICLE, which one. Keeping them apart means that a halo for every particle in the game is one line of config rather than a hundred, and that a particle added by a game update works without anything here being touched.

config-version1
enabledtrue
commands1 key
particles{ enabled: true, aliases: [ "particle", "pp" ] }
interval-ticks4

How many ticks between redraws. 4 = five times a second, which looks smooth. Raise it if a great many players have an effect switched on.

max-range32

The distance past which there is no point drawing them.

hide-when-vanishedtrue

An invisible staff member trailing sparks behind them is not invisible.

hide-when-afktrue

A player left AFK at spawn for six hours is a particle generator nobody asked for.

The shapes

HALO    ring above the head
AURA    cloud around the body
TRAIL   a trail left while walking
FEET    circle at the feet
WINGS   two wings behind the shoulders (they follow the rotation)
ORBIT   ring turning at waist height
BEAM    column going upwards
RAIN    rain from above
HELIX   double helix climbing

The entries

effects7 keys
shape       one of the shapes above
particle    the Minecraft name of the particle
color       #RRGGBB, only for DUST and ENTITY_EFFECT
count       how many per frame
size        radius, or scale for DUST
group       how they are grouped in the menu
permission  who may wear it (default shadowessentials.particle.<id>)
icon        the item in the menu
effects.sparks8 keys
name"&eSparks"
shapeHALO
particleEND_ROD
count8
size0.7
groupbase
iconNETHER_STAR
lore["&7A ring of light above your head."]
6 more entries shaped like sparks: flame, hearts, dust, wings, helix, beam

Effects pinned to a spot

blocks{ }

Written by /particles block <name> <effect> while looking at the block.

Other plugins - the crates one, for instance - do NOT write here: they attach theirs at runtime through the API, and they disappear when the plugin removes them. That way a hundred crates do not leave you a hundred blocks of YAML to read.

modules/player.yml

Module: player
38 settings
plugins/ShadowEssentials/modules/player.yml
File notes

The classic essentials utilities.

config-version1
enabledtrue
commands17 keys
heal{ enabled: true, aliases: [ ] }
feed{ enabled: true, aliases: [ "eat" ] }
fly{ enabled: true, aliases: [ ] }
god{ enabled: true, aliases: [ ] }
gamemode{ enabled: true, aliases: [ "gm" ] }
speed{ enabled: true, aliases: [ ] }
repair{ enabled: true, aliases: [ "fix" ] }
hat{ enabled: true, aliases: [ ] }
more{ enabled: true, aliases: [ ] }
workbench{ enabled: true, aliases: [ "craft", "wb" ] }
enderchest{ enabled: true, aliases: [ "ec" ] }
trash{ enabled: true, aliases: [ "disposal", "bin" ] }
invsee{ enabled: true, aliases: [ ] }
clearinventory{ enabled: true, aliases: [ "ci" ] }
suicide{ enabled: true, aliases: [ ] }
ping{ enabled: true, aliases: [ ] }
seen{ enabled: true, aliases: [ ] }
heal5 keys
cooldown"60s"
restore-healthtrue
restore-hungertrue
clear-effectstrue
extinguishtrue
fly3 keys
persisttrue

Keep flight enabled across relogs.

blacklist-worlds[ ]

Worlds where flight is refused even with permission.

safe-landingtrue

Brief fall immunity when flight is removed mid-air, so taking flight away from someone in the sky is not a death sentence.

invsee2 keys
allow-edittrue
readonly-against"shadowessentials.invsee.protect"

Players with this permission cannot have their inventory edited, only viewed. Protects senior staff from junior staff.

repair1 key
cooldown"30s"

Nicknames

nick8 keys

The name shown in chat, in the tab list and to other plugins. The real account name never changes, and /realname always reads it back.

Keep reading

Colours are given out one permission at a time, so a rank can have a coloured name without every rank being able to paint themselves like a staff member:

shadowessentials.nick.color     &a &c &7 ...
shadowessentials.nick.hex       &#ff8800
shadowessentials.nick.gradient  <gradient:...>
shadowessentials.nick.format    bold, italic, underline
shadowessentials.nick.magic     &k

Anything not allowed is dropped from the name, not refused.

enabledtrue
min-length3

Length is measured on the visible text, colours do not count.

max-length16
allow-spacesfalse

Letters, digits and _ only. shadowessentials.nick.bypass.characters skips it.

prefix"&7~&r"

Put in front of every nickname, so a nicked player is recognisable. Leave empty for no marker.

block-real-namestrue

Refuse a nickname that is somebody else's real account name. Turning this off lets a player be indistinguishable from another one.

uniquetrue

Refuse a nickname another online player is already wearing.

blacklist[admin, owner, staff, mod, console, server]

Matched against the visible text, case insensitive, anywhere inside.

modules/portal.yml

Module: portal
10 settings
plugins/ShadowEssentials/modules/portal.yml
File notes

Boxes that run something when a player walks into them.

These are NOT protected regions: no claims, no flags, no overlap with ShadowRegions. All a portal does is notice you walked in.

Build one in game:

/portal wand      then left click one corner, right click the other
/portal create hub-to-survival command:/warp survival

Two portals that lead into each other:

/portal create entrance
(go somewhere else)
/portal create exit
/portal link entrance exit both

"both" links the way back as well; leave it out for one way only. /portal on its own opens the list, and from there every portal has a card with all of this in it - link, block, cost, wait, mirror.

config-version1
enabledtrue
commands1 key
portal{ enabled: true, aliases: [ ] }

Portals

portals{ }

Empty by default. The movement listener is always registered, but its first line returns when there are no portals, so an empty list costs one comparison per move and nothing else.

It used to be registered only when a portal already existed at boot, and that is why the FIRST portal of a server did nothing until the next restart - while the message said it was live straight away.

Example, copy it outside the { } above to use it:

portals:
  hub-to-survival:
    world: "world"
    corner1: { x: 10, y: 60, z: 10 }
    corner2: { x: 14, y: 65, z: 14 }
    actions:
      - "command:/warp survival"
# Optional gate. Without the permission the player is told why.
permission: null
denied-message: "&cYou cannot go through here."
# Optional price and wait.
cooldown: "3s"
cost:
  amount: 0
# Optional requirements.
requirements:
  vip-tier: null
  playtime: null
# Only fires while standing in this block, so you can lay the box
# over a real nether portal or a water column.
trigger-block: null
effects:
  sound: { name: "BLOCK_PORTAL_TRAVEL", volume: 0.4, pitch: 1.2 }
  particles: { type: PORTAL, count: 30 }
  title: "<gradient:#8A2BE2:#00BFFF>SURVIVAL</gradient>"

How it looks when you create it

creation3 keys

A portal is an area, not blocks: without this, whoever created one saw nothing in the world and had to build it by hand to know where it was.

filltrue

false to leave the area invisible, as before.

blockNETHER_PORTAL

What it is filled with. Change the block of an existing portal with

/portal block <id> <blocco>

and use "air" to empty it.

Keep reading

It has to be a block you can WALK INTO. That rules out glass, panes and every other solid: a portal made of those is a wall, you stop in front of it, and nothing happens - with nothing on screen to say why. NETHER_PORTAL looks the part and lets you through; the vanilla trip to the Nether is cancelled inside our own portals, so it goes where the link says instead. WATER, AIR and LIGHT work too.

frame-blockOBSIDIAN

The block the ready-made frames are drawn with (/portal shape ... circle, rect). A free-hand outline (/portal build) is whatever blocks you place.

Shapes, looks and the mirror

A portal is a box from the wand, or any set of cells drawn in a plane:

/portal shape <id> circle <radius>      a ring where you look
/portal shape <id> rect <width> <height>
/portal build <id>   ...place blocks...   /portal finish [action]

The outline you build stays; what it encloses is the portal (cells:).

Per portal, in the file or with /portal edit <id> <field> <value>:

fill-block: WHITE_STAINED_GLASS_PANE   the block inside (air = nothing)
facing: SOUTH                          the side players stand on; set on
                                       creation, matters for the mirror
effects:
  ambient: { type: PORTAL, count: 6, distance: 24, interval: 10 }
                                       particles inside it while somebody
                                       is within "distance" blocks
mirror:                                see the far side of another portal
  enabled: true
  target: other-portal                 /portal mirror <id> <target|off>
  distance: 24                         only for players this close
  depth: 12                            how deep the window goes
  refresh-ticks: 40                    how often the window is redrawn
  max-blocks: 4096                     the most blocks a window may use
  show-players: true                   players on the far side, as a name
                                       with their head under it

The mirror is drawn on the client only: the blocks behind the portal are shown as the blocks in front of the target, for each viewer, and put back the moment they walk away. It costs nothing while nobody is near.

Actions: "portal:<id>" lands on the doorstep of that portal, facing away from it - the usual way to link two portals to each other.

Performance

performance1 key

Areas are indexed by chunk, so the check on movement is one map lookup no matter how many portals exist. Nothing to tune here, the entry is kept for the record.

check-on-block-change-onlytrue

Safety

safety2 keys

A portal is a piece of the world that reacts to whoever is standing in it, and a moment later that player is usually somewhere else. Three kinds of trouble come from that, and they are the kind that stop the server rather than the kind that annoy people:

Keep reading
- two portals pointing at each other: A takes you to B, B takes you
  back to A, and on arrival it fires again. Nothing in the config is
  wrong; the server simply stops responding.
- the edge: standing on the boundary and stepping in and out fires
  the portal on every block change. For a portal that runs console
  commands, that means running them twenty times a second.
- paying twice: the price goes through the economy plugin, which
  answers later. Stepping back in while the first answer is still in
  flight starts a second payment.

They are one thing seen from three sides, so they get one cure: after a portal fires, that player is deaf to portals for a moment.

grace"1s"

How long they stay deaf. Raise it if you have chains of portals close together.

max-per-10s20

A safety net for a chain long enough to outlast the grace period: past this many firings in 10 seconds the portal is refused and the console tells you who and where.

modules/reward.yml

Module: reward
25 settings
plugins/ShadowEssentials/modules/reward.yml
File notes

Italian texts (testi in italiano): esempi/it_IT/modules/reward.yml - copy it over this file. Daily rewards with streaks, and playtime rewards. The actions use the same language as the GUIs, vouchers and signs:

money:give:500 · xp:give:100 · kit:give:bonus · console:<command>
message:&aCiao · sound:ENTITY_PLAYER_LEVELUP
config-version1
enabledtrue
commands1 key
daily{ enabled: true, aliases: [ "dailyreward" ] }

Daily reward

daily6 keys
enabledtrue
timezone"Europe/Rome"
grace-period"6h"

How far over you may go before losing the streak. Without this, joining at 00:30 instead of 23:30 would wipe out thirty days in a row, which is the most infuriating part of systems like this.

cycle7

Length of the cycle: once finished it starts again from day 1.

daily.streak-bonus2 keys

A compounding bonus for long streaks.

multiplier1.1

+10% for every week in a row

max-multiplier2.0
daily.days7 keys
daily.days.12 keys
iconIRON_INGOT
actions["money:give:250", "message:&aDay 1: 250 coins"]
daily.days.22 keys
iconIRON_INGOT
actions["money:give:500", "message:&aDay 2: 500 coins"]
daily.days.32 keys
iconDIAMOND
actions
["console:give <player> diamond 2", "message:&aDay 3: 2 diamonds"]+1
daily.days.42 keys
iconGOLD_INGOT
actions
["money:give:1000", "message:&aDay 4: 1000 coins"]+1
daily.days.52 keys
iconCHEST
actions
["xp:give:200", "message:&aDay 5: 200 experience"]+1
daily.days.62 keys
iconEMERALD
actions
["money:give:2000", "message:&aDay 6: 2000 coins"]+1
daily.days.72 keys
iconNETHER_STAR
actions
["money:give:5000", "console:give <player> diamond 5", "sound:UI_TOAST_CHALLENGE_COMPLETE", "broadcast:&6<player> completed the week!"]+3

Playtime rewards

AFK time does NOT count (see modules/afk.yml), so these cannot be farmed by leaving the client running.

playtime2 keys
enabledtrue
tiers
[{ after: 1h, repeating: true, actions: […] }, { after: 10h, repeating: false, actions: […] }, { after: 50h, repeating: false, actions: […] }, { after: 100h, repeating: false, actions: […] }]+3

modules/sign.yml

Module: sign
20 settings
plugins/ShadowEssentials/modules/sign.yml
File notes

Signs that do something when clicked, plus colours on normal signs.

A sign type is just a block in "types:" below. The actions are the same chain language the GUIs, kits and vouchers use, so you can invent your own sign types without waiting for a plugin update.

config-version1
enabledtrue

Colours on ordinary signs

colors2 keys
enabledtrue
permission"shadowessentials.sign.color"

Only players with this permission get their colour codes translated.

Functional signs

types7 keys

First line is [Tag]. The other lines are parameters, available in the actions as <line2>, <line3> and <line4>.

types.warp5 keys
tag"Warp"
create-permission"shadowessentials.sign.create.warp"
use-permission"shadowessentials.sign.use.warp"
format["&8[&bWarp&8]", "&f<line2>"]

How the sign is rewritten when it is placed.

actions["command:/warp <line2>"]
5 more entries shaped like warp: kit, heal, spawn, trash, craft
types.command5 keys

Runs whatever is written on lines 2 to 4. Staff only, for obvious reasons: whoever can place one of these can run any command.

tag"Command"
create-permission"shadowessentials.sign.create.command"
use-permission"shadowessentials.sign.use.command"
format
["&8[&dCommand&8]", "&f<line2>", "&f<line3>", "&f<line4>"]+1
actions["command:/<line2> <line3> <line4>"]

Protection

protection3 keys
prevent-breaktrue

A functional sign can only be broken by someone with the permission.

break-permission"shadowessentials.sign.break"
protect-attachedtrue

Also protects the block the sign hangs on, so it cannot be dropped by mining the wall behind it.

Feedback

feedback1 key
feedback.sound3 keys
name"UI_BUTTON_CLICK"
volume0.6
pitch1.2

modules/skin.yml

Module: skin
23 settings
plugins/ShadowEssentials/modules/skin.yml
File notes

Skins: /skin set <name>, /skin url <link>, /skin reset, and a wardrobe menu with /skin. The same sources work for NPCs (npcs.yml "skin:") and for mannequins.

A skin source is one line:

Notch  or  name:Notch        the skin of that Mojang account
url:https://.../skin.png     an image, signed through MineSkin (*)
file:guard                   skins/guard.png, signed once through MineSkin (*)
preset:knight                one of the presets below

(*) only once you have filled in "mineskin:" below. Skins by name

need nothing: they come from Mojang.

The skin is put into the player's profile BEFORE they join, so nobody ever sees them with the wrong one for a second.

config-version1
enabledAUTO

AUTO = on, unless SkinsRestorer is installed on this server (it keeps /skin, and the console says so once). If SkinsRestorer runs on your PROXY, write false here yourself: a server cannot see the proxy, and two plugins writing the same skin overwrite each other.

commands1 key
skin{ enabled: true, aliases: [ "skins" ] }
default-skinAUTO

What a player wears before choosing anything.

AUTO      OWN_NAME in offline mode, KEEP in online mode (and KEEP
          whenever the login already brought a signed skin, as a
          proxy forwarding the real one does)
KEEP      whatever the login gave them
OWN_NAME  the Mojang skin of the account with the same name, if any
LIST      one of default-list, always the same one for the same player
default-list[ ]
sources3 keys

Which kinds of source players may use (each one also has a permission).

nametrue
urltrue

needs "mineskin:" below filled in

filetrue

skins/<id>.png, uploaded once through MineSkin

presets3 keys

Ready-made skins for the wardrobe: name:, url: or file:. A file preset needs the PNG in plugins/ShadowEssentials/skins/ and

"mineskin:" filled in, e.g.   knight: "file:knight"
notch"name:Notch"
jeb"name:jeb_"
dinnerbone"name:Dinnerbone"
mineskin6 keys
endpoint""

Skins from a link or a file are signed by MineSkin, an outside service, and stay off until you fill in BOTH lines below: create a MineSkin account and paste its API address and key here (the manual shows where to find them). While either one is empty, /skin url and file: skins are refused and say why. Each server uses its own key: one key shared by every server would run out in an hour.

api-key""
visibilityUNLISTED

UNLISTED keeps your players' skins out of MineSkin's public gallery.

timeout"30s"
max-queue5

How many uploads may wait at once on this server.

allowed-hosts[ ]

Empty = any https address. Otherwise only these hosts (and their subdomains). Local and private addresses are always refused.

cache2 keys
name-refresh"3d"

A skin taken from a name is fetched again after this long: the owner of that account may have changed it.

keep-unused"30d"

Entries nobody wore for this long are thrown away.

cooldown"30s"

Between two changes of the same player (shadowessentials.skin.bypass-cooldown skips it).

apply-livetrue

Apply at once (Paper refreshes the player; an open window closes). false = from the next join. On Folia it is always from the next join.

join-wait"1s"

How long a join may wait for a skin not in the cache yet. After that the player enters, and the skin arrives a moment later.

blocked-names[ ]

Names whose skin cannot be copied: your staff, for instance.

modules/spawn.yml

Module: spawn
16 settings
plugins/ShadowEssentials/modules/spawn.yml
config-version1
enabledtrue
commands2 keys
spawn{ enabled: true, aliases: [ ] }
setspawn{ enabled: true, aliases: [ ] }
main{ }

Written automatically by /setspawn. You can also edit it by hand.

per-world2 keys
enabledfalse
worlds{ }

Written by /setspawn --world

first-join5 keys
teleporttrue

Teleport the player the first time they connect.

Goes to the point below when there is one, otherwise to the ordinary spawn. Turning it off does NOT turn off the message, the broadcast and the commands: those still run, they are separate things.

location{ }

The first-join point, written by /setfirstspawn. For when the first thing you want somebody to see is not the middle of the hub but the sign that explains the rules. Remove it, or use /setfirstspawn clear, to use the ordinary spawn.

message"<gradient:#8A2BE2:#00BFFF>Welcome, <player>!</gradient>"
broadcast"&8[&a+&8] &f<player> &7joined for the first time!"
commands[ ]

Commands run once, on the first join. <player> is replaced.

on-join1 key
teleportfalse

Teleport to spawn on every login.

respawn1 key
modeBED
SPAWN = always the plugin spawn
BED = bed or anchor when available, plugin spawn otherwise
VANILLA = leave it to the server
teleport2 keys
warmup"3s"
cooldown"5s"

modules/spawner.yml

Module: spawner
15 settings
plugins/ShadowEssentials/modules/spawner.yml
File notes

Italian texts (testi in italiano): esempi/it_IT/modules/spawner.yml - copy it over this file.

Picking spawners up, and deciding WHERE they may be picked up.

The second half is the one that matters. A server nearly always wants them collectable in some worlds and not others: letting a silk touch pickaxe empty the resource world and carry the spawners into a plot world is the shortest road to an economy that cannot be repaired afterwards.

config-version1
enabledtrue
commands1 key
spawner{ enabled: true, aliases: [ "spawnermob" ] }

Sharing the server with another spawner plugin

conflict1 key

ShadowSpawners, SilkSpawners and the like do this same job. Two plugins on the same break event means the spawner you place and the spawner you pick up are named by different plugins, and they do not match.

So when one of them is installed this module stands aside and lets it work. Set this to false to take over anyway - and expect the two to disagree.

auto-disabletrue

Where

worlds4 keys

Picking up and placing are two separate questions: wanting them collectable in survival only but placeable anywhere is perfectly ordinary.

pickup-everywherefalse

true = they can be picked up in any world and the list below is ignored. false = only in the worlds listed.

pickup[world]
place-everywheretrue
place[ ]

How

pickup5 keys
require-silk-touchtrue

Silk touch is required on the pickaxe in hand.

minimum-fortune0

Minimum fortune level. 0 to not ask for it.

chance1.0

Chance the spawner survives being broken. 1.0 = always. Below 1 it becomes a rare drop rather than a certainty.

creative-always-dropstrue

In creative it drops regardless, with no silk touch.

explosions-dropfalse

Explosions make it drop. Left off: on means collecting them with TNT and without a pickaxe at all.

The item

item2 keys

<mob> is the readable name, <type> the technical one. Colours with &.

name"&e&l<mob> Spawner"
lore
["&7Place it to make &f<mob> &7appear.", "&8<type>"]+1
Permissions:
  shadowessentials.spawner.pickup        picking them up
  shadowessentials.spawner.place         placing them
  shadowessentials.spawner.mob.<mob>     one particular mob
  shadowessentials.spawner.mob.*         all of them
  shadowessentials.command.spawner       /spawner

modules/tablist.yml

Module: tablist
17 settings
plugins/ShadowEssentials/modules/tablist.yml
File notes

Italian texts (testi in italiano): esempi/it_IT/modules/tablist.yml - copy it over this file. Player list header and side scoreboard. Lines are only redrawn when they actually change: a board of fixed lines costs nothing per tick.

config-version1
enabledtrue
commands1 key
scoreboard{ enabled: true, aliases: [ "sidebar" ] }

Player list (the TAB key)

Placeholders available: %player%, %world%, %ping%, %online%, %max_players%, %tps%, and every %shadowessentials_...%

tablist6 keys
enabledtrue
header
["<gradient:#8A2BE2:#00BFFF>&lSHADOW &fNETWORK</gradient>", "&7Online: &f%online%&8/&f%max_players%", ""]+2
name-format"<rank_prefix><white><name><rank_suffix>"

The name shown in the list. Besides the %...% placeholders, here <name>, <player>, <rank_prefix>, <rank_suffix> and <rank_group> work too. Leave exactly "<name>" to not touch the name at all.

nametagtrue

The rank above the head as well, using the scoreboard teams that are already needed for the sorting: it costs not one extra packet. Set it to false if another plugin handles nametags.

tablist.sorting1 key
enabledtrue

Sorts by rank weight, so staff and ranked players end up at the top. Uses the scoreboard teams, which is the only dependable way to do it without custom packets.

Side scoreboard

Every line is a component, not bare text: colours, gradients and placeholders work across the whole line, and two identical lines are no trouble (no fake spaces needed to tell them apart).

Keep reading

A board with "worlds" applies only in those worlds. Two names carry a meaning of their own:

default   applies wherever no other board does
skyblock  with no "worlds", applies in ShadowSkyBlock's island
          world whatever it is called: we ask it for the name.
          Without ShadowSkyBlock installed it never applies.

WHO OWNS THE SIDEBAR

Minecraft has one per player. Out of the box this plugin owns it, everywhere, islands included: on the islands it draws the "skyblock" board below, whose real figures - level, members, bank - it asks ShadowSkyBlock for. On the other side island_scoreboard.yml has "enabled: false", so the two never collide.

If you would rather have it the other way round - the island sidebar drawn by ShadowSkyBlock itself - set "yield-to-skyblock: true" here and "enabled: true" in its island_scoreboard.yml.

scoreboard5 keys
enabledtrue
update-interval"1s"
yield-to-skyblockfalse

true = in the island world the sidebar is drawn by ShadowSkyBlock and only the header, footer and TAB sorting are left to this plugin. False out of the box: this one draws it, with the "skyblock" board.

ignored-worlds[ ]

Worlds where this sidebar must not appear, for whatever reason (a lobby with its own GUI, a minigame). Header, footer and TAB sorting go on working.

scoreboard.boards2 keys
scoreboard.boards.default2 keys
title"<gradient:#8A2BE2:#00BFFF>&lSHADOW &fNETWORK</gradient>"
lines
["&7", "&f%player%", "&7Rank: &f%shadowessentials_vip_tier_name%", "&7Money: &a%shadowessentials_balance_formatted%", "&7", "&7Online: &f%online%&7/&f%max_players%", "&7Played: &f%shadowessentials_playtime%", "&7", "&7H …+7
scoreboard.boards.skyblock2 keys

The island board. The %island_...% placeholders come from ShadowSkyBlock, and a line containing one removes itself for anybody without an island - a visitor, somebody who just arrived - rather than showing them zeroes:

%island_name%    %island_owner%       %island_role%
%island_level%   %island_members%     %island_max_members%
%island_radius%  %island_bank%        %has_island%
title"<gradient:#8A2BE2:#00BFFF>&lSKYBLOCK</gradient>"
lines
["&7", "&f%player%", "&7Money: &a%shadowessentials_balance_formatted%", "&7", "&fIsland: &b%island_name%", "&7Owner: &f%island_owner%", "&7Role: &f%island_role%", "&7Level: &e%island_level%", "&7Members: &f%island_membe …+11

modules/teams.yml

Module: teams
9 settings
plugins/ShadowEssentials/modules/teams.yml
File notes

The teams players make for themselves: a group, some roles, and a chat of their own.

This is not a permission group and not a rank. It is the squad, the guild, the four friends who always build together.

The teams live in teams.yml, in the plugin folder. The plugin writes that file: you can read it and correct it, but normally there is no need to touch it.

config-version1
enabledtrue
commands2 keys
team{ enabled: true, aliases: [ "t", "party" ] }
teamchat{ enabled: true, aliases: [ "tc" ] }
max-size8

How many members at most. A VIP tier that defines teams.size-multiplier widens it for its holders.

name2 keys
min-length3
max-length16
invite-timeout"2m"

How long an invitation stays valid before it expires.

allow-tagstrue

Lets the owner give the team a short tag, shown next to the names of its members.

modules/teleport.yml

Module: teleport
40 settings
plugins/ShadowEssentials/modules/teleport.yml
File notes

Everything that moves a player: /tp, /tpa, /back, /rtp, /top. Homes, warps and spawn reuse the warmup/cooldown/safety logic here.

config-version1
enabledtrue
commands9 keys

Rename a command, add aliases, or switch it off entirely.

tp{ enabled: true, aliases: [ "teleport" ] }
tphere{ enabled: true, aliases: [ "s" ] }
tpa{ enabled: true, aliases: [ "call", "tpask" ] }
tpahere{ enabled: true, aliases: [ ] }
tpaccept{ enabled: true, aliases: [ "tpyes", "tpok" ] }
tpdeny{ enabled: true, aliases: [ "tpno" ] }
back{ enabled: true, aliases: [ ] }
rtp{ enabled: true, aliases: [ "wild", "randomtp" ] }
top{ enabled: true, aliases: [ ] }

Warmup: the wait before the teleport happens

warmup5 keys
duration"3s"
cancel-on-movetrue
cancel-on-damagetrue
move-tolerance0.6

Blocks of movement tolerated before the teleport is cancelled. Without this, the smallest mouse twitch cancels the teleport, which is why most servers end up disabling warmups entirely.

displayACTION_BAR

ACTION_BAR | BOSSBAR | TITLE | CHAT | NONE

cooldown1 key
duration"5s"
cost1 key
amount0

/tpa requests

requests2 keys
expire"60s"
max-pending5

/back

back3 keys
enabledtrue
history-size3

How many previous positions to remember: /back 1, /back 2, ...

on-deathtrue

/rtp - random teleport

Destinations are prepared in the background and validated before a player ever asks, so the command answers instantly instead of freezing the server while it looks for a safe spot.

rtp9 keys
rtp.cache2 keys
enabledtrue
size-per-world20
rtp.center2 keys
x0
z0
rtp
min-radius500
max-radius10000
min-y50
max-attempts20
cooldown"5m"
rtp.cost1 key
amount0
rtp
worlds[ ]

Empty list = every world is allowed.

Safety

Before a teleport lands, the destination is checked and, if needed, the closest safe spot is used instead.

safety6 keys
enabledtrue
search-radius5
require-solid-groundtrue
require-air-above2
on-failCANCEL

CANCEL = refuse the teleport | FORCE = go anyway

unsafe-blocks
[LAVA, FIRE, SOUL_FIRE, MAGMA_BLOCK, CACTUS, POWDER_SNOW, WITHER_ROSE, SWEET_BERRY_BUSH, CAMPFIRE]+6

modules/vip.yml

Module: vip
10 settings
plugins/ShadowEssentials/modules/vip.yml
File notes

GLOBAL VIP settings. Each tier is its own file in vips/<name>.yml

config-version1
enabledtrue
commands1 key
vip{ enabled: true, aliases: [ ] }
menu"vip"
check-interval"1m"

How often expiries are checked. The check runs against the database, so it also works for offline players and across several servers.

Perk resolution

A player can hold more than one tier at a time. These settings decide what happens when two tiers define the same perk.

perk-resolution3 keys
flagsANY_TRUE

ANY_TRUE | ALL_TRUE | HIGHEST_WEIGHT

valuesHIGHEST

HIGHEST | LOWEST | HIGHEST_WEIGHT | SUM

multipliersBEST
BEST = whichever is more favourable to the player
  (lowest for cost/cooldown perks, highest for gain perks)

MULTIPLY | HIGHEST_WEIGHT

What happens to "material" perks when a tier expires

For example a player with 15 homes whose base limit is 1.

KEEP   = the extra homes stay usable
LOCK   = they stay but cannot be used until the rank is renewed
REMOVE = they are deleted (not recommended)
overflow-policyLOCK

Wording of the perks

Every perk this plugin knows already has a translated line in the language files, under vip.perk. You only need this section to override one of them, or to name a perk invented by another plugin.

Keep reading

Available inside a line:

<value>    the number itself           7   1.25x
<percent>  the difference from normal, always positive   25%

Colours with &, as everywhere else.

perk-descriptions

Example, remove the # to use it: homes.limit: "&8 • &7Up to &f<value>&7 homes"

modules/voucher.yml

Module: voucher
7 settings
plugins/ShadowEssentials/modules/voucher.yml
File notes

Redeemable codes. A code runs a chain of actions, so it covers giveaways, store deliveries, event prizes and promotions without a line of code for each case.

config-version1
enabledtrue
commands2 keys
redeem{ enabled: true, aliases: [ "code" ] }
voucher{ enabled: true, aliases: [ ] }
generation2 keys
pattern"XXXX-XXXX-XXXX"

X is replaced with a random character.

charset"ABCDEFGHJKLMNPQRSTUVWXYZ23456789"

No 0/O and no 1/I/l: a code also has to be read out loud.

redeem1 key
cooldown"3s"

The wait between one attempt and the next, which makes guessing a code impractical.

Examples:
  /voucher create christmas money:give:5000;kit:give:bonus --uses 500 --per-player 1 --expires 30d
  /voucher create vipgold vip:give:gold:30d --uses 1
  /voucher bulk christmas 100       generates 100 single-use codes

modules/warps.yml

Module: warps
20 settings
plugins/ShadowEssentials/modules/warps.yml
File notes

System warps, created by staff. Documentation: docs/moduli/warps.md

config-version1
enabledtrue
commands4 keys
warp{ enabled: true, aliases: [ ] }
warps{ enabled: true, aliases: [ "warplist" ] }
setwarp{ enabled: true, aliases: [ "createwarp" ] }
delwarp{ enabled: true, aliases: [ "removewarp" ] }
permissions2 keys
per-warptrue

Require shadowessentials.warp.<name> for each warp.

show-lockedtrue

Show warps the player cannot use (greyed out) instead of hiding them. Showing what exists is usually better: it gives players a goal.

teleport3 keys
warmup"3s"
cooldown"10s"
teleport.cost1 key
amount0
categories3 keys

Categories are used to group warps in the GUI. A warp declares its own category when created: /setwarp <name> <category>

categories.main3 keys
display-name"&6Main"
iconNETHER_STAR
weight100
categories.shops3 keys
display-name"&aShops"
iconEMERALD
weight90
categories.events3 keys
display-name"&dEvents"
iconFIREWORK_ROCKET
weight80

modules/world.yml

Module: world
35 settings
plugins/ShadowEssentials/modules/world.yml
File notes

World management and the diagnostic commands.

Creates, loads, unloads, deletes and applies rules to worlds, so a server does not need a second plugin to have more than one:

/world create <name> <kind> [--seed <s>] [--no-structures]
/world delete <name>          asks twice, then the folder is gone
/world load <name> [<kind>]   for a folder copied in by hand
/world tp <name>

Kinds: normal, flat, large_biomes, amplified, void, nether, end

config-version1
enabledtrue
commands7 keys
world{ enabled: true, aliases: [ ] }
time{ enabled: true, aliases: [ ] }
weather{ enabled: true, aliases: [ ] }
killall{ enabled: true, aliases: [ "butcher" ] }
tps{ enabled: true, aliases: [ ] }
entitycount{ enabled: true, aliases: [ "entities" ] }
gc{ enabled: true, aliases: [ "memory", "mem" ] }

Managed worlds

worlds3 keys

Only the worlds listed here are touched. A world that is not listed keeps whatever settings the server itself gave it.

Keep reading

/world create writes its world here by itself, with the "kind" it was built as. That line is not decoration: the server remembers a world's blocks but not the generator that made them, so a void world reopened without it comes back full of stone.

kind:       normal | flat | large_biomes | amplified | void
            | nether | end     (leave it out for a world the server
            already knows, such as the ones in server.properties)
seed:       the seed it was made with, left out to let the server pick
structures: false to generate no villages, temples or strongholds
worlds.world10 keys
auto-loadtrue

Load this world at startup if the server has not loaded it already. Loading generates terrain, so it only ever happens at startup, never on a /se reload.

worlds.world.gamerules4 keys

Applied every time the world is loaded or the module reloads.

doDaylightCycletrue
keepInventoryfalse
mobGriefingtrue
announceAdvancementstrue
worlds.world
difficultyNORMAL
pvptrue
fixed-timenull

Freeze the clock on this tick. Setting it also turns off doDaylightCycle, otherwise the time would drift straight away. 0 = dawn, 6000 = noon, 13000 = night, 18000 = midnight.

fixed-weathernull

CLEAR | RAIN | THUNDER, or null to leave the weather alone.

spawn-monsterstrue
spawn-animalstrue
allow-flytrue

Flight in this world. A player who lands here while flying has it taken away unless they have shadowessentials.world.fly.bypass.

enter-messagenull

Shown when a player walks into this world. MiniMessage, <world> works.

worlds.world_nether3 keys
auto-loadtrue
allow-flytrue
worlds.world_nether.gamerules1 key
keepInventoryfalse
worlds.world_the_end2 keys
auto-loadtrue
allow-flytrue

killall

killall5 keys
protected
[PLAYER, ARMOR_STAND, ITEM_FRAME, GLOW_ITEM_FRAME, PAINTING, VILLAGER, ALLAY, END_CRYSTAL]+5

Never removed, whatever the command says.

skip-namedtrue

A named mob is somebody's pet project: leave it alone.

skip-tamedtrue
default-radius-1

-1 = the whole world. Any other number is a radius in blocks around the player who ran the command.

confirm-above200

Above this many entities the command asks for confirmation first, with the usual clickable buttons.

Diagnostics

diagnostics3 keys
detailed-tpstrue

/tps also reports MSPT, memory, chunks and entities.

tps-historytrue

Two days of TPS as a row of bars under /tps, one bar per half hour, hover for the time and the lowest value seen. Kept in data/tps-history.yml.

entity-warn-threshold200

/entitycount points out the worst chunks once one of them is above this many entities.

Languages

The texts the plugin shows to players, one file per language.

lang/

Texts and messages
2 files
plugins/ShadowEssentials/lang/
File notes

This file is the final fallback: any key missing from another language is looked up here, so a partial translation still works.

Format: MiniMessage, explained in the manual. Placeholders are written <like_this>.

To start a new language: /se lang export <locale>

Every message the plugin shows to players, one file per language. The keys are not listed one by one: here are the files, how many texts they hold and the placeholders they use.

FileLanguageTexts
lang/en_US.yml reference English (US) 1,681
lang/it_IT.yml Italiano 1,681

Most used placeholders

The plugin replaces them with the right value: leave them written as they are.

  • <prefix>
  • <player>
  • <id>
  • <count>
  • <name>
  • <world>
  • <value>
  • <time>
  • <state>
  • <file>
  • <kit>
  • <x>
  • <y>
  • <z>

Message groups

  • prefix 1
  • common 2
  • command 7
  • confirm 6
  • input 3
  • gui 14
  • lang 5
  • admin 179
  • economy 1
  • world 98
  • teleport 31
  • homes 21
  • warps 18
  • spawn 9
  • kits 55
  • vip 44
  • kitadmin 6
  • kiteditor 16
  • chat 25
  • inventory 8
  • afk 3
  • mail 15
  • moderation 80
  • reward 3
  • voucher 28
  • leaderboard 7
  • tablist 5
  • hologram 40
  • player 59
  • custom 2
  • sign 5
  • portal 108
  • motd 10
  • rules 10
  • teams 68
  • rules-book 3
  • spawner 12
  • particles 31
  • npc 47
  • item 10
  • armorstand 312
  • elevator 18
  • autotool 65
  • lock 145
  • skin 46

Other

Ready-made content, examples, imports: the files you copy and edit as a model.

data/particles.yml

Data written by the plugin
1 setting
plugins/ShadowEssentials/data/particles.yml
File notes

Which effect each player has chosen. THIS FILE IS WRITTEN BY THE PLUGIN: the settings live in modules/particles.yml.

config-version1

kits/

Kits, one per file
9 files
plugins/ShadowEssentials/kits/

9 files with the same structure. Below, the most commented one in full, as a model; the others are listed by name.

  • daily-basic.yml
  • daily-epic.yml
  • daily-magic.yml
  • daily-staff.yml
  • daily.yml
  • starter.yml
  • twitch.yml
  • youtuber-daily.yml
  • youtuber.yml

Example kits/starter.yml

File notes

One file per kit. Copy this file to create a new one: the file name is the kit id, so kits/pvp.yml becomes /kit pvp.

config-version1
enabledtrue
Presentation
display-name"&a&lStarter"
description"&7Il necessario per iniziare."
category"base"
iconWOODEN_SWORD
weight100

Higher weight = higher in the menu.

hide-when-lockedfalse

Hide the kit from the menu when the player lacks permission.

Who can claim it
permission"shadowessentials.kit.starter"
publictrue

true = no permission needed, the kit is open to everyone.

requirements4 keys
playtime"0m"
level0
vip-tiernull
worlds[ ]

Empty list = every world.

Cooldown
cooldown"once"

"once" = claimable a single time, ever.

cooldown-modeDURATION
DURATION = N hours after the last claim
DAILY    = resets at midnight (see modules/kits.yml -> timezone)

WEEKLY | MONTHLY

max-claims-1

-1 = unlimited claims

respect-vip-multipliertrue
cost1 key
amount0
full-inventoryQUEUE

What to do when the inventory is full: DROP | QUEUE | CANCEL

Contents
items
["STONE_SWORD 1", "STONE_PICKAXE 1", "STONE_AXE 1", "STONE_SHOVEL 1", "COOKED_BEEF 16", "TORCH 32", { material: LEATHER_CHESTPLATE, amount: 1, slot: 38, name: "&6Corazza del Novizio", lore: […], enchantments: {…}, color …+5

Short form: "MATERIAL amount" Long form: a block with name, lore, enchantments, slot, chance, ...

slot

38 = chest slot. Omit to use the first free inventory slot.

Extra rewards
rewards3 keys
experience0
rewards.money1 key

Requires an economy provider (ShadowEconomy or Vault).

default0
rewards
commands[ ]
Feedback
feedback5 keys
message"&aBenvenuto! Hai ricevuto il kit &f<kit>."
title"<gradient:#00FF87:#60EFFF>KIT RICEVUTO</gradient>"
subtitle"&7Starter"
feedback.sound3 keys
name"ENTITY_PLAYER_LEVELUP"
volume0.8
pitch1.2
feedback
broadcastnull

Announce to the whole server. null = no announcement.

vips/

VIP ranks, one per file
3 files
plugins/ShadowEssentials/vips/

3 files with the same structure. Below, the most commented one in full, as a model; the others are listed by name.

  • basic.yml
  • epic.yml
  • magic.yml

Example vips/basic.yml

File notes

Italian texts (testi in italiano): esempi/it_IT/vips/basic.yml - copy it over this file.

COLOURS: written with &, as in Minecraft.
  &6 oro  &c rosso  &7 grigio  &#ff8800 colore esatto  &r reset

Only gradients use the tag, because they cannot be done with &.

config-version1
enabledtrue
display-name"<gradient:#7FD8FF:#3BA7E0>BASIC</gradient>"
short-name"&b[BASIC]"
description
["&7The first step. What you need to be comfortable:", "&7more homes, less waiting, and flight at the spawn."]+1
iconIRON_INGOT
weight100
inheritsnull
next"magic"
permission"shadowessentials.vip.basic"
default-duration"30d"
grant1 key

What to run when the rank is given and taken away. Nothing by default: permissions are handled by your permission plugin, and these commands are the place where you tell it.

commands[ ]
revoke1 key
commands[ ]
perks3 keys
perks.flags3 keys
fly.enabledtrue
chat.colorstrue
kits.preview-lockedtrue
perks.values3 keys
homes.limit5
back.history2
warps.player-limit1
perks.multipliers9 keys
teleport.cooldown-multiplier0.75
teleport.warmup-multiplier0.5
kits.cooldown-multiplier0.9
economy.cost-multiplier0.95
economy.gain-multiplier1.1
shop.price-multiplier0.95
crate.luck-multiplier1.05
minion.speed-multiplier1.1
skyblock.island-size-multiplier1.1
on-grant3 keys
message"<gradient:#7FD8FF:#3BA7E0>You are BASIC now. Thank you for your support!</gradient>"
broadcast"&7Welcome &f<player> &7to the <gradient:#7FD8FF:#3BA7E0>BASIC</gradient> &7rank!"
commands[ ]
expiry2 keys
reminders[7d, 3d, 1d, 6h, 1h]
expiry.on-expire1 key
message"&7Your BASIC rank has expired. &fThank you for supporting us."

All the documentation