# mukulx/javaskript architecture

> Architecture diagram of the GitHub repository mukulx/javaskript, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mukulx/javaskript
- Repository: https://github.com/mukulx/javaskript

## Overview

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: [`src/main/java/dev/mukulx/javaskript/script/ScriptManager.java`](https://github.com/mukulx/javaskript/blob/main/src/main/java/dev/mukulx/javaskript/script/ScriptManager.java) (ScriptManager), [`src/main/java/dev/mukulx/javaskript/JavaSkriptPlugin.java`](https://github.com/mukulx/javaskript/blob/main/src/main/java/dev/mukulx/javaskript/JavaSkriptPlugin.java) (JavaSkriptPlugin), [`src/main/java/dev/mukulx/javaskript/api`](https://github.com/mukulx/javaskript/tree/main/src/main/java/dev/mukulx/javaskript/api) (API Helpers), [`src/main/java/dev/mukulx/javaskript/script/loader/ScriptClassLoader.java`](https://github.com/mukulx/javaskript/blob/main/src/main/java/dev/mukulx/javaskript/script/loader/ScriptClassLoader.java) (ScriptClassLoader)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Plugin Core"]
  node_plugin["JavaSkriptPlugin<br/>plugin entrypoint"]
  node_config["config.yml<br/>plugin config<br/>[config.yml]"]
end

subgraph group_pipeline["Script Pipeline"]
  node_script_manager["ScriptManager<br/>script lifecycle<br/>[ScriptManager.java]"]
  node_script_instance["ScriptInstance<br/>script state"]
  node_compiler["ScriptCompiler"]
  node_classloader["ScriptClassLoader<br/>isolated loader"]
  node_watcher["FileWatcher<br/>hot reload<br/>[FileWatcher.java]"]
  node_dep_manager["DependencyManager<br/>dependency resolver"]
  node_dep_loader["DependencyLoader<br/>dependency loader"]
  node_script_annotations["Folia/Paper Flags<br/>compat markers"]
end

subgraph group_integration["Integrations"]
  node_cmd_registry["Command Registry<br/>dynamic commands"]
  node_cmd["JavaSkriptCommand<br/>command handler"]
  node_perm_registry["Permission Registry<br/>dynamic permissions"]
  node_util(("ServerUtil<br/>platform util<br/>[ServerUtil.java]"))
end

subgraph group_surface["Public Surface"]
  node_api["JavaSkriptAPI<br/>external API<br/>[JavaSkriptAPI.java]"]
  node_api_helpers["API Helpers<br/>script helpers"]
  node_gui["GUI Tools<br/>inventory gui"]
  node_examples["Examples<br/>sample scripts"]
end

node_plugin -->|"creates"| node_script_manager
node_plugin -->|"starts"| node_watcher
node_plugin -->|"initializes"| node_dep_manager
node_plugin -->|"registers"| node_cmd_registry
node_plugin -->|"registers"| node_perm_registry
node_plugin -->|"loads"| node_config
node_plugin -->|"exposes"| node_api
node_watcher -->|"reloads"| node_script_manager
node_script_manager -->|"resolves deps"| node_dep_manager
node_dep_manager -->|"delegates"| node_dep_loader
node_script_manager -->|"compiles"| node_compiler
node_compiler -->|"loads into"| node_classloader
node_script_manager -->|"creates"| node_classloader
node_classloader -->|"instantiates"| node_script_instance
node_script_manager -->|"tracks"| node_script_instance
node_script_annotations -.->|"gates"| node_script_manager
node_api_helpers -->|"includes"| node_gui
node_api -->|"uses"| node_api_helpers
node_script_manager -->|"publishes"| node_cmd_registry
node_script_manager -->|"publishes"| node_perm_registry
node_api_helpers -->|"relies on"| node_util
node_examples -.->|"demonstrates"| node_script_manager
node_examples -.->|"demonstrates"| node_api_helpers

click node_plugin "https://github.com/mukulx/javaskript/blob/main/src/main/java/dev/mukulx/javaskript/JavaSkriptPlugin.java"
click node_api "https://github.com/mukulx/javaskript/blob/main/src/main/java/dev/mukulx/javaskript/api/JavaSkriptAPI.java"
click node_script_manager "https://github.com/mukulx/javaskript/blob/main/src/main/java/dev/mukulx/javaskript/script/ScriptManager.java"
click node_script_instance "https://github.com/mukulx/javaskript/blob/main/src/main/java/dev/mukulx/javaskript/script/ScriptInstance.java"
click node_compiler "https://github.com/mukulx/javaskript/blob/main/src/main/java/dev/mukulx/javaskript/script/compiler/ScriptCompiler.java"
click node_classloader "https://github.com/mukulx/javaskript/blob/main/src/main/java/dev/mukulx/javaskript/script/loader/ScriptClassLoader.java"
click node_watcher "https://github.com/mukulx/javaskript/blob/main/src/main/java/dev/mukulx/javaskript/watcher/FileWatcher.java"
click node_dep_manager "https://github.com/mukulx/javaskript/blob/main/src/main/java/dev/mukulx/javaskript/dependency/DependencyManager.java"
click node_dep_loader "https://github.com/mukulx/javaskript/blob/main/src/main/java/dev/mukulx/javaskript/dependency/DependencyLoader.java"
click node_cmd_registry "https://github.com/mukulx/javaskript/blob/main/src/main/java/dev/mukulx/javaskript/command/DynamicCommandRegistry.java"
click node_cmd "https://github.com/mukulx/javaskript/blob/main/src/main/java/dev/mukulx/javaskript/command/JavaSkriptCommand.java"
click node_perm_registry "https://github.com/mukulx/javaskript/blob/main/src/main/java/dev/mukulx/javaskript/permission/DynamicPermissionRegistry.java"
click node_api_helpers "https://github.com/mukulx/javaskript/tree/main/src/main/java/dev/mukulx/javaskript/api"
click node_gui "https://github.com/mukulx/javaskript/tree/main/src/main/java/dev/mukulx/javaskript/api/gui"
click node_util "https://github.com/mukulx/javaskript/blob/main/src/main/java/dev/mukulx/javaskript/util/ServerUtil.java"
click node_script_annotations "https://github.com/mukulx/javaskript/tree/main/src/main/java/dev/mukulx/javaskript/script"
click node_examples "https://github.com/mukulx/javaskript/tree/main/src/main/resources/examples"
click node_config "https://github.com/mukulx/javaskript/blob/main/src/main/resources/config.yml"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_plugin,node_config toneBlue
class node_script_manager,node_script_instance,node_compiler,node_classloader,node_watcher,node_dep_manager,node_dep_loader,node_script_annotations toneAmber
class node_cmd_registry,node_cmd,node_perm_registry,node_util toneMint
class node_api,node_api_helpers,node_gui,node_examples toneRose
```

## Components

### Plugin Core

Top-level plugin entrypoint and runtime orchestration.

- [JavaSkriptPlugin](https://github.com/mukulx/javaskript/blob/main/src/main/java/dev/mukulx/javaskript/JavaSkriptPlugin.java): plugin entrypoint · Main plugin lifecycle and wiring root. · `src/main/java/dev/mukulx/javaskript/JavaSkriptPlugin.java`
- [config.yml](https://github.com/mukulx/javaskript/blob/main/src/main/resources/config.yml): plugin config · Plugin-level configuration resource. · `src/main/resources/config.yml`

### Script Pipeline

Script discovery, compilation, loading, and lifecycle management.

- [ScriptManager](https://github.com/mukulx/javaskript/blob/main/src/main/java/dev/mukulx/javaskript/script/ScriptManager.java): script lifecycle · Tracks loaded scripts and coordinates reload/unload. · `src/main/java/dev/mukulx/javaskript/script/ScriptManager.java`
- [ScriptInstance](https://github.com/mukulx/javaskript/blob/main/src/main/java/dev/mukulx/javaskript/script/ScriptInstance.java): script state · Represents one loaded script and its runtime state. · `src/main/java/dev/mukulx/javaskript/script/ScriptInstance.java`
- [ScriptCompiler](https://github.com/mukulx/javaskript/blob/main/src/main/java/dev/mukulx/javaskript/script/compiler/ScriptCompiler.java): compiler · Compiles source scripts into bytecode. · `src/main/java/dev/mukulx/javaskript/script/compiler/ScriptCompiler.java`
- [ScriptClassLoader](https://github.com/mukulx/javaskript/blob/main/src/main/java/dev/mukulx/javaskript/script/loader/ScriptClassLoader.java): isolated loader · Loads scripts in isolation for reload/unload support. · `src/main/java/dev/mukulx/javaskript/script/loader/ScriptClassLoader.java`
- [FileWatcher](https://github.com/mukulx/javaskript/blob/main/src/main/java/dev/mukulx/javaskript/watcher/FileWatcher.java): hot reload · Detects script file changes and triggers reloads. · `src/main/java/dev/mukulx/javaskript/watcher/FileWatcher.java`
- [DependencyManager](https://github.com/mukulx/javaskript/blob/main/src/main/java/dev/mukulx/javaskript/dependency/DependencyManager.java): dependency resolver · Coordinates runtime dependency resolution for scripts. · `src/main/java/dev/mukulx/javaskript/dependency/DependencyManager.java`
- [DependencyLoader](https://github.com/mukulx/javaskript/blob/main/src/main/java/dev/mukulx/javaskript/dependency/DependencyLoader.java): dependency loader · Fetches and attaches external libraries for script use. · `src/main/java/dev/mukulx/javaskript/dependency/DependencyLoader.java`
- [Folia/Paper Flags](https://github.com/mukulx/javaskript/tree/main/src/main/java/dev/mukulx/javaskript/script): compat markers · 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](https://github.com/mukulx/javaskript/blob/main/src/main/java/dev/mukulx/javaskript/command/DynamicCommandRegistry.java): dynamic commands · Registers script-defined commands with the server. · `src/main/java/dev/mukulx/javaskript/command/DynamicCommandRegistry.java`
- [JavaSkriptCommand](https://github.com/mukulx/javaskript/blob/main/src/main/java/dev/mukulx/javaskript/command/JavaSkriptCommand.java): command handler · Runtime command implementation used by dynamic commands. · `src/main/java/dev/mukulx/javaskript/command/JavaSkriptCommand.java`
- [Permission Registry](https://github.com/mukulx/javaskript/blob/main/src/main/java/dev/mukulx/javaskript/permission/DynamicPermissionRegistry.java): dynamic permissions · Registers script-defined permissions with the server. · `src/main/java/dev/mukulx/javaskript/permission/DynamicPermissionRegistry.java`
- [ServerUtil](https://github.com/mukulx/javaskript/blob/main/src/main/java/dev/mukulx/javaskript/util/ServerUtil.java): platform util · 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](https://github.com/mukulx/javaskript/blob/main/src/main/java/dev/mukulx/javaskript/api/JavaSkriptAPI.java): external API · Programmatic facade for other plugins. · `src/main/java/dev/mukulx/javaskript/api/JavaSkriptAPI.java`
- [API Helpers](https://github.com/mukulx/javaskript/tree/main/src/main/java/dev/mukulx/javaskript/api): script helpers · Common script-facing helpers for UI, config, scheduling, and placeholders. · `src/main/java/dev/mukulx/javaskript/api`
- [GUI Tools](https://github.com/mukulx/javaskript/tree/main/src/main/java/dev/mukulx/javaskript/api/gui): inventory gui · Inventory GUI abstraction and item builder. · `src/main/java/dev/mukulx/javaskript/api/gui`
- [Examples](https://github.com/mukulx/javaskript/tree/main/src/main/resources/examples): sample scripts · In-repo script examples covering commands, config, GUI, scheduling, and compatibility. · `src/main/resources/examples`

## Connections

- 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.
