路线图

Paper提供了一个丰富的API,具有广泛的功能,可以帮助你充分发挥服务器的潜力。 然而,为了给新功能和改进腾出空间,一些旧的API将被逐步淘汰。本页面 旨在记录任何计划中的API变更或可能即将到来的弃用。

未来计划

接口化的ItemStack

当你创建ItemStack时,你创建的是ItemStack的API表示。 然而,在某些地方你也可以获得由NMS对象支持的ItemStack。 这可能导致不一致性和不必要的维护工作,因为我们需要维护我们自己的ItemStack实现,并且还要 通过丑陋的方法支持NMS支持的对象,因为它不是一个简单的接口。

在未来,ItemStack将被转换为一个接口,允许开发者直接使用底层的 ItemStack,而不是通过API实现。

注意事项

• 避免直接扩展ItemStack类。
  • 不支持此类的自定义实现。

ServerPlayer重用

注意:仅适用于NMS使用,不适用于API。

避免直接存储玩家(ServerPlayer)实体实例。目前,在切换 世界时会重用玩家实例,但在未来,这种行为将恢复为匹配原版行为。API实体(包装器)将 继续工作,并且会自动替换其底层实例。

这样做是为了帮助减少在原版和Paper之间切换世界时可能出现的不一致性。

弃用政策

注意

强烈建议你避免使用任何标记为已弃用的API。

如果你继续使用已弃用的API,你的服务器可能会变得不稳定,可能无法按预期工作。 你也可能遇到性能问题和其他问题。为了确保插件获得最佳体验和长期 可用性,重要的是要跟上最新的API变更,避免使用任何标记为 弃用的API。

标记为@Deprecated的API不应该在你的代码库中使用, 因为可能有替代的API可以使用。虽然某些API可能在被弃用后仍然可以工作, 但不能保证这些API将来不会被标记为待移除。

@Deprecated
public void exampleMethod(); // 示例已弃用方法

标记为待移除

除了标记为@Deprecated外,API还可能被标记为forRemoval,并给出 @ApiStatus.ScheduledForRemoval版本。 计划移除的API应该只在Minecraft的主要版本更新中发生。 强烈建议你迁移到不使用计划移除的API。

应该注意的是,计划移除的API将给予足够的时间让插件开发者迁移 到其他API。

@ApiStatus.ScheduledForRemoval(inVersion = "1.20")
@Deprecated(forRemoval = true)
public void exampleMethod(); // 示例在1.20中标记为移除的方法

弃用原因

API可能因多种可能的原因而被弃用。 一些常见的API弃用原因是:

旧API

随着游戏的发展,API可能代表核心游戏中不再存在的概念。

旧API很可能在较新版本的游戏中无法正常工作和/或可能表现异常, 因此可能会被计划移除。

重复的API

由于Paper过去是从Spigot下游而来,它有时可能包含与Paper已有的API冲突的Spigot添加的API。 通常,Paper会弃用Spigot的API,转而使用自己的API。

然而,在上游提供更强大的API的情况下,Paper的API可能会被弃用。

过时的API

Paper致力于改进可能已经包含的API。在某些情况下,我们可能已经构建了新的 API作为另一个API的替代品。

过时的API预计在很长一段时间内都能正常工作,可能在相当长的时间内 不会被计划移除。