P_Arvores v1.0

# P_Arvore

P_Arvore is a plugin for Paper servers that replaces normal tree growth with custom schematics. Instead of letting Minecraft generate the default tree, the plugin detects sapling growth and pastes a .schem structure defined by you.

The goal of the plugin is to allow custom trees with control over sapling type, biome, tree size, generation chance, random rotation, schematic offset, and blocked-area behavior.

## What the plugin does

The plugin intercepts tree growth caused by:

• natural sapling growth
• bonemeal use

When that happens, it:

• identifies which sapling caused the growth
• checks whether the world is allowed
• checks whether the biome is allowed
• checks the configured replacement chance
• chooses a compatible schematic
• validates whether the area can be used
• removes the original sapling
• pastes the custom tree in its place

If the area is blocked, the plugin can:

• let the vanilla tree grow normally
• cancel natural growth
• cancel bonemeal growth
• notify the player when the block happens with bonemeal

## Requirements

• Paper 1.21.3
• Java 21
• WorldEdit installed on the server

The plugin depends on WorldEdit to read and paste .schem files.

## Installation

1. Put WorldEdit in the server plugins folder.
2. Put P_Arvore in the server plugins folder.
3. Start the server once so the plugin can generate its data folder.
4. Open plugins/P_Arvore/.
5. Place your schematics inside plugins/P_Arvore/schematics/.
6. Adjust config.yml for the tree types you want to use.
7. Restart the server or use the plugin reload command.

## Basic usage flow

The normal plugin workflow is:

1. You create or export your trees as .schem files.
2. You place those files in the plugin schematic folder.
3. You enable the saplings you want to control in config.yml.
4. You tell the plugin which files belong to each sapling type.
5. You plant the saplings in the world.
6. When they grow, the plugin tries to replace the vanilla tree with your schematic.

## Schematics folder

All schematics must be stored inside plugins/P_Arvore/schematics/.

You can organize them in subfolders. A practical structure would be:

• schematics/oak/
• schematics/birch/
• schematics/jungle/

In the configuration, each entry points to the relative path inside that folder. If a schematic is missing, the plugin logs a warning in the console and does not load it into cache.

## How the plugin decides which tree to generate

For each growth attempt, the plugin follows this decision order:

### 1. World

If the world whitelist is enabled, the plugin only acts in the listed worlds. Outside them, growth continues without replacement.

### 2. Found sapling

The plugin searches for a configured sapling near the point where Paper reported the growth. If it cannot find an enabled sapling, no replacement happens.

### 3. Growth form

The plugin distinguishes between:

• single sapling
• 2x2 arrangement

Each sapling type can accept:

• any form
• single only
• 2x2 only

### 4. Biome

There are three biome filter levels:

• global plugin filter
• sapling rule filter
• individual schematic filter

The schematic can only be selected if it passes all active filters.

### 5. Chance

Each sapling can have a replacement chance. If the chance roll fails, the plugin does not generate a custom tree for that attempt.

### 6. Preferred size

The plugin tries to classify the growth as:

• SMALL
• LARGE

In general:

• 2x2 growth is treated as LARGE
• simple trees are usually treated as SMALL
• internal Paper tree types with names such as MEGA, TALL, or REDWOOD also push the preference to LARGE

### 7. Schematic selection

Among compatible schematics, the plugin selects one based on the configured weight.

If it cannot find a schematic for the preferred size, it tries to use a schematic marked as AUTO.

## Tree origin and positioning

The base point used to paste the schematic depends on the sapling layout:

• for single trees, the origin is the sapling itself
• for 2x2 trees, the origin is the north-west corner of the four-sapling square

This is important for aligning the schematic correctly.

If your tree is appearing in the wrong place, the adjustment is done with:

• offset-x
• offset-y
• offset-z

These offsets shift the paste location relative to the detected origin.

## Random rotation

Each schematic can have random rotation enabled or disabled.

When enabled, the plugin randomly chooses between:

• no rotation
• 90 degrees
• 180 degrees
• 270 degrees

This allows forests to look less repetitive even when reusing the same file.

