Home

UnderwaterTrees lets players plant saplings underwater and helps them grow there, on Paper 26.3.x servers. This page is the complete guide for server admins: installation, upgrading from 1.x, every setting, commands and permissions, and troubleshooting. To build UnderwaterTrees from source or contribute, see the Developer Guide.

1. Requirements Checklist

• Paper server (or fork) on 26.3.x (any 26.3 hotfix release). Spigot/vanilla are unsupported; other Minecraft versions log an "unsupported server version" warning and run at your own risk.
• Java 25 runtime.
• Ability to upload plugins and execute commands in console or in-game (recommended: operator permissions or LuckPerms).

2. Installation Flow

1. Download the latest underwatertrees-paper-<version>.jar from Modrinth or Hangar.
2. Drop the JAR into plugins/.
3. Start the server once. UnderwaterTrees creates:
   • plugins/UnderwaterTrees/config.yml
   • plugins/UnderwaterTrees/lang/ with all 14 bundled language files (the one set in language is active)
4. Edit config.yml (saplings, soils, chat prefix, watcher settings).
5. Run /underwatertrees reload after any edits to apply the changes instantly (console or with permission underwatertrees.admin).

Upgrading from 1.x

UnderwaterTrees 2.0.0 requires Paper/Minecraft 26.3 and Java 25 (1.x ran on 26.2). The upgrade itself is automatic:

1. Stop the server, replace the old jar with underwatertrees-paper-2.0.0.jar, and start the server.
2. On the first start, UnderwaterTrees recognizes the 1.x files, moves the complete old content of plugins/UnderwaterTrees/ to plugins/UnderwaterTrees/backup-1.x/, and creates a fresh config.yml and lang/ folder with the current comments.
3. Every setting you had changed from the 1.x default is carried over under its new name (for example update-check.sources becomes update_check.provider). Settings you never changed get the new defaults; for instance growth_light_override.minimum_level becomes 0, so saplings grow on the deep-sea floor too.
4. The console reports the backup folder, every carried-over setting, settings that no longer exist, and language files you had edited (your version stays in the backup; copy your changes over if you still need them). Files that still hold the defaults of any earlier 1.x version count as unedited and aren't listed. New default entries in the soils/saplings lists (such as POPLAR_SAPLING and PALE_OAK_SAPLING) are already part of the fresh config.yml.
5. Coming from 1.0 or 1.0.1: your files are moved to the same backup folder and fresh files are created, but no settings are carried over, because 1.0.x used a different format. The console says so and lists the files you had edited; re-apply your changes from the backup. If 1.1 or 1.2 later ran on the same files, the upgrade works as in step 3: the settings those versions used are carried over (including a 1.0.x default such as MANGROVE_PROPAGULE: true that stayed active), and the 1.0.x settings they no longer read (e.g. auto-reload or update-check: false) are skipped.
6. Going back to 1.2.x for a while: 1.2.x doesn't read the renamed settings and uses its own defaults for them meanwhile (soils and saplings keep their names and stay in use). It writes its old setting names with their 1.x defaults back into config.yml, so the next 2.0 start runs the upgrade again (new backup folder backup-1.x-2). Your 2.0 values are carried over and win over changes you made under 1.2.x, but entries you had deleted from soils or saplings (e.g. MUD) come back, because 1.2.x added them again.

What behaves differently in 2.0.0:

• Underwater planting respects the server's spawn protection and adventure mode, and fires a normal BlockPlaceEvent, so protection plugins can deny it.
• The new permission underwatertrees.place (granted to everyone by default) controls underwater planting.
• Saplings on land no longer hold back flowing water, and no sapling holds back lava.
• Saplings that end up underwater later (flooded, or planted while the override was off) now get growth help too.
• /underwatertrees is visible to every player (it lists the subcommands they may use), and the new /underwatertrees version shows the plugin version.
• Every reload lists the settings and language files that changed since the last load.

3. Core Configuration

