UltimatePerms

An ultimate Permission Management plugin for PocketMine-MP

Tabla de Contenidos

Características
Instalación
Configuración
Comandos
Sistema de Permisos
Grupos y Rangos
Almacenamiento
API Pública
Wiki Completa

Características

✅ Sistema de Permisos Contextual — Permisos que varían según el mundo o gamemode

✅ Grupos con Jerarquía — Herencia lineal con detección de ciclos

✅ Rangos Temporales — Expiración automática de permisos y rangos

✅ Múltiples Rangos por Jugador — Combinación de varios grupos

✅ Chat Formatter Personalizado — Prefijos, sufijos y colores dinámicos

✅ 4 Backends de Almacenamiento — YAML, JSON, SQLite, MySQL

✅ Eventos de Expiración — RankExpireEvent, PermissionExpireEvent, GroupPermExpireEvent

✅ Wildcard Support — Permisos con comodines (essentials.*) y negación específica

✅ Metadata Personalizada — Key-value libre para extensibilidad

✅ API Pública — Integración fácil con otros plugins

Instalación

Requisitos

PocketMine-MP 5.0.0 o superior

PHP 8.1+

Pasos

Copiar la carpeta del plugin a plugins/
Iniciar el servidor — el plugin creará config.yml automáticamente
Verificar instalación ejecutando /uperms

Configuración

config.yml

── Chat & Display ────────────────────────────────────────────────────

Placeholders: {prefix} {suffix} {name} {displayname}

{message} {group} {group_display} {chat_color}

chat: enabled: true format: "{prefix}{name}{suffix}§r: {chat_color}{message}"

nametag: enabled: true format: "{prefix}{name}{suffix}"

displayName: enabled: true

locale: en_US

── Storage ──────────────────────────────────────────────────────────

storage:

Opciones: yaml | json | sqlite | mysql

type: json

Solo necesario si type: mysql

mysql: host: 127.0.0.1 port: 3306 user: root password: "" database: ultimateperms

Elegir Backend de Almacenamiento

JSON (por defecto)

storage: type: json

MySQL (recomendado para servidores grandes)

storage: type: mysql mysql: host: tu-servidor.com port: 3306 user: ultimateperms password: tu-contraseña database: ultimateperms

Comandos

Comando Principal: /uperms · alias: /up, /perms

Usuarios (ultimateperms.command.user)

Información del jugador

/uperms user info

Gestión de rangos

/uperms user group set [duración] # Reemplaza todos los rangos /uperms user group add [duración] # Agrega rango adicional /uperms user group remove # Quita un rango

Permisos personales (overrides)

/uperms user perm set [true|false] [duración] [ctx=valor...] /uperms user perm unset /uperms user perm check

Auditoría de permisos resueltos

/uperms user audit [página]

Prefix / Suffix personal

/uperms user prefix set /uperms user prefix unset /uperms user prefix get /uperms user suffix set /uperms user suffix unset /uperms user suffix get

Metadata

/uperms user meta set /uperms user meta unset /uperms user meta get

Grupos (ultimateperms.command.group)

Listar todos los grupos (ordenados por weight)

/uperms group list

Crear / info / eliminar / clonar

/uperms group create [displayName] [weight] /uperms group info /uperms group delete [confirm] /uperms group clone [displayName]

Permisos del grupo

/uperms group perm set [true|false] [duración] [ctx=valor...] /uperms group perm unset /uperms group perm list [página]

Herencia (un solo padre por grupo)

/uperms group parent set /uperms group parent unset

Display

/uperms group setweight <número> /uperms group setprefix /uperms group setsuffix

Metadata

/uperms group meta set /uperms group meta unset /uperms group meta get

Diagnóstico

Verificar origen de un permiso con trazabilidad

/uperms check

Simular permiso con contexto personalizado (sin aplicar)

/uperms simulate [ctx=valor...]

alias: /uperms sim

Listar permisos registrados por un plugin

/uperms inspect

Recargar config.yml y recalcular permisos de todos los jugadores online

/uperms reload

Abrir interfaz gráfica (experimental)

/uperms ui

Formato de Duración

Sufijo Unidad Ejemplo

Y Años 1Y

M Meses 2M

w Semanas 3w

d Días 7d

h Horas 24h

m Minutos 30m

s Segundos 3600s

Se pueden combinar: 1d12h = 36 horas. Omitir duración = permanente.

Ejemplos Prácticos

Crear rango YouTuber

/uperms group youtuber create "§c§lYouTuber" 65

Establecer herencia

/uperms group youtuber parent set vip

Agregar permisos

/uperms group youtuber perm set essentials.fly true

Prohibir fly solo en PvP

/uperms group youtuber perm set essentials.fly false world=pvp

Asignar a jugador permanente (reemplaza rangos anteriores)

/uperms user John group set youtuber

Asignar temporalmente 7 días (sin reemplazar)

