PocketMine-MP/changelogs/5.8.md

# 5.8.0
Released 1st November 2023.

**Borked release, forgot to merge branches.**

# 5.8.1
Released 1st November 2023.

**For Minecraft: Bedrock Edition 1.20.40**

This is a minor feature release, including new gameplay features, various performance improvements to internal `World` and `Block` systems, and changes to the API.

**Plugin compatibility:** Plugins for previous 5.x versions will run unchanged on this release, unless they use internal APIs, reflection, or packages like the `pocketmine\network\mcpe`  or `pocketmine\data` namespace.
Do not update plugin minimum API versions unless you need new features added in this release.

**WARNING: If your plugin uses the `pocketmine\network\mcpe` namespace, you're not shielded by API change constraints.**
Consider using the `mcpe-protocol` directive in `plugin.yml` as a constraint if you're using packets directly.

## General
- Neighbour block updates now have a separate timer for timings. Previously, these were counted under `Scheduled Block Updates`, which was misleading.

## Performance
- `LightUpdate` now avoids attempting to propagate back in the same direction the light came from. This produces a small performance improvement of around 6% in light propagation.
- Improved worst-case (non-cached) performance of `World::getCollisionBlocks()` (and its successor `World::getBlockCollisionBlocks()`).
  - While 5.5.0 introduced caching at the `World` level for AABBs, the cache was rarely useful due to entity and player movement being too unpredictable. This meant that most users saw a performance degradation with lots of moving entities, except in specific situations.
  - Performance for fetching non-cached AABBs for a cell is now improved by 2x. Overall performance benefit to a server depends on the number of entities and players.
- Added cache for hydrated farmland blocks to remember the last known location of nearby water.
  - If nearby water sources are not changed, this cache allows hydrated farmland to completely avoid checking up to 161 nearby blocks for water after the first check.
  - Tests with large wheat farms showed a 25% performance improvement in overall server performance compared to previous 5.x versions.
- Migrated various internal enums to native PHP 8.1 enums. Bypassing magic `__callStatic()` accessors improved performance in many areas, although it's hard to quantify the exact benefit.
- Made use of `Facing::OFFSET` constant in various places to avoid unnecessary `Vector3` and `Position` object allocations. Many pathways benefit from this, including neighbour block updates (due to faster `Block::getSide()` and less useless objects).
- Avoided clearing block AABB caches except when strictly necessary. Previously, the cache was wiped every time blocks were read from the world, making them mostly useless.
- Avoided random updates on blocks which have reached their final state, such as fully-grown crops. This produces a minimal performance improvement.
- Removed useless checks in some `World` hot paths.

## API
### General
- All enums have been migrated to native PHP 8.1 enums.
  - For now, the old APIs and accessors are still usable (via `LegacyEnumShimTrait`), but these will be removed in the next major release.
  - `EnumTrait` has been deprecated, and will be removed in the next major release.
  - Migration for most plugin developers will simply involve deleting `()` from the end of enum case usages, which is a trivial change and also improves performance.
  - Plugin usages of `EnumTrait` are encouraged to move to native enums, optionally using `LegacyEnumShimTrait` to provide backwards compatibility.
    - See [this code](https://github.com/pmmp/PocketMine-MP/blob/9832fe899f13a8ea47cc9d73de7088f7775a12f5/src/block/utils/DyeColor.php#L85-L107) for an example of how to associate properties with enum cases (since native enums don't support this directly).
  - Thanks to improvements in `RuntimeDataDescriber`, any native enum can now be used as a custom block's state property.

### `pocketmine\block`
- The following classes have been added:
  - `utils\AgeableTrait` - used by blocks which have an age property, such as crops
  - `utils\StaticSupportTrait` - used by blocks which have the same support requirements regardless of their state, such as crops

### `pocketmine\data\runtime`
- The following API methods have been added:
  - `public RuntimeDataDescriber->boundedIntAuto(int $min, int $max, int &$value) : void` - similar to `boundedInt()`, but automatically calculates the needed number of bits based on the given min/max
  - `public RuntimeDataDescriber->enum(T extends \UnitEnum &$case) : void` - describes any native PHP 8.1 enum case
  - `public RuntimeDataDescriber->enumSet(array<int, T extends \UnitEnum> &$set, array<int, T extends \UnitEnum> $allCases) : void` - describes a set of enum cases (similar to bitflags)
- The following API methods have been deprecated:
  - `RuntimeDataDescriber->bellAttachmentType()` - use `enum()` instead
  - `RuntimeDataDescriber->boundedInt()` - use `boundedIntAuto()` instead
  - `RuntimeDataDescriber->brewingStandSlots()` - use `enumSet()` instead
  - `RuntimeDataDescriber->copperOxidation()` - use `enum()` instead
  - `RuntimeDataDescriber->coralType()` - use `enum()` instead
  - `RuntimeDataDescriber->dirtType()` - use `enum()` instead
  - `RuntimeDataDescriber->dripleafState()` - use `enum()` instead
  - `RuntimeDataDescriber->dyeColor()` - use `enum()` instead
  - `RuntimeDataDescriber->froglightType()` - use `enum()` instead
  - `RuntimeDataDescriber->leverFacing()` - use `enum()` instead
  - `RuntimeDataDescriber->medicineType()` - use `enum()` instead
  - `RuntimeDataDescriber->mobHeadType()` - use `enum()` instead
  - `RuntimeDataDescriber->mushroomBlockType()` - use `enum()` instead
  - `RuntimeDataDescriber->potionType()` - use `enum()` instead
  - `RuntimeDataDescriber->slabType()` - use `enum()` instead
  - `RuntimeDataDescriber->suspiciousStewType()` - use `enum()` instead

### `pocketmine\player`
- `TitleID` is now included in `PlayerInfo` metadata for plugin consumption.

### `pocketmine\world`
- The following API methods have been added:
  - `public World->getBlockCollisionBoxes(AxisAlignedBB $bb) : list<AxisAlignedBB>` - similar to `getCollisionBoxes` but exclusively for blocks, avoiding the need for conditionally useless parameters
- The following API methods have been deprecated:
  - `World->getCollisionBoxes()` - use `getBlockCollisionBoxes()` instead (alongside `getCollidingEntities()` if entity collision boxes are also required)

### `pocketmine\utils`
- The following classes have been deprecated:
  - `EnumTrait` - use native PHP 8.1 enums instead
- The following classes have been added:
  - `LegacyEnumShimTrait` - can be `use`d by native PHP 8.1 enums to provide the same API as `EnumTrait`

## Gameplay
### Blocks
- Implemented the following blocks:
  - Amethyst
  - Amethyst Cluster
  - Chiseled Bookshelf
  - Crimson Roots
  - Pitcher Crop
  - Pitcher Plant
  - Torchflower
  - Torchflower Crop
  - Warped Roots

### Items
- Implemented the following items:
  - Pitcher Pod
  - Torchflower Seeds

## Internals
- `Farmland` block now has an extra property (`waterPositionIndex`) stored in its blockstate ID to track the position of nearby water. This property is not saved to disk, and is only used for caching.
- The format of internal blockstate ID has been updated.
  - The lower `11` bits are now reserved for state data (previously `8` bits). This increase facilitates the new cache for `Farmland` blocks.
  - The state data bits are now XOR'd with the `xxh3` of the block's type ID, instead of being directly XOR'd with the type ID.
    - This XOR improves the distribution of the lower bits of the blockstate ID, which is important for hashtable indexing to minimize collisions.
    - Previously, the lower bits were XOR'd with the type ID directly, but the effectiveness of this reduced as more state data bits were added.
    - `xxh3` produces consistently good results for this purpose regardless of the number of state data bits allocated.
    - Hash collisions with blockstate IDs are reduced by 50% with this change, which is a happy side effect.
  - This is backwards-incompatible, so anyone saving internal blockstate IDs on disk or in a DB will be burned by this change (though they shouldn't have been doing that anyway).
- Removed code generation step for `RuntimeDataDescriber` enum serialization. All described enums now use PHP 8.1 native enums, which can be described without codegen using `RuntimeDataDescriber->enum()`.
- Added `DeprecatedLegacyEnumAccessRule` custom PHPStan rule to flag legacy `EnumTrait` case accessors.
- Cleaned up remaining hardcoded `Config` keys in `SetupWizard`. These usages now use auto-generated constants like the rest of the codebase.

# 5.8.2
Released 9th November 2023.

## Performance
- Improved performance of small packet zero-compression (unintended use of slow zlib compressor instead of fast libdeflate one).
  - This affected the majority of outbound packets, as most packets are below the 256-byte threshold for compression.
  - This faster method is over 20x faster than the old method, producing noticeable performance gains for large servers.

## Fixes
- Fixed melons and pumpkins not growing.
- Fixed melon and pumpkin stems not attaching to the grown melon/pumpkin.
- Fixed iron and gold ores not being affected by the Fortune enchantment.
- Fixed ancient debris burning in lava.
- Fixed sign (front) text loading from vanilla world saves (back text is not yet supported).

## Internals
- Removed bogus optimization from `tools/generate-blockstate-upgrade-schema.php` that could cause incorrect `remappedStates` generation when some of the states stayed under the old ID.
- Fixed possible crash in `BlockStateUpgrader` name flattening rule handling with invalid blockstate NBT data.