Permission

Yeow provides its own permission node API — compatible with the Paper ecosystem (permissions.yml / LuckPerms and other permission management plugins), while also offering a higher-priority permission check hook for the Yeow ecosystem (onPermissionCheck checkers, cross-platform and relying only on the Yeow specification).

import { registerPermission } from 'yeow-api';

const perm = await registerPermission({ node: 'myplugin.home', default: 'all' });
// → { node: 'myplugin.home', default: 'all' }

registerPermission

registerPermission({ node: string, default?: 'all' | 'op' | 'none' }): Promise<Permission>

Registers a permission node (idempotent) and returns a Permission object ({ node, default }). default is 'op' by default.

default	Meaning
'all'	Everyone has it by default (regular players can use it; the server owner can revoke it via a permission plugin)
'op'	Only op has it by default — the default value
'none'	No one by default (requires authorization via a permission plugin / permissions.yml)

• The node is registered into the Paper permission system (PermissionDefault mapping) — on the Paper platform it can be statically declared via permissions.yml or managed by permission management plugins such as LuckPerms
• Coarse-grained: it only declares the default; fine-grained management is delegated to permission plugins (Paper ecosystem) or onPermissionCheck (Yeow ecosystem)

Command permissions

registerCommand's permission accepts: a string (wrapped on the JS side as { node, default: 'op' }), a permission node object ({ node, default }), or the return value of registerPermission:

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

const homePerm = await registerPermission({ node: 'myplugin.home', default: 'all' });

registerCommand('home', {
    permission: homePerm,              // or { node: 'myplugin.home', default: 'all' }, or 'myplugin.home'
    executor: (p) => { /* ... */ },
});

• The node is registered into the Paper permission system (manageable by permission plugins)
• Checked at execution time (commands don't set a Paper-side setPermission to intercept): the permission checker (onPermissionCheck) result takes priority; when unhandled it falls back to Paper-side hasPermission; players without permission are shown "No permission."; tab completion is not filtered by permission

Checking permissions

Plugins can use player.hasPermission anywhere:

const ok = await player.hasPermission('myplugin.home');   // string
const ok2 = await player.hasPermission(homePerm);         // permission node object

Check flow (the check is triggered only in the Yeow ecosystem; other Java plugins' hasPermission / command execution do not go through it):

player.hasPermission / Yeow command execution check
  → permission checker (any Yeow plugin handling it?)
      → returns { allowed }  → adopted (overrides Paper ecosystem)
      → returns nothing      → falls back to Paper-side hasPermission

onPermissionCheck (Yeow ecosystem permission check)

WARNING

Ordinary plugins should not register a permission checker. It is asked on every Yeow permission check and the main thread spins while waiting — this API exists for permission management plugins (role/allowlist/ time-limited VIP managers). To gate your own features, call player.hasPermission(node) with a node you registered via registerPermission.

Designed for Yeow ecosystem permission management plugins (cross-platform, depending only on the Yeow specification), and in the Yeow ecosystem it takes priority over the Paper permission system:

import { onPermissionCheck } from 'yeow-api';

const sub = onPermissionCheck((check) => {
    const { target, node, permission } = e;   // permission: { node, default }
    if (node === 'myplugin.home' && isVip(target)) {
        return { allowed: true };   // overrides the Paper ecosystem result
    }
    // returns nothing → falls back to Paper-side hasPermission
});

• Trigger scope (Yeow ecosystem only): player.hasPermission tasks + execution checks of commands registered by Yeow plugins — other Java plugins' permission checks do not go through it
• Async is allowed: if the handler returns a Promise the runtime waits for it to settle before taking the result (game calls made while awaiting are executed by the waiter draining the scheduler, so DB/service lookups work fine);
• ⚠ Cost: while waiting for the answer the main thread spins (same as event dispatch) — keep async handlers very short; after the timeout (5s default) the check falls back to "unhandled".
• Priority: when a value is returned it overrides the Paper ecosystem; when multiple handlers return conflicting values, the last one to return wins (order of execution not guaranteed); a timeout (following the normal event timeout config profile.callback-timeout-event-ms, default 5s) is treated as unhandled
• Event data: { target, node, permission } — permission is the permission object (including the node's default value)
• ⚠ Infinite loop: calling hasPermission inside a permission checker (including after an await) triggers this check again — this can cause an infinite loop, so avoid it (if you need to query, read your own data directly)

Permission management

Method	Applies to	Description
Paper ecosystem permission plugins (LuckPerms, etc.) / permissions.yml	Server owners (Paper ecosystem)	Nodes are registered into the Paper permission system and can be granted/revoked finely
onPermissionCheck checker	Yeow ecosystem permission management plugins	Arbitrary logic (allowlist/time-limited/VIP, etc.), cross-platform, higher priority