Configuration

⚙️ Configuration

Rivet separates global presentation, module switches, module settings and generated data. This keeps routine configuration changes away from player records.

Global effects

config.yml controls feedback shared by several commands:

effects:
  titles: true
  sounds: true
  particles: true

Turning one off removes that kind of feedback without changing the underlying command.

Module switches

modules.yml contains one Boolean per feature:

Switch	Controls
chat	Public chat, item links, /msg, /r, /me, ignore, social spy and chat colours
homes	Personal homes
warps	Public warps
graves	Graves, death locations and /back
breeders	Auto Breeder recipes, machines and tasks
egg-capture	Mob capture with thrown eggs
tree-feller	Tree felling and vein mining
mob-heads	Mob drops and /head
holograms	Persistent holograms
glow	Persistent coloured player outlines and rainbow animation
permissions	Rivet's built-in groups and direct grants
worlds	Test worlds, world spawns, crop protection, mob cleanup, biome search, /top and /tree
staff	Gamemode, teleport, vanish, flight, heal, feed, god, boss bars, toasts, notes and address checks
environment	Time and weather commands
inventory	Clear, give, condense, donate, hats, inventory access, repair, rename and lore
spawn	Rivet server spawn
tpa	Teleport requests
kits	Configured kits and cooldowns
afk	Manual and automatic AFK
join-leave	Join, first-join, quit and welcome content
announcements	Rotating broadcasts
nicknames	Persistent nicknames
statistics	/stats and /playtime output
trash	Disposable inventory
utilities	Portable vanilla interfaces, /jump, /ride, /list and /ping
poses	Sitting, laying and crawling
backpacks	Persistent personal storage
daily	Daily streak rewards
rtp	Safe random teleport
near	Nearby-player search
filter	Persistent pickup filters
help	Permission-aware command help

Disabled modules do not register listeners or start tasks. Their commands remain known to Paper but return a clear disabled-module message.

Important

Restart the server after changing modules.yml. /rivet reload reports module changes but does not start or stop modules mid-session.

Settings index

The table below covers every shipped settings file. Values shown are defaults.

File	Main options
afk.yml	automatic-after-minutes: 10, exclude-from-sleep: true, indicator switch/format and AFK/return messages
announcements.yml	interval-seconds: 300, skip-when-empty: true, optional sound name/volume/pitch and any number of named announcement entries
backpacks.yml	default-rows: 3, title, blocked-world list and overflow/blocked messages
breeders.yml	No tuning options yet; generated breeder state is kept in data/breeders.yml
chat.yml	Chat, /me and PM formats, allowed colour styles, social-spy format/messages and ignore messages
daily.yml	Claim/reset hours, reward cycling, reward days, milestones and messages
egg-capture.yml	No tuning options yet
environment.yml	No tuning options yet
filter.yml	Maximum size, blocked worlds, action-bar/sound feedback, GUI title and messages
glow.yml	Reference comments; player assignments and colours are generated in data/glow.yml
graves.yml	Death message, /back, ownership, expiry and tracking compass
holograms.yml	No global tuning options yet; properties are saved per hologram
homes.yml	No tuning options yet
help.yml	Help title, subtitle, navigation text and commands per page
inventory.yml	Item-editing limits, blocked materials and repair/rename/lore/hat messages
join-leave.yml	Join, first-join, leave, welcome title, welcome chat and MOTD sections
kits.yml	Kit definitions, equipment, cooldowns and messages
mob-heads.yml	Drop chance and player-head display name/lore
near.yml	Radius, result limit, spectator exclusion and result messages
nicknames.yml	Maximum visible length and set/remove/error messages
permissions.yml	Built-in group definitions and inheritance
poses.yml	Allowed worlds and enabled/disabled/error messages
rtp.yml	Allowed worlds, radii, attempts, cooldown, warm-up, movement, Nether ceiling, biome rules, world overrides and messages
spawn.yml	Delay, movement cancellation, join teleport rules and messages
staff.yml	God persistence, boss-bar and toast defaults, shared-address output and staff feedback messages
statistics.yml	/stats header and lines plus the /playtime format
tpa.yml	Expiry, cooldown, delay, movement cancellation and all request messages
trash.yml	Rows, title and warning
tree-feller.yml	No tuning options yet; safety caps are built in
utilities.yml	Interface switches, jump and ride ranges, player riding, list format and ping format
warps.yml	No tuning options yet
worlds.yml	Flat-world natural spawning, biome-search radius/steps and tree targeting range

Chat settings

format: "<gray><player>:</gray> <white><message></white>"
private-messages:
  sent: "<gray>[you → <player>]</gray> <white><message></white>"
  received: "<gray>[<player> → you]</gray> <white><message></white>"

chat-colors:
  allow-hex: true
  allow-gradients: true
  allow-rainbow: true

