序表

《癸卯重修增廣箋註<事件監聽大典>》序

事件监听,是 Bukkit 插件开发领域内最为重要的话题之一。开发者所编写的每一段代码,都需要执行的入口。通常,程序的起点是 main 函数,但插件不然。onLoad 和 onEnable 函数固然是插件运行的开端,但它们只会在刚加载时被调用一次。BukkitScheduler 任务调度器可以让代码定时、延时执行,但失之刻板,无法在特定情景下触发,只能一次次地循环。onCommand 方法的确能响应玩家的特定指令,但 Bukkit 框架中的指令系统过于简陋,令人不忍卒读。
因而事件系统是不可或缺的。通过监听事件,可以让一段代码在某个特定情景下被即时触发。事件对象内蕴许多与该情景有关的信息,而不像指令系统那样,留下解析的工作给用户。监听器仅在事件发生时被调用,不会像定时任务那样屡屡空转。如果能够恰当地运用事件监听器,即可在关键的节点附上插件的逻辑,使得种种波谲云诡的想法得到实现。
虽然如此,仍有许多开发者不懂得如何使用事件系统。也许这些开发者初入 Bukkit 插件开发领域不久,尚未掌握部分词汇术语。加以事件相关的 API 文档本身就质量欠佳,不乏舛错,益加俾人生疑。比如 PlayerToggleSprintEvent,把未来注为旧有,BlockPistonRetractEvent,将收回抄作推出。还有部分文档词不达意、句不成篇。未设计完的草稿,打上 @deprecated 记号就杂厕于过时文档之中(曾经的 EntityPlaceEvent)。过时的方法,经过更新后已经紧跟上最新版本了,却又不去掉过时标签(PlayerEditBookEvent)。如此种种,更让人无法分辨。
在 2017 年的 PVPIN 社区中,我借由 Google Blockly 积木,首次接触到了 Bukkit API 的事件系统。彼时,我只了解一些简单的 JavaScript 语法,仅会堆砌积木,不通程序设计的原理。一次遇到 event.setCancelled(true); 语句,自知是取消事件,使之不再发生。想要修改该语句,欲覆盖前人操作之结果,俾已被取消的事件在服务器内发生。怎料积木中惟有“取消事件”,却无“不取消事件”。一时窘然。承蒙 czm 前辈照拂,晓我以 setCancelled(false); ,我方知 Cancellable 接口之含义,第一次读懂了 JavaDoc 文档。此后我尝试使用 GYHHY 道席所制的自定义监听积木,监听了积木中所未囊括的 SlimeSplitEvent 。那时我才知道,PVPIN 自带的积木只囊括了几十个常用事件的监听器,对于全 Spigot API 甚至是全 Paper API 来说,实在是沧海一粟。故此,我不知天高地厚,欲将所有事件、所有方法全部用积木表示出来,以便其余不懂得如何阅读 JavaDoc 的用户使用。
遂乃有《EventListeners——事件监听大典》,它是不才 2018 年在 PVPIN 社区利用 Google Blockly 编辑器所纂的一个小项目。拙作以事件监听器积木的形式列出了时为最新的 1.12.2 版本中所有事件的全限定名、触发时机,并对事件类所提供的方法作注。随着 PVPIN 的瓦解,该项目已经亡佚不存。现基于 1.16.5 版本的 Spigot API 对原作予以重修增广。
本项目根目录为一个 Maven Project ,用于读取 Spigot API 的 JavaDoc 信息,并转换为可以被 GitBook 读取的 MarkDown 格式,再按照一个标准 GitBook 项目的文件结构进行输出。这些 JavaDoc 是 Spigot BuildTools 在构建服务端以后所留下的,为此,用户在运行本项目之前必须首先在本地运行 Spigot BuildTools 构建一个 1.16.5 或以上版本的服务端。此后在 net.pvpin.eventlisteners.ClazzParser 源代码中修改 JAVADOC_DIR 字段的值为本地 BuildTools 运行后得到的 BuildTools/Spigot/Spigot-API/src/main/java/ 这一文件夹的路径,比如 C:\\Users/williamshi/Documents/Code/Minecraft/BuildTools/Spigot/Spigot-API/src/main/java/ 即是鄙人本地计算机上的路径。其次,需要在 net.pvpin.eventlisteners.Main 中指定将用于存放 MarkDown 文件的目录路径。本项目中,这一文件夹为 EventListeners/docs 。同理,再次需要指定 SUMMARY.md 的路径以便输出,本项目中为 EventListeners/SUMMARY.md 。
在恰当配置了路径并直接在 Java IDE 中运行 net.pvpin.eventlisteners.Main 类的 main 函数以后,EventListeners/ 文件夹中即有一个完整的 GitBook 项目结构。目前本项目即基于此结构加以修缮而成,并在 SUMMARY.md 中将页面重新分组。
区区窃不自揆,希望昭著文档之本意,刊正谬误,舍短取长。晦涩的言辞,加以注释,抽象的论述,辅以示例。屏退谬论,昌明各个事件的真正功用,是我所愿也!本项目主要以对 JavaDoc 的翻译为主,同时旁缀补缺,添加译注,以便读者查阅。然而事件细节实在非我一人所能穷尽,我自知才疏学浅,见识粗鄙,故而仅能抛砖引玉,尚要仰仗各位道席予以雅正。
如您发现翻译不确切、译注脱离实情等一应问题,烦请在 GitHub 项目(https://github.com/William-Shi233/EventListeners)提出 Issue 或发送 Pull Request 斧正。如您有不刊之论愿意赐教,望您于 QQ 群 681811254 启沃为盼,诠才不胜屏营感激之至,顿首顿首。

進《癸卯重修增廣箋註<事件監聽大典>》表

PVPIN Studio 成员臣 William_Shi 跪奏,编辑《事件监听大典》告成,恭呈宸览,臣谨奉表恭进者。
伏惟“子入太庙每事问”,即云先进鸿才,未能生而知礼,后生晚辈,惟愿困而学之。文档汇一代宏才,集百年定论,或言方法功用,或语接口行为。架构可穷,坐看矿艺万里之世,细节尽备,探骊代码数句之章。倘闭户下帷,推敲终日,悉毁典籍,尽燔旧闻,固能管窥一斑,怎奈蹉跎岁月,所谓“思无益不如学”是也!然文档系英文所著,多有语言不通,加以汗漫无边,舛错间厕。或脱,或漏,或讹,或衍。别有抄袭通篇,不论方法之名,阔谈己观,未知高论所据。注疏同经典抵牾,文档与实情各异。未成之草稿,冠以过时之名,已订之文辞,杂于故纸之侧。是以臣与纂修诸同列开馆排辑,译文档为汉语,首尾既具,用为初稿,公慎讨论,辨析谬误。艰深之处,多为旁注,抽象之说,再添示例。伏愿参观文档,堪充旁征,有益于编程焉。
纂成文档十一卷,二百四十三篇,谨奉表随进以闻。
公元二千零二十三年,闰二月。
PVPIN Studio 成员 William_Shi
开列在事者职名:
监理:
PVPIN Studio 组长 Rain_Effect
银河系气功开发协会 组长 yumc
正总裁:
PVPIN Studio 成员 William_Shi
副总裁:
原任 PVPIN 社区成员 椎名淅雨
总纂:
PVPIN Studio 成员 HopeLight
协修:
PVPIN Studio 成员 Tao
校对:
原任 PVPIN 社区成员,今任 Alicorn Union 组长 青蛙的名单
PVPIN Studio 成员 Banaira
PVPIN Studio 成员 Eustia_Saint
PVPIN Studio 成员 Minamototennsai
Last modified 1mo ago