PocketMine-MP/changelogs/3.0.md

**For Minecraft: Bedrock Edition 1.4.0**

Plugin scheduler rewrite, RCON rewrite, performance improvements, improved idle memory usage

**While this release is nominally not an alpha, it is still not feature complete and does not include all gameplay features. Please do not create issues for missing gameplay features.**

This build has breaking API changes.
This release is the first to use the new merged versioning system. The PocketMine-MP version and the API version are now one and the same.

Please use our issue tracker to report bugs.

# 3.0.0
## Core
### General
- This release introduces a new dependency library called `Snooze`, which PocketMine-MP utilizes for managing notifications between threads. This library is currently utilized by command reading, RCON and RakLib, allowing faster response times to commands, reduced network latency, and better performance due to lack of need for polling.
- Fixed race condition causing `ServerKiller` to sometimes kill the server for no reason on shutdown.

### Dependency libraries
Requires the following libraries:
- [`pocketmine/raklib` `^0.12.0`](https://github.com/pmmp/RakLib/releases/0.12.0)
- [`pocketmine/spl` `^0.3.0`](https://github.com/pmmp/SPL/releases/0.3.0)
- [`pocketmine/binaryutils` `^0.1.0`](https://github.com/pmmp/BinaryUtils/releases/0.1.0)
- [`pocketmine/nbt` `^0.2.0`](https://github.com/pmmp/NBT/releases/0.2.0)
- [`pocketmine/math` `^0.2.0`](https://github.com/pmmp/Math/releases/0.2.0)
- [`pocketmine/snooze` `^0.1.0`](https://github.com/pmmp/Snooze/releases/0.1.0)

These libraries may individually have changes which are not recorded here. See their independent repository releases for their changelogs.

### Async pooling
- Async workers are now started dynamically when they are needed only, instead of being started immediately on startup. This allows reducing idle memory usage.
- AsyncPool now appropriately shuts down the workers when instructed to, instead of leaving it up to the ThreadManager to clean it up. This eliminates debug messages of shutting down async workers on server shutdown.
- Default maximum async worker memory limit has been lowered from 1024MB to 256MB.
- Async workers are now started using the options `PTHREADS_INHERIT_CONSTANTS | PTHREADS_INHERIT_INI`, which reduces idle memory wastage and works around some bugs in pthreads.

### Entities
- Fixed entities not being despawned when flagged, if they weren't scheduled for an update.

### Levels
- Seed handling is now always consistent between `pocketmine.yml` and `server.properties`.
- Fixed generation bugs in imported LevelDB worlds where the classpath was saved into level.dat.
- Generators for levels are no longer created on the main thread, reducing memory usage.

### Plugins
- Plugin data is now stored under `<data dir>/plugin_data` by default on new installations, instead of in `<plugins dir>`. This behaviour does not affect existing installations by default - if you want to enable it, set `plugins.legacy-data-dir` to `false` in `pocketmine.yml`.

### RCON
RCON has been almost completely rewritten in this release.
- Now event-driven (using Snooze) instead of poll-based, improving performance.
- Fixed segmentation fault when stopping the server with RCON enabled.

## API
**WARNING: Dependency library API changes are not listed here. See their individual release notes for changes (linked above in the Core section).**

### API versioning changes for plugins
The way that the API versioning is done has changed. Now the API version is synonymous with the PocketMine-MP version.
Plugin compatibility is determined by the following:
- Take the base version, and strip any metadata (everything after the `+` sign, for example `3.0.0+dev.1191` becomes `3.0.0`).
- Assert that:
  - The major versions is the same
  - The server's minor version is greater than or equal to the plugin's
  - The server's patch version is greater than or equal to the plugin's

Currently there is no support for locking version by metadata, although this could be implemented if it is a wanted feature.

### General
- `Server->getCodename()` and `\pocketmine\CODENAME` have been removed.
- Added API method `Server->getTickSleeper()`, which returns a `\pocketmine\snooze\SleeperHandler` instance.
- `Server->getIp()` now returns `0.0.0.0` if not set.

### Block
- Added `Block->getXpDropForTool()`.

### Entity
- Calling `scheduleUpdate()` on an `Entity` after it has been `close()`d will now cause an exception to be thrown.
- `Entity->motionX`, `Entity->motionY` `Entity->motionZ` have been removed in favour of an `Entity->motion` `Vector3` field. This also applies for the `lastMotion` fields.
- `Entity->isInsideOfWater()` has been renamed to `isUnderwater()`.

### Events
- Added support for `@softDepend` annotation on event handlers, which allows the event handler to not be registered if the dependency plugin is not loaded.
- Added support for `@notHandler` annotation for `Listener` methods to indicate that such methods are not event handlers.
- Typehints have been applied to the events API to PHP 7.2 standards.
- Fixed preventing effect expiry using `EntityEffectRemoveEvent` not being reflected on the client.
- `EntityDamageEvent` API has significant changes. The general purpose of this is to split up base damage from modifiers.
  - Added methods `getBaseDamage()`, `setBaseDamage()`, `getOriginalBaseDamage()`, `getModifiers()`, `getOriginalModifiers()`
  - `setDamage()` renamed to `setModifier()`, and type parameter is now mandatory
  - `getDamage()` renamed to `getModifier()`, and type parameter is now mandatory
  - `getOriginalDamage()` renamed to `getOriginalModifier()`, and type parameter is now mandatory
  - Removed `MODIFIER_BASE` constant
  - Constructors now accept: `float baseDamage`, `float[] modifiers` instead of just `float[] modifiers`
- Added `BlockBreakEvent->getXpDropAmount()` and `BlockBreakEvent->setXpDropAmount()`.

### Inventory
- `InventoryTransaction->getCreationTime()` has been removed.
- `EntityInventoryChangeEvent` and `EntityArmorChangeEvent` are no longer fired during entity inventory intialization.

### Item
- Methods `isPickaxe()`, `isAxe()`, `isSword()`, `isShovel()`, `isHoe()`, `isShears()` have been removed. These should be replaced with `instanceof` checks for the relevant classes.
- Removed `Item->useOn()`. This has been superseded by new methods used for handling durability changes.
- Added hooks `Item->onDestroyBlock()` and `Item->onAttackEntity()`. These are called when a player uses the item to destroy a block or attack an entity respectively. This is used in the core code for updating durability.
- `Item->pop()` now accepts an optional count parameter.
- `Enchantment` now has separated primary items (which can be enchanted directly) and secondary items (which can be enchanted on an anvil). The constructor of `Enchantment` has been updated to reflect this.
  - Removed `Enchantment->getSlot()` and `Enchantment->hasSlot()`.
  - Added `Enchantment->getPrimaryItemFlags()`, `Enchantment->hasPrimaryItemFlag()`, `Enchantment->getSecondaryItemFlags()` and `Enchantment->hasSecondaryItemFlag()`

### Level
- `Biome` classes have been moved to `pocketmine\level\biome` namespace. This is in preparation for future work on Levels which requires biome information (such as weather conditions).
- `WeakPosition` has been removed.
- Added `Level->getBiome()`.
- `Level->getSafeSpawn()` now always returns a `Position` instance.
- `Level->getBlockExtraData()` and `Level->setBlockExtraData()` have been removed (as well as their associated `Chunk` methods).
- `ChunkManager->isInWorld()` now accepts integers instead of floats.
- Added `SubChunkIteratorManager->invalidate()`.

#### Generator
- `BiomeSelector` has been refactored to make it simpler and more robust.
- Generator-management methods `registerDefaultGenerators()`, `addGenerator()`, `getGeneratorList()`, `getGenerator()`, and `getGeneratorName()` have been moved from `Generator` to a new `GeneratorManager` class.
- Static noise functions in the `Generator` base class have been moved to `Noise` instance methods.
- Added static method `Generator::convertSeed()`, which converts an int or string into a numeric seed for generation.

### Network
- `SourceInterface->process()` no longer returns a value.

### Plugin
- `PluginBase->getResources()` now returns an associative array where the index is the path to the resource relative to the plugin's `resources` directory.
- `PluginLoader`s have been almost completely rewritten to make them simpler and more robust.
  - `PluginManager->registerInterface()` does not return anything, and now accepts a `PluginLoader` instance instead of a `string`.
  - `PluginLoader`:
    - `getPluginFilters()`, `enablePlugin()` and `disablePlugin()` are removed.
    - `loadPlugin()` responsibilities are now solely confined to doing whatever is necessary to make the plugin's classes visible by the server, and does not emit log messages or check for data directories.
    - Added method `getAccessProtocol()` which determines what prefix to apply to the plugin path to access the files inside it (for example `phar://`).
  - `PluginBase->init()` and `PluginBase->isInitialized()` have been removed.
  - `Plugin` interface now declares a signature for the constructor which implementations must comply with.
  - `Plugin` interface now declares `setEnabled()`.
- It is now possible to create a custom `Plugin` implementation without requiring a custom `PluginLoader`.

### Scheduler
This release features major changes to how plugin task scheduling works.
- Removed `Server->getScheduler()`. All plugins now have their own scheduler which is accessible using `Plugin->getScheduler()`. Aside from being syntactically more concise and pleasant, this also allows much more effective management of tasks when plugins are disabled.
- Removed `PluginTask` class, because it's now unnecessary. Previously it was required to allow the server to delete tasks associated with a plugin when the plugin was disabled. With plugin-owned schedulers, this is no longer a requirement. Plugins may now utilize the `Task` class as a base if they like.
- Added `Server->getAsyncPool()`. Since the global scheduler does not exist any more, it does not manage the server's `AsyncPool` any more. Additionally, `ServerScheduler` was previously bloated by a lot of `AsyncTask` related methods, which are now not necessary because direct access to `AsyncPool` is granted instead.
- `ServerScheduler`:
  - `ServerScheduler` has been renamed to `TaskScheduler` since it is now a general-purpose task scheduler which is non-dependent on the user. This allows much greater flexibility and also makes it possible to unit-test.
  - All `AsyncTask`/`AsyncPool` related methods have been removed - the task scheduler does not manage the async pool anymore.
    - Calls to `Server->getScheduler()->scheduleAsyncTask()` should be replaced with `Server->getAsyncPool()->submitTask()`.
    - Calls to `Server->getScheduler()->scheduleAsyncTaskToWorker()` should be replaced with and `Server->getAsyncPool()->submitTaskToWorker()`.

### Tile
- Calling `scheduleUpdate()` on a `Tile` after it has been `close()`d will now cause an exception to be thrown.
- Tile NBT is now ephemeral and is not retained after creating the tile.
  - `Tile->namedtag` has been removed.
  - `Tile->saveNBT()` now returns a new `CompoundTag` containing saved data.
  - Added new protected methods `Tile->readSaveData()` and `Tile->writeSaveData()`. These should be overridden to add or read tile-specific data, instead of overriding `saveNBT()` and `__construct()`.

### Utils
- Added `MainLogger->getFormat()` and `MainLogger->setFormat()` to allow manipulating console output format.

## Gameplay
### General
- Fixed a range of block collision issues stemming from off-by-one errors when fetching areas.

### Blocks
- Fixed a crash which occurred when leaving a bed which was broken and replaced during sleep.
- Fixed dark oak and acacia saplings growing into oak trees - now they will not grow at all (they need to be implemented).
- Saplings now take light level into account when trying to grow.
- Ores and other blocks now drop experience when broken with an appropriate tool.

### Entities
- Fixed dropped items not being correctly destroyed by fire, cacti and other damage sources.

### Generation
- Grass no longer generates as the top layer of ground cover in river biomes.
- Ocean biomes now use gravel instead of grass+dirt for ground cover.
- Reduced maximum elevation of plains biomes to make them less bumpy.
- Snow layers and other can-be-flowed-into blocks no longer generate underwater.

### Items
- Buckets are no longer able to delete any block by replacing it with water.
- Dried Kelp, Bleach, Nautilus Shell and Heart of the Sea items are registered (although crafting recipes for these are not yet available).
- Implemented `Vanishing` enchantment.
- Implemented Totems.

### World
- Fixed explosions sometimes leaving behind air blocks with non-zero damage values.

# 3.0.1
- Fixed error when players move things around in the crafting grid after plugins cancel `PlayerInteractEvent` on crafting tables.

# 3.0.2
- Fixed memory dumps not showing private properties of parent classes.
- Fixed a memory leak when cancelling all tasks in the `TaskScheduler`.
- Fixed scheduled task timings showing `Unknown` as the plugin name.

# 3.0.3
- Fixed possible crash in Sign when placed by a plugin.
- Fixed slightly-damaged and very-damaged anvils dropping incorrect items.
- `Living->applyPostDamageEffects()` is no longer called if the mob died from an attack.
- Cooldown for mob attack is now reset prior to applying post-damage effects.
- Added constant `ItemIds::MUTTON` to resolve crashes using PC worlds.
- Fixed emerald ore not dropping XP when broken with a valid tool.
- Fixed mobs getting crazy vertical knockback if attacked while airborne.
- Fixed XP orbs continuing to follow dead players.

# 3.0.4
- Fixed RCON spamming the console when a client does not disconnect correctly.
- Fixed dropping chunk cache unnecessarily when no blocks need to be updated on a chunk.
- Fixed outdated block updates getting sent on chunks replaced using `setBlock()`.

# 3.0.5
- Fixed not being able to place blocks where a player died and has not yet respawned (#2265).
- Fixed mob death animation not being played when `Entity->kill()` is called directly or `/kill` is used.
- Fixed viewers of different halves of double chests not seeing changes made by viewers who opened the other half (#2261).
- Fixed bugs setting items into wrong indexes when double chest halves have differently sized inventories.
- Fixed `getConfig()` crashing when called when the plugin's data directory doesn't exist.
- Fixed a possible exploit with keychain signing for XBL login.

# 3.0.6
- Fixed invalid keys in `.properties` config files being considered as invalid strings.
- Fixed whitespace between key and value `key = value` being invalid in `.properties` config files.
- Fixed a bug in exception message when an invalid permission type is written for a command in plugin.yml.
- Properly fixed newline issues when parsing event handler annotations - `@notHandler` will now work as expected when CRLF line endings are used.
- Fixed `PluginManager->registerEvents()` registering functions as event handlers declared by parent classes which are not `Listener` instances (#2293).

# 3.0.7
- Fixed setting spawn points in un-generated chunks causing the player to fall out of the world.
- Fixed spawn protection deactivating when there are no ops set (this was an unwanted/unexpected feature, so it's considered a bug).
- Fixed cursor items not getting dropped when closing the inventory or dying.
- Fixed more issues with blocks with invalid metadata appearing as update! blocks.
- `Entity->setNameTagAlwaysVisible()` now works (although nametags will still not be shown if the entity is invisible, due to a behavioural change in Minecraft PE).
- Fixed errors passing zero motions to projectiles in some cases.

# 3.0.8
- Fixed player on-ground state not updating when moving horizontally. This allowed fly hacks with the built in anti-cheat, and also affected some third party anti-cheat plugins due to the effect on `inAirTicks`.
- Fixed knockback. PC 1.9-style knockback was mistakenly introduced in 3.0.3. This has now been reverted back to the old 1.8-style behaviour.

# 3.0.9
- Cleaned up odd behaviour of `/kill` due to old broken code.
- Fixed patch level check for plugin APIs not allowing lesser patch versions on greater minor versions.
- Fixed `/timings paste`. This now reports directly to the timings host instead of using Ubuntu Pastebin.
- Minor code cleanups in various places.
- Zip resource packs will now give slightly less useless errors - errors for broken manifest have been separated from those with fields missing, and now reports why decoding failed if it failed.

# 3.0.10
- Syntax error crashdumps will no longer be reported to the crash archive.
- Chunk sending is now fault-tolerant. Before this release, any error on a worker during async chunk sending (such as memory errors caused by pthreads) would cause that chunk to never get sent, resulting in invisible and missing chunks. Levels will now attempt to retry chunk prepare when a task crashes, which should fix most invisible chunk bugs.
- `MainLogger` now logs exception stack traces in a synchronized block to ensure that they are coherent when log messages are emitted from multiple threads at once.
- `AsyncTask->isCrashed()` now returns `true` if a fatal error occurred during the task execution.

# 3.0.11
- `DropItemAction` will now consider itself invalid if attempting to drop a null item.
- Fixed leaking globally broadcasted Level packets when no players are on the server.
- Fixed title bar not being cleared on server stop on some terminals.
- Fixed `FallingBlock` saving corrupted data.
- Fixed the structure of `GuiDataPickItemPacket`.
- Cleaned up some code in `OfflinePlayer`.
- Splash potions no longer apply effects to dead (but not yet respawned) players.
- Coal ore no longer drops XP when mined with a silk touch tool.
- Item entities now cannot be picked up when a negative pickup delay is used.

# 3.0.12
- `Config` keys which are considered bools by YAML 1.1 will no longer be transformed into 1 or 0.
- Fixed painting motives not getting saved.
- Fixed cacti spewing items when placed in some invalid locations.
- Fixed entity fire damage not applying in the void.
- Fixed entities not getting updated appropriately in some conditions.