Перейти к содержимому
Mineforgian

PySpigot

A Python scripting engine (plugin) for Minecraft servers running Bukkit or one of its forks (Spigot, Paper, etc.).

Загрузки
2K
Подписчики
20
Обновлён
27 июля 2025 г.
Лицензия
Apache-2.0

Опубликован 22 декабря 2024 г.

Исходный кодСообщить об ошибке

Description

PySpigot is a Python scripting engine for your Minecraft server. It allows you to create scripts, which act as "mini-plugins": they can register event listeners, commands, schedule tasks, and more!

PySpigot is a lot like Skript, but much more powerful. PySpigot utilizes Jython, a Python implementation that runs entirely on Java. This means that PySpigot scripts have full access to the entire Bukkit/Spigot API, as well as APIs of any other loaded plugins. In general, a PySpigot script can do anything Python can do, and anything a plugin can do as well.

Currently supports Bukkit server implementations, including Spigot, Paper, and Purpur, on Minecraft versions 1.16 and newer. There is currently an unofficial, preliminary release of PySpigot for BungeeCord available for open testing. Download it here.

For complete documentation on the plugin and writing scripts, visit the official documentation.



Join the discord for support and to stay in the loop regarding updates!

Features

  • Load scripts on server start and via commands
  • Stop, reload, and unload server scripts via commands
  • Support for both single-file scripts and multi-file projects
  • Register event listeners
  • Register commands
  • Schedule tasks (synchronous and asynchronous)
  • Work with config files
  • Register ProtocolLib packet listeners and send packets
  • Register PlaceholderAPI placeholder expansions
  • Comprehensive logging of errors and exceptions on a per-script basis, to file
  • Load Java libraries you'd like to work with at runtime
  • Write scripts in Python syntax
  • Scripts have complete access to the Bukkit/Spigot API, as well as APIs of other plugins, so anything is possible.
  • Support for working with SQL, Mongo, and redis servers
  • And more!

Commands

  • /pyspigot reload: List some useful links (Documentation, Discord, etc.)
  • /pyspigot info [scriptname/projectname]: Displays detailed information about a script or project, including uptime, registered listeners, commands, and more info
  • /pyspigot listscripts: List loaded and unloaded scripts and projects
  • /pyspigot load [scriptname/projectname]: Load a script or project with the given name
  • /pyspigot loadlibrary [libraryname]: Load a Java library with the given name
  • /pyspigot reloadall: Reload the entire plugin, including scripts, projects, libraries, and config
  • /pyspigot reload [scriptname/projectname]: Reload a loaded script or project
  • /pyspigot reloadconfig: Reload PySpigot's config.yml
  • /pyspigot unload [scriptname/projectname]: Unload a script or project

Configuration

# If false, will disable collection of metrics information by bStats for PySpigot. You may also disable bStats server-wide in the bStats config.yml under /plugins/bStats.
metrics-enabled: true
# The delay for loading scripts (in ticks) after the server finishes loading.
script-load-delay: 20
# List of relocation rules for libraries in the libs folder. Format as <pattern>|<relocated pattern>
library-relocations: []
# Date/time format for timestamps in script log files, written in Java's SimpleDateFormat pattern: https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/time/format/DateTimeFormatter.html
log-timestamp-format: 'MMM dd yyyy HH:mm:ss'
# If true, will print log messages to console every time a script is loaded, run, and unloaded.
script-action-logging: true
# If true, will log all redis events to the console and to a script's logger. If false, will only log reconnect events (reconnect attempts and failures)
verbose-redis-logging: true
# If true, scripts will be automatically unloaded if a plugin the script depends on is unloaded. This is especially useful to ensure script shutdown tasks that require a depending plugin complete successfully (prior to the plugin being unloaded).
script-unload-on-plugin-disable: true
# Options that pertain to Jython. Changing options in this section requires a server restart.
jython-options:
  # If true, the Jython runtime will be initialized during plugin load/server start. If false, the Jython runtime will not be initialized until the first script is loaded.
  init-on-startup: true
  # A list of system properties that will be passed to Jython. For a complete list, see https://javadoc.io/doc/org.python/jython-standalone/latest/org/python/core/RegistryKey.html
  properties:
    - 'python.cachedir.skip=true'
  # A list of args to pass to Jython when initialized. Equivalent to sys.argv in Python.
  args:
    - ''