/uperms user John group add youtuber 7d

Verificar origen de un permiso

/uperms check John essentials.fly

Simular en otro contexto

/uperms simulate John essentials.fly world=pvp

Sistema de Permisos

Algoritmo de Resolución

El plugin resuelve permisos en este orden de prioridad:

Overrides Personales (máxima prioridad) — permisos asignados directamente al jugador; las negaciones explícitas siempre prevalecen

Grupos del Jugador (ordenados por weight DESC) — se procesan del más pesado al menos pesado

Herencia de Grupos — cada grupo puede heredar de un único padre

Wildcard Support — essentials.* cubre essentials.fly, essentials.nick, etc.

Default: Denegado — si un permiso no está definido en ningún nivel, se deniega

Contextos

Los permisos pueden condicionarse a contextos. Los contextos disponibles son world y gamemode, calculados automáticamente cuando el jugador cambia de mundo o modo de juego.

Permiso global (sin contexto = siempre aplica)

/uperms group vip perm set essentials.fly true

Solo en mundo específico

/uperms group vip perm set essentials.fly true world=creative

Solo en gamemode específico

/uperms group vip perm set essentials.nick true gamemode=survival

Negación en contexto (sobreescribe herencia)

/uperms group vip perm set essentials.fly false world=pvp

Múltiples contextos en un mismo nodo

/uperms user John perm set mycommand.use true world=spawn gamemode=survival

Wildcards

Otorgar todos los permisos bajo essentials

/uperms group admin perm set essentials.* true

Negar uno específico dentro del wildcard

/uperms group admin perm set essentials.ban false

Resultado: tiene todo de essentials EXCEPTO essentials.ban

Grupos y Rangos

Crear Grupo

/uperms group youtuber create "§c§lYouTuber" 65

Parámetros:

youtuber — ID único e inmutable del grupo (lowercase)

"§c§lYouTuber" — Nombre mostrado (soporta códigos de color §)

65 — Weight: mayor = más prioritario en resolución y para el prefijo visible

Jerarquía

Cada grupo puede tener un único padre. La herencia es lineal y el plugin detecta y bloquea ciclos automáticamente:

default (weight=0) ↑ vip (weight=30) ↑ youtuber (weight=65) ↑ admin (weight=100)

Establecer padre

/uperms group youtuber parent set vip

Quitar herencia

/uperms group youtuber parent unset

Protecciones automáticas:

Ciclos de herencia (A→B→C→A) — bloqueados
Auto-herencia — bloqueada
Padres inexistentes — bloqueados; al cargar, el padre se ignora con una advertencia en log

Multi-Rango

Un jugador puede tener varios rangos simultáneamente:

/uperms user John group set vip # Asigna vip, elimina otros rangos /uperms user John group add helper 7d # Agrega helper temporal, mantiene vip

Permisos = unión de todos los grupos + overrides personales

Prefijo = del grupo con mayor weight

Display

/uperms group youtuber setprefix "§7[§c§lYT§7] §f" /uperms group youtuber setsuffix " §c♦"

Override personal para un jugador específico

/uperms user John prefix set "§b[CUSTOM] " /uperms user John suffix set " §b⭐"

Volver al prefijo del grupo

/uperms user John prefix unset

Chat formatter — Placeholders

Placeholder Valor

{prefix} Prefijo resuelto (personal > grupo primario > herencia)

{suffix} Sufijo resuelto (misma lógica)

{name} Nombre del jugador

{displayname} Display name actual (nametag)

{message} Mensaje del chat

{group} ID del grupo primario

{group_display} DisplayName del grupo primario

{chat_color} Meta chat-color (personal > grupo)

Almacenamiento

Tipos Disponibles

Tipo Descripción Recomendado para

json Un archivo JSON por jugador, grupos en un archivo separado Inicio, desarrollo

yaml Equivalente en formato YAML Desarrollo

sqlite Base de datos SQLite local Servidores medianos

mysql Base de datos MySQL remota Servidores grandes

Setup MySQL:

CREATE DATABASE ultimateperms; CREATE USER 'ultimateperms'@'localhost' IDENTIFIED BY 'contraseña'; GRANT ALL PRIVILEGES ON ultimateperms.* TO 'ultimateperms'@'localhost'; FLUSH PRIVILEGES;

API Pública

Otros plugins pueden acceder a UltimatePerms declarando la dependencia en plugin.yml:

depend:

UltimatePerms

Obtener Instancias

use appgallery\uperms\Loader;

$loader = Loader::getInstance();$ sessionManager = $loader->getSessionManager();$ groupManager = $loader->getGroupManager();$ storage = $loader->getStorage();

Consultar Sesión de Jugador

Nota: Los métodos de sesión solo funcionan con jugadores online.

// Por nombre de jugador $session =$ sessionManager->getByName("PlayerName");

// Por XUID $session =$ sessionManager->get($player->getXuid());

