PixelScript documentation

A hot-reloadable JavaScript and TypeScript runtime for Minecraft servers.
Read the docs →

Onboard your AI · PixelScript on GitHub · Downloads

---

What PixelScript is

PixelScript runs your server logic as JavaScript on the JVM, calling the real Bukkit/Paper API. Save a file and the change is live. No rebuild, no restart, no reconnect.

You are not learning a scripting language. You are writing Java with JavaScript syntax, against the same API you already know, with the iteration loop of a web app.

registerCommand('heal', (sender, args) => {
  if (!sender.hasPermission('server.heal')) {
    sender.sendRichMessage('<red>No permission.</red>');
    return;
  }

  sender.setHealth(20);
  sender.sendRichMessage('<green>Healed.');
});

That is a complete feature. Save the file and /heal exists. Delete the file and it is gone, unregistered cleanly, with no restart in either direction.

Commands, event listeners and scheduled tasks are unregistered for you on reload. Everything else you own, via a single unload callback. Scripts form an explicit tree of reload barriers, so a change to one feature does not reboot the rest of your server's logic.

Using an AI assistant

Coding agents already speak JavaScript. What they lack is the runtime: the load tree, the globals, the threading rules, the cleanup contract. One command fixes that.

From your scripts directory (plugins/PixelScript/scripts):

git clone --depth 1 https://github.com/pixelib/pixelscript-docs .pixelscript-docs \
  && cp .pixelscript-docs/CLAUDE.md ./CLAUDE.md \
  && grep -qxF '.pixelscript-docs/' .gitignore 2>/dev/null || echo '.pixelscript-docs/' >> .gitignore

You get CLAUDE.md, a condensed reference to the whole runtime, plus the full documentation in the workspace for when the agent needs detail. Nothing in .pixelscript-docs/ is loaded by PixelScript; the runtime only picks up .js and .ts files.

Just the reference file, without the docs:

curl -fsSL https://raw.githubusercontent.com/pixelib/pixelscript-docs/main/CLAUDE.md -o CLAUDE.md

Full guide, including other agents and how to add project-specific context: Onboard your AI.

Contents

Getting started: Overview · Download · How to think about a script

Tutorial: Work environment · Configuration · Scripts and script management

API reference: Script · $ magic imports · Modules · Bukkit · Commands · Events · Scheduler · Concurrency · Database · Fetch · Console · JSON · Shared state · Java implementations

Tips and tricks: Java interop · Interfaces and abstract classes · TypeScript · Profiling · Built-in commands

Contributing

Found a mistake, or something the docs never explained? Open an issue or send a pull request. Corrections from people who just hit the problem are the most valuable kind.

House rules for edits:

• Every article carries YAML front matter. title, parent, nav_order and permalink drive the site navigation.
• Do not change an existing permalink. Published URLs should stay stable. Renaming a file is fine; changing where it resolves is not.
• Link between articles with relative .md paths (./spec-001-script.md). jekyll-relative-links rewrites them to permalinks at build time, so the same link works both here on GitHub and on the published site.
• Screenshots go in assets/img/.
• No em dashes.

Building locally

bundle install
bundle exec jekyll serve

The site is served at http://localhost:4000/pixelscript-docs/.

Pushing to main deploys automatically via the Pages workflow.

License

The documentation in this repository is public. PixelScript itself is commercial software; see the main repository.