All options live in plugins/UnderwaterTrees/config.yml. New default keys are merged automatically whenever the plugin reloads, so you only maintain the values you change.

If config.yml isn't valid YAML (e.g. a wrong indentation or a missing quote), UnderwaterTrees doesn't apply it and leaves the file exactly as it is; the console names the line and column of the error. On a reload (command or watcher), the previous settings stay active, and /underwatertrees reload answers with the error instead of "Configuration reloaded". At startup, UnderwaterTrees runs with the default settings instead, but keeps bStats and update checks off. Once the file is fixed, the next reload applies everything as usual.

If config.yml is deleted or emptied while the server runs (a file with only comments counts as empty), the watcher doesn't reload: the current settings stay active, and the console warns once. /underwatertrees reload or a restart then creates a fresh config.yml, or fills the empty one with the default settings. If the file comes back with its old content, nothing is reloaded.

Key naming: settings and language keys use snake_case (e.g. chat_prefix_label), like Minecraft's own names. If you copy an old 1.x config.yml back from backup-1.x/, the next restart runs that upgrade again (new backup folder backup-1.x-2, your changed values carried over); /underwatertrees reload instead renames old keys (e.g. chat-prefix-label) in place, keeping comments and formatting. Settings added by an update are inserted into your config.yml at their proper place with their comment, and a console line lists them.

General Section

Key	Default	Purpose
language	en_US	Locale file inside lang/. Missing keys are added from the bundled file of that language (English for a language without a bundled translation); invalid codes load en_US.
chat_prefix_label	UwTrees	Text rendered inside <prefix_label> placeholder.
startup_banner_enabled	true	Shows the MiniMessage banner on enable.
config_watch_enabled	true	Keeps the async watcher on config.yml running; a detected edit triggers a full reload. Edits to lang/ files need /underwatertrees reload.
config_watch_interval_seconds	5	Poll interval (minimum 1 second).
update_check.enabled	true	Contacts Modrinth/Hangar for updates.
update_check.provider	0	0 = Modrinth + Hangar, 1 = Modrinth only, 2 = Hangar only.
update_check.interval_hours	24	Poll interval (minimum 1 hour).
update_check.include_prereleases	false	Whether beta/alpha builds qualify as latest.
update_check.filter_by_server_version	true	Only report builds made for the server's Minecraft version; builds without version info count only if none matches.
update_check.notify_console / update_check.notify_op_join	true	Console summary and join hints for ops or players with underwatertrees.update.notify; with notify_console off, the join hint doesn't point to the server log. An unreachable Modrinth or Hangar logs one warning with the reason, then stays quiet until it answers again or the plugin reloads.
update_check.notify_console_always_shown	false	When true, also logs the provider summary once after each start/reload if no update exists.
log_stats	true	Logs a multi-line summary of the loaded configuration (soil/sapling counts, flags) on startup and reload.
log_detail	false	Additionally lists every enabled soil and sapling individually.
metrics_enabled	true	Toggle for bStats telemetry; the global opt-out in plugins/bStats/config.yml also applies.

Placement & Protection

Key	Default	Notes
require_water_above	false	When true, placement needs plain water (not a bubble column) in the target space, and physics protection only holds while water sits directly above the sapling.
protect_underwater_saplings	true	Keeps flowing water from washing away saplings that sit underwater (water directly above) on an allowed soil, and cancels physics breaks there. Lava and saplings on land behave as in vanilla.
growth_light_override.enabled	true	Lets saplings grow in light too low for vanilla (level 9) (applies to saplings on an allowed soil with water directly above).
growth_light_override.minimum_level	0	Light level threshold (0–15); 0 means saplings grow at any depth. Invalid values fall back to 9 (vanilla).
growth_light_override.attempt_period_seconds	60	Interval between growth scans (minimum 1). Raise this to slow the pacing toward vanilla.
growth_light_override.attempt_chance	0.25	Chance per scan (0–1) that each tracked sapling attempts to grow. Lower values ≈ fewer tries per minute; out-of-range values fall back to 0.25.