# Default values for script options. If one or more options are not defined in the script_options.yml for the script, then PySpigot will fall back to these values.
script-option-defaults:
  # For projects, the main script file for the project.
  main: 'main.py'
  # Whether the script is enabled
  enabled: true
  # An integer load priority for the script
  load-priority: 1
  # A list of plugins the script depends on
  plugin-depend: []
  # Whether script log messages should be logged to its respective log file
  file-logging-enabled: true
  # The minimum level to log to the console and to the script's log file
  min-logging-level: 'INFO'
  # The default permission level for permissions
  permission-default: 'op'
# Advanced debug options for scripts
debug-options:
  # If true, will print stack traces for all script-related exceptions to the server console
  print-stack-traces: false
  # If true, the plugin will show messages in console and on join (to players with the permission pyspigot.admin) when a newer version of PySpigot is available to download on spigotmc.org.
  show-update-messages: true
  # The logging level for Jython internals. Can be useful to set this to FINE or ALL for debugging purposes. Note: the server's root logger will also need to be configured to accept debug messages for Jython's debug messages to show.
  jython-logging-level: 'INFO'
  # If true, PySpigot will patch the threading module on script unload (if it's being used in the script) in order to prevent the server from hanging. For more information, see https://github.com/magicmq/pyspigot/issues/18#issue-3012022678
  patch-threading: true

Some Helpful Links

Metrics

PySpigot collects anonymous server statistics via bStats, an open-source statistics collection service for Minecraft servers. You may opt out of this feature in the PySpigot config.yml or in /plugins/bStats/config.yml.


Ченджлог

0.9.1Релиз1.21.6, 1.21.7, 1.21.8 · 27 июля 2025 г.

Additions in this version:

  • Added a new PluginMessageManager to interface with Spigot's plugin messaging framework and send/listen for plugin messages
  • A notification is now sent when using a SNAPSHOT version as opposed to a release version
  • A warning message is now displayed if a tab complete function returns something other than a list

Changes in this version:

- PySpigot is now compiled with Java 21. From this version onwards, PySpigot will only work on Java 21+

  • PySpigot now uses the Kyori Adventure API for messaging
  • Improved the information displayed in the /pyspigot info command
  • Logging improvements
  • A lot of code cleanup, reorganization, and improvements
  • JavaDocs improvements

Bugs fixed in this version:

  • Fixed an issue where duplicate scripts/project could be loaded, or the same script/project could be loaded more than once, if case-variant names were passed
  • Fixed an issue where the script_options.yml file was never loaded on the BungeeCord platform
  • Fixed an error that occurred when listeners, commands, etc. were registered from a utility module or a non-main project file
  • The main script displayed in the /pyspigot info command now show the correct script file for single-file scripts
  • Fixed a memory leak associated with fetching the latest plugin version from Spigot
  • Fixed issue where command registration parameters were not recognized
  • Fixed an issue where the configuration files were saved before the plugin folder was initialized/created
  • The version checking system now evaluates SNAPSHOT versions as older than release versions of the same number
0.9.1Релиз1.21.6, 1.21.7, 1.21.8 · 27 июля 2025 г.

Additions in this version:

  • Added a new PluginMessageManager to interface with Spigot's plugin messaging framework and send/listen for plugin messages
  • A notification is now sent when using a SNAPSHOT version as opposed to a release version
  • A warning message is now displayed if a tab complete function returns something other than a list

Changes in this version:

  • PySpigot is now compiled with Java 21. From this version onwards, PySpigot will only work on Java 21+
  • PySpigot now uses the Kyori Adventure API for messaging
  • Improved the information displayed in the /pyspigot info command
  • Logging improvements
  • A lot of code cleanup, reorganization, and improvements
  • JavaDocs improvements

Bugs fixed in this version:

  • Fixed an issue where duplicate scripts/project could be loaded, or the same script/project could be loaded more than once, if case-variant names were passed
  • Fixed an issue where the script_options.yml file was never loaded on the BungeeCord platform
  • Fixed an error that occurred when listeners, commands, etc. were registered from a utility module or a non-main project file
  • The main script displayed in the /pyspigot info command now show the correct script file for single-file scripts
  • Fixed a memory leak associated with fetching the latest plugin version from Spigot
  • Fixed issue where command registration parameters were not recognized
  • Fixed an issue where the configuration files were saved before the plugin folder was initialized/created
  • The version checking system now evaluates SNAPSHOT versions as older than release versions of the same number
