Roadmap
Paper offers a rich API that has a wide range of features that can help you unlock the full potential of your server. However, in order to make room for new features and improvements, some of the older APIs will be phased out. This page is intended to document any future API changes that are planned or possible deprecations that may be coming up.
Future Plans
Interface ItemStacks
When you create ItemStacks, you create an API representation of an ItemStack. However, there are also places where you can obtain an ItemStack that is backed by an NMS object instead. This can lead to inconsistencies and unnecessary upkeep since we need to maintain our own implementation of ItemStack and support the NMS backed object using ugly methods due to it not being a plain interface.
In the future, ItemStack will be converted to an interface that allows developers to use an underlying ItemStack directly instead of going through the API implementation.
Precautions
- Avoid directly extending the
ItemStack
class.- Custom implementations of this class are not supported
ServerPlayer Reusing
Note: Only applies to NMS usage, will not apply to API.
Avoid directly storing player (ServerPlayer) entity instances. Currently the player instance is reused when switching worlds, however, in the future, this behavior will be reverted to match vanilla behavior. API entities (wrappers) will continue to function and will have their underlying instance replaced automatically.
This is being done to help reduce possible inconsistencies between world switching between Vanilla and Paper.
Experimental API
Teleport Flags
Teleport flags offer a way to teleport entities whilst being able to customize behavior. This allows you to do things like teleport players using relative flags and being able to retain passengers.
This API is currently finalized and will be marked as stable in a future release.
Player Teleportation
Teleport a player relatively, preventing velocity from being reset in the X, Y, and Z axis.
player.teleport(location,
TeleportFlag.Relative.X,
TeleportFlag.Relative.Y,
TeleportFlag.Relative.Z
);