## Area validation before pasting

The plugin can validate the entire schematic area before pasting.

When this validation is enabled, it scans the structure blocks and checks whether the world can be replaced at each target position. If any non-allowed block is found in the way, custom generation is blocked.

This validation uses separate lists for:

• replaceable materials in trunk regions
• replaceable materials in leaf regions

In practice, this prevents the schematic from destroying important map blocks.

## How blocked area handling works

If the schematic area is occupied by blocks that cannot be replaced, the plugin marks the attempt as blocked.

After that, it follows the configured policy:

• if fallback-to-vanilla-when-blocked is enabled, the plugin lets vanilla growth happen
• if that fallback is disabled, the plugin can cancel natural growth, bonemeal growth, or both

When the block happens with bonemeal, the plugin can notify the player with a configurable message.

## Whether air should be pasted

The ignore-air option controls whether air blocks from the schematic should be ignored during validation and paste.

In practice:

• enabled: the plugin does not try to paste air and does not use schematic air to clear the area
• disabled: the plugin treats schematic air as part of the structure

For most setups, keeping it enabled avoids clearing nearby blocks unintentionally.

## Sapling types included in the default configuration

The default configuration already includes sections for these materials:

• OAK_SAPLING
• SPRUCE_SAPLING
• BIRCH_SAPLING
• JUNGLE_SAPLING
• ACACIA_SAPLING
• DARK_OAK_SAPLING
• CHERRY_SAPLING
• MANGROVE_PROPAGULE

You can enable or disable each one individually.

## How to configure each sapling

Each sapling rule controls the full behavior for that tree type. The main fields are:

### enabled

Enables or disables that sapling rule.

### chance

Defines the chance for the custom tree to be used on that attempt. The value ranges from 0.0 to 1.0.

### growth-form

Controls which planting layout is accepted:

• ANY: accepts both single saplings and 2x2
• SINGLE: accepts only single saplings
• TWO_BY_TWO: accepts only 2x2

### biome-whitelist

If filled, the sapling only works in the listed biomes.

### biome-blacklist

If filled, the sapling stops working in the listed biomes.

### schematics

Generic schematic list. This group is useful to:

• keep compatibility with older configs
• use files marked as AUTO
• keep schematics that should work for more than one size

### schematic-groups.small

List of schematics meant for small trees.

### schematic-groups.large

List of schematics meant for large trees or 2x2 growth.

## How to configure each schematic

Each schematic entry supports these behaviors:

### file

Points to the .schem file inside plugins/P_Arvore/schematics/.

### weight

Defines the relative chance for that schematic to be chosen among compatible ones. Higher weight means higher frequency.

### offset-x, offset-y, offset-z

Adjust the paste point relative to the detected sapling origin.

### random-rotation

Enables or disables random rotation for that structure.

### size

Lets you mark the schematic as:

• SMALL
• LARGE
• AUTO

Use AUTO when the structure should work as a fallback for any size.

### biome-whitelist

If filled, that schematic can only be selected in the listed biomes.

### biome-blacklist

If filled, that schematic cannot be used in the listed biomes.

## Global world and biome rules

The plugin also has global filters, independent from each sapling rule:

### Worlds

In worlds, you can enable a global whitelist. When enabled, the plugin only tries to replace trees in the listed worlds.

### Biomes

In biomes, you can define:

• global biome whitelist
• global biome blacklist

These rules are applied before the final schematic selection.

## Replaceable materials

The replaceable-materials lists define what the schematic is allowed to overwrite during area validation.

The plugin uses two categories:

• trunk: used for trunk blocks and for blocks that are not recognized as leaves
• leaves: used for leaves

This allows leaves to replace light vegetation and air without allowing replacement of structural map blocks.

The default configuration already includes several lightweight materials, such as:

• air
• grass and small plants
• flowers
• snow
• vines
• some leaf types
• water

If a tree keeps failing to grow in places that should be valid, the adjustment is usually in these lists.

## Commands

The plugin has one main command:

• /parvore reload
• /parvore stats
• /parvore resetstats