<player> and <message> are inserted as safe components. The social-spy format also supports <sender> and <recipient>.

Grave settings

back:
  teleport-delay-seconds: 3
  cooldown-seconds: 30
  cancel-on-move: true

ownership:
  owner-only: true
  allow-others-after-seconds: 0

expiry:
  seconds: 0
  drop-items: true

tracking-compass:
  enabled: true

Zero expiry keeps graves forever. Zero access delay means other players never gain access while owner-only is true.

Spawn and TPA settings

settings/spawn.yml:

teleport-delay-seconds: 3
cancel-on-move: true
join:
  teleport-every-join: false
  teleport-first-join: false

If both join switches are false, joining never changes the player's position. teleport-every-join takes precedence by simply matching every join.

settings/tpa.yml:

request-expiry-seconds: 60
cooldown-seconds: 30
teleport-delay-seconds: 3
cancel-on-move: true

All durations are clamped to zero or greater. Zero request expiry keeps a request until it is answered or a player logs out.

Random teleport settings

allowed-worlds:
  - world

minimum-radius: 500
maximum-radius: 5000
maximum-attempts: 24
cooldown-seconds: 300
warmup-seconds: 3
cancel-on-movement: true
nether-maximum-y: 120

biomes:
  allowlist: []
  denylist:
    - deep_frozen_ocean
    - frozen_ocean

worlds:
  world:
    minimum-radius: 500
    maximum-radius: 5000

World names are matched case-insensitively. Add Nether or End worlds explicitly. Biome keys can be short (plains) or namespaced (minecraft:plains). A denylist wins over the allowlist.

The radius is sampled by area, which avoids clustering destinations near the inner edge.

Filter settings

maximum-size: 50
blocked-worlds: []
feedback:
  action-bar: true
  sound: ""
gui:
  title: "<dark_green>Item Filter"

The sound is a namespaced registry key such as minecraft:block.note_block.bass. Leave it empty to disable it. rivet.filter.admin bypasses maximum-size.

Inventory editing settings

item-editing:
  maximum-name-length: 50
  maximum-lore-line-length: 100
  maximum-lore-lines: 10
  blocked-materials: []

Blocked materials use Bukkit enum names such as BEDROCK or COMMAND_BLOCK. Length checks use visible plain text and reject control characters.

Backpacks, near and poses

Backpack rows are clamped to 1–6. Blocked worlds are matched case-insensitively.

/near uses a minimum radius of 1 and a minimum result count of 1. Distances are rounded to whole blocks.

An empty allowed-worlds list in poses.yml permits every world. Otherwise names are exact apart from letter case.

Help and utility settings

settings/help.yml controls the title, subtitle, navigation labels and page size for /help. The page size is clamped from 3 to 10. <commands>, <page> and <pages> are available in the subtitle.

settings/utilities.yml contains these command-specific controls:

jump:
  maximum-range: 50
ride:
  maximum-range: 10
  allow-players: false

Both ranges are clamped from 1 to 200 blocks. The same file contains the /list and /ping message formats. Ping formats receive the player, milliseconds and quality label.

settings/worlds.yml sets tree.maximum-range, which defaults to 50 and is also clamped from 1 to 200.

Join, leave and MOTD

Each section in settings/join-leave.yml has its own enabled switch. <player> is available in every join, leave, title, chat and MOTD line.

Welcome-title timings are fixed at a short 250 ms fade-in, 1.5 second stay and 500 ms fade-out.

Announcements

Add entries under announcements: with any unique key:

announcements:
  rules:
    enabled: true
    message: "<yellow>Read the rules at <white>/rules</white>.</yellow>"
  store:
    enabled: false
    message: "<aqua>Visit our store.</aqua>"

Only enabled entries with a string message join the rotation.

Statistics placeholders

These placeholders are available in the header and lines:

Placeholder	Value
<player>	Account name
<playtime>	Formatted playtime
<deaths>	Death count
<player_kills>	Player kills
<mob_kills>	Mob kills
<jumps>	Jumps
<blocks_broken>	Sum of mined block statistics
<blocks_placed>	Sum of block use/place statistics
<distance>	Combined travel distance in kilometres
<since_first_join>	Time since the first recorded join

Message formatting

Most configurable messages use MiniMessage. Keep placeholders written exactly as shown in the default file. Values supplied by players, such as names and AFK reasons, are inserted without parsing, which prevents them from injecting formatting.

Useful MiniMessage examples:

<red>Error</red>
<gold><bold>Important</bold></gold>
<gradient:blue:aqua>Welcome!</gradient>

Reload behaviour

Run /rivet reload after editing settings. Rivet loads every file into a temporary configuration set first. Invalid YAML leaves the live set unchanged.

Generated data/*.yml files are not re-read or rewritten by /rivet reload.