Yeow

Yeow

Write Paper/Folia plugins in TypeScript.

Yeow is a plugin runtime and framework that turns a Paper server into a multi-language plugin host. Plugins you write in TypeScript / JavaScript run inside their own isolated QuickJS threads, load live as .yeow.zip packages, and get a fully-typed API for everything a Paper plugin can touch.

Why Yeow

Yeow is designed for developer productivity: TypeScript-first with complete type inference, an async API that never blocks the server thread, source-map error location (including full async call chains), and a safe-by-default permission model.

Quick Start

npm create yeow@latest -- -y --ts
cd my-plugin && npm install
npm run dev        # Paper test server + hot reload
npm run build      # dist/<name>.yeow.zip + standard JAR

Install the runtime on the server: put yeow-runtime-0.8.0.jar (or yeow-runtime-folia-0.8.0.jar on Folia) into plugins/. Drop your plugin's .yeow.zip into plugins/Yeow/ (auto-scanned at startup) or load it live with /yeow load.

A plugin in TypeScript

import { eventWatch, registerCommand } from 'yeow-api';

// 订阅事件：只读、不阻塞事件派发
eventWatch('playerJoin', async (e) => {
    const name = await e.player.getName();
    await e.player.sendMessage(`<green>欢迎回来，${name}!</green>`);
});

registerCommand('heal', {
    description: '恢复生命值',
    permission: { node: 'myplugin.heal', default: 'op' },
    async executor(p) {
        if (p.sender === 'CONSOLE') return;
        const player = p.sender;
        await player.setHealth(await player.getMaxHealth());
        await player.sendActionBar('<green>已恢复!</green>');
    },
});

字段统一走方法（await player.getHealth() / await player.setHealth(20)）；读取多个字段时用只读快照 const s = await player.snap()，一次往返取回全部。事件可以是订阅（eventWatch，只读）或 拦截（eventIntercept，可修改事件并等待完成）。所有 API 都带类型，编辑器与 AI 助手都能在编译期发现问题。

What's included

Game API — players, worlds, entities, items, inventories (including custom GUI), bossbars, scoreboards, advancements, recipes, PDC, sounds, particles, potions, events, commands.

Runtime services — file system (fs), HTTP client + yeow-server HTTP server, gzip/UTF-8 utilities, logging, environment info, worker threads ("virtual plugins" with their own isolated context), and a cross-plugin service registry.

Developer tools — npm create yeow scaffolding, dev server with hot reload and source-map error display (async call chains included), read-only snapshots (snap) for batch reads, PDC JSON serialization.

Safety — sensitive capabilities (server files, HTTP, resources, processes) are default-deny: each must be declared in yeow.config.json. Native services (spawned subprocesses) require SHA-256 approval before first load.

Upgrading to 0.8.0

0.8.0 removes the entire synchronous API surface. Highlights:

• no *Sync methods and no synchronous property access — use await player.getHealth() / await player.setHealth(20)
• eventOn → eventWatch (subscribe); modify events with the new eventIntercept
• permission checks moved out of the event system: onPermissionCheck(handler)
• registerCommand / registerPermission return a Promise; http.listen returns a Promise
• getEnv() no longer includes timestamp

Full notes: Changelog · rationale: Why the sync API was removed

Folia support

Yeow ships a yeow-runtime-folia build with region-resident scheduling, hot-spot migration, budget control and global-thread routing — the same plugin runs unchanged on Paper or Folia.

Documentation

• Quick Start
• API Reference — every module, typed
• Platform Specifications — protocol/adapters for other runtimes
• Advanced — architecture, scheduler, events, lifecycle
• Runtime Operations — /yeow admin commands & config
• Offline docs (.zip) — full documentation as Markdown
• Changelog

License & source

MIT licensed. Source: github.com/iYeXin/Yeow