PocketMine-MP/changelogs/5.0-alpha.md

**For Minecraft: Bedrock Edition 1.19.0**

# 5.0.0-ALPHA1
Released 6th July 2022.

This is a development snapshot of 5.0.0, an upcoming major update to PocketMine-MP. This version includes many new improvements, including support for Bedrock worlds from 1.13 onwards, a large array of new blocks, and various changes to the plugin API.

## WARNING
**This is an ALPHA release.** It is an early development snapshot of the upcoming 5.0.0 release.
This means it is LIKELY to be unstable, and/or have performance issues not found in the latest stable releases.

**BACK UP your data before testing this.** This version will work with worlds and player data from 4.x, **BUT** any world or player data loaded in 5.0.0 **will not work in 4.x** due to backwards-incompatible storage format changes.

In addition, there are a number of breaking API changes. Plugins for 4.x may require code changes to run on this version.

The API is **not finalized**. You should expect further changes in later alphas.

## Core
- Worlds are now saved according to the Bedrock 1.19.0 format.
- Worlds generated by Bedrock from 1.13.0 and up are now supported (previously, only worlds up to 1.12 were supported).
- `/particle` now accepts strings for particle data instead of integers.
- `/particle` no longer accepts integers for block or item IDs.
- The usage of `blockcrack`, `iconcrack` and `blockdust` particle types in `/particle` now follows the same pattern as other particle types, with the data for each being passed in the `data` parameter instead of being baked into the particle name.

## Tools
- The following tool scripts have been added:
  - `generate-block-palette-spec.php` - generates a JSON file with a readable overview of blocks, their state properties, and their possible values
  - `generate-blockstate-upgrade-schema.php` - generates JSON blockstate upgrade schemas like those found in [BedrockBlockUpgradeSchema](https://github.com/pmmp/BedrockBlockUpgradeSchema)
  - `generate-item-upgrade-schema.php` - generates JSON item ID/meta upgrade schemas like those found in [BedrockItemUpgradeSchema](https://github.com/pmmp/BedrockItemUpgradeSchema)

## Gameplay
### Blocks
- Added the following new blocks:
  - Amethyst Block
  - Ancient Debris
  - Basalt
  - Blackstone blocks, slabs, stairs, and walls
  - Calcite
  - Chiseled Deepslate
  - Chiseled Nether Bricks
  - Chiseled Polished Blackstone
  - Cobbled Deepslate blocks, slabs, stairs, and walls
  - Copper Ore
  - Cracked Deepslate Bricks
  - Crached Deepslate Tiles
  - Cracked Nether Bricks
  - Cracked Polished Blackstone Bricks
  - Crimson buttons, doors, fences, fence gates, hyphae, planks, pressure plates, signs, slabs, stairs, stems, and trapdoors
  - Deepslate
  - Deepslate Bricks blocks, slabs, stairs, and walls
  - Deepslate Ores (coal, copper, diamond, emerald, gold, iron, lapis lazuli, redstone)
  - Deepslate Tiles blocks, slabs, stairs, and walls
  - Honeycomb Block
  - Light Block
  - Mangrove buttons, doors, fences, fence gates, logs, planks, pressure plates, signs, slabs, stairs, trapdoors, and wood
  - Mud Bricks blocks, slabs, stairs, and walls
  - Nether Gold Ore
  - Polished Basalt
  - Polished Blackstone blocks, buttons, pressure plates, slabs, stairs, and walls
  - Polished Blackstone Bricks blocks, slabs, stairs, and walls
  - Polished Deepslate blocks, slabs, stairs, and walls
  - Quartz Bricks
  - Shroomlight
  - Smooth Basalt
  - Soul Fire
  - Soul Lantern
  - Soul Soil
  - Soul Torch
  - Tuff
  - Warped buttons, doors, fences, fence gates, hyphae, planks, pressure plates, signs, slabs, stairs, stems, and trapdoors
- Added support for basalt generators
- Iron Ore and Gold Ore now drop Raw Iron and Raw Gold respectively, instead of the ore blocks.
- Item frames can now be placed on the top and bottom of blocks.
- All-sided logs ("wood", for want of a better name) can now be placed in X, Y, and Z orientations.
- Walls now connect when placed, following the pre-1.16 logic. (1.16 logic is planned to be implemented, but currently low priority.)
- Stripping logs by right-clicking them with an axe is now supported.

### Items
- Added the following new items:
  - Amethyst Shard
  - Copper Ingot
  - Disc Fragment (5)
  - Echo Shard
  - Glow Ink Sac
  - Honeycomb
  - Phantom Membrane
  - Raw Copper
  - Raw Gold
  - Raw Iron
  - Spyglass

## API
### General
- Protected and public properties now use native property types wherever possible.
- Parameter and return typehints have been applied in many places where it wasn't previously possible.

### `pocketmine\block`
#### Runtime block representation
- Blocks no longer use internal Minecraft IDs and metadata to identify themselves. All APIs associated with legacy IDs and meta have been removed.
- A new set of runtime IDs generated from `VanillaBlocks` is used to identify block types. These IDs are defined in `BlockTypeIds`.
  - These new IDs are used for runtime representation of blocks on chunks, and for type comparison purposes.
  - Block type IDs are used at **runtime only**. They should **NOT** be stored in configs or databases, as they are subject to change without warning.
- Block state properties (e.g. facing, colour, etc.) are now represented by PM-specific state data instead of legacy metadata. The state data consists of:
  - Dynamic type data - this is retained by items when the block is broken (colour, wet/dry, coral type, etc.) - handled by `Block->decodeType()` and `Block->encodeType()`
  - State data - this is discarded when the block is broken (facing direction, lit/unlit, powered/unpowered, etc.) - handled by `Block->decodeState()` and `Block->encodeState()`

**Block type IDs, and state/type data, are intended for use at RUNTIME only. The values of type IDs and state data may change without warning. They should NOT be saved in configs or databases.**

#### Implementing new blocks
To register a new block, the following changes are now required:

- Add a new type ID to `BlockTypeIds`
- Register the block in `BlockFactory`
- Amend `VanillaBlocks` to include the new block
- Amend `BlockStateToBlockObjectDeserializer` to deserialize the block from disk
- Amend `BlockObjectToBlockStateSerializer` to serialize the block for disk
- Optionally, amend `StringToItemParser` to add string alias(es) for the block, so that it can be given via `/give`

This is admittedly rather more of a hassle than in the old days, but that's the price of abstraction. Research is underway for ways to improve this without spaghettifying the code again.

#### Change list
- The following classes have been removed:
  - `BlockIdentifierFlattened`
  - `BlockLegacyIds`
  - `BlockLegacyMetadata`
  - `utils\ColorInMetadataTrait` - `utils\ColoredTrait` now implements colour type data serialization uniformly
  - `utils\InvalidBlockStateException` - this has been superseded by `pocketmine\data\runtime\InvalidSerializedRuntimeDataException`
  - `utils\NormalHorizontalFacingInMetadataTrait` - `utils\HorizontalFacingTrait` now implements facing type data serialization uniformly
  - `utils\PillarRotationInMetadataTrait` - `utils\PillarRotationTrait` now implements rotation type data serialization uniformly
  - `utils\BlockDataSerializer`
- The following classes have been added:
  - `BaseFire`
  - `SoulFire`
  - `BlockTypeIds`
    - This is a generated enum of PocketMine-MP-specific block type IDs
    - There is one for every entry in `VanillaBlocks`
    - Do NOT save these IDs in a config or database, as they may change without warning
    - Block type IDs are intended for comparison purposes only
    - Block type IDs cannot be negative
  - `CopperOre`
  - `GoldOre`
  - `IronOre`
  - `Light`
  - `NetherGoldOre`
  - `utils\WallConnectionType` - enum of all possible wall connection types
  - `utils\WoodType` - enum of all possible wood types, used for wood material blocks like planks and logs
  - `utils\WoodTypeTrait`
- The following API methods have been removed:
  - `Block->getId()` - for type comparisons, use `Block->getTypeId()` instead
  - `Block->getMeta()` - for state comparisons, use `Block->getStateId()` instead
  - `Block->readStateFromData()`
  - `Block->writeStateToMeta()`
  - `Block->writeStateToItemMeta()`
  - `Block->getStateBitmask()`
  - `BlockFactory->get()`
    - To get a block at runtime, e.g. stone, use `VanillaBlocks::STONE()`
    - To load a block from old config or database data:
      1. Use `GlobalBlockStateHandlers::getUpgrader()->upgradeIntIdMeta()` to convert it to modern data
      2. Pass the data to `GlobalBlockStateHandlers::getDeserializer()` to get a blockstate ID
      3. Pass the blockstate ID to `BlockFactory::fromStateId()` to get a `Block` instance
  - `BlockIdentifier->getBlockId()`
  - `BlockIdentifier->getAllBlockIds()`
  - `BlockIdentifier->getVariant()`
  - `BlockIdentifier->getItemId()`
  - `Door->isPowered()`
  - `Door->setPowered()`
  - `Skull->isNoDrops()`
  - `Skull->setNoDrops()`
  - `VanillaBlocks::*_GLAZED_TERRACOTTA()` - use `VanillaBlocks::GLAZED_TERRACOTTA()->setColor(DyeColor::WHATEVER())` instead
  - `utils\FallableTrait->getId()` is no longer required
  - `utils\FallableTrait->getMeta()` is no longer required
- The following constants have been renamed:
  - `Block::INTERNAL_METADATA_BITS` -> `Block::INTERNAL_STATE_DATA_BITS`
  - `Block::INTERNAL_METADATA_MASK` -> `Block::INTERNAL_STATE_DATA_MASK`
- The following API methods have been renamed:
  - `Block->getFullId()` -> `Block->getStateId()`
- The following API methods have signature changes:
  - `BlockIdentifier->__construct()` now accepts `int $blockTypeId`, and no longer accepts `int $blockId, int $variant, ?int $itemId`
  - `ItemFrame->getFacing()` may now return `Facing::UP` and `Facing::DOWN`
  - `ItemFrame->setFacing()` now accepts `Facing::UP` and `Facing::DOWN`
- The following API methods have been added:
  - `protected Block->decodeState()` - encodes the block's state properties, e.g. facing, powered/unpowered, etc.
  - `protected Block->decodeType()` - encodes the block's type properties, e.g. colour, wet/dry, coral type, etc.
  - `public Block->getRequiredStateDataBits()` - returns the number of bits required to encode the block's state data
  - `public Block->getRequiredTypeDataBits()` - returns the number of bits required to encode the block's type data
  - `public BlockIdentifier->getBlockTypeId()` - returns the block's type ID according to `BlockTypeIds`
  - `public GlazedTerracotta->getColor()` (from `ColoredTrait`) - this was previously unsupported due to legacy limitations
  - `public GlazedTerracotta->setColor()` (from `ColoredTrait`) - this was previously unsupported due to legacy limitations
  - `public Wall->getConnections()` - returns the wall's connections and their types (see `utils\WallConnectionType`)
  - `public Wall->setConnections()` - sets the wall's connections and their types (see `utils\WallConnectionType`)
  - `public Wall->getConnection()`
  - `public Wall->setConnection()`
  - `public Wall->isPost()`
  - `public Wall->setPost()`
  - `public Wood->isStripped()`
  - `public Wood->setStripped()`
- The following classes now use new traits, adding API methods and/or properties:
  - `FenceGate` uses `utils\WoodTypeTrait`
  - `GlazedTerracotta` uses `utils\ColoredTrait`
  - `Planks` uses `utils\WoodTypeTrait`
  - `Wood` uses `utils\WoodTypeTrait`
  - `WoodenButton` uses `utils\WoodTypeTrait`
  - `WoodenDoor` uses `utils\WoodTypeTrait`
  - `WoodenFence` uses `utils\WoodTypeTrait`
  - `WoodenPressurePlate` uses `utils\WoodTypeTrait`
  - `WoodenSlab` uses `utils\WoodTypeTrait`
  - `WoodenStairs` uses `utils\WoodTypeTrait`
  - `WoodenTrapdoor` uses `utils\WoodTypeTrait`

### `pocketmine\crafting`
- The following classes have been added:
  - `RecipeIngredient` interface
  - `ExactRecipeIngredient` - matches an exact item
  - `MetaWildcardRecipeIngredient` - matches an item with the given legacy Minecraft ID, but any metadata value
- The following API methods have signature changes:
  - `FurnaceRecipe->__construct()` now accepts `RecipeIngredient` instead of `Item`
  - `FurnaceRecipe->getInput()` now returns `RecipeIngredient` instead of `Item`
  - `PotionContainerChangeRecipe->__construct()` now accepts `string, RecipeIngredient, string` (using Minecraft string IDs instead of legacy integers).
  - `PotionContainerChangeRecipe->getIngredient()` now returns `RecipeIngredient` instead of `Item`.
  - `PotionContainerChangeRecipe->getInputItemId()` now returns `string` (using Minecraft string IDs instead of legacy integers).
  - `PotionContainerChangeRecipe->getOutputItemId()` now returns `string` (using Minecraft string IDs instead of legacy integers).
  - `PotionTypeRecipe->__construct()` now accepts `RecipeIngredient` instead of `Item`
  - `PotionTypeRecipe->getIngredient()` now returns `RecipeIngredient` instead of `Item`
  - `PotionTypeRecipe->getInput()` now returns `RecipeIngredient` instead of `Item`
  - `ShapedRecipe->__construct()` now accepts `RecipeIngredient` instead of `Item`
  - `ShapedRecipe->getIngredient()` now returns `?RecipeIngredient` instead of `?Item`
  - `ShapedRecipe->getIngredientList()` now returns `RecipeIngredient[]` instead of `Item[]`
  - `ShapedRecipe->getIngredientMap()` now returns `RecipeIngredient[][]` instead of `Item[][]`
  - `ShapelessRecipe->__construct()` now accepts `RecipeIngredient` instead of `Item`
  - `ShapelessRecipe->getIngredientList()` now returns `RecipeIngredient[]` instead of `Item[]`

### `pocketmine\entity`
- `Entity` now declares new abstract methods which must be implemented by subclasses:
  - `public Entity->getInitialDragMultiplier()`
  - `public Entity->getInitialGravity()`

### `pocketmine\item`
#### Runtime item representation
- Items no longer use internal Minecraft string IDs and metadata to identify themselves. All APIs associated with legacy IDs and/or meta have been removed.
- A new set of runtime item IDs generated from `VanillaItems` is now used to identify item types. These IDs are defined in `ItemTypeIds`.
  - These new IDs are primarily intended for type comparison purposes.
  - Item type IDs are used at **runtime only**. They should **NOT** be stored in configs or databases, as they are not guaranteed to remain the same between versions.
- In some cases, items may have additional "type data" which provides extra type information about an item. This replaces item metadata in some cases.
  - Type data may be used to store dynamic type information such as dye colour, potion type, etc.
  - Items must have the same type ID **and** type data in order to be stackable.
- Blocks, when represented as items:
  - retain their block type data, but not state data (for example, different colours of concrete don't stack, but things like facing don't affect stackability)
  - use the negative of their block type ID (e.g. a block with type ID `1` will have an item type ID of `-1`).
- Durable items (e.g. tools, armour) now use NBT `Damage` tag to store durability (like Minecraft 1.13+), instead of legacy meta values.

**Item type IDs and type data are intended for RUNTIME use only. The values of type IDs and/or type data may change without warning. They should NOT be saved in configs or databases.**

#### Implementing new items
To register a new item, the following changes are now required:

- Add a new ID to `ItemTypeIds`
- Register the item in `ItemFactory`
- Amend `VanillaItems` to add the item
- Amend `ItemDeserializer` to add a deserializer for loading the item from disk
- Amend `ItemSerializer` to add a serializer for saving the item to disk
- Optionally, amend `StringToItemParser` to add string alias(es) for the item, so it can be given via `/give`

Again, it's acknowledged this is rather more cumbersome than it should be, but this is an ongoing process.

#### Change list
- `Item` is no longer `json_encode()`-able.
  - The original purpose of this was to allow items to be serialized to JSON for crafting data generated from `CraftingDataPacket`. Due to changes in the generation methodology, bypassing `Item`s entirely, this is no longer necessary.
  - `jsonSerialize()` requires the item to know about the method by which it will be serialized, creating a cyclic dependency between the `Item` implementation and its serialization method.
  - It's relatively easy to write a replacement method to encode items to JSON as you desire.
- The following classes have been removed:
  - `ItemIds`
  - `Skull`
  - `Bed`
- The following classes have been added:
  - `CoralFan`
  - `Spyglass`
- The following API methods have been added:
  - `public Dye->setColor()`
  - `public ItemIdentifer->getTypeId()`
  - `public static ItemIdentifier::fromBlock()`
  - `public Potion->setType()`
  - `public SplashPotion->setType()`
- The following API methods have been removed:
  - `Item->getId()` - for type comparisons, use `Item->getTypeId()` instead
  - `Item->getMeta()` - use the item's specific API methods to compare information such as colour, potion type etc.
  - `Item->hasAnyDamageValue()` - for meta wildcard recipe ingredients, use `pocketmine\crafting\MetaWildcardRecipeIngredient` instead
  - `ItemFactory->get()`
    - To get an item at runtime, e.g. iron ingot, use `VanillaItems::IRON_INGOT()`
    - To get a block as an item, e.g. stone, use `VanillaBlocks::STONE()->asItem()`
    - To load an item from legacy ID and meta:
      1. Use `GlobalItemDataHandlers::getUpgrader()->upgradeItemTypeDataInt()` to convert the legacy ID and meta to `ItemStackData`
      2. Pass the itemstack data to `GlobalItemDataHandlers::getDeserializer()` to get an `Item` instance
  - `ItemFactory->remap()`
  - `ItemIdentifier->getId()`
  - `ItemIdentifier->getMeta()`
- The following API methods have been renamed:
  - `Item::jsonDeserialize()` -> `Item::legacyJsonDeserialize()`
  - `ItemFactory->getAllRegistered()` -> `ItemFactory->getAllKnownTypes()`
- The following API methods have signature changes:
  - `ItemFactory->isRegistered()` no longer accepts a `$variant` parameter, and now expects an item type ID for the ID parameter
  - `ItemIdentifier->__construct()` no longer accepts a `$variant` parameter, and now expects an item type ID for the ID parameter
  - `LegacyStringToItemParser->addMapping()` now accepts a string for ID, instead of an integer

### `pocketmine\world`
- The following classes have been added:
  - `pocketmine\world\format\io\GlobalBlockStateHandlers`
  - `pocketmine\world\format\io\GlobalItemDataHandlers`

# 5.0.0-ALPHA2
Released 14th July 2022.

## Core
- Reduced memory usage of the server on startup.
- Fixed error spam when loading item frames without items in them.

## Gameplay
### Blocks
- Added the following new blocks:
  - Cakes with Candle & Dyed Candle
  - Candle & Dyed Candle
  - Cartography Table (not currently usable due to maps not being implemented)
  - Copper block (random oxidation not yet implemented)
  - Cut Copper block, stairs and slabs (random oxidation not yet implemented)
  - Crying Obsidian
  - Gilded Blackstone
  - Glow Item Frame
  - Hanging Roots
  - Lightning Rod
  - Netherite Block
  - Smithing Table
  - Tinted Glass
  - Warped Wart Block
  - Wither Rose

### Items
- Added the following new items:
  - Honey Bottle
  - Netherite Axe
  - Netherite Boots
  - Netherite Chestplate
  - Netherite Helmet
  - Netherite Ingot
  - Netherite Leggings
  - Netherite Pickaxe
  - Netherite Scrap
  - Netherite Shovel
  - Netherite Sword

## API
### `pocketmine\block`
- Dependency between `BlockFactory` and `VanillaBlocks` has been inverted.
  - Now, blocks are defined in `VanillaBlocks`, and automatically registered in `BlockFactory`.
  - Manual registration in `BlockFactory` is still required for custom blocks.
  - `BlockFactory` now has only one purpose, which is to map internal blockstate IDs to `Block` objects when reading blocks from chunks.
- The following new API methods have been added:
  - `public Block->isFireProofAsItem()`
  - `public Block->onProjectileHit()`
  - `public ItemFrame->isGlowing()`
  - `public ItemFrame->setGlowing()`
- The following new classes have been added:
  - `BaseCake`
  - `CakeWithCandle`
  - `CakeWithDyedCandle`
  - `Candle`
  - `CartographyTable`
  - `CopperSlab`
  - `CopperStairs`
  - `Copper`
  - `DyedCandle`
  - `GildedBlackstone`
  - `HangingRoots`
  - `LightningRod`
  - `SmithingTable`
  - `WitherRose`
  - `utils\CandleTrait`
  - `utils\CopperOxidation`
  - `utils\CopperTrait`

### `pocketmine\crafting`
- JSON models have been updated to reflect updated crafting data format.
- The following enum classes have new members:
  - `ShapelessRecipeType` has new members `CARTOGRAPHY` and `SMITHING`

### `pocketmine\data`
- `LegacyToStringBidirectionalIdMap` has been reduced to `LegacyToStringIdMap`.
  - Since we never map from string ID to legacy ID, bidirectional mapping is no longer necessary.
  - This affects the following subclasses:
    - `LegacyBiomeIdToStringIdMap`
    - `LegacyBlockIdToStringIdMap`
    - `LegacyEntityIdToStringIdMap`
    - `LegacyItemIdToStringIdMap`
- The following internal API methods have been added:
  - `public LegacyToStringIdMap->add(string $string, int $legacy) : void` - adds a mapping from a custom legacy ID to custom string ID, needed for upgrading old saved data
  - `public LegacyBlockStateMapper->addMapping(string $stringId, int $intId, int $meta, BlockStateData $stateData) : void` - adds a mapping from legacy block data to a modern blockstate, needed for upgrading old saved data
  - `public BlockStateData->getState(string $name) : ?Tag`
- The following internal API methods have signature changes:
  - `BlockStateData->__construct()` now accepts `array<string, Tag`> for `$states` instead of `CompoundTag`
  - `BlockStateData->getStates()` now returns `array<string, Tag>` instead of `CompoundTag` (allows reducing memory usage)
- The following classes have been added:
  - `UnsupportedItemTypeException`

### `pocketmine\item`
- `ItemFactory` has been removed.
  - Vanilla item registration is now done via `VanillaItems`.
  - The procedure for registering a custom item is the same as in ALPHA1, minus the `ItemFactory` step.
- The following API methods have been added:
  - `public ArmorTypeInfo->getToughness() : int`
  - `public ArmorTypeInfo->isFireProof() : bool`
  - `public Item->isFireProof() : bool`
- The following API methods have signature changes:
  - `ArmorTypeInfo->__construct()` now accepts optional parameters `int $toughness` and `bool $fireProof`
- The following classes have been added:
  - `HoneyBottle`
- The following enums have new members:
  - `ToolTier` has new member `NETHERITE`

### `pocketmine\world`
- The following API methods have signature changes:
  - `SubChunk->__construct()` parameter `$blocks` has been renamed to `$blockLayers`.
- The following classes have been added:
  - `CopperWaxApplySound`
  - `CopperWaxRemoveSound`

# 5.0.0-ALPHA3
Released 14th August 2022.

## Core
- Support for Bedrock 1.19.20.
- Dropped support for Bedrock versions older than 1.19.20.
- Improved performance of dropping block inventory contents when the block is destroyed.

## Fixes
- Fixed errors when loading air itemstacks from PM4 worlds. These weren't supposed to exist (vanilla doesn't save them), but they were present in older PM worlds due to a bug in older versions.
- Fixed server crash when discovering unknown blocks in non-leveldb worlds during conversion.
- Fixed crimson / warped planks being usable as furnace fuel.

## Gameplay
### Blocks
- Added the following new blocks:
  - Cauldron
  - Chorus Flower
  - Chorus Plant
  - Froglight (pearlescent, verdant, ochre)
  - Mangrove Roots
  - Muddy Mangrove Roots
  - Rooted Dirt
  - Spore Blossom
- Fixed lava setting entities on fire for an incorrect duration (Java vs Bedrock inconsistency).

### Items
- Glass bottles can now be filled with water by clicking on a water source block.

## API
### `pocketmine\block`
#### Highlights
- Introduced "type tags" concept, which allows marking certain blocks as having certain behaviours.
  - The idea for this system was borrowed from the Minecraft Java tags system.
  - It's still in very early concept stage, but is currently used for deciding which types of blocks plants can be placed on without needing to enumerate every single ID in every class, eliminating a bunch of boilerplate code and improving consistency.
- All `Block` descendents now accept `BlockTypeInfo` in the constructor, instead of `BlockBreakInfo`.
  - This allows for future additions without needing to change dozens of overridden constructors.
- Dynamic type and state property serialization now each use a single, unified method (`describeType` and `describeState` respectively) which accept `RuntimeDataReader|RuntimeDataWriter`, instead of separate decode/encode methods.
  - This simplifies implementing new blocks and avoids duplication of information.
- `&$returnedItems` reference parameter is now used in some places to enable actions to return items to players without caring about whether they are in creative or anything else.
  - This eliminates boilerplate code of deciding whether to set the player's held item or not, as well as automatically dropping any overflow items that don't fit into the inventory.
  - This is currently used when filling/emptying cauldrons using buckets or glass bottles.
- `BlockTypeIds` now exposes `newId()` static method to ease addition of custom blocks.

#### Changes
- The following API methods have signature changes:
  - `Block->onInteract()` now accepts `array<Item> &$returnedItems` reference parameter.
  - `Block->onBreak()` now accepts `array<Item> &$returnedItems` reference parameter.
  - `Block->readStateFromWorld()` now returns `Block`.
    - This allows blocks to replace themselves with a different block entirely based on world conditions.
- The following new classes have been added:
  - `BlockTypeInfo`
  - `BlockTypeTags`
- The following new API methods have been added:
  - `protected Block->describeState(RuntimeDataReader|RuntimeDataWriter $w) : void` - describes to a runtime data reader/writer how to read/write the block's state properties
  - `protected Block->describeType(RuntimeDataReader|RuntimeDataWriter $w) : void` - describes to a runtime data reader/writer how to read/write the block's dynamic type properties
  - `public Block->getTypeTags() : array<string>`
  - `public Block->hasTypeTag(string $tag) : bool`
  - `public Spawnable->getRenderUpdateBugWorkaroundStateProperties(Block $block) : array<string, Tag>` - allows spawnable tiles to spoof block state properties to work around client-side rendering bugs without actually changing the block server-side
  - `public static BlockBreakInfo::axe(float $hardness, ?ToolTier $toolTier = null, ?float $blastResistance = null) : BlockBreakInfo`
  - `public static BlockBreakInfo::pickaxe(float $hardness, ?ToolTier $toolTier = null, ?float $blastResistance = null) : BlockBreakInfo`
  - `public static BlockBreakInfo::shovel(float $hardness, ?ToolTier $toolTier = null, ?float $blastResistance = null) : BlockBreakInfo`
  - `public static BlockBreakInfo::tier(float $hardness, int $toolType, ToolTier $toolTier, ?float $blastResistance = null) : BlockBreakInfo`
  - `public static BlockTypeIds::newId() : int` - returns a new dynamic block type ID for use by custom blocks

### `pocketmine\data`
- The following classes have been renamed:
  - `LegacyBlockStateMapper` -> `BlockIdMetaUpgrader`
- The following API methods have been added:
  - `public BlockDataUpgrader->getIdMetaUpgrader() : BlockIdMetaUpgrader`
  - `public BlockIdMetaUpgrader->addIdMetaToStateMapping(string $stringId, int $meta, BlockStateData $stateData) : void`
  - `public BlockIdMetaUpgrader->addIntIdToStringIdMapping(int $intId, string $stringId) : void`
- The following API methods have been removed:
  - `BlockIdMetaUpgrader->addMapping()` - use `addIdMetaToStateMapping()` (and `addIntIdToStringIdMapping()` if necessary) instead
- `LegacyToStringMap` no longer throws exceptions when adding the same mapping twice if the addition would have no effect.

### `pocketmine\item`
#### Highlights
- `&$returnedItems` reference parameter is now used in some places to enable actions to return items to players without caring about whether they are in creative or anything else.
  - This eliminates boilerplate code of deciding whether to set the player's held item or not, as well as automatically dropping any overflow items that don't fit into the inventory.
  - This is used for things like filling/emptying buckets and bottles, and equipping armor.

#### Changes
- The following new API methods have been added:
  - `public Armor->clearCustomColor() : $this` - clears the custom color of an armor item
  - `public static ItemTypeIds::newId() : int` - returns a new dynamic item type ID for use by custom items
- The following API methods have signature changes:
  - `Item->onAttackEntity()` now accepts `array<Item> &$returnedItems` reference parameter.
  - `Item->onClickAir()` now accepts `array<Item> &$returnedItems` reference parameter.
  - `Item->onDestroyBlock()` now accepts `array<Item> &$returnedItems` reference parameter.
  - `Item->onInteractBlock()` now accepts `array<Item> &$returnedItems` reference parameter.
  - `Item->onReleaseUsing()` now accepts `array<Item> &$returnedItems` reference parameter.

# 5.0.0-ALPHA4
Released 24th September 2022.

## Core
- Now targeting Minecraft: Bedrock 1.19.30.
- All tests and static analysis are now being run on PHP 8.1 as well as PHP 8.0.
- Silenced warning about Xdebug when it's loaded but disabled by `xdebug.mode` configuration.
- A new `console.enable-input` option has been added to `pocketmine.yml`, which allows disabling the console reader in environments where it's not needed (e.g. a Docker container). This can be useful to save processor and memory resources.
- Console reader polling is now done on the main thread. Since the console reader communication is now done via sockets, there's no longer any reason for it to have its own thread.
- Crashdumps now include JIT mode information for use by the Crash Archive.
- Improved handling of "UI" inventories in network `InventoryManager`. Their contents are now synced correctly.
- Fixed cartography table recipes pretending to be smithing table recipes in `CraftingDataPacket`.
- Fixed incorrect key being used for saving entity type IDs in save data.

## API
### General
- Plugin dependents are now always disabled before their dependencies on shutdown, to ensure that the dependents can finish what they are doing correctly.

### `pocketmine\block`
- The following new API methods have been added:
  - `public SignText->isGlowing() : bool`
  - `public SignText->getBaseColor() : pocketmine\color\Color`
- The following API methods have signature changes:
  - `SignText::fromBlob()` now accepts two new optional parameters: `?Color $baseColor` and `bool $glowing`
  - `SignText::__construct()` now accepts two new optional parameters: `?Color $baseColor` and `bool $glowing`
- The following API methods have been removed:
  - `TreeType::fromMagicNumber()`
  - `TreeType->getMagicNumber()`

### `pocketmine\command`
- Command permissions are now always checked by the server when running a command.
  - This only affects commands implemented by extending `Command`. Plugins using `PluginBase->onCommand()` are not affected by this change, since they already had permissions checked by the server anyway.
  - Previously, direct inheritors of `Command` were responsible for checking permissions, which required developers to duplicate the same code in every command, and opened lots of potential for security vulnerabilities.
  - If you want to do something on permission denied (e.g. sending a special message, or audit logging), you can do so by overriding `Command->testPermission()`, instead of baking the code directly into `Command->execute()`.
  - If you don't want to use permissions at all, just create a permission with a default of `true` (or belonging to `pocketmine.group.user`) and assign that.

### `pocketmine\data`
#### Highlights
- Introduced an experimental, mostly unified item (de)serializer registrar, `ItemSerializerDeserializerRegistrar`.
  - This class includes helper methods to register symmetric serializer and deserializer callbacks into an `ItemSerializer` and `ItemDeserializer`.
  - This halves the amount of code needed to register new items in the vast majority of cases.
  - This is currently used to register all currently implemented items.

#### Other changes
- The following classes have been renamed:
  - `BlockObjectToBlockStateSerializer` -> `BlockObjectToStateSerializer`
  - `BlockStateToBlockObjectDeserializer` -> `BlockStateToObjectDeserializer`
- The following classes have been removed:
  - `CachingBlockStateDeserializer`
  - `CachingBlockStateSerializer`
  - `DelegatingBlockStateDeserializer`
  - `DelegatingBlockStateSerializer`
- The following new API methods have been added:
  - `public BlockStateToObjectDeserializer->mapSimple(string $stringId, \Closure() : Block $getBlock) : void` - for symmetry with the serializer

### `pocketmine\event`
- `BlockFormEvent` now includes information about the block which caused the event.
  - Added `public BlockFormEvent->getCausingBlock() : Block`

### `pocketmine\inventory`
- Introduced a new `TransactionBuilder` class, which considerably simplifies the process of constructing an `InventoryTransaction` from generic `setItem()` calls.
  - This is currently used to build server-side transactions for evicting the contents of the crafting grid when closing the main inventory.
  - This is planned for use with the new Minecraft Bedrock item stack request system.
- Improved PHPStan type information available for `Inventory` and `BaseInventory`.

### `pocketmine\item`
- The following API methods have been changed:
  - `Item->encodeType(RuntimeDataWriter $w) : void` -> `Item->describeType(RuntimeDataReader|RuntimeDataWriter $w) : void`
- The following new classes have been added:
  - `SuspiciousStew`
  - `SuspiciousStewType`

### `pocketmine\utils`
- The following new API methods have been added:
  - `public static Utils::getOpcacheJitMode() : int`

### `pocketmine\world`
- The following new classes have been added:
  - `sound\DyeUseSound`
  - `sound\InkSacUseSound`
- The following API methods have changed signatures:
  - `GlobalBlockStateHandlers::getSerializer()` now returns `BlockObjectToStateSerializer` directly instead of `BlockStateSerializer`.
  - `GlobalBlockStateHandlers::getDeserializer()` now returns `BlockStateToObjectDeserializer` directly instead of `BlockStateDeserializer`.

## Gameplay
### General
- Spectator players are no longer able to acquire blocks by block picking that they don't already have in their inventories. The behaviour is now the same as survival mode.

### Blocks
- Coral and coral fans now behave correctly when placed out of water (they no longer immediately die).
- Added support for dyeing sign text and making it glow.
- Fixed dead bush being able to be placed on some invalid blocks (e.g. stone).
- TNT can now be ignited by fire charges.
- Vines can now only be placed on the side of full-cube blocks.
- Fixed sugarcane not being able to be placed on some blocks.

### Items
- Added the following new items:
  - Fire Charge
  - Suspicious Stew

### Effects
- Updated damage modifier amounts for Instant Damage to be more in line with vanilla.
- Updated duration modifier amounts for Regeneration to be more like vanilla.

# 5.0.0-ALPHA5
Released 13th November 2022.

**This release includes changes from [4.11.0-BETA2](https://github.com/pmmp/PocketMine-MP/releases/4.11.0-BETA2) and earlier, which may not be listed here.**

## General
- Added support for Minecraft: Bedrock 1.19.40.
- Removed support for earlier versions.

## API
### `pocketmine\block`
- `FallableTrait` now includes a default implementation of `tickFalling()`.

### `pocketmine\event`
- The following API methods have been removed:
  - `PlayerCommandPreprocessEvent`
- The following API methods have been added:
  - `public DataPacketSendEvent->setPackets(list<ClientboundPacket> $packets) : void`

## Gameplay
### General
- Fixed dyeing leather armour in cauldrons.

### Blocks
- Copper blocks now play the correct scrape sound when using an axe on them.

## Internals
- Moved command timings to `Timings`.

# 5.0.0-ALPHA6
Released 19th December 2022.

**This release includes changes from the following releases, which may not be mentioned:**
- [4.10.2](https://github.com/pmmp/PocketMine-MP/releases/tag/4.10.2)
- [4.11.0](https://github.com/pmmp/PocketMine-MP/releases/tag/4.11.0)
- [4.12.0](https://github.com/pmmp/PocketMine-MP/releases/tag/4.12.0)
- [4.12.1](https://github.com/pmmp/PocketMine-MP/releases/tag/4.12.1)
- [4.12.2](https://github.com/pmmp/PocketMine-MP/releases/tag/4.12.2)

## General
- Fixed the Bedrock client asking to upgrade worlds exported from PocketMine-MP to Bedrock (missing level.dat fields).
- Added support for 1.19.40 and newer Bedrock worlds.
- Commands are now enabled by default in worlds exported from PocketMine-MP to Bedrock.

## Gameplay
### Blocks
- Added the following new blocks:
  - Twisting Vines
  - Weeping Vines
- Anvils are now damaged when they hit the ground after falling.
- Added missing sounds for anvils hitting the ground after falling.
- Fixed missing sounds when a projectile strikes an amethyst block.
- Fixed some blocks being incorrectly able to be placed on top of a candle cake.

### Items
- Added the following new items:
  - Music Disc (5)
  - Music Disc (Otherside)
  - Music Disc (Pigstep)
- Implemented Swift Sneak enchantment.
- Armour durability is now only reduced when the wearer receives a type of damage that the armour can protect against.

## API
### General
- Union and mixed native parameter, return and property types are now used where appropriate.

### `pocketmine\block`
- The following new API methods have been added:
  - `public Furnace->getType() : utils\FurnaceType`
- The following interfaces have new requirements:
  - `utils\Fallable` now requires `onHitGround()` to be implemented (although filled by default implementation in `FallableTrait`).
  - `utils\Fallable` now requires `getLandSound()` to be implemented (although filled by default implementation in `FallableTrait`).
- The following new API constants have been added:
  - `public BlockTypeTags::FIRE` - used by fire and soul fire

### `pocketmine\crafting`
- The `$type` parameter of `ShapelessRecipe->__construct()` is now mandatory.

### `pocketmine\entity`
- The following new API methods have been added:
  - `public Living->getDisplayName() : string`
- The following API methods have changed signatures:
  - `EntityFactory->register()` no longer accepts a `$legacyMcpeSaveId` parameter (now handled by internal conversions instead).

### `pocketmine\event`
- The following classes have been renamed:
  - `entity\ExplosionPrimeEvent` -> `entity\EntityPreExplodeEvent`
- The following new classes have been added:
  - `world\WorldParticleEvent` - called when a particle is spawned in a world
  - `world\WorldSoundEvent` - called when a sound is played in a world
- The following API methods have changed signatures:
  - `entity\EntityPreExplodeEvent->__construct()` has the `$force` parameter renamed to `$radius`
  - `entity\EntityPreExplodeEvent->getForce() : float` -> `entity\EntityPreExplodeEvent->getRadius() : float`
  - `entity\EntityPreExplodeEvent->setForce(float $force) : void` -> `entity\EntityPreExplodeEvent->setRadius(float $radius) : void`

### `pocketmine\item`
- The following new API methods have been added:
  - `public Item->keepOnDeath() : bool` - returns whether this item will be retained when a player carrying it dies
  - `public Item->onInteractEntity(Player $player, Entity $entity, Vector3 $clickPos) : bool` - called when a player interacts with an entity with this item in their hand
  - `public Item->setKeepOnDeath(bool $keepOnDeath) : void` - sets whether this item will be retained when a player carrying it dies
  - `public StringToItemParser->lookupAliases(Item $item) : list<string>` - returns a list of all registered aliases for the given item
  - `public StringToItemParser->lookupBlockAliases(Block $block) : list<string>` - returns a list of all registered aliases for the given block

### `pocketmine\resourcepacks`
- The following new API methods have been added:
  - `public ResourcePackManager->setPackEncryptionKey(string $id, ?string $key) : void` - sets the encryption key to be used for the resource pack identified by the given UUID
  - `public ResourcePackManager->setResourceStack(list<ResourcePack> $resourceStack) : void` - sets the resource stack to be used by the server

### `pocketmine\world`
- The following API methods have changed signatures:
  - `Explosion->__construct()` has the `$size` parameter renamed to `$radius`
- The following public properties have been renamed:
  - `Explosion->size` -> `Explosion->radius`

## Internals
- `EntityLegacyIds` has been removed. Legacy entity IDs found during world loading are now converted via `LegacyEntityIdToStringIdMap`.
- All usages of NBT keys now use class constants instead of hardcoded strings (except for an occasional overlooked one).
- All members of `BlockTypeTags` now have a `pocketmine:` prefix on the value. This does not affect constant usages.

# 5.0.0-ALPHA7
Released 18th January 2023.

**This release includes changes from the following releases, which may not be mentioned:**
- [4.12.3](https://github.com/pmmp/PocketMine-MP/releases/tag/4.12.3)
- [4.12.4](https://github.com/pmmp/PocketMine-MP/releases/tag/4.12.4)
- [4.12.5](https://github.com/pmmp/PocketMine-MP/releases/tag/4.12.5)
- [4.12.6](https://github.com/pmmp/PocketMine-MP/releases/tag/4.12.6)
- [4.12.7](https://github.com/pmmp/PocketMine-MP/releases/tag/4.12.7)
- [4.12.8](https://github.com/pmmp/PocketMine-MP/releases/tag/4.12.8)
- [4.12.9](https://github.com/pmmp/PocketMine-MP/releases/tag/4.12.9)
- [4.12.10](https://github.com/pmmp/PocketMine-MP/releases/tag/4.12.10)
- [4.13.0-BETA1](https://github.com/pmmp/PocketMine-MP/releases/tag/4.13.0-BETA1)

## Fixes
- Fixed glowing item frame placement creating the wrong tile, causing invisible items.

## Localization
- Localized disconnect messages are now used in the following cases:
  - Server full
  - Player not on the server whitelist
  - Player on the server ban list
  - Invalid skin
  - Invalid username
  - Kicked using `/kick`
  - Banned using `/ban`
  - Failure to find a safe spawn position
- Session open, session close and session player name discovery messages are now localized.
- All permissions now have localized descriptions. These are not currently used by PocketMine-MP, but may be useful for plugins.

## Gameplay
### Worlds
- Added support for 3D biomes. This isn't used by PocketMine-MP yet, but is necessary to be able to fully load 1.18 worlds.

### Blocks
- Added the following new blocks:
  - Chain
  - Sculk

### Items
- Added the following new items:
  - Eye Drops (from Education Edition)
  - Antidote (from Education Edition)
  - Elixir (from Education Edition)
  - Tonic (from Education Edition)

## API
### Overview
- Biome-related APIs have changed to accommodate 3D biomes.
- Disconnect-related APIs have changed to accommodate localized disconnect messages.
- New, more powerful chat formatting API introduced to `PlayerChatEvent`.
- Glowing item frames moved to a separate block type instead of being a property of regular item frames (due to technical limitations).

### `pocketmine\block`
- The following API methods have been removed:
  - `ItemFrame->isGlowing() : bool`
  - `ItemFrame->setGlowing(bool $glowing) : void`
- The following new API methods have been added:
  - `public static VanillaBlocks::GLOWING_ITEM_FRAME() : ItemFrame`
- The following constants have been added:
  - `BlockTypeIds::GLOWING_ITEM_FRAME`
  - `BlockTypeIds::CHAIN`
  - `BlockTypeIds::SCULK`
- The following new classes have been added:
  - `Chain`
  - `Sculk`

### `pocketmine\event\player`
- The following API methods have changed signatures:
  - `PlayerDuplicateLoginEvent->getDisconnectMessage()` now returns `Translatable|string` instead of `string`
  - `PlayerDuplicateLoginEvent->setDisconnectMessage()` now accepts `Translatable|string` instead of `string`
  - `PlayerKickEvent->getReason()` now returns `Translatable|string` instead of `string`
  - `PlayerKickEvent->setReason()` now accepts `Translatable|string` instead of `string`
  - `PlayerLoginEvent->getKickMessage()` now returns `Translatable|string` instead of `string`
  - `PlayerLoginEvent->setKickMessage()` now accepts `Translatable|string` instead of `string`
  - `PlayerPreLoginEvent->getFinalKickMessage()` now returns `Translatable|string` instead of `string`
  - `PlayerPreLoginEvent->getKickMessage()` now returns `Translatable|string|null` instead of `string|null`
  - `PlayerPreLoginEvent->setKickReason()` now accepts `Translatable|string` for the `$message` parameter instead of `string`
  - `PlayerQuitEvent->getQuitReason()` now returns `Translatable|string` instead of `string`
- The following API methods have been removed:
  - `PlayerChatEvent->getFormat()` (use `PlayerChatEvent->getChatFormatter()` instead)
  - `PlayerChatEvent->setFormat()` (use `PlayerChatEvent->setChatFormatter()` instead)
- The following new API methods have been added:
  - `public PlayerChatEvent->setChatFormatter(\pocketmine\player\chat\ChatFormatter $formatter) : void` - sets the chat formatter to be used for this event
  - `public PlayerChatEvent->getChatFormatter() : \pocketmine\player\chat\ChatFormatter` - returns the chat formatter to be used for this event

### `pocketmine\item`
- The following new classes have been added:
  - `Medicine`
  - `MedicineType`
- The following new class constants have been added:
  - `ItemTypeIds::MEDICINE`

### `pocketmine\network\query`
- The following API methods have changed signatures:
  - `QueryInfo->getPlayerList()` now returns `list<string>` instead of `list<Player>`
  - `QueryInfo->setPlayerList()` now accepts `list<string>` instead of `list<Player>`

### `pocketmine\player`
- The following API methods have changed signatures:
  - `Player->kick()` now accepts `Translatable|string` for `$reason` instead of `string` (to allow localized kick messages)
  - `Player->disconnect()` now accepts `Translatable|string` for `$reason` instead of `string` (to allow localized disconnect messages)
  - `Player->sendJukeboxPopup()` now accepts `Translatable|string` instead of `string, string[]`

#### `pocketmine\player\chat`
- The following new classes have been added:
  - `ChatFormatter` - interface implemented by chat formatters
  - `StandardChatFormatter` - formats chat messages in the vanilla Minecraft style
  - `LegacyRawChatFormatter` - implements the same behaviour previously used by `PlayerChatEvent->setFormat()`

### `pocketmine\world`
- The following API methods have changed signatures:
  - `World->getBiome()` now accepts `int $x, int $y, int $z` instead of `int $x, int $z`
  - `World->getBiomeId()` now accepts `int $x, int $y, int $z` instead of `int $x, int $z`
  - `World->setBiomeId()` now accepts `int $x, int $y, int $z` instead of `int $x, int $z`

#### `pocketmine\world\format`
- The following new API methods have been added:
  - `public SubChunk->getBiomeArray() : PalettedBlockArray`
- The following API methods have changed signatures:
  - `Chunk->getBiomeId()` now accepts `int $x, int $y, int $z` instead of `int $x, int $z`
  - `Chunk->setBiomeId()` now accepts `int $x, int $y, int $z` instead of `int $x, int $z`
  - `Chunk->__construct()` no longer accepts `BiomeArray` as a parameter (contained in each subchunk instead)
  - `SubChunk->__construct()` now accepts `int $emptyBlockId, list<PalettedBlockArray> $blocks, PalettedBlockArray $biomes, ?LightArray $blockLight, ?LightArray $skyLight` instead of `int, list<PalettedBlockArray>, ?LightArray, ?LightArray` 
- The following classes have been removed
  - `BiomeArray`

## Internals
- Built-in commands now declare their names inside the class constructor, rather than accepting them as parameters. This improves code consistency.
- `NetworkSession` disconnect APIs now accept `Translatable|string` instead of `string` to allow localized disconnect messages.
- All external usages of `KnownTranslationKeys` are now removed. All localized messages are now sent using `Translatable` objects (usually from `KnownTranslationFactory`).

# 5.0.0-ALPHA8
Released 23rd January 2023.

## Core
- Updated `ext-pthreads` requirement to `^5.1.0`. This version improves performance, memory usage, includes BC-breaking API changes, and removes a lot of confusing behaviour.
  - See [`ext-pthreads` 5.0.0 release](https://github.com/pmmp/pthreads/releases/tag/5.0.0) for more information.
  - For the most part, plugins will be unaffected, unless using `Threaded` objects directly, or directly interacting with other pthreads APIs.

## API
### Overview
- It's now possible to specify a different disconnect reason and disconnection screen message. This is useful if you want to display a fancy disconnect screen, but don't want to spam the server log with useless information.

### `pocketmine\event\player`
- The following API methods have been removed:
  - `PlayerKickEvent->getReason()` - replaced by `getDisconnectReason()` and `getDisconnectScreenMessage()`
  - `PlayerKickEvent->setReason()` - replaced by `setDisconnectReason()` and `setDisconnectScreenMessage()`
  - `PlayerDuplicateLoginEvent->getDisconnectMessage()` - replaced by `getDisconnectReason()` and `getDisconnectScreenMessage()`
  - `PlayerDuplicateLoginEvent->setDisconnectMessage()` - replaced by `setDisconnectReason()` and `setDisconnectScreenMessage()`
- The following new API methods have been added:
  - `public PlayerKickEvent->getDisconnectReason() : Translatable|string` - returns the reason for the disconnection displayed in the console and server log
  - `public PlayerKickEvent->setDisconnectReason(Translatable|string $disconnectReason) : void` - sets the reason for the disconnection displayed in the console and server log
  - `public PlayerKickEvent->getDisconnectScreenMessage() : Translatable|string|null` - returns the message to be displayed on the disconnect screen (the message in `getDisconnectReason()` is used if null is returned)
  - `public PlayerKickEvent->setDisconnectScreenMessage(Translatable|string|null $disconnectScreenMessage) : void` - sets the message to be displayed on the disconnect screen (the message in `setDisconnectReason()` is used if null is passed)
  - `public PlayerDuplicateLoginEvent->getDisconnectReason() : Translatable|string` - returns the reason for the disconnection displayed in the console and server log
  - `public PlayerDuplicateLoginEvent->setDisconnectReason(Translatable|string $disconnectReason) : void` - sets the reason for the disconnection displayed in the console and server log
  - `public PlayerDuplicateLoginEvent->getDisconnectScreenMessage() : Translatable|string|null` - returns the message to be displayed on the disconnect screen (the message in `getDisconnectReason()` is used if null is returned)
  - `public PlayerDuplicateLoginEvent->setDisconnectScreenMessage(Translatable|string|null $disconnectScreenMessage) : void` - sets the message to be displayed on the disconnect screen (the message in `setDisconnectReason()` is used if null is passed)

### `pocketmine\network`
- The following API methods have changed signatures:
  - `NetworkSessionManager->close()` now accepts an additional `Translatable|string|null $disconnectScreenMessage` parameter.

### `pocketmine\player`
- The following API methods have changed signatures:
  - `Player->kick()` now accepts an additional `Translatable|string|null $disconnectScreenMessage` parameter, which is the message to be displayed on the disconnect screen (the message in `$reason` is used if null is passed)
  - `Player->disconnect()` now accepts an additional `Translatable|string|null $disconnectScreenMessage` parameter, which is the message to be displayed on the disconnect screen (the message in `$reason` is used if null is passed)

## Internals
- `NetworkSession` disconnect methods have been altered to allow specifying a different disconnect reason and disconnection screen message.

# 5.0.0-ALPHA9
Released 21st February 2023.

## Core
- Introduced timings for individual packet encoding.
- Network timings now cover more parts of the network system which weren't previously accounted for.

## API
### `pocketmine\block`
- Blocks are no longer required to explicitly specify how many type or state data bits they require. This is now automatically calculated using `RuntimeDataSizeCalculator`.
- The following API methods have changed signatures:
  - `Block->describeState()` now accepts `RuntimeDataDescriber` instead of `RuntimeDataReader|RuntimeDataWriter`
  - `Block->describeType()` now accepts `RuntimeDataDescriber` instead of `RuntimeDataReader|RuntimeDataWriter`
  - `Block->getRequiredStateDataBits()` is now `final`.
  - `Block->getRequiredTypeDataBits()` is now `final`.
  - `Leaves->__construct()` now `LeavesType $leavesType` instead of `TreeType $treeType`
- The following API methods have been added:
  - `public Leaves->getLeavesType() : LeavesType` - returns the type of leaves
- The following classes have been added:
  - `LeavesType` - an enum of all the different types of leaves
- The following classes have been renamed:
  - `BlockFactory` -> `RuntimeBlockStateRegistry` - this more accurately describes the purpose of the class
- The following API methods have changed behaviour:
  - `RuntimeBlockStateRegistry->register()` now throws a `LogicException` if a block does not properly reject invalid state data.

### `pocketmine\command`
- `SimpleCommandMap` now requires all commands to have a permission set when registered.
  - If you actually want to allow everyone to use your command (not advised), you can add a new permission to the `pocketmine.group.user` group, or use `default: true` for `plugin.yml` permissions.
- The following API methods have changed behaviour:
  - `Command->testPermissionSilent()` now returns `false` if there are no permissions associated with the command. This is to prevent commands with no permissions being usable by everyone, which has previously been a source of security issues.
- The following API methods have been added:
  - `public Command->getPermissions() : list<string>` - returns a list of permissions which grant usage access to this command. A user with one or more of these permissions will be able to invoke the command's `execute()` method
  - `public Command->setPermissions(list<string> $permissions) : void` - sets the permissions which grant usage access to this command. This should be used instead of `setPermission()` with `;` separators (which is now deprecated)

### `pocketmine\data\bedrock\block`
- The following API methods have been added:
  - `public static BlockStateData::current(string $name, array<string, Tag> $states) : BlockStateData` - creates a new `BlockStateData` instance with the current blockstate version

### `pocketmine\data\bedrock\block\upgrade`
- Blockstate upgrade schemas are now indexed by schema ID instead of Minecraft version. This is because the Minecraft blockstate version isn't consistently bumped when changes are made.
- `BlockStateUpgrader` now requires that every schema added must have a unique schema ID.
- The following API methods have been removed:
  - `BlockStateUpgradeSchema->getPriority()`
- The following API methods have been added:
  - `public BlockStateUpgradeSchema->getSchemaId() : int` - returns the schema ID of this upgrade schema, usually the number at the start of the JSON filename
- The following API methods have changed signatures:
  - `BlockStateUpgradeSchemaUtils::fromJsonModel()` now accepts `int $schemaId` instead of `int $priority`
  - `BlockStateUpgradeSchemaUtils::loadSchemaFromString()` now accepts `int $schemaId` instead of `int $priority`
  - `BlockStateUpgradeSchemaUtils::loadSchemas()` now accepts `int $maxSchemaId` instead of `int $currentVersion`

### `pocketmine\data\bedrock\item\upgrade`
- The following API methods have changed signatures:
  - `ItemUpgradeSchemaUtils::loadSchemas()` now accepts `int $maxSchemaId`
- The following API methods have been renamed:
  - `ItemIdMetaUpgradeSchema->getPriority()` -> `ItemIdMetaUpgradeSchema->getSchemaId()`
- The following classes have been added:
  - `ItemIdMetaUpgrader` - encapsulates handling for upgrading item string IDs and meta to newer versions
- The following API methods have been moved:
  - `ItemDataUpgrader->addIdMetaUpgradeSchema()` -> `ItemIdMetaUpgrader->addSchema()`
  - `ItemDataUpgrader->upgradeItemStringIdMeta()` -> `ItemIdMetaUpgrader->upgrade()`

### `pocketmine\data\runtime`
- The following interfaces have been added:
  - `RuntimeDataDescriber` - contract for symmetric APIs exposed by `RuntimeDataReader`, `RuntimeDataWriter` and `RuntimeDataSizeCalculator`

### `pocketmine\event\player`
- `PlayerPreLoginEvent` now supports setting separate log reasons (disconnect reason) and disconnect screen messages.
- The following classes have inheritance changes:
  - `PlayerPreLoginEvent` no longer implements `Cancellable`. This caused unexpected behaviour for most plugin devs due to default-ignoring cancelled events, forcing people to usually have to use `@handleCancelled` to handle the event when they wanted to use it.
- The following API methods have been added:
  - `public PlayerPreLoginEvent->getDisconnectScreenMessage(int $flag) : Translatable|string|null` - returns the message to be displayed on the disconnect screen for the specified kick flag, if set
  - `public PlayerPreLoginEvent->getFinalDisconnectScreenMessage() : Translatable|string|null` - returns the message to be displayed on the disconnect screen, taking into account the kick flags set
- The following API constants have been renamed:
  - `PlayerPreLoginEvent::KICK_REASON_BANNED` -> `PlayerPreLoginEvent::KICK_FLAG_BANNED`
  - `PlayerPreLoginEvent::KICK_REASON_PLUGIN` -> `PlayerPreLoginEvent::KICK_FLAG_PLUGIN`
  - `PlayerPreLoginEvent::KICK_REASON_PRIORITY` -> `PlayerPreLoginEvent::KICK_FLAG_PRIORITY`
  - `PlayerPreLoginEvent::KICK_REASON_SERVER_FULL` -> `PlayerPreLoginEvent::KICK_FLAG_SERVER_FULL`
  - `PlayerPreLoginEvent::KICK_REASON_SERVER_WHITELISTED` -> `PlayerPreLoginEvent::KICK_FLAG_SERVER_WHITELISTED`
- The following API methods have been renamed:
  - `PlayerPreLoginEvent->clearAllKickReasons()` -> `PlayerPreLoginEvent->clearAllKickFlags()`
  - `PlayerPreLoginEvent->clearKickReason()` -> `PlayerPreLoginEvent->clearKickFlag()`
  - `PlayerPreLoginEvent->getFinalKickMessage()` -> `PlayerPreLoginEvent->getFinalDisconnectReason()` (now used for logs only, if a disconnect screen message is set for the highest priority flag)
  - `PlayerPreLoginEvent->getKickMessage()` -> `PlayerPreLoginEvent->getDisconnectReason()` (now used for logs only, if a disconnect screen message is set for the flag)
  - `PlayerPreLoginEvent->getKickReasons()` -> `PlayerPreLoginEvent->getKickFlags()`
  - `PlayerPreLoginEvent->isKickReasonSet()` -> `PlayerPreLoginEvent->isKickFlagSet()`
  - `PlayerPreLoginEvent->setKickReason()` -> `PlayerPreLoginEvent->setKickFlag()`
- The following API methods have changed signatures:
  - `PlayerPreLoginEvent->setKickFlag()` (previously `setKickReason()`) now accepts `Translatable|string $disconnectReason, Translatable|string|null $disconnectScreenMessage = null` instead of `Translatable|string $message`

### `pocketmine\event\block`
- The following classes have inheritance changes:
  - `BlockPlaceEvent` no longer extends `BlockEvent`, and therefore no longer has `getBlock()`.
- The following API methods have been removed:
  - `BlockPlaceEvent->getBlockReplaced()` - this information is now provided in the `BlockTransaction` object returned by `BlockPlaceEvent->getTransaction()`
- The following API methods have been added:
  - `public BlockPlaceEvent->getTransaction() : BlockTransaction` - returns the transaction containing a list of changed block positions and the blockstates they will be changed to
- The following API methods have changed signatures:
  - `BlockPlaceEvent->__construct()` now accepts `BlockTransaction $transaction` instead of `Block $blockPlace, Block $blockReplace`

### `pocketmine\item`
- The following API methods have signature changes:
  - `Item->describeType()` now accepts `RuntimeDataDescriber` instead of `RuntimeDataReader|RuntimeDataWriter`

### `pocketmine\world\format`
- The following API methods have been renamed:
  - `Chunk->getFullBlock()` -> `Chunk->getBlockStateId()`
  - `Chunk->setFullBlock()` -> `Chunk->setBlockStateId()`
  - `SubChunk->getFullBlock()` -> `SubChunk->getBlockStateId()`
  - `SubChunk->setFullBlock()` -> `SubChunk->setBlockStateId()`

## Gameplay
### Blocks
- The following new blocks have been added:
  - Mangrove Leaves
  - Azalea Leaves
  - Flowering Azalea Leaves
  - Reinforced Deepslate
- Fixed incorrect drops of deepslate when mined without a Silk Touch tool.
- Bells now ring when hit by a projectile.

## Internals
- `build/generate-runtime-enum-serializers.php` now generates the following additional classes:
  - `interface RuntimeEnumDescriber`
  - `trait RuntimeEnumSizeCalculatorTrait`
- Block type/state data required bits are now calculated from `Block->describeType()` using `RuntimeDataSizeCalculator`.
- Commands now use an array for permissions internally, instead of a string separated by `;`.