# PaperTS<\/p>\n
PaperTS is a Paper Minecraft plugin that enables you to write Minecraft server plugins in TypeScript, running on the Node.js JavaScript engine via Javet. It provides a runtime environment for TypeScript modules, allowing you to leverage the power and flexibility of JavaScript\/TypeScript for Minecraft server development. **Node.JS runtime is downloaded at runtime**, the plugins install it from Javet Official Depedencies, you may verify if your platform is supported.<\/p>\n
## Features<\/p>\n
– **TypeScript\/JavaScript Plugin Support**: Write Minecraft plugins in TypeScript or JavaScript and run them directly on your Paper server.
\n– **Automatic Module Loading**: Scans the plugin’s data folder for modules (directories with a `package.json`), initializes, and starts them automatically.
\n– **Node.js Environment**: Provides a Node.js-like environment using Javet’s NodeRuntime.
\n– **Event and Command Registration**: Exposes APIs for registering\/unregistering Bukkit events and commands from TypeScript.
\n– **Hot Reloading**: Modules can be released and reloaded without restarting the server.<\/p>\n
## How It Works<\/p>\n
1. On server start, PaperTS scans its data folder for subdirectories containing a `package.json` file.
\n2. For each module, it reads the `main` field in `package.json` to find the entry script.
\n3. The entry script is executed in a Node.js runtime, with access to PaperTS APIs for interacting with the server.
\n4. Modules can register event handlers and commands using the provided global `PaperTS` object.<\/p>\n
## Getting Started<\/p>\n
1. **Install PaperTS**: Place the PaperTS plugin JAR in your server’s `plugins` folder.
\n2. **Create a Module**:
\n – In the `plugins\/PaperTS` folder, create a new directory for your module (e.g., `my-plugin`).
\n – Add a `package.json` file with a `main` field pointing to your entry script (e.g., `index.js`).
\n – Write your TypeScript\/JavaScript code and compile it to JavaScript if needed.
\n3. **Example `package.json`**:<\/p>\n
“`json
\n {
\n “name”: “my-plugin”,
\n “main”: “index.js”
\n }
\n “`
\n4. **Example `index.js`**:<\/p>\n
“`js
\n class ServerModule {
\n constructor() {
\n console.log(“My plugin has been loaded!”);
\n }<\/p>\n
public handlePlayerJoin(event) {
\n \/\/ Handle player join event
\n event.player.sendMessage(event.player.name, “Welcome to the server!”);
\n }<\/p>\n
public helloCommand(sender, args) {
\n sender.sendMessage(“Hello from PaperTS!”);
\n }
\n }<\/p>\n
const server = new ServerModule();<\/p>\n
PaperTS.registerEvent(
\n org.bukkit.event.player.PlayerJoinEvent,
\n server.handlePlayerJoin.bind(server),
\n );
\n PaperTS.registerCommand(
\n “hello”,
\n “Says hello to the player”,
\n “\/hello”,
\n “”,
\n [],
\n server.helloCommand.bind(server),
\n );<\/p>\n
“`
\n5. Start your Paper server. PaperTS will automatically load your module. You can reload the modules any time using the `\/paperts reload` command.<\/p>\n
### Note<\/p>\n
#### Importing Node Modules<\/p>\n
The root for the imports of node modules is the root of the working directory, so if your directory structure is like this:<\/p>\n
“`
\nmy-plugin\/
\n\u251c\u2500\u2500 package.json
\n\u251c\u2500\u2500 src\/
\n\u2502 \u2514\u2500\u2500 index.ts
\n\u251c\u2500\u2500 dist\/
\n\u2502 \u2514\u2500\u2500 index.js
\n\u2514\u2500\u2500 node_modules\/
\n \u2514\u2500\u2500 some-node-module\/
\n“`<\/p>\n
PaperTS will look for modules in `my-plugin` directory, you may need to adjust the `require` functiion if you want to import scripts from diferents paths that the root of the module. The required function is already modified with the following code to allow importing the java classes:<\/p>\n
“`js
\nconst Module = require(“module”);
\nconst originalRequire = Module.prototype.require;<\/p>\n
Module.prototype.require = function () {
\n if (arguments.length === 1 && typeof arguments[0] === “string” && (arguments[0].startsWith(“org.”) || arguments[0].startsWith(“java.”) || arguments[0].startsWith(“net.”) || arguments[0].startsWith(“com.”))) {
\n return javet.package[arguments[0]];
\n }<\/p>\n
return originalRequire.apply(this, arguments);
\n};
\n“`<\/p>\n
#### Get and Set methods<\/p>\n
According to the Javet wiki, Javet guesses the `get` and `set` methods. For example, `getName()` turns into `name`, and `setName(value)` becomes `name = value`. So, when using these methods, you should use the property-like syntax. For example, instead of calling `player.getName()`, you should use `player.name`. Similarly, to set a value, use the assignment syntax like `player.name = “NewName”`.<\/p>\n
### PaperTS Global API<\/p>\n
The following global API is available in your TypeScript\/JavaScript code:<\/p>\n
“`ts
\nimport { Event } from “org.bukkit.event”;
\nimport { CommandSender } from “org.bukkit.command”;
\nimport { PersistentDataContainer } from “org.bukkit.persistence”;
\nimport { List } from “java.util”;
\nimport { Runnable } from “java.lang”;
\nimport { JavaPlugin } from “org.bukkit.plugin.java”;<\/p>\n
declare namespace PaperTS { export function registerCommand( export function getPersistentContainerString( export function hasKeyPersistentContainer( export function setPersistentContainerString( export function getJavaPlugin(): JavaPlugin;<\/p>\n export function createRunnable(runnable: () => void): Runnable; #### Registering Events<\/p>\n To register events, use the `PaperTS.registerEvent` method. You can pass the event class and a callback function that will be executed when the event is triggered.<\/p>\n “`js const server = new ServerModule();<\/p>\n PaperTS.registerEvent( #### Registering Commands<\/p>\n To register commands, use the `PaperTS.registerCommand` method. You can specify the command name, description, usage message, permission, aliases, and an executor function that will handle the command execution.<\/p>\n “`js const server = new ServerModule();<\/p>\n PaperTS.registerCommand( #### Note<\/p>\n Using `bind` is necessary when passing methods as callbacks to ensure the correct context (`this`) is maintained.<\/p>\n ### Using typescript<\/p>\n To use TypeScript, you can set up a `tsconfig.json` in your module directory:<\/p>\n “`json Install the necessary depedencies in your module directory:<\/p>\n “`sh You can substitute the version, with another version of the `paperts-java-ts-bind` package, if you want to use a different version. You can also request another version by opening an issue on this repository.<\/p>\n Then, you can write your TypeScript code in the `src` directory and compile it to JavaScript in the `dist` directory.<\/p>\n Your `package.json` should look like this:<\/p>\n “`json Then you can use `npm run build` to bundle your TypeScript code into a single JavaScript file that can be run by PaperTS.<\/p>\n Example `index.ts`:<\/p>\n “`ts declare namespace PaperTS { export function registerCommand( export class ServerModule { public handlePlayerJoin(event: PlayerJoinEvent) { public helloCommand(sender: CommandSender, args: string[]) { const server = new ServerModule();<\/p>\n PaperTS.registerEvent( ### Internationalization (i18n)<\/p>\n PaperTS supports internationalization (i18n) through the Node.js runtime, enabling it may lead to more compatible behavior with some Node.js modules. To enable i18n, create a folder name `node-icu` in the data folder of the plugin (normally `plugins\/PaperTS\/node-icu`) and place the ICU data files there. You can download the ICU data files from any actions run of the Javet repository. The plugin will automatically detect the presence of the `node-icu` folder and enable i18n support.<\/p>\n ### Setting up the Run Type<\/p>\n You can configure how the script runs by specifying the `runType` field in the `package.json` of your module. This determines whether the script executes synchronously or asynchronously, and on which thread. Below is an example configuration:<\/p>\n “`json The available options for `runType` are:<\/p>\n – **`SynchronousOnNextTick`**: Executes the script synchronously on the next server tick. ### Resource Cleanup<\/p>\n When unloading or reloading a module, PaperTS attempts to clean up resources by calling a `cleanup` function if it exists in the module’s main script. This function should handle any necessary cleanup tasks, such as closing database connections, closing a http server, or freeing up memory.<\/p>\n ## Plugin Commands<\/p>\n You can use the following commands to manage your PaperTS modules: ## Development<\/p>\n PaperTS uses Javet to embed the V8 engine and Node.js runtime. The plugin manages engine pools, working directories, and exposes a `Globals` API for event and command management.<\/p>\n ### Building<\/p>\n Build with Gradle:<\/p>\n “`sh The output JAR will be in `app\/build\/libs\/`.<\/p>\n ## Contributing<\/p>\n Contributions are welcome! Please open issues or pull requests for bug fixes, features, or documentation improvements.<\/p>\n ## Inspiration<\/p>\n Some projects that inspired PaperTS: PaperTS is a Paper Minecraft plugin that enables you to write Minecraft server plugins in TypeScript.<\/p>\n","protected":false},"featured_media":119335,"template":"","meta":{"_minecraft_slug":"paperts","_minecraft_project_id":"uqOgfcal","_minecraft_author":"MetlHedd","_minecraft_license":"MIT","_minecraft_downloads":127,"_minecraft_follows":1,"_minecraft_client_side":"unsupported","_minecraft_server_side":"required","_minecraft_storage_type":"zip","_minecraft_archive_name":"paperts.zip","_minecraft_size_bytes":652556615,"_minecraft_version_count":6,"_minecraft_updated_at":"2026-05-15T19:09:13.196297Z","_minecraft_date_created":"2025-07-29T01:23:52.728378Z","_minecraft_date_modified":"2026-01-16T13:50:34.907740Z","_minecraft_project_url":"https:\/\/modrinth.com\/mod\/paperts","_minecraft_icon_attachment_id":119335,"_minecraft_imported_at":"2026-06-07T00:26:53+00:00","_minecraft_import_hash":"02e4a962987e7ea7dc5cc7bae2b43601","_minecraft_versions":"","_minecraft_links":"","_minecraft_gallery":"","_minecraft_api_metadata":""},"mod_category":[124,125,873,127,128,129,123],"mod_loader":[130,131,132,133,134],"minecraft_version":[59,36,60,93,94,101,102,62,37,40,41,73,74,38,78,79,80,81,82],"class_list":["post-119334","mod","type-mod","status-publish","has-post-thumbnail","hentry","mod_category-bukkit","mod_category-folia","mod_category-library","mod_category-paper","mod_category-purpur","mod_category-spigot","mod_category-technology","mod_loader-bukkit","mod_loader-folia","mod_loader-paper","mod_loader-purpur","mod_loader-spigot","minecraft_version-1-20","minecraft_version-1-20-1","minecraft_version-1-20-2","minecraft_version-1-20-3","minecraft_version-1-20-4","minecraft_version-1-20-5","minecraft_version-1-20-6","minecraft_version-1-21","minecraft_version-1-21-1","minecraft_version-1-21-10","minecraft_version-1-21-11","minecraft_version-1-21-2","minecraft_version-1-21-3","minecraft_version-1-21-4","minecraft_version-1-21-5","minecraft_version-1-21-6","minecraft_version-1-21-7","minecraft_version-1-21-8","minecraft_version-1-21-9"],"yoast_head":"\n
\n export function registerEvent
\n eventClass: { new (…args: any[]): T },
\n listener: (event: T) => void,
\n ): void;<\/p>\n
\n name: string,
\n description: string,
\n usageMessage: string,
\n permission: string,
\n aliases: string[],
\n executor: (sender: CommandSender, args: string[]) => void,
\n ): void;<\/p>\n
\n key: string,
\n container: PersistentDataContainer
\n ): string;<\/p>\n
\n key: string,
\n container: PersistentDataContainer
\n ): boolean;<\/p>\n
\n key: string,
\n value: string,
\n container: PersistentDataContainer
\n ): void;<\/p>\n
\n}
\n“`<\/p>\n
\nexport class ServerModule {
\n public handlePlayerJoin(event) {
\n console.log(`Player ${event.player.name} has joined the server!`);
\n }
\n}<\/p>\n
\n org.bukkit.event.PlayerJoinEvent,
\n server.handlePlayerJoin.bind(server),
\n);
\n“`<\/p>\n
\nclass ServerModule {
\n public command(sender, args) {
\n console.log(`Command executed by ${sender.displayName()} with args: ${args.join(“, “)}`);
\n }
\n}<\/p>\n
\n “commandname”,
\n “Command description”,
\n “\/commandname
\n “command.permission”,
\n [“alias1”, “alias2”],
\n server.command.bind(server),
\n);
\n“`<\/p>\n
\n{
\n “compilerOptions”: {
\n “incremental”: true,
\n “module”: “commonjs”,
\n “esModuleInterop”: true,
\n “strict”: true,
\n “outDir”: “.\/dist”,
\n “forceConsistentCasingInFileNames”: true,
\n “skipLibCheck”: true,
\n “typeRoots”: [
\n “node_modules\/paperts-java-ts-bind”,
\n “node_modules\/@types”
\n ]
\n },
\n “include”: [
\n “src\/**\/*”
\n ]
\n}
\n“`<\/p>\n
\nnpm install –save github:MetlHedd\/java-ts-bind#1.20-R0.1-SNAPSHOT
\n“`<\/p>\n
\n{
\n “main”: “dist\/index.js”,
\n “scripts”: {
\n “build”: “bun build .\/src\/index.ts –outdir=.\/dist –target=node –format=cjs –external=org.* –external=com.* –external=net.* –external=io.* –external=java.* –external=javet.* –watch”
\n },
\n “dependencies”: {
\n “bun”: “^1.2.19”,
\n “paperts-java-ts-bind”: “github:MetlHedd\/java-ts-bind#1.21.4-R0.1-SNAPSHOT”,
\n “typescript”: “^5.8.3”,
\n “@types\/node”: “^24.0.15”
\n }
\n}
\n“`<\/p>\n
\nimport { Event } from “org.bukkit.event”;
\nimport { PlayerJoinEvent } from “org.bukkit.event.player”;
\nimport { CommandSender } from “org.bukkit.command”;<\/p>\n
\n export function registerEvent
\n eventClass: { new (…args: any[]): T },
\n listener: (event: T) => void,
\n ): void;<\/p>\n
\n name: string,
\n description: string,
\n usageMessage: string,
\n permission: string,
\n aliases: string[],
\n executor: (sender: CommandSender, args: string[]) => void,
\n ): void;
\n}<\/p>\n
\n constructor() {
\n \/\/ This constructor is called when the module is loaded
\n console.log(“My plugin has been loaded!”);
\n }<\/p>\n
\n \/\/ Handle player join event
\n event.player.sendMessage(event.player.name, “Welcome to the server!”);
\n }<\/p>\n
\n sender.sendMessage(“Hello from PaperTS!”);
\n }
\n}<\/p>\n
\n PlayerJoinEvent,
\n server.handlePlayerJoin.bind(server),
\n);
\nPaperTS.registerCommand(
\n “hello”,
\n “Says hello to the player”,
\n “\/hello”,
\n “”,
\n [],
\n server.helloCommand.bind(server),
\n);
\n“`<\/p>\n
\n{
\n “runType”: “SynchronousOnNextTick”
\n}
\n“`<\/p>\n
\n– **`AsynchronousOnNextTick`**: Executes the script asynchronously on the next server tick.
\n– **`NewThread`**: Executes the script asynchronously on a separate thread.<\/p>\n
\n– `\/paperts reload`: Reloads all modules.
\n– `\/paperts reload
\n– `\/paperts list`: Lists all loaded modules.
\n– `\/paperts unload
\n– `\/paperts load
\n.\/gradlew build
\n“`<\/p>\n
\n– Grakkit
\n– Javet
\n– Custom Realms
\n– CraftJS
\n– ScriptCraft<\/p>\n","protected":false},"excerpt":{"rendered":"