Light under water: sky light drops by one level per block of water, so from about 15 blocks deep it is completely dark (light 0). With the default minimum_level: 0, saplings still get growth attempts there, on the deep-sea floor too. Raise the value to keep dark spots from growing, e.g. 1 for everything but pitch-dark water. After an upgrade from 1.x you get 0 too, unless you had changed the 1.x default (1) yourself.

How underwater placement works: right-click the top face of an allowed soil block with an allowed sapling while the space above it is water (or a bubble column). Either hand works; like in vanilla, the off hand is only used when the main hand holds no block. The player needs underwatertrees.place (granted to everyone by default), and a BlockPlaceEvent is fired so protection plugins (WorldGuard, GriefPrevention, …) can cancel it in protected regions. The server's own spawn-protection radius applies as well (non-ops can't plant there), and players in adventure mode can't plant underwater at all. Placement that isn't into water is left entirely to vanilla.

Materials

soils:
  DIRT: true
  MUD: true
  SAND: false
saplings:
  OAK_SAPLING: true
  MANGROVE_PROPAGULE: false # already water-placeable in vanilla

• Boolean maps accept Bukkit Material names. Unknown entries are ignored (with a console warning).
• Deleting an entry from soils or saplings is permanent: updates don't put it back. Only entries that are new in a later version are added once, with their default. UnderwaterTrees remembers which defaults it has already offered in plugins/UnderwaterTrees/.seen-defaults.yml; don't edit that file.
• If soils or saplings is missing, empty, or has no enabled entry, that section alone falls back to built-in defaults: the seven default-enabled soils (DIRT … MUD), or the nine default-enabled saplings (MANGROVE_PROPAGULE stays off, as in the default config).

4. Localization

• Locale files live in plugins/UnderwaterTrees/lang/<locale>.yml and use MiniMessage formatting.
• <prefix> and <prefix_label> are injected automatically, along with placeholders such as <label>, <subcommands>, <code>, <current>, <current_ver>, <latest_ver>, <provider>, <version>, <url>, <error>, <file>, <changes>, <key>, <value>. Keep the placeholders of a message when you edit its text; others stay literal.
• Console output (update-check summaries, the "config reloaded externally" notice, the startup stats block) is translated too, using the same locale.
• Bundled locales: en_US, de_DE, ar_SA, es_ES, fr_FR, it_IT, ja_JP, ko_KR, nl_NL, pl_PL, pt_PT, tr_TR, uk_UA, zh_CN.
• /underwatertrees reload refreshes both config and language changes; missing keys are added from the bundled file of the same language.

Color Names 🎨

MiniMessage knows exactly these 16 named colors (plus the spellings grey and dark_grey). Any other name, e.g. <light_red>, is not a color and shows up as literal text in chat.

Tag	Hex	Legacy code
<black>	#000000	§0
<dark_blue>	#0000AA	§1
<dark_green>	#00AA00	§2
<dark_aqua>	#00AAAA	§3
<dark_red>	#AA0000	§4
<dark_purple>	#AA00AA	§5
<gold>	#FFAA00	§6
<gray>	#AAAAAA	§7
<dark_gray>	#555555	§8
<blue>	#5555FF	§9
<green>	#55FF55	§a
<aqua>	#55FFFF	§b
<red>	#FF5555	§c
<light_purple>	#FF55FF	§d
<yellow>	#FFFF55	§e
<white>	#FFFFFF	§f

• <red> is the bright red (often called "light red"); <dark_red> is the darker one.
• Any other shade works as a hex color: <#FF8800>text</#FF8800> or <color:#FF8800>text</color>.
• Formatting tags such as <bold>, <italic>, <underlined>, <gradient:…> and <rainbow> are described in the MiniMessage format reference.

5. Commands & Permissions

Command	Permission	Default	Description
/underwatertrees reload	underwatertrees.admin	op	Reloads config, watchers, locales, and logs active materials and the files that changed since the last load.
/underwatertrees version	none	–	Shows the current plugin version (console + player).
(underwater planting)	underwatertrees.place	true	Plant allowed saplings into water. Negate it to disable underwater planting for specific players or groups.
(join notification)	underwatertrees.update.notify	op	Receive chat reminders when updates are available.

Every player can run /underwatertrees; without a subcommand it lists the subcommands that player may use. Running reload without underwatertrees.admin shows a "no permission" message.

Use LuckPerms (or equivalent) to delegate without giving full operator access.

6. Troubleshooting & FAQ

Symptom	Resolution
Saplings still break underwater	Ensure protect_underwater_saplings is true, soil entry is enabled, and water/conditions remain valid.
Players can't plant underwater	Check underwatertrees.place, that the target space is water on top of an enabled soil, whether a protection plugin blocks building there, whether the spot is inside spawn-protection, and that the player isn't in adventure mode.
"No permission" on reload	Grant underwatertrees.admin (or use LuckPerms to assign). Confirm the plugin enabled successfully on boot.
Config changes ignored	Run /underwatertrees reload or wait for the watcher interval; if the console reports that config.yml isn't valid YAML, fix the line it names (until then the previous settings stay active).
Update reminders missing	Check update_check.enabled, update_check.notify_*, and ensure the server can reach Modrinth/Hangar.
Metrics log warnings	Set metrics_enabled: false or fix global bStats configuration.

• Can players plant custom saplings underwater? Only saplings that exist in Minecraft itself: every saplings entry must be a Minecraft material name (e.g. CHERRY_SAPLING). Custom items from other plugins (e.g. ItemsAdder or Oraxen) aren't supported. Unknown names are skipped with a console warning.
• Does the plugin support different settings per world? Not natively. Combine with a region/flag plugin or separate server profile if you need diverging rules.
• Will light override cause TPS issues? No. Sapling positions are cached in each chunk's own data and only re-read (not re-scanned) on load or reload. The one exception is the very first time an existing chunk loads after installing/upgrading: it's scanned once, off the main thread and only a few chunks per tick, and cached from then on. Newly generated chunks (exploring, pre-generation) are never scanned, since nobody can have planted anything there yet. Each growth scan also handles at most 64 tracked saplings and continues with the next ones on the following scan, so every sapling gets its turn.
• Does a sapling count if it gets flooded later? Yes. Saplings on an allowed soil are remembered even on dry land and while the light override is off. Once water covers one (bucket or flowing water), it starts getting growth attempts; if it's drained (e.g. with sponges), it pauses and resumes when flooded again. Water added without a game event (commands, WorldEdit) is picked up the next time the chunk loads or the config is reloaded.
• Do dark oaks and pale oaks grow underwater? Yes: plant four saplings in a 2x2 square, as on land. Vanilla can't grow their trunk through water, so UnderwaterTrees drains the trunk cells for the moment the tree grows and refills them right after, in the same tick; leaves that end up in the water are waterlogged. This covers every kind of growth (bone meal, dispensers, natural growth and the light override). The tree grown this way is reported as normal tree growth before any block is set, with the player who used the bone meal, so protection plugins (WorldGuard, GriefPrevention, …) can forbid or trim it and block loggers such as CoreProtect record it. If a protection plugin forbids it, nothing changes: the saplings and the water stay, and the bone meal isn't used up.
• How do I audit what changed after reload? Every reload logs the changed settings of config.yml and the changed language files ("Detected file changes"), or "No configuration changes detected". Enable log_stats/log_detail to also print counts and explicit lists of active saplings/soils.
• Can I run without the watcher? Yes. Set config_watch_enabled to false if you prefer manual reloads. Just remember to run /underwatertrees reload after every edit.
• What happens if bStats is disabled globally? UnderwaterTrees respects the global plugins/bStats/config.yml opt-out and simply skips initializing metrics; no separate log line is printed for it.