跳转至

1.绪论

​ PySpigot是一种允许在Minecraft服务器运行Python脚本的Spigot插件，可以灵活的调用API、捕捉事件、注册命令、生成占位符、调用数据库等。

​ Spigot API是服务端为我们提供的二次开发接口，通过这个接口，我们可以捕捉发生的事件，并且进行多种动作。在PySpigot中我们可以直接地调用Spigot API来完成我们想要的信息获取和操作，还可以完成对发生事件的捕捉。除了Spigot API以外，各种插件同样也为我们提供了这些接口，甚至是可以实现多个插件的协调配合。

​ PySpigot程序设计的目的是，通过Python脚本调用各类API完成信息的读取和修改，从而实现既定的功能，这本质上与直接开发Spigot插件没有什么不同。这就要求我们既要掌握Python程序设计方法，又要能够在Javadoc中找到API调用方法。

​ 本“入门道场”将通过五章来帮助各位读者掌握PySpigot的基本编程方法。第一章介绍PySpigot基本情况和开发环境配置；第二章夯实Python语法基础，强调面向对象程序设计；第三章介绍如何学会找到并调用所需的API；第四章将带领读者初步的编写程序，掌握各个模块使用方法；第五章将介绍如何使用Util2库简化开发；第六章将介绍如何编写图形菜单和捕捉玩家输入；第七章将结合具体情境帮助读者进行练习。

​ 在进行“入门道场”的“试炼”之前，请先具备一定的Python程序设计能力。初学者可根据菜鸟教程中“基础教程”学习，曾学过其他编程语言者可在简单阅读了解语法区别后开始学习。由于Jython仍停留在Python 2.7，所以请读者注意可能的区别，拿不准时多进行搜索。

​ 在本“入门道场”中，会特别强调利用面向对象的程序设计方法。了解Python的读者可能会疑惑，一般作为脚本来执行的Python似乎并不会特别的进行面向对象的程序设计。虽然Python在使用上可能有这样的倾向，但重要的是Java是“非常面向对象”的语言，注意面向对象会使程序更具一致性。同理，在本“入门道场”中变量可能使用的是更Java的而不是更Pythonic的格式，但这可以根据您的自身喜好决定。

1.1 配置开发环境

​ PySpigot是一个Python脚本引擎，它允许您编写Python脚本，这些脚本可以与Bukkit以及Minecraft服务器的其他API无缝交互，无需编写插件。脚本在运行时可以完全访问Java类路径（这意味着一切皆有可能！），并且还可以访问PySpigot的管理器，这些管理器可以使编写脚本变得更加容易。——翻译自PySpigot文档

1.1.1 配置Java环境

​ Java是Minecraft Java版的开发语言，因此在配置客户端和主要服务端前都离不开配置Java环境。在启动器没有自动安装的时代，这成为阻挡广大“熊孩子”的首个门槛。

​ 时下很多启动器已内置自动安装功能，但是在控制台输入java并不一定有正确的反应，这是因为启动器内置的Java并不在环境变量中。当然，也可以通过绝对路径来访问。您可输入java --version来测试。

1
2
3
openjdk 21.0.5 2024-10-15
OpenJDK Runtime Environment (build 21.0.5+11-Ubuntu-1ubuntu120.04)
OpenJDK 64-Bit Server VM (build 21.0.5+11-Ubuntu-1ubuntu120.04, mixed mode, sharing)

​ 如果您没有出现类似提示，或版本低于21，则需要安装Java。若存在多种Java版本，您可参考此博文。

​ 对于Debian系发行版用户，可直接使用sudo apt install openjdk-21-jdk。对于Windows用户，请下载Microsoft Build of OpenJDK 21中适用于您的操作系统和架构的.msi文件，然后双击安装。

​ 安装完毕后再次尝试java --version，应当出现正确的显示信息。

1.1.2 配置Paper服务端

​ PySpigot需要在Minecraft版本在1.16及以上的Spigot和Paper服务端运行，考虑到与DC的一致性，本文将介绍Paper的基本配置方法。

初始化Paper服务端

​ PaperMC 通过快速、安全的软件和扩展的插件 API 改善了 Minecraft 的生态系统，作为使用最广泛、性能最高且稳定的软件，提供快速发布和有用的支持。请在这里下载Paper服务端，并将.jar文件移动到您拟定的工作目录。

​ 首先，尝试首次启动Paper服务端：

1
java -Xmx4G -Xms4G -jar paper.jar --nogui

​ 运行后生成“eula.txt”文件，修改内容同意EULA：eula=true。

​ 然后再次启动服务端，等待生成服务器文件和世界，之后stop关闭服务端。恭喜您，您现在已经成为一位“服主”啦！当在测试服务端内调试时，不要忘了在控制台处给予自己OP权限：/op <玩家名>。

​ 为了方便下次启动，建议您将命令内容存为.sh文件（Windows为.bat文件）。在下次启动时可直接执行。

下载安装PySpigot

​ 请在GitHub Releases页面下载最新版本的PySpigot，然后将其移入~/plugins文件夹。启动服务端后可见PySpigot调试信息。因为PySpigot已内建Jython，所以我们不用像学习Python一样单独安装任何解释器。

1.1.3 配置VSCode编辑器

