How mukulx/javaskript works
1. Overall shape
- This is a single Paper/Folia plugin, packaged as a Gradle Java 21 project, whose main purpose is to act as a runtime scripting engine.
- The server loads one plugin jar, and that plugin then discovers, compiles, and manages user-authored .java scripts from a scripts directory.
2. Plugin entrypoint and lifecycle
- JavaSkriptPlugin is the top-level runtime entrypoint.
- It likely owns startup/shutdown wiring: loading config, initializing managers, registering commands/permissions, starting file watching, and exposing the public API to other plugins.
3. Script ingestion pipeline
- The core flow is: script file on disk → compile → load into isolated classloader → register into the server.
- script/compiler/ScriptCompiler turns source .java files into bytecode.
- script/loader/ScriptClassLoader isolates loaded scripts from the plugin’s own classes and helps support unloading/reloading.
- ScriptManager and ScriptInstance appear to track the lifecycle state of each loaded script.
4. Hot reload subsystem
- watcher/FileWatcher is the mechanism for automatic reload when script files change.
- This creates the key runtime behavior of the project: scripts are not static artifacts, but live assets that can be modified and reloaded without rebuilding the plugin jar.
5. Dynamic dependencies
- dependency/DependencyManager and DependencyLoader provide runtime fetching/loading of Maven dependencies for scripts.
- This is an important architectural boundary: scripts can declare libraries beyond the plugin jar, so the engine needs to resolve and attach dependencies before compilation or class loading.
6. Server integration: commands and permissions
- command/DynamicCommandRegistry and JavaSkriptCommand manage commands defined by scripts at runtime, without plugin.yml entries per command.
- permission/DynamicPermissionRegistry does the same for permissions.
- These registries are part of the “script becomes server feature” layer, translating script metadata into Bukkit/Paper registrations.
7. Built-in script-facing API
- The api package is the public surface scripts use instead of directly depending on internal engine classes.
- Helpers cover common plugin tasks: ActionBarHelper, TitleHelper, PlaceholderHelper, DatabaseHelper, ScriptScheduler, and ScriptConfig.
- JavaSkriptAPI is the facade for external plugins to load/unload/query scripts programmatically.
8. GUI and utility support
- api/gui contains a small GUI abstraction (GUI, GUIManager, ItemBuilder) for inventory-based interfaces.
- util/ServerUtil likely centralizes Paper/Folia/server capability checks and environment-specific behavior.
- These helpers keep script authors from reimplementing repetitive Bukkit patterns.
9. Paper vs Folia compatibility boundary
- The script package includes FoliaSupport and PaperOnly, which indicate runtime annotations or markers used to gate scripts by server type.
- The README and examples show the project is explicitly built for Paper and Folia, not Bukkit/Spigot.
- This compatibility layer is important because scheduling and thread-affinity rules differ between Paper and Folia.
10. External integrations
- PlaceholderAPI support is built in through PlaceholderHelper.
- The database API is explicitly SQLite-oriented, with the README also showing examples using HikariCP for richer database setups.
- These integrations are not core infrastructure themselves, but they extend script capabilities into common plugin ecosystem services.
11. Configuration and packaging
- src/main/resources/config.yml is the plugin’s own configuration, separate from per-script configs handled by ScriptConfig.
- paper-plugin.yml defines the plugin metadata for Paper’s loader.
- The Gradle build is standard Java plugin packaging, producing one deployable jar that hosts the scripting engine.
12. Repository structure as a whole
- src/main/java/dev/mukulx/javaskript/ contains the runtime engine.
- src/main/resources/examples/ acts as an in-repo gallery of supported use cases: commands, events, config, database, GUI, scheduling, permissions, placeholders, Folia compatibility, and multi-class scripts.
- The docs folder is substantial, which suggests the project’s architecture is API-driven and expected to be used by both script authors and other plugin developers.
Main entry points: ScriptManager.java ScriptManager · JavaSkriptPlugin.java JavaSkriptPlugin · api API Helpers · ScriptClassLoader.java ScriptClassLoader
Components 18
Plugin Core
Top-level plugin entrypoint and runtime orchestration.
- JavaSkriptPlugin · Main plugin lifecycle and wiring root.
src/main/java/dev/mukulx/javaskript/JavaSkriptPlugin.java - config.yml · Plugin-level configuration resource.
src/main/resources/config.yml
Script Pipeline
Script discovery, compilation, loading, and lifecycle management.
- ScriptManager · Tracks loaded scripts and coordinates reload/unload.
src/main/java/dev/mukulx/javaskript/script/ScriptManager.java - ScriptInstance · Represents one loaded script and its runtime state.
src/main/java/dev/mukulx/javaskript/script/ScriptInstance.java - ScriptCompiler · Compiles source scripts into bytecode.
src/main/java/dev/mukulx/javaskript/script/compiler/ScriptCompiler.java - ScriptClassLoader · Loads scripts in isolation for reload/unload support.
src/main/java/dev/mukulx/javaskript/script/loader/ScriptClassLoader.java - FileWatcher · Detects script file changes and triggers reloads.
src/main/java/dev/mukulx/javaskript/watcher/FileWatcher.java - DependencyManager · Coordinates runtime dependency resolution for scripts.
src/main/java/dev/mukulx/javaskript/dependency/DependencyManager.java - DependencyLoader · Fetches and attaches external libraries for script use.
src/main/java/dev/mukulx/javaskript/dependency/DependencyLoader.java - Folia/Paper Flags · Markers for Folia-only and Paper-only script behavior.
src/main/java/dev/mukulx/javaskript/script
Integrations
Server-facing dynamic features and external service hooks.
- Command Registry · Registers script-defined commands with the server.
src/main/java/dev/mukulx/javaskript/command/DynamicCommandRegistry.java - JavaSkriptCommand · Runtime command implementation used by dynamic commands.
src/main/java/dev/mukulx/javaskript/command/JavaSkriptCommand.java - Permission Registry · Registers script-defined permissions with the server.
src/main/java/dev/mukulx/javaskript/permission/DynamicPermissionRegistry.java - ServerUtil · Server capability and environment helper.
src/main/java/dev/mukulx/javaskript/util/ServerUtil.java
Public Surface
API helpers and example scripts exposed to script authors.
- JavaSkriptAPI · Programmatic facade for other plugins.
src/main/java/dev/mukulx/javaskript/api/JavaSkriptAPI.java - API Helpers · Common script-facing helpers for UI, config, scheduling, and placeholders.
src/main/java/dev/mukulx/javaskript/api - GUI Tools · Inventory GUI abstraction and item builder.
src/main/java/dev/mukulx/javaskript/api/gui - Examples · In-repo script examples covering commands, config, GUI, scheduling, and compatibility.
src/main/resources/examples
Connections 23
- JavaSkriptPlugin → ScriptManager: creates · Bootstraps lifecycle management.
- JavaSkriptPlugin → FileWatcher: starts · Enables hot reload of script files.
- JavaSkriptPlugin → DependencyManager: initializes · Sets up runtime dependency handling.
- JavaSkriptPlugin → Command Registry: registers · Publishes dynamic commands to the server.
- JavaSkriptPlugin → Permission Registry: registers · Publishes dynamic permissions to the server.
- JavaSkriptPlugin → config.yml: loads · Reads plugin configuration on startup.
- JavaSkriptPlugin → JavaSkriptAPI: exposes · Makes the public facade available to other plugins.
- FileWatcher → ScriptManager: reloads · Signals script load and reload operations.
- ScriptManager → DependencyManager: resolves deps · Ensures script dependencies are available before load.
- DependencyManager → DependencyLoader: delegates · Performs fetch and attach work.
- ScriptManager → ScriptCompiler: compiles · Turns script sources into bytecode.
- ScriptCompiler → ScriptClassLoader: loads into · Hands compiled artifacts to an isolated loader.
- ScriptManager → ScriptClassLoader: creates · Creates per-script loading boundaries.
- ScriptClassLoader → ScriptInstance: instantiates · Produces runtime script instances.
- ScriptManager → ScriptInstance: tracks · Maintains script lifecycle state.
- Folia/Paper Flags → ScriptManager: gates · Constrains scripts by server type and capability.
- API Helpers → GUI Tools: includes · Groups GUI support within the script API.
- JavaSkriptAPI → API Helpers: uses · Surfaces helper functionality to external callers.
- ScriptManager → Command Registry: publishes · Binds script metadata to runtime commands.
- ScriptManager → Permission Registry: publishes · Binds script metadata to runtime permissions.
- API Helpers → ServerUtil: relies on · Shares server-specific capability checks.
- Examples → ScriptManager: demonstrates · Shows the supported script lifecycle and features.
- Examples → API Helpers: demonstrates · Illustrates helper usage patterns.