if ( $session !== null) { // Verificar permiso (usa el caché resuelto)$ session->hasPermission("essentials.fly");

// Obtener rangos: [groupId => expiresAt|null] $groups =$ session->getGroups();

// Rango primario (mayor weight) $primary =$ sessionManager->getPrimaryGroup($session); // Group|null

// Prefix / suffix actuales $prefix =$ session->getPrefix(); $suffix =$ session->getSuffix();

// Metadata $value =$ session->getMeta("max-homes");

// Contexto actual $context =$ session->getContext(); // ["world" => "...", "gamemode" => "..."]

// Todos los permisos resueltos $all =$ session->getResolvedPermissions(); // [permission => bool] }

Gestión de Rangos (vía SessionManager)

// Asignar rango — elimina todos los rangos anteriores excepto el default $sessionManager->setGroup($ player, "vip");

// Asignar temporal $expiresAt = time() + 7 * 86400; // 7 días$ sessionManager->setGroup( $player, "vip",$ expiresAt);

// Agregar rango sin reemplazar otros $sessionManager->addGroup($ player, "event-bonus", $expiresAt);

// Quitar rango (si el jugador se queda sin rangos, se asigna el grupo default) $sessionManager->removeGroup($ player, "event-bonus");

Gestión de Permisos Personales

use appgallery\uperms\permission\node\Node;

// Permiso permanente $node = new Node(permission: "essentials.fly", state: true);$ sessionManager->addNode( $player,$ node);

// Permiso temporal con contexto $node = new Node( permission: "mycommand.use", state: true, expiresAt: time() + 86400, // 1 día context: ["world" => "spawn"], );$ sessionManager->addNode( $player,$ node);

// Quitar override personal $sessionManager->removeNode($ player, "essentials.fly");

Consultar Grupos

$group =$ groupManager->get("youtuber"); // Group|null

if ( $group !== null) {$ group->getId(); // "youtuber" $group->getDisplayName(); // "§c§lYouTuber"$ group->getWeight(); // 65 $group->getParent(); // "vip" | null$ group->getPrefix(); // "§7[§c§lYT§7] §f" $group->getSuffix(); // " §c♦"$ group->getMetaValue("max-homes"); // string|null $group->getNodes(); // Node[] }

// Grupo por defecto $default =$ groupManager->getDefault(); // siempre existe

Eventos de Expiración

Clase Cuándo se dispara

appgallery\uperms\event\GroupExpireEvent Un rango temporal de un jugador expira

appgallery\uperms\event\PermissionExpireEvent Un nodo personal temporal de un jugador expira

appgallery\uperms\event\GroupPermExpireEvent Un nodo temporal de un grupo expira

use appgallery\uperms\event\GroupExpireEvent; use appgallery\uperms\event\PermissionExpireEvent; use appgallery\uperms\event\GroupPermExpireEvent; use pocketmine\event\Listener;

class MyListener implements Listener {

// Cuando expira el rango de un jugador public function onGroupExpire(GroupExpireEvent $event): void {$ player = $event->getPlayer();$ groupId = $event->getGroupId();$ player->sendMessage("§cTu rango $groupId ha expirado."); }

// Cuando expira un permiso personal de un jugador public function onPermExpire(PermissionExpireEvent $event): void {$ player = $event->getPlayer();$ node = $event->getNode(); // Node$ permission = $event->getPermission(); // string }

// Cuando expira un nodo temporal en un grupo public function onGroupPermExpire(GroupPermExpireEvent $event): void {$ group = $event->getGroup(); // Group$ node = $event->getNode(); // Node$ permission = $event->getPermission(); // string } }

Permisos de Plugin

Todos los permisos tienen default: op.

Nodo Descripción

ultimateperms.admin Acceso total al plugin

ultimateperms.notify.expire Recibir notificaciones cuando expiran permisos o rangos

ultimateperms.command Acceso a la ayuda general

ultimateperms.command.check Verificar permisos de jugadores

ultimateperms.command.inspect Inspeccionar permisos de plugins

ultimateperms.command.reload Recargar configuración

ultimateperms.command.simulate Simular permisos con contexto

ultimateperms.command.ui Interfaz gráfica (experimental)

ultimateperms.command.group Comandos de gestión de grupos

ultimateperms.command.group.create Crear grupos

ultimateperms.command.group.delete Eliminar grupos

ultimateperms.command.group.info Ver información de grupos

ultimateperms.command.group.edit Editar grupos

ultimateperms.command.user Comandos de gestión de usuarios

ultimateperms.command.user.audit Ver auditoría de permisos

ultimateperms.command.user.info Ver información de jugadores

ultimateperms.command.user.perm Gestionar overrides personales

ultimateperms.command.user.meta Gestionar metadata de jugadores

ultimateperms.command.user.group Asignar/quitar rangos a jugadores

Desarrollado por AppGallery