跳到主要内容

事件

Paper API 中的事件有几个要求。

备注

请注意,虽然并非所有现有事件都遵循这些准则,但所有新的和修改的事件都应该遵守它们。

所有新事件都应该放在 io.papermc.paper.event 包(或其子包)中。

构造函数

所有新添加的构造函数都应该使用 @ApiStatus.Internal 注解,以表明它们不被视为 API,可以随时更改而不会发出警告。

如果要替换的构造函数没有被移除,应该使用 @Deprecated@DoNotUse 标记。

可变性

某些 API 类型是"可变的",这可能会导致事件中出现意外行为。像 LocationVector 这样的可变类型在事件中的"getter"返回时应该被克隆。

HandlerList

要使事件类或其任何子类可以被监听,必须有一个 HandlerList 字段,包含一个实例和用于获取它的静态方法。具体细节请参见 Event 的文档。这个字段应该是静态的和 final 的,命名为 HANDLER_LIST

还要考虑不要在每个事件上都放置 HandlerList,而是放在一个"公共父类"事件上,这样插件可以监听父事件并捕获任何子事件,同时也可以单独监听子事件。

其他注意事项

  • 在大多数情况下,类型为 ItemStack 的新参数或方法返回值不应该是 @Nullable,而应该接受一个空的物品堆。