Configuration

Everything lives in plugins/SnJoinItem/:

There is no messages.yml and no config-version key anywhere. data.yml is never seeded from the jar and never merged - it is player state, and touching it would hand the item back to everyone who had opted out.

Run /joinitem reload after editing config.yml, items.yml or the language file.

config.yml

The rest of this section explains the ones with consequences.

Delivery

delivery:
  give-on-join: true
  give-delay-ticks: 20
  restore-interval-ticks: 40
  worlds: []

give-on-join is read first by the single eligibility check that join, respawn and the restore sweep all share. Setting it to false therefore does more than its name suggests: the respawn re-give stops, and the restore sweep stops re-placing for every player. /joinitem give becomes the only way in, and an external /clear then removes the item permanently.

give-delay-ticks is not cosmetic. Lobby, login/auth and inventory-restore plugins populate or empty the inventory right after a player joins, and an item handed out inside the join event is wiped by whichever of them runs a moment later. If the item does not appear on join, raise this to 40 or 80.

restore-interval-ticks is what makes the item genuinely un-removable. The lock cancels player actions; it cannot see another plugin emptying the inventory, so this repeating sweep is what survives Essentials /ci, /clear and any plugin that writes to the inventory directly. It is also the retry that lets placement be skipped safely when an inventory is full. 0 disables both halves: no restore after a clear, and no second attempt for a player whose inventory was full.

The sweep re-places when the target slot has lost the item or when a copy exists anywhere else, which is how stray duplicates get cleaned up rather than accumulating as locked items the player cannot remove.

worlds gates giving only. A player who receives the item in lobby and walks into survival keeps it - the plugin never takes it away for being in the wrong world. Leave the list empty for every world.

Placement

placement:
  slot: 4

A full-inventory index, not a hotbar index:

Anything outside 0-40 falls back to 4 with a warning in the console.

The plugin never destroys what is already in that slot. An occupant is moved to the first free slot; if there is none the placement is skipped entirely and retried by the restore sweep once a slot frees. Note that the relocation target is always a normal inventory slot (0-35), so if you pin the item to an armour or off-hand slot whose occupant cannot be relocated, placement is skipped rather than the occupant being destroyed.

Command aliases

command:
  aliases: [jit]

The config list is authoritative for the dynamic aliases and is re-read by /joinitem reload, so an alias you add works without a restart. jit itself is also declared in the plugin's plugin.yml, so removing it from this list does not unregister /jit. An alias that collides with an existing command is skipped and reported in the console.

Language

Set lang: es and drop lang/messages_es.yml next to the English file. Keys missing from your language file fall back to the English value, with a console line naming the key.

The snlib.* block is SnLib's shared command contract (permission errors, usage, help layout). It is shipped so the whole fleet looks alike; restyle it freely.

There is deliberately no status: block. The only state SnJoinItem exposes is through the two placeholders below, which return the literal strings true and false.

Debug

debug:
  enabled: false
  level: DEBUG
  categories: []

SnJoinItem itself does not emit debug lines; what this switch surfaces is SnLib's own runtime detail, which is mostly useful for action lines that silently do nothing (a positional guard skipped for lack of a click surface, for example). There is no /joinitem debug subcommand, and unlike every other key on this page the debug block is read once at startup - /joinitem reload does not re-read it, so a change here needs a server restart.

items.yml

One section, join-item. The id is referenced from Java: do not rename it. This file is merged from the jar on every boot, so a renamed section is not replaced - the default join-item section is simply re-inserted alongside yours, and the plugin keeps using that one while silently ignoring your copy. Change the fields, not the id.

Appearance

Choose the material with the lock in mind. The plugin re-creates the item whenever it leaves its slot, so any material that can leave the inventory becomes a duplicator. Two classes to avoid: things the player spends (food, potions, buckets, ender pearls, snowballs, eggs, fireworks, discs, books) and things an entity takes from the hand (wheat and seeds for breeding, bone for taming, name tags, dye, lead, saddle). Item frames and armour stands are blocked by the plugin; other entity interactions are deliberately left alone so trading with a villager or clicking an NPC while holding the item still works.

custom-model-data is deliberately shipped commented out. SnLib gates on the key being present, not on its value, so custom-model-data: 0 stamps a real model data of 0 onto the item rather than meaning "none". Add the line when your pack needs it.

Lock

SnJoinItem closes what SnLib's lock does not reach: handing the item to an item frame or an armour stand, and the client resync that has to follow a cancelled creative-mode edit. Creative clicks themselves are already covered, because Bukkit routes them through the ordinary inventory-click event.

The lock applies to everyone holding the item, staff included. snjoinitem.bypass only controls whether a player receives it; it does not exempt anyone from the lock or from the click. To take the item off someone, use /joinitem disable <player>.

placeable: false only matters if you change material to a block, but it is left on deliberately: a placeable join item is re-created by the restore sweep after every placement.

Click actions

  right-click-actions:
    - "[player] menu"

  left-click-actions:
    - "[player] menu"

  cooldown: 4

One action per line, each starting with a prefix. The most used ones:

A line may also carry leading guards, such as [right-click], [shift-left-click], [chance=25] or [click=RIGHT,SHIFT_RIGHT], before its real prefix.

Optional keys, not shipped because they are off by default:

interact-requirements are placeholder comparisons: left OP right with >, <, >=, <=, =, == and !=, joined with && and || and groupable with parentheses. Lines in the list are joined with an implicit AND.

cooldown is in ticks, per player: 20 is one second. It is shared between the two click surfaces, so one cooldown covers both. 0 disables it and leaves the click completely unthrottled.

Declare both sides

The two sides never cross. A right click runs right-click-actions and a left click runs left-click-actions, and neither ever falls back to the other, in the world or inside an open inventory. Declare only one side and the opposite click does nothing at all, on both surfaces, with nothing logged.

Declare both right-click-actions and left-click-actions if both clicks have to act. Declaring them with different contents is fine and fully supported - each click then runs its own list on both surfaces.

Not every click reaches these lists either. Middle click, drop, number keys, off-hand swap and double click never fire on either surface, and the positional guards [click-air] and [click-block] never fire on an inventory click because there is no clicked block. A line guarded by one of those is skipped silently, with no console error.

PlaceholderAPI

Optional. When PlaceholderAPI is installed, placeholders resolve in the item name and lore, in the messages and inside the click actions, and this expansion is registered (a console line confirms it):

Both resolve by UUID, so they answer for offline players too, and both return the literal strings true and false.

The identifiers and their true/false output are a wire contract: other plugins' configs and scoreboard lines compare against them, so they are not renameable and not restyleable.

Automatic updates and backups

There is no config-version key. On every boot SnJoinItem compares each of its YML files against the copy bundled in the jar and inserts the keys you are missing, in place, with their comments. Your values, your comments, your ordering and any extra keys you added are all preserved - nothing is deleted, nothing is reformatted. You never have to reconfigure after an update.

Before writing a merge, the file on disk is copied next to itself as old-<name>-<yyyyMMdd-HHmmss>.yml, and the last three of those are kept. If a file is so broken it does not parse as YAML at all, it is moved aside to <name>.backup-N and regenerated from the jar rather than crashing the plugin, with a warning naming the backup.

update-configs: false freezes the merge: instead of inserting anything, the console reports how many keys are missing in each file. Two things stay outside the gate by design - config.yml itself, so the update-configs key can arrive through a merge in the first place, and SnLib's own snlib.* message block, which is the library's command contract rather than your content. data.yml is outside all of this: it is never seeded and never merged.

Every merge line in the console is prefixed [update-configs], so a search for that tag tells you exactly what happened to your files on the last boot.