PocketMine-MP/changelogs/5.5-beta.md

# 5.5.0-BETA1
Released 23rd August 2023.

**For Minecraft: Bedrock Edition 1.20.10**

This is a minor feature release, including performance improvements, new API methods, and new gameplay features.

**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.

## Dependencies
- Updated `pocketmine/math` dependency to [`1.0.0`](https://github.com/pmmp/Math/releases/tag/1.0.0).
- Updated `pocketmine/nbt` dependency to [`1.0.0`](https://github.com/pmmp/NBT/releases/tag/1.0.0).

## Performance
- Some events are now no longer fired if no handlers are registered.
  - This improves performance by avoiding unnecessary object allocations and function calls.
  - Events such as `DataPacketReceiveEvent`, `DataPacketSendEvent` and `PlayerMoveEvent` are optimized away almost completely by this change, offering some much-needed performance gains.
- Significantly improved performance of small moving entities, such as dropped items.
  - This was achieved by a combination of changes, which together improved observed performance with 2000 item entities moving in water by 30-40%.
  - The benefit of this will be most noticeable in SkyBlock servers, where large cactus farms can generate thousands of dropped items.
- `World->getCollisionBoxes()` now uses an improved search method, which reduces the work done by the function by almost 90% for small entities.
  - This improves performance of collision detection for small entities, such as dropped items.

## Gameplay
### General
- Implemented enchanting using an enchanting table (yes, finally!)
  - Thanks to [@S3v3Nice](https://github.com/S3v3Nice) for investing lots of time and effort into developing this.
  - Since this feature is quite complex, it's possible there may be bugs. Please be vigilant and report any issues you find.

### Blocks
- The following new blocks have been implemented:
  - Pink Petals
- Pressure plates are now functional, in the sense that they react when entities stand on them and perform the correct logic.
  - Note that since redstone is not yet implemented, pressure plates do not activate any redstone devices, similar to buttons and levers.
- Signs can now be edited by right-clicking them.
- Signs can now be waxed using a honeycomb, which prevents them from being edited.

### Items
- The following new items have been implemented:
  - Enchanted Book

## API
### `pocketmine\block`
- The following new API methods have been added:
  - `public Block->getEnchantmentTags() : list<string>` returns a list of strings indicating which types of enchantment can be applied to the block when in item form
  - `public BlockTypeInfo->getEnchantmentTags() : list<string>`
  - `protected PressurePlate->getActivationBox() : AxisAlignedBB` - returns the AABB entities must intersect with in order to activate the pressure plate (not the same as the visual shape)
  - `protected PressurePlate->hasOutputSignal() : bool` - returns whether the pressure plate has an output signal - this should be implemented by subclasses
  - `protected PressurePlate->calculatePlateState() : array{Block, ?bool}` - returns the state the pressure plate will change to if the given list of entities are standing on it, and a bool indicating whether the plate activated or deactivated this tick
  - `protected PressurePlate->filterIrrelevantEntities(list<Entity> $entities) : list<Entity>` - returns the given list filtered of entities that don't affect the plate's state (e.g. dropped items don't affect stone pressure plates)
  - `public BaseSign->isWaxed() : bool`
  - `public BaseSign->setWaxed(bool $waxed) : $this`
  - `public inventory\EnchantInventory->getInput() : Item`
  - `public inventory\EnchantInventory->getLapis() : Item`
  - `public inventory\EnchantInventory->getOutput(int $optionId) : ?Item` - returns the item that would be produced if the input item was enchanted with the selected option, or `null` if the option is invalid
  - `public inventory\EnchantInventory->getOption(int $optionId) : EnchantOption` - returns the enchanting option at the given index
- The following API methods have signature changes:
  - `BlockTypeInfo->__construct()` now accepts an optional `list<string> $enchantmentTags` parameter
  - `PressurePlate->__construct()` now accepts an optional `int $deactivationDelayTicks` parameter
  - `WeightedPressurePlate->__construct()` now accepts optional `int $deactivationDelayTicks` and `float $signalStrengthFactor` parameters
  - `SimplePressurePlate->__construct()` now accepts an optional `int $deactivationDelayTicks` parameter
- The following new classes have been added:
  - `PinkPetals`
  - `utils\BlockEventHelper` - provides helper methods for calling block-related events
- The following classes have been deprecated:
  - `WeightedPressurePlateLight`
  - `WeightedPressurePlateHeavy`

### `pocketmine\entity`
- The following new API methods have been added:
  - `public Human->getEnchantmentSeed() : int` - returns the current seed used to randomize options shown on the enchanting table for this human
  - `public Human->setEnchantmentSeed(int $seed) : void`
  - `public Human->regenerateEnchantmentSeed() : void` - returns a new randomly generated seed which can be set with `setEnchantmentSeed()`

### `pocketmine\event`
- The following new classes have been added:
  - `block\FarmlandHydrationChangeEvent` - called when farmland is hydrated or dehydrated
  - `block\PressurePlateUpdateEvent` - called when a pressure plate is activated or changes its power output
  - `player\PlayerEnchantingOptionsRequestEvent` - called when a player puts an item to be enchanted into an enchanting table, to allow plugins to modify the enchanting options shown
  - `player\PlayerItemEnchantEvent` - called when a player enchants an item in an enchanting table
  - `world\WorldDifficultyChangeEvent` - called when a world's difficulty is changed
- The following new API methods have been added:
  - `public static Event::hasHandlers() : bool` - returns whether the event class has any registered handlers - used like `SomeEvent::hasHandlers()`
  - `public HandlerListManager->getHandlersFor(class-string<? extends Event> $event) : list<RegisteredListener>` - returns a list of all registered listeners for the given event class, using cache if available

### `pocketmine\inventory\transaction`
- The following new classes have been added:
  - `EnchantingTransaction` - used when a player enchants an item in an enchanting table

### `pocketmine\item`
- The following new API methods have been added:
  - `public Armor->getMaterial() : ArmorMaterial` - returns an object containing properties shared by all items of the same armor material
  - `public ArmorTypeInfo->getMaterial() : ArmorMaterial`
  - `public Item->getEnchantability() : int` - returns the enchantability value of the item - higher values increase the chance of more powerful enchantments being offered by an enchanting table
  - `public Item->getEnchantmentTags() : list<string>` - returns a list of strings indicating which types of enchantment can be applied to the item
  - `public ToolTier->getEnchantability() : int`
- The following API methods have signature changes:
  - `Item->__construct()` now accepts an optional `list<string> $enchantmentTags` parameter
  - `ArmorTypeInfo->__construct()` now accepts an optional `?ArmorMaterial $material` parameter
- The following new classes have been added:
  - `ArmorMaterial` - container for shared armor properties
  - `VanillaArmorMaterials` - all vanilla armor materials
  - `EnchantedBook` - represents an enchanted book item

### `pocketmine\item\enchantment`
- The following new classes have been added:
  - `AvailableEnchantmentRegistry` - enchantments to be displayed on the enchanting table are selected from here - custom enchantments may be added
  - `EnchantingHelper` - static class containing various helper methods for enchanting tables
  - `EnchantingOption` - represents an option on the enchanting table menu
  - `IncompatibleEnchantmentGroups` - list of constants naming groups of enchantments that are incompatible with each other - custom enchantments may be added using these group names to make them incompatible with existing enchantments in the same group
  - `IncompatibleEnchantmentRegistry` - manages which enchantments are considered incompatible with each other - custom enchantments may be added using existing group names to make them incompatible with existing enchantments in the same group, or to entirely new groups
  - `ItemEnchantmentTagRegistry` - manages item enchantment compatibility tags and which tags include which other tags
  - `ItemEnchantmentTags` - list of constants naming item types for enchantment compatibility checks
- The following classes have been deprecated
  - `ItemFlags`
- The following API methods have been added:
  - `public Enchantment->isCompatibleWith(Enchantment $other) : bool`
  - `public Enchantment->getMinEnchantingPower()` - returns the minimum enchanting power (derived from enchantability and number of bookshelves) needed to allow this enchantment to show on the enchanting table with a given level
  - `public Enchantment->getMaxEnchantingPower()` - upper limit of enchanting power for this enchantment to be offered on the enchanting table with a given level
- The following API methods have signature changes:
  - `Enchantment->__construct()` now accepts optional `(\Closure(int $level) : int)|null $minEnchantingPower` and `int $enchantingPowerRange` parameters
  - `Enchantment->__construct()` parameters `$primaryItemFlags` and `$secondaryItemFlags` are now deprecated and no longer used
  - `ProtectionEnchantment->__construct()` has extra parameters to reflect `Enchantment->__construct()` changes
- The following API methods have been deprecated:
  - `Enchantment->getPrimaryItemFlags()` - use API methods provided by `AvailableEnchantmentRegistry` instead
  - `Enchantment->getSecondaryItemFlags()` - use API methods provided by `AvailableEnchantmentRegistry` instead
  - `Enchantment->hasPrimaryItemType()`
  - `Enchantment->hasSecondaryItemType()`

### `pocketmine\plugin`
- The following new API methods have been added:
  - `public PluginBase->getResourcePath(string $filename) : string` - returns a URI to an embedded resource file that can be used with `file_get_contents()` and similar functions
  - `public PluginBase->getResourceFolder() : string` - returns a URI to the plugin's folder of embedded resources
- The following API methods have been deprecated:
  - `PluginBase->getResource()` - prefer using `getResourcePath()` with `file_get_contents()` or other PHP built-in functions instead

### `pocketmine\resourcepacks`
- The following new API methods have been added:
  - `public ResourcePackManager->setResourcePacksRequired(bool $value) : void` - sets whether players must accept resource packs in order to join

### `pocketmine\world\generator`
- The following new API methods have been added:
  - `public GeneratorManager->addAlias(string $name, string $alias) : void` - allows registering a generator alias without copying the generator registration parameters

### `pocketmine\world\sound`
- The following new classes have been added:
- `PressurePlateActivateSound`
- `PressurePlateDeactivateSound`

### `pocketmine\utils`
- The following new API methods have been added:
  - `public StringToTParser->registerAlias(string $existing, string $alias) : void` - allows registering a string alias without copying registration parameters