​ Visual Studio Code是一款由微软开发且跨平台的免费源代码编辑器，其社区版本为VS Codium。VSCode具有诸多强大的扩展，对于PySpigot开发具有良好的辅助作用。读者也可按照自己的喜好选用其他的编辑器或IDE。

​ 首先，根据您的操作系统和系统架构下载VSCode并安装。

​ 其次，打开VSCode的“扩展”，安装以下扩展：

  1. Chinese (Simplified) (简体中文) Language Pack for Visual Studio Code；
  2. Python
  3. Pylance
  4. 对于不使用本地服务器的读者，还推荐您安装“Remote - SSH”。

​ 接着，我们进入~/plugins/PySpigot/scripts创建一个hello.py，并用VSCode打开（或者干脆设为默认打开方式），编写对我们最爱的世界问好吧：

1
2
3
4
5
6
7
import pyspigot as ps

def onCommand(sender, label, args):
    sender.sendMessage('Loveless World!')
    return True

ps.command.registerCommand(onCommand, 'hello')

​ 现在我们利用命令来使服务端加载他/pyspigot load hello.py。

​ 太棒了！您已经完成第一个PySpigot程序了！输入/hello是不是就会有显示了？PySpigot在编写和调试上具备十足的便捷性。但至于ps.command是什么，sendMessage方法怎么查，就是我们接下来要逐步介绍的了。

​ 高兴之余，刚才程序的第一行编辑器大大的波浪线似乎提示我们配置工作并未结束。这是因为编辑器并未检索到pyspigot这一插件内建库，对于其他的Java路径也会产生这类问题。接下来我们就来修复强迫症问题：

  1. 在VSCode中“文件”点击“打开文件夹”，选择~/plugins/PySpigot/
  2. 找到“.vscode”文件夹，若没有则新建
  3. 新建settings.json文件，并将以下内容复制进去，然后保存
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
{
    "python.autoComplete.extraPaths": [
        "python-libs" // 库位置
    ],
    "python.analysis.extraPaths": [
        "python-libs"
    ],
    "python.analysis.diagnosticSeverityOverrides": {
        "reportMissingImports": "none" //忽略导入库报错
    }
}

1.2 PySpigot简介

1.2.1 PySpigot文件结构简介

​ 刚才粘贴的时候，细心的读者就会发现“python-libs”这一文件夹。下边我们就来简单介绍PySpigot的文件结构：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
plugins/
├─ PySpigot/ 
│  ├─ configs/ 
|  |  ├─ test.yml
|  |  └─ ...
│  ├─ java-libs/ 
|  |  ├─ lib-example.jar
|  |  └─ ...
|  ├─ logs/ 
|  |  ├─ test.log
|  |  └─ ...
|  ├─ python-libs/ 
|  |  ├─ lib-example.py
|  |  └─ ...
|  ├─ scripts/ 
|  |  ├─ test.py
|  |  └─ ...
|  ├─ config.yml 
|  └─ script_options.yml 
└─ ...
  • configs：保存所有的ConfigManager生成和读写的配置文件
  • java-libs：存放开发所需的Java库文件
  • logs：脚本运行时的控制台输出，可查看报错等内容
  • python-libs：Python库，一般是自行编写或从外部下载，经常提到的util2库就是放在这里的
  • scripts：放置脚本的主程序，PySpigot也会检索所有子文件夹
  • config.yml：PySpigot插件的配置
  • script_options.yml：逐个脚本的设置

1.2.2 PySpigot管理器简介

​ PySpigot有各种管理器，可从pyspigot库（亦称作PySpigot Helper Module）导入。

管理器 说明 使用
Script Manager 脚本管理器，管理各脚本的加载、卸载和状态 ps.script
Listener Manager 监听器管理器，监听各类Spigot API和插件的事件，如打开容器 ps.listener
Command Manager 命令管理器，注册和注销命令 ps.command
Task Manager 任务管理器，创建同步、异步、回调、定时重复任务 ps.scheduler
Config Manager 配置管理器，读取、写入配置文件，可用于存储数据 ps.config
Database Manager 数据库管理器，与MySQL, MariaDB, PostgreSQL, MongoDB交互 ps.database_manager()
Redis Manager Redis管理器，用于存储临时性缓存等 ps.redis_manager()
Protocol Manager ProtocolLib管理器，用于处理数据包，实现如让玩家改变俯仰角等 ps.protocol
Placeholder Manager 占位符管理器，通过PlaceholderAPI显示占位符 ps.placeholder

表格中“使用”部分已假设import pyspigot as ps。当然也可以通过路径等方式导入。

​ 其中，前5个是最重要的管理器，脚本功能的实现离不开它们，作为PySpigot程序的开发者应该尽量全部掌握。

1.2.3 PySpigot常用命令

​ PySpigot有一系列常用命令，帮助我们开发和调试脚本。

功能 命令
/pyspigot help 显示命令帮助
/pyspigot info <脚本名> 显示脚本信息
/pyspigot list 列出所有脚本
/pyspigot load <脚本名> 加载指定脚本
/pyspigot reload <脚本名> 重载指定脚本
/pyspigot unload <脚本名> 写在指定脚本
/pyspigot loadlibrary <文件名> 加载Java库文件
/pyspigot reloadall 重载所有脚本
/pyspigot reloadconfig 重载所有配置文件

所有脚本名要以文件名.py结尾，不会有开发者不打开系统的尾缀显示把？