### /parvore reload

Reloads the configuration, messages, and schematic cache without restarting the server.

### /parvore stats

Shows internal plugin usage statistics.

### /parvore resetstats

Resets the accumulated statistics since startup or since the last manual reset.

## Permission

Administrative permission:

- p_arvore.admin

By default, this permission is granted to server operators.

## What appears in /parvore stats

The statistics help diagnose whether the plugin is behaving as expected. The displayed counters are:

### Tentativas

Total number of growth events processed by the plugin.

### Custom geradas

Number of custom trees actually pasted.

### Bloqueadas

Attempts where the schematic area failed validation.

### Fallback vanilla

Cases where the area was blocked but the plugin allowed vanilla growth.

### Falha por chance

Attempts where the sapling passed the other checks but was not selected because of the chance roll.

### Bioma negado

Attempts blocked by biome filters.

### Mundo negado

Attempts blocked by world filters.

### Muda nao encontrada

Cases where the growth event happened but the plugin could not find an enabled sapling near the reported origin.

### Schematic ausente/incompativel

Cases where no loaded schematic was suitable for that growth.

### Tipos em cache

Number of sapling types with schematics loaded in memory.

### Schematics carregadas

Total number of schematic files loaded successfully.

### Geradas <SAPLING_TYPE>

Per-sapling counter for generated custom trees.

## Configurable messages

The messages are in the messages section of config.yml. You can change texts such as:

• plugin prefix
• no-permission message
• reload success message
• command usage message
• bonemeal blocked message
• statistics header
• statistics line format
• statistics reset confirmation

Important note: in the current version, the automatic blocked-growth message sent to players is the bonemeal one. The blocked-natural key exists in the configuration, but it is not automatically used by the current plugin flow.

## Practical organization example

A common way to work with the plugin is:

1. Keep one folder per tree species inside schematics.
2. Separate small and large schematics according to the visual result you want.
3. Use higher weights for the trees that should appear more often.
4. Use biome filters for trees that should only appear in certain environments.
5. Keep one or more AUTO schematics as fallback.
6. Test both natural growth and bonemeal growth.
7. Check /parvore stats to validate behavior.

## Best practices for building your schematics

• Align the schematic origin with the point where the trunk should start.
• Test small offsets instead of moving the full structure in your editor.
• Use random rotation only when the tree still looks correct from every side.
• For 2x2 trees, make sure the base was designed from the north-west corner of the four saplings.
• Review whether leaves and branches are entering blocks you do not want to mark as replaceable.
• If the structure contains internal air blocks and you do not want them to clear the area, keep ignore-air enabled.

## Troubleshooting

### The sapling grows as vanilla and does not become a schematic

Check:

• whether the sapling type is enabled
• whether at least one valid schematic is loading for it
• whether the file is in the correct folder
• whether the biome and world are allowed
• whether the chance is lower than expected
• whether the sapling layout matches growth-form

### Nothing happens when I use bonemeal

Check:

• whether the area is blocked by non-replaceable blocks
• whether the plugin is configured to cancel bonemeal growth when blocked
• whether the schematic is heavily misplaced because of wrong offsets

### The console says the schematic was not found

Check:

• file name
• .schem extension
• configured relative path
• whether the file is really inside plugins/P_Arvore/schematics/

### The tree appears in the wrong place

Review:

• the schematic origin
• x, y, and z offsets
• the difference between single sapling and 2x2

### The tree does not grow in tight locations

This usually means the area validation found blocks outside the replaceable-material lists. Adjust replaceable-materials carefully.

## Quick usage summary

To use the plugin properly:

1. Install WorldEdit and P_Arvore.
2. Place your .schem files in plugins/P_Arvore/schematics/.
3. Enable the desired saplings in config.yml.
4. Assign the correct schematics to each sapling.
5. Adjust biomes, chance, size, rotation, and offsets.
6. Reload the plugin.
7. Test sapling growth in game.
8. Use /parvore stats to validate the results.

## Current version

• Plugin: 1.2.0
• Target: Paper 1.21.3