0.9.0Релиз1.21.2, 1.21.3, 1.21.4 · 30 апреля 2025 г.

This update contains some major additions (including support for projects), as well as some key bug fixes.

Additions in this version:

  • Added support for multi-file script projects! For more information, see the documentation.
  • Calling sys.exit from within a script now works as intended.

Changes in this version:

  • Added back the option to specify default permissions in script-option-defaults in the config.yml
  • Major improvements to exception throwing and handling, including delegation of most exception handling to Jython
  • Miscellaneous code and JavaDocs improvements
  • Updated many dependencies to their latest versions

Bugs fixed in this version:

  • Fixed a bug where PySpigot would not load if the optional dependencies ProtocolLib and/or PlaceholderAPI were not running on the server
  • Fixed a bug where color codes were not printing correctly for /pyspigot listscripts command messages
  • Fixed a bug where scripts could desync from their own PySystemState when calling script code at a later time, such as event listeners, tasks, commands, etc.
  • Fixed a bug where PySpigot would attempt to shutdown before it was initialized
  • Fixed a bug where a script could access a manager before it was initialized
  • Fixed a bug where the main server thread would hang on script unload if the script accessed the threading module from an asynchronous context by patching the threading module on script unload. This can be disabled by setting debug-options.patch-threading to false in the config.yml

This release also contains a preliminary release for a BungeeCord-compatible version of PySpigot. This is not an official release because I have not comprehensively tested it. Download it here. Feel free to download, test it out, and report any issues here on GitHub or on Discord.

See the complete change log for this update here: https://github.com/magicmq/pyspigot/releases/tag/v0.9.0

0.8.0Релиз1.21.2, 1.21.3, 1.21.4 · 6 марта 2025 г.

This update contains key bug fixes and performance improvements, as well as some minor additions/changes.

Additions:

  • Script start and stop functions now optionally accept one parameter, the script object, which is passed to the functions by PySpigot when they are called
  • Added support for relational placeholders in script PlaceholderAPI expansions
  • Added a new function.py helper module, bundled into the PySpigot JAR file, that wraps Java functional inferfaces in a Python-friendly format
  • Added Jython-specific options to the config.yml, including initialization on startup, Jython properties, and args/sys.argv

Changes:

  • The pyspigot.py helper library is now precompiled and bundled into the /Lib folder within the PySpigot JAR file. It is no longer copied into the python-libs folder. You can safely delete the pyspigot.py and corresponding pyspigot$py.class files from the python-libs folder.
  • The auto-pyspigot-lib-update-enabled was removed
  • Jython is now initialized on server startup/plugin load by default, rather than when loading the first script, which increases performance in most cases
  • Updated several example scripts to use the latest recommended PySpigot features
  • Reformatted and removed some redudancy from script error messages in console
  • The plugin prefix is now hard-coded (no longer defined in the config.yml), and the footer was removed from the /pyspigot help command
  • Increased precision when reporting Java library load times
  • A lot of code cleanup and miscellaneous improvements
  • Updated several dependencies to their latest versions

Bug Fixes:

  • Fixed an issue where Paper was unnecessarily relocating Jython internals, which resulted in diminished performance
  • Fixed an issue where PySpigot managers were being shut down if they weren't initialized first
  • The Database manager now specifies default HikariCP properties if none are explicitly defined

This release also contains a preliminary release for a BungeeCord-compatible version of PySpigot. This is not an official release because I have not comprehensively tested it. Download it here. Feel free to test it out and report issues on GitHub or Discord.

See the complete change log for this update here: https://github.com/magicmq/pyspigot/releases/tag/v0.8.0

0.7.1Релиз1.21.2, 1.21.3, 1.21.4 · 22 декабря 2024 г.

0.7.1 Update

This update is a minor release, and it only contains one new feature (custom script events) as well some minor bug fixes and code improvements.

The bigger news with this update is that the new documentation site is live! Check it out here.

Additions:

  • Added a CustomEvent that an be created and called by scripts to signal a custom event to other scripts/plugins (visit the docs for more information)
  • Added another example script

Changes:

  • Updated all dependencies to latest versions (including Jython to 2.7.4)
  • Minor code improvements/cleanup
  • Minor improvements to config file comments and JavaDocs

Bug Fixes:

  • Fixed an issue with log messages not being printed correctly when running regular Spigot server software
  • Fixed an issue with the library manager attempting to load non-JAR files and folders

See the complete change log here.

Комментарии

Загружаем…