treegen-ADR-003 - Java Plugin: Platform-Abstracted Runtime for Placing and Tracking Trees¶
Status: Accepted Date: 2026-06-11
Context¶
ADR-002 covered the offline Python tree-gen generator: how a tree is described
in JSON and how species map to biomes. That generator is an authoring/baking tool;
it does not run on a live server. The companion piece is the Java plugin that
runs inside the Minecraft server and is responsible for actually getting those
trees into the world, letting players plant them, and keeping the world's vanilla
trees out of the way.
The plugin must settle a different set of concerns from the generator:
- Where the trees come from at runtime. The same data-driven species JSON used by the Python tool must also be readable by the server so the plugin can either bake worldgen datapacks or place trees procedurally at runtime - without a second, divergent authoring format.
- Server portability. The project targets Paper/Folia first, but the core logic (species parsing, geometry, datapack writing, tree tracking) should not be tied to the Bukkit API so a Fabric/NeoForge port remains possible.
- Folia thread-safety. Modern Paper/Folia is regionised; block reads and writes must happen on the owning region thread, not on a global main thread.
- Datapack timing. Worldgen datapacks (and the vanilla-tree suppression they
carry) are only discovered by the server early in boot; writing them in the legacy
JavaPlugin#onLoad()was too late and needed an extra restart to take effect. - Closing the loop for players. Custom trees placed by worldgen or by a sapling must drop the correct species' sapling when their leaves break or decay, even where the biome alone is ambiguous.
Prior art / discussion: the configuration model and biome map are documented in
ADR-002 and docs/biome-trees.md; the growth mechanic that consumes the same baked
structures is ADR-001. This ADR records the runtime plugin that ties them together.
Decision¶
Structure the plugin as a platform-agnostic common core behind a Platform
service interface, with thin server-specific modules (paper, and stub
fabric/neoforge) implementing that interface.
Core (common) responsibilities, all free of any server API:
PlatformSPI. A single interface abstracts everything the core needs from the host: logging, world/root folders, biome lookup, single- and batched-block placement, structure placement, scheduling, messaging, per-chunk persistent data (getChunkData/setChunkData), and the structureDataVersion. Platforms that cannot persist chunk data inherit safe no-op defaults.TreeRegistry. Extracts the bundledspecies/*.json(and a defaultconfig.yml) into the data folder, then loads and parses every species intoTreeSpecies(trunk/canopy/branches/roots/decorators + procedural params), shared by both the generator-equivalent baking path and runtime placement.ProceduralGenerator. A Java reimplementation of the same shaping logic the Python tool uses (trunk shaping, canopy presets, branch system, decorators, Perlin noise), producing an in-memory voxelTreeModelthat is either placed live or baked to.nbtviaStructureNbtWriter.DatapackGenerator. Writes an Iris/jigsaw-style worldgen datapack: bakes variant structures, builds weightedtemplate_pools, normalises weights, and - when species opt intoreplace-vanilla- writes theplaced_featureoverrides that suppress the biome's vanilla trees.TreeGenConfig. Parsesconfig.yml(reusing RTP'sRtpYamlConfig) into a typed config with fourGenerationModes -DATAPACK(bake jigsaw pools),PROCEDURAL(place at runtime),BOTH, andNONE- plus helpers (needsDatapack,suppressionOnly,hasVanillaSuppression) that decide whether a full datapack, a suppression-only datapack, or no datapack is required.- Hybrid sapling-drop resolution.
TreeFarmStorerecords each placed tree as an axis-aligned region tagged with its species id, written into the per-chunk persistent data of every chunk it overlaps (so it survives restarts and a leaf lookup only inspects its own chunk).SaplingDropResolveris the biome-based fallback (match a broken leaf block to a species allowed in that biome).
Paper module responsibilities:
PaperBootstrapwrites datapacks in the bootstrap phase, before the server discovers datapacks, so both baked trees and vanilla suppression take effect on the same boot rather than after an extra restart. It generates for the main level folder always and for the legacy split_nether/_the_endfolders only when they exist (Folia single-folder vs. legacy Spigot layout).- Four event listeners, all Folia-safe via the
RegionScheduler: PaperSaplingListener- a tagged sapling item is planted: validate permission/biome, place a random baked variant, record the region.PaperChunkPlacementListener- inPROCEDURALmode, deterministic spacing/salt grid placement on new-chunk load, deferred ~40 ticks so neighbour chunks finish generating (avoids trees clipped square at chunk borders).PaperTreeSuppressionListener- cancels vanillaStructureGrowEventfor biomes where areplace-vanillaspecies is active and optionally replaces it with our tree (the runtime counterpart to the datapack suppression).PaperLeafDropListener- on leaf decay/break, drops the species sapling using the hybrid resolution (preciseTreeFarmStorefirst, biome fallback second).- Fabric/NeoForge are intentionally stubs. They implement
Platformwith no-op/placeholder behaviour to keep the abstraction honest and the port path open, without yet shipping a working mod.
Alternatives Considered¶
| Alternative | Why Rejected |
|---|---|
| Bukkit-coupled single module | No port path; geometry, parsing, and datapack writing would be locked to one server API. |
Write datapacks in onLoad() |
Runs after datapack discovery; trees/suppression needed an extra server restart to apply. |
| Datapack baking only (no runtime placement) | Loses live sapling planting, runtime vanilla replacement, and per-chunk procedural variety; PROCEDURAL/BOTH modes cover these. |
| Runtime procedural only (no datapack) | Worldgen integration and Iris/jigsaw pools want a real datapack; suppression of vanilla trees is cleanest as placed_feature overrides. |
| Biome-only sapling resolution | Ambiguous where several species share a biome/leaf; the precise per-region store disambiguates actual plantings. |
| Global main-thread block edits | Breaks on Folia's regionised threading; all edits are dispatched through the RegionScheduler. |
| Separate runtime authoring format | Duplicates the Python tool's schema; instead the same species/*.json feeds both. |
Consequences¶
- Positive:
- One species schema drives the Python tool, the Java baking path, and runtime placement - no divergent formats.
- The
PlatformSPI keeps all real logic server-agnostic and unit-testable, with a clear Fabric/NeoForge port path. - Bootstrap-phase datapack writing makes baked trees and vanilla suppression take effect on first boot.
- Folia-safe scheduling and per-chunk persistence make placement and tracking correct on modern regionised servers and across restarts.
- Hybrid sapling resolution drops the correct species even in shared biomes.
- Negative / Trade-offs:
ProceduralGeneratorduplicates the Python generator's shaping logic in Java; the two must be kept behaviourally in sync.- Fabric/NeoForge modules are non-functional stubs today.
- Per-chunk region records add persistent-data writes per placed tree (bounded, but non-zero) and grow with farmed forests.
- Reusing RTP's
RtpYamlConfigcouples config parsing to that library. - Vanilla-tree detection in the suppression listener is name-substring based and must be widened as new vanilla tree types appear.
References¶
common/src/main/java/net/leaf/treegen/common/Platform.java- the server SPI.common/src/main/java/net/leaf/treegen/common/TreeRegistry.java- species loading and parsing.common/src/main/java/net/leaf/treegen/common/ProceduralGenerator.java- runtime geometry (Java port of the Python shaping logic).common/src/main/java/net/leaf/treegen/common/DatapackGenerator.java- jigsaw pool and vanilla-suppression datapack writer.common/src/main/java/net/leaf/treegen/common/TreeGenConfig.java- config and generation modes.common/src/main/java/net/leaf/treegen/common/TreeFarmStore.java/SaplingDropResolver.java- hybrid sapling-drop resolution.paper/src/main/java/net/leaf/treegen/paper/PaperBootstrap.java- bootstrap-phase datapack generation.paper/src/main/java/net/leaf/treegen/paper/Paper*Listener.java- the four runtime listeners (sapling, chunk placement, suppression, leaf drop).- ADR-001 (tree growth) and ADR-002 (configuration and the Python generator) - the decisions this plugin runtime consumes.