Documentación · SRanks 1.0.0

SRanks

Rankups y prestigios para Spigot/Paper con una GUI totalmente configurable, requisitos combinables y recompensas reales. Un solo JAR desde 1.7.10 hasta 26.x.

Instalación Ver comandos Editor in-game →

1.7.10 → 26.x Java 8 Spigot / Paper Vault y PAPI opcionales

Visión general

Todo lo que puedes hacer

SRanks no es solo una lista de rangos: es un sistema de progresión completo, pensado para que un administrador pueda ajustar cada detalle sin tocar Java.

Un JAR para todo

Bytecode Java 8 y capa de compatibilidad para arrancar en 1.7.10, 1.8.8, 1.21.x y 26.x sin builds separados.

Rangos y prestigios

Progresión ordenada, grupos de Vault, rango inicial, reset de prestigio y detección por datos, Vault o permisos.

Requisitos combinables

Dinero, tiempo de juego, XP, ítems, permisos y PlaceholderAPI. Se pueden combinar y consumir al subir.

Recompensas reales

Dinero, comandos de consola, ítems custom capturados de la mano, mensajes, broadcasts, títulos y action bar.

GUI configurable

Cabecera con tu rango actual, indicador de página, paginación, estados visuales, lore por estado, sonidos y botones.

Editor in-game

Recompensas, comandos, requisitos, apariencia de cada estado y selector de ítems con cabezas Base64.

Permisos y LuckPerms

Nodos claros, permiso por rango, editor separado y ejemplos de comandos para LuckPerms.

Rendimiento

Textos e ítems estáticos cacheados, E/S async, top con caché y nada de bucles innecesarios por tick.

Compatibilidad

Un JAR, muchas versiones

SRanks se compila contra la API de Spigot 1.16.5 pero genera bytecode Java 8. Las APIs posteriores se usan por reflexión y degradan si no existen.

Entorno	Estado	Qué se comprobó
Paper 1.7.10 + Java 8	Probado	Arranque, configs, comandos, datos y `/rankup` dinámico.
Paper 1.8.8 + Java 8	Probado	GUI legacy, clics, paginación, editor, recompensas y prestigios.
Paper 1.21.4 + Java 21/26	Probado	GUI, Adventure, hex, PlaceholderAPI, rankup y prestige.
Paper 26.3 + Java 25/26	Probado	Carga, comandos, `/rankup`, Adventure y Materiales modernos.
Spigot 1.7.10 – 1.21.x	Soportado	Misma API usada; solo APIs presentes en 1.7.10.
Spigot/Paper 26.x	Soportado	Detección tolerante a versiones como `26.3.build.231-stable`.

Java

El JAR apunta a Java 8. Los servidores 1.7.10–1.21.x pueden usar Java 8 o superior; los servidores 26.x requieren Java 25+. Para compilar hace falta JDK 21+.

SpigotPaper Java 8 bytecode1.7.10 → 26.x Sin FoundationAdventure opcional

Primeros pasos

Instalación en 5 minutos

Compila o descarga el JARmvn clean package o usa SRanks-1.0.0.jar.

Cópialo a plugins/Arranca el servidor una vez para generar los archivos.

Instala dependencias opcionalesVault + economía para dinero/grupos; PlaceholderAPI para placeholders; LuckPerms para permisos.

Edita los YAMLEmpieza por rankups.yml, gui.yml y messages.yml.

Recarga y pruebaEjecuta /sranks reload y luego /sranks gui o /sranks rankup.

Archivos que se crean

Archivo	Función
`config.yml`	Prefijo, autosave, Vault, detección, sonidos, top y `/rankup` opcional.
`messages.yml`	Todos los mensajes, títulos, action bars y textos del editor.
`gui.yml`	GUI de rangos y prestigios, bordes, relleno, sonidos, plantillas y botones.
`rankups.yml`	Rangos, requisitos, recompensas y overrides de GUI por rango.
`prestiges.yml`	Niveles de prestigio, rango de reset, requisitos y recompensas.
`editor.yml`	Overrides creados por el editor in-game.
`playerdata/<uuid>.yml`	Rango, prestigio y tiempo de juego por jugador.

Actualizar desde otra versión

Los archivos existentes no se sobrescriben. Si vienes de una versión anterior, añade manualmente el bloque commands.rankup-command a tu config.yml. Los mensajes nuevos del editor se rellenan automáticamente desde los defaults del JAR.

Referencia

Comandos

El comando raíz es /sranks (alias /sr). No se registran /ranks, /prestiges ni /rankup3.

Comando	Qué hace	Permiso
`/sranks` o `/sr`	Abre la GUI principal. En consola muestra ayuda.	`sranks.use`
`/sranks gui`	Abre la GUI de rangos.	`sranks.use`
`/sranks rankup`	Intenta subir al siguiente rango.	`sranks.use`
`/sranks ranks`	Lista o GUI según `commands.ranks-mode`.	`sranks.use`
`/sranks prestiges`	GUI o lista de prestigios según `commands.prestiges-mode`.	`sranks.use`
`/sranks prestige`	Intenta ejecutar un prestigio.	`sranks.use`
`/sranks info [jugador]`	Rango actual, siguiente, progreso y requisitos.	`sranks.use`
`/sranks top`	Top por prestigio, rango y tiempo jugado.	`sranks.top`
`/sranks reload`	Recarga configs, mensajes, GUI, ranks y overrides.	`sranks.admin`
`/sranks set <jugador> <rango>`	Fuerza un rango (online u offline).	`sranks.admin`
`/sranks reset <jugador>`	Resetea al rango inicial.	`sranks.admin`
`/sranks editor`	Abre el editor in-game.	`sranks.admin.editor`
`/sranks help`	Muestra la ayuda.	`sranks.use`

Comando opcional `/rankup`

Pensado para jugadores acostumbrados a Rankup3. Se registra dinámicamente y solo si el nombre está libre; SRanks no reemplaza el comando de otro plugin.

YAML

commands:
  rankup-command:
    enabled: true
    root: rankup   # rankup = intenta subir; gui = abre la GUI

/rankup sin argumentos ejecuta la acción de root.
Subcomandos: gui, rankup, ranks, prestiges, prestige, info, top, reload, set, reset, editor, help.
Por defecto está desactivado. Si otro plugin ya usa /rankup, se avisa y no se toca.
/sranks y /sr siguen funcionando siempre.

Seguridad

Permisos y LuckPerms

Los permisos están declarados en plugin.yml. El permiso explícito de un rango se exige siempre; el toggle global solo activa el nodo automático.

Nodo	Default	Uso
`sranks.use`	true	Comandos básicos, GUI, rankup, prestige e info.
`sranks.admin`	op	Reload, set, reset y bypass del editor.
`sranks.admin.editor`	op	Editor in-game de recompensas/requisitos.
`sranks.top`	op	Consultar la clasificación.
`sranks.rankup.<id>`	opcional	Permiso automático si el rango no define uno y el toggle está activo.

Con LuckPerms

BASH

lp user Nombre permission set sranks.use true
lp user Nombre permission set sranks.admin.editor true
lp group admin permission set sranks.admin true
lp user Nombre permission set sranks.rankup.avanzado true

Permiso por rango

El campo permission: de un rango se exige siempre, aunque require-rank-permission esté en false. Si el rango no define permiso y el toggle está en true, se exige sranks.rankup.<id>. Puedes editar el nodo desde el editor in-game, pero el permiso real se concede en LuckPerms.

LuckPermsPermissionsEx Cualquier plugin de permisosOP para el editor

Progresión

Rangos y prestigios

El orden de los rangos se define con order. Si se omite, se usa el orden del archivo. Los prestigios se definen como una lista y su nivel es la posición.

Ejemplo de rango

YAML

ranks:
  aprendiz:
    order: 1
    group: aprendiz
    display-name: "<gradient:#A0A0A0:#FFFFFF><bold>Aprendiz</bold></gradient>"
    permission: ""            # opcional; si se define, se exige siempre
    requirements:
      money: { amount: 1000, take: true }
      playtime: { minutes: 30 }
    rewards:
      money: 250
      commands:
        - "say {PLAYER} ha ascendido de {OLD_RANK} a {RANK}."
      message: "<green>¡Has subido a <bold>{rank}</bold>!</green>"
    gui-item:
      material: LEATHER_CHESTPLATE

Campos de un rango

Campo	Descripción
`order`	Orden numérico. Menor = antes.
`group`	Grupo de Vault al que se cambia. Por defecto, el id.
`display-name`	Nombre visible con formato MiniMessage/legacy.
`permission`	Permiso opcional. Si existe, se exige siempre para subir.
`requirements`	Requisitos combinables (dinero, tiempo, XP, ítems, permiso, placeholder).
`rewards`	Dinero, comandos, ítems, mensaje, broadcast.
`gui-item`	Override opcional del ítem de la GUI para ese rango.

Ejemplo de prestigio

YAML

require-max-rank: true

prestiges:
  - id: prestige_1
    display-name: "<gradient:#FFD700:#FFAA00><bold>✦ Prestigio {level} ✦</bold></gradient>"
    reset-rank: aprendiz
    requirements:
      money: { amount: 100000, take: true }
      playtime: { hours: 5 }
    rewards:
      money: 25000
      commands:
        - "say {PLAYER} alcanzó el prestigio {PRESTIGE}. Vuelve a {RANK}."
      message: "<gold>¡Prestigio {prestige}!</gold>"

Detección del rango

Modo	Comportamiento
`data`	Manda el rango guardado en `playerdata`. Recomendado.
`vault`	Al entrar se sincroniza con el grupo primario de Vault.
`permission`	Al entrar se busca el rango más alto cuyo permiso tenga el jugador.

Vault y grupos

La sincronización de grupo depende de que el proveedor de permisos de Vault implemente grupos. Si no lo hace, usa comandos de recompensa: lp user {PLAYER} parent set {RANK}.

Configuración

Requisitos

Se combinan todos los requisitos definidos. Cada uno muestra su progreso y puede consumir el recurso al subir si take: true.

YAML

requirements:
  money:
    amount: 7500
    take: true
  playtime:
    hours: 2
  xp:
    levels: 5
    take: true
  items:
    take: true
    list:
      - material: DIAMOND
        amount: 8
      - material: EMERALD
        amount: 4
        data: 0
  permission: "sranks.extra.vip"
  placeholder:
    placeholder: "%statistic_hours_played%"
    operator: ">="
    value: "10"

Tipos disponibles

Tipo	Campos	Consumo
`money`	`amount`, `take`	Vault: retira el dinero.
`playtime`	`seconds`, `minutes`, `hours`, `days`, `time: "2h30m"`	No aplica.
`xp`	`levels`, `points`, `amount` + `mode`, `take`	Niveles o XP.
`items`	`list` de `material`, `amount`, `data`, `name`, `take`	Retira los ítems.
`permission`	Cadena o lista de nodos	No aplica.
`placeholder`	`placeholder`, `operator`, `value`	No aplica.

Detalles

playtime se mide desde la instalación del plugin. Un número suelto se interpreta como minutos. En xp, un número suelto es niveles; usa points para XP total. Los ítems aceptan "DIAMOND:8" o mapas. Todos los requisitos aceptan name: para personalizar su etiqueta.

Operadores de placeholder

Operador	Significado
`>=`, `>`, `<=`, `<`	Comparación numérica si el valor es numérico.
`==`, `equals`	Igualdad de texto (sin distinguir mayúsculas).
`!=`	Desigualdad.
`contains`	El valor contiene el texto esperado.

Formato lista

También se admite una lista de mapas con type:

YAML

requirements:
  - type: money
    amount: 1000
  - type: playtime
    minutes: 30
  - type: items
    take: true
    list:
      - material: DIAMOND
        amount: 8

Configuración

Recompensas

Las recompensas se ejecutan al subir de rango o prestigiar. Cada bloque está aislado: si un ítem o comando falla, los demás siguen ejecutándose.

YAML

rewards:
  money: 1500
  commands:
    - "say {PLAYER} ha subido de {OLD_RANK} a {RANK}."
    - "lp user {PLAYER} parent set {RANK}"
  items:
    - material: NETHER_STAR
      amount: 2
      name: "<gold>Recompensa</gold>"
      lore:
        - "<gray>Un premio por tu esfuerzo.</gray>"
      glow: true
      custom-model-data: 100
  message: "<green>¡Ahora eres <bold>{rank}</bold>!</green>"
  broadcast: "<gradient:#FFD700:#FF8C00>✦ {PLAYER} alcanzó {rank}.</gradient>"

Campos de ítem

Campo	Descripción
`material`	Material moderno o legacy. Se mapea automáticamente.
`amount`	Cantidad; se reparte en stacks de 64 si hace falta.
`data`	Data value legacy (1.7–1.12).
`name`, `lore`	Texto con formato y placeholders.
`custom-model-data`	CustomModelData en 1.14+.
`glow`	Brillo falso; se oculta si la versión lo permite.
`skull-owner`	Nombre del jugador para cabezas.
`enchantments`	Lista de `ENCHANT:level`.
`skull-base64`	Textura de cabeza en Base64.
`serialized`	Ítem exacto serializado (lo genera el editor).

Dinero y Vault

Las recompensas de dinero requieren Vault y una economía. Si no hay proveedor, se avisa en consola y se omiten solo esas recompensas; los comandos y los ítems se entregan igual.

Placeholders de recompensa

Placeholder	Valor
`{PLAYER}`	Nombre del jugador.
`{RANK}` / `{OLD_RANK}`	Grupo de Vault del rango nuevo/anterior.
`{rank}` / `{old_rank}`	Nombre visible del rango nuevo/anterior.
`{RANK_DISPLAY}` / `{RANK_ID}`	Nombre visible / id del rango.
`{PRESTIGE}` / `{OLD_PRESTIGE}`	Nivel de prestigio nuevo/anterior.

Los comandos aceptan una cadena o una lista. Los ítems aceptan un mapa o una lista. Los ítems custom capturados desde el editor conservan nombre, lore, NBT, custom model data y encantamientos para la misma versión del servidor.

Apariencia

GUI configurable

La raíz de gui.yml define la GUI de rangos y prestige-gui: la de prestigios. Todo se puede cambiar: título, filas, relleno, bordes, sonidos, botones y la plantilla de cada rango.

YAML

title: "<bold><gradient:#00BFFF:#1E90FF>✦ SRanks ✦</gradient></bold>"
rows: 6
fill: true
fill-item:
  material: GRAY_STAINED_GLASS_PANE
  name: " "
border:
  enabled: true
  material: BLACK_STAINED_GLASS_PANE
  name: " "
sounds:
  open: BLOCK_NOTE_BLOCK_PLING
  click: UI_BUTTON_CLICK
  rankup: ENTITY_PLAYER_LEVELUP
  error: ENTITY_VILLAGER_NO
  page: ITEM_BOOK_PAGE_TURN
sounds-volume: 0.8
sounds-pitch: 1.2

rank-slots: [10, 11, 12, 13, 14, 15, 16,
             19, 20, 21, 22, 23, 24, 25,
             28, 29, 30, 31, 32, 33, 34]

items:
  current-rank:
    slot: 4
    material: NETHER_STAR
    name: "<bold><gradient:#00E5FF:#3B82F6>TU RANGO ACTUAL</gradient></bold>"
    lore:
      - "<dark_gray>────────────────────────</dark_gray>"
      - "<gray>Rango: <white>{rank}</white></gray>"
      - "<gray>Siguiente: <white>{next_rank}</white></gray>"
      - "<gray>Progreso: <white>{progress}%</white></gray>"
      - "{progress_bar}"
      - "<gray>Tiempo jugado: <white>{playtime}</white></gray>"
      - "<gray>Prestigio: <gold>{prestige}</gold></gray>"
      - "<gray>Página: <white>{page}</white>/<white>{pages}</white></gray>"
      - "{requirements}"
    glow: true
    action: none

  page-info:
    slot: 8
    material: PAPER
    name: "<gray>Página <white>{page}</white>/<white>{pages}</white></gray>"
    lore:
      - "<gray>Usa las flechas para cambiar de página.</gray>"
    action: none

  next-rank:
    # Sin slot = plantilla para cada rango
    material: DIAMOND
    material-by-status:
      current: NETHER_STAR
      available: EMERALD
      locked: COAL
      unlocked: IRON_INGOT
      future: STONE
    name: "<bold><gold>➤ {rank}</gold></bold>"
    lore:
      - ""
      - "{status}"
      - ""
      - "<bold>Requisitos:</bold>"
      - "{requirements}"
    lore-by-status:
      current:
        - ""
        - "{status}"
        - "<gray>Este es tu rango actual.</gray>"
      unlocked:
        - ""
        - "{status}"
        - "<gray>Ya superaste este rango.</gray>"
    glow-when: [current, available]
    action: rankup

  rank-button:
    slot: 49
    material: EMERALD
    name: "<bold><gradient:#00FF7F:#32CD32>✔ SUBIR DE RANGO</gradient></bold>"
    action: rankup
  close:
    slot: 45
    material: BARRIER
    name: "<bold><red>✘ Cerrar</red></bold>"
    action: close
  prev-page:
    slot: 48
    material: ARROW
    name: "<bold><yellow>◀ Página anterior</yellow></bold>"
    action: prev-page
  next-page:
    slot: 50
    material: ARROW
    name: "<bold><yellow>Página siguiente ▶</yellow></bold>"
    action: next-page

Cabecera y páginas

El slot 4 muestra TU RANGO ACTUAL con rango, siguiente, progreso, tiempo jugado, prestigio y página. El slot 8 muestra Página X/Y; las flechas 48/50 cambian de página y los rangos se reparten automáticamente entre rank-slots. En instalaciones antiguas, si page-info no existe, SRanks lo añade en memoria sin tocar tu gui.yml.

Variantes por estado

Cada ítem de la plantilla puede cambiar material, nombre, lore y cabeza según el estado. El editor in-game escribe estas claves:

YAML

items:
  next-rank:
    material-by-status:
      current: NETHER_STAR
      available: EMERALD
      locked: COAL
      unlocked: IRON_INGOT
      future: STONE
    name-by-status:
      current: "<green>Tu rango actual</green>"
      available: "<gold>Siguiente rango</gold>"
    lore-by-status:
      current:
        - "<gray>Este es tu rango actual.</gray>"
    skull-base64-by-status:
      current: "eyJ0ZXh0dXJlcyI6..."
    serialized-by-status:
      current:
        ==: org.bukkit.inventory.ItemStack
        type: PLAYER_HEAD
    glow-when: [current, available]

Reglas de la plantilla

Un ítem sin slot es la plantilla que se replica en rank-slots.
Un ítem con slot es fijo (cabecera, botón, cierre, etc.).
Los slots de contenido se paginan automáticamente según rank-slots.
Los botones de página se ocultan en la primera/última página.
Puedes sobrescribir la plantilla de un rango con gui-item en rankups.yml.

Acciones

Acción	Función
`rankup`	Intenta subir al siguiente rango.
`prestige`	Intenta ejecutar el prestigio.
`close`	Cierra el inventario.
`prev-page` / `next-page`	Cambia de página.
`prestige-gui`	Abre la GUI de prestigios.
`ranks-gui`	Vuelve a la GUI de rangos.
`none`	Sin acción.

Estados visuales

Estado	Cuándo se usa	Aspecto por defecto
`current`	Rango actual del jugador.	Verde, “✔ Rango actual”.
`available`	Siguiente rango y requisitos cumplidos.	Dorado, “✔ Puedes subir”.
`locked`	Siguiente rango con requisitos pendientes.	Rojo, “✘ Requisitos incompletos”.
`unlocked`	Rango ya superado.	Verde, “✔ Completado”.
`future`	Rango posterior al siguiente.	Gris, “◈ Bloqueado”.
`max`	El jugador está en el rango máximo.	Dorado, “✦ Rango máximo”.

Ítems y multi-versión

Campo	Detalle
`material`	Nombre moderno o legacy; se mapea automáticamente.
`amount`	Cantidad de 1 a 64.
`data`	Data value en 1.7–1.12.
`custom-model-data`	Se ignora por debajo de 1.14.
`skull-owner`	Nombre para cabezas de jugador.
`glow` / `glow-when`	Brillo falso; en 1.7 no se puede ocultar el encantamiento.
`material-by-status`	Cambia el material según el estado.
`lore-by-status`	Cambia el lore según el estado.

Sonidos

sounds de gui.yml sobrescribe los sonidos globales de config.yml. Los nombres modernos se traducen a legacy en 1.7/1.8 cuando es posible.

GUI de prestigios

YAML

prestige-gui:
  title: "<bold><gradient:#FFD700:#FF8C00>✦ Prestigios ✦</gradient></bold>"
  rows: 5
  fill: true
  border:
    enabled: true
    material: BLACK_STAINED_GLASS_PANE
    name: " "
  prestige-slots: [10, 11, 12, 13, 14, 15, 16, 19, 20, 21, 22, 23, 24, 25]
  items:
    prestige-info:
      slot: 4
      material: NETHER_STAR
      name: "<gold>Prestigio actual: {prestige}</gold>"
      lore:
        - "<gray>Siguiente: {next_prestige}</gray>"
        - "{requirements}"
    prestige-item:
      material: NETHER_STAR
      name: "<gold>Prestigio {prestige}</gold>"
      lore:
        - "{status}"
        - "{requirements}"
      action: prestige
    prestige-button:
      slot: 40
      material: END_CRYSTAL
      name: "<green>✦ PRESTIGIAR ✦</green>"
      action: prestige

Placeholders de GUI

{player}, {rank}, {rank_id}, {next_rank}, {current_rank}, {player_next_rank}, {entry_next}, {status}, {status_icon}, {status_key}, {progress}, {progress_bar}, {requirements}, {requirement_money}, {requirement_playtime}, {requirement_xp}, {requirement_items}, {requirement_permission}, {requirement_placeholder}, {prestige}, {next_prestige}, {current_prestige}, {prestige_display}, {playtime}, {page}, {pages}, {rank_index}, {ranks_total}.

Potencia

Editor in-game

El editor permite a un administrador configurar rangos, prestigios, requisitos y recompensas desde Minecraft, sin editar YAML a mano.

TEXT

/sranks editor

Permiso: sranks.admin.editor También sranks.admin Guardado en editor.yml Persistente

Qué puedes editar

Pantalla	Qué hace
Menú principal	Acceso a rangos, prestigios, recarga y cierre.
Lista de rangos	Lista paginada con id, grupo, requisitos, comandos e ítems.
Lista de prestigios	Lista paginada con nivel, reset, requisitos y recompensas.
Editor de rango	Nombre, grupo, permiso, orden, requisitos, recompensas, comandos, ítems, apariencia, probar y reset.
Editor de prestigio	Nombre, reset-rank, requisitos, recompensas, comandos, ítems, apariencia, probar y reset.
Recompensas	Dinero, comandos, ítems, mensaje, broadcast y probar.
Comandos	Añadir, editar y eliminar comandos de recompensa.
Ítems	Añadir de la mano, elegir desde una GUI, cabeza Base64, cantidad y eliminar.
Apariencia	Ítem de cada estado: actual, siguiente disponible, bloqueado, superado, futuro y máximo.
Selector de ítems	Espacio central para colocar ítems normales o custom con NBT/comandos.
Requisitos	Añadir, editar, eliminar, elegir ítem y alternar consumo.

Flujo rápido

Abre el editorCon un jugador con permiso: /sranks editor.

Elige rango o prestigioLa lista está paginada automáticamente.

Edita recompensasPincha en Recompensas. Para comandos e ítems entra en sus pantallas específicas.

Añade ítems desde la mano o la GUIEl selector abre un espacio central para colocar el ítem; guarda una copia exacta y devuelve el original.

Personaliza la aparienciaEn Apariencia elige el estado (actual, siguiente, bloqueado, superado...) y cambia su ítem, nombre, lore o cabeza Base64.

Prueba y ajustaEl botón “Probar recompensas” ejecuta dinero/ítems/comandos sobre ti.

Atajos

Acción	Resultado
Click izquierdo en un comando	Abre el chat para editarlo.
Click derecho en un comando	Elimina el comando.
Click izquierdo en un ítem	Pide la nueva cantidad.
Click derecho en un ítem	Elimina el ítem.
Click izquierdo en un requisito	Edita su valor.
Click derecho en un requisito	Elimina el requisito.
Shift + click en un requisito	Activa/desactiva si se consume (dinero/ítems/XP).
Escribe “cancelar” en un prompt	Cancela la edición y vuelve al menú.

Prompts de chat

Los textos se piden por chat para evitar límites de la GUI. Se validan antes de guardar y hay un tiempo máximo de 120 segundos por prompt. Puedes escribir cancelar para salir sin cambios.

Cabezas Base64 y ítems custom

En la pantalla de apariencia, el botón Cabeza Base64 pide el código de textura. El chat de 1.7/1.8 limita a 100 caracteres, así que el editor acepta el código en varias partes y lo une; escribe fin al terminar. En versiones modernas se usa PlayerProfile; en 1.7–1.16 se aplica con GameProfile por reflexión. También puedes colocar una cabeza custom en el selector y se guarda su NBT exacto.

YAML

gui-item:
  skull-base64-by-status:
    current: "eyJ0ZXh0dXJlcyI6..."
  serialized-by-status:
    current:
      # ítem exacto con nombre, lore, NBT y comandos
      ==: org.bukkit.inventory.ItemStack
      type: PLAYER_HEAD

Overrides: `editor.yml`

El editor no reescribe rankups.yml ni prestiges.yml. Guarda solo los campos modificados en editor.yml, que se aplica después del YAML base. Así se conservan comentarios y el resto de la configuración.

YAML

ranks:
  aprendiz:
    rewards:
      money: 1234.0
      commands:
        - "say {PLAYER} ha subido a {RANK}."
      items:
        - material: DIAMOND_SWORD
          amount: 1
          name: "<gold>Espada del aprendiz</gold>"
          glow: true
          serialized:
            type: DIAMOND_SWORD
            meta:
              display-name: "§r§6Espada del aprendiz"
prestiges:
  prestige_1:
    rewards:
      money: 7777.0

Alcance del editor

El editor edita rangos/prestigios existentes, sus requisitos, recompensas, comandos, ítems y metadatos. No crea/elimina rangos, no cambia la disposición de gui.yml, no edita messages.yml ni los ajustes globales de config.yml. Eso sigue siendo YAML para no romper el diseño.

Si quieres volver al YAML base, usa “Restablecer override” en el editor de ese rango o prestigio. Los cambios se aplican al instante y persisten tras reiniciar el servidor.

Texto

Formato, colores y gradientes

Todos los textos del plugin aceptan formato mixto. El motor elige la mejor salida disponible según el servidor.

Motor	Cuándo se usa	Sintaxis
MiniMessage / Adventure	Paper 1.16.5+ y 26.x, si está disponible.	`<bold>`, `<gradient>`, `<rainbow>`, `<#RRGGBB>`.
Hex legacy	1.16+, sin Adventure o como fallback.	`&#RRGGBB`, `§x§R§R§G§G§B§B`.
Legacy	Siempre disponible; obligatorio en 1.7–1.15.	`&c`, `§c`, `&l`, `&r`.

TEXT

&c&lHola
&#FF0000Hola
<bold><color:#FF5555>Hola</color></bold>
<bold><gradient:#00BFFF:#1E90FF>SRanks</gradient></bold>
<rainbow>Arcoíris</rainbow>
<bold><italic><underlined>Énfasis</underlined></italic></bold>

Degradación automática

1.16+/26.x: hex real por carácter.
1.7–1.15: el color hex se sustituye por el color vanilla más cercano.
Sin hex, un gradiente usa su primer color para evitar códigos literales.
Sin Adventure, se usa el renderizador legacy interno; con Adventure, chat/títulos/action bar usan componentes nativos.
Las etiquetas desconocidas se conservan como texto literal: <3 no desaparece.

NegritaCursiva SubrayadoTachado ObfuscatedGradientes RainbowHex

Símbolos seguros

Los símbolos ✔ ✘ ✦ ➤ ◀ ▶ ◈ se renderizan igual en 1.7 y 26.x. Los títulos de inventario muy largos pueden truncarse por el cliente; usa textos cortos.

Integraciones

Placeholders

SRanks registra una expansión de PlaceholderAPI con identificador sranks y también expone placeholders propios en mensajes y GUI.

Placeholder	Valor
`%sranks_rank%`	ID del rango actual.
`%sranks_rank_display%`	Nombre visible sin formato.
`%sranks_rank_index%`	Posición 1-based del rango.
`%sranks_ranks_total%`	Total de rangos.
`%sranks_next_rank%`	ID del siguiente rango.
`%sranks_next_rank_display%`	Nombre del siguiente rango.
`%sranks_prestige%`	Prestigio actual.
`%sranks_next_prestige%`	Siguiente nivel de prestigio.
`%sranks_next_prestige_display%`	Nombre del siguiente prestigio.
`%sranks_playtime%`	Tiempo jugado formateado.
`%sranks_playtime_seconds%`	Segundos jugados.
`%sranks_progress%`	Progreso 0–100 hacia el siguiente rango.
`%sranks_progress_bar%`	Barra de progreso.
`%sranks_can_rankup%`	`true`/`false`.
`%sranks_status%`	`available`, `locked` o `max`.
`%sranks_requirements%`	Requisitos en texto.
`%sranks_requirement_<tipo>%`	money, playtime, xp, items, permission o placeholder.

Placeholders internos en mensajes y GUI

En messages.yml, gui.yml y recompensas: {player}, {rank}, {next_rank}, {old_rank}, {RANK}, {OLD_RANK}, {PRESTIGE}, {progress}, {progress_bar}, {requirements}, {requirement_money}, {requirement_playtime}, {requirement_xp}, {requirement_items}, {requirement_permission}, {requirement_placeholder}, {playtime}.

YAML

requirements:
  placeholder:
    placeholder: "%player_level%"
    operator: ">="
    value: "30"

PAPI en 26.3

Algunas versiones antiguas de PlaceholderAPI (por ejemplo 2.11.6) fallan al arrancar en 26.3 por su propio parser de versión. SRanks lo detecta y sigue funcionando sin PAPI. Usa una build de PlaceholderAPI compatible con tu servidor.

Referencia

Archivos y configuración

La configuración está separada por responsabilidades. Los archivos existentes no se sobrescriben; las claves nuevas de mensajes se rellenan desde los defaults del JAR.

Archivo	Contenido
`config.yml`	Prefijo, autosave, playtime, Vault, detección, compatibilidad, sonidos, top y comandos.
`messages.yml`	Todos los mensajes, títulos, action bars y textos del editor.
`gui.yml`	GUI de rangos/prestigios, bordes, relleno, sonidos, plantillas y botones.
`rankups.yml`	Rangos, requisitos, recompensas y overrides de GUI.
`prestiges.yml`	Niveles de prestigio, reset, requisitos y recompensas.
`editor.yml`	Overrides del editor in-game (precedencia sobre el YAML base).
`playerdata/<uuid>.yml`	Rango, prestigio y tiempo de juego.

Claves principales de `config.yml`

Clave	Default	Descripción
`prefix`	gradient SRanks	Prefijo usado en los mensajes con `{prefix}`.
`settings.playtime-tick-seconds`	`60`	Consolidación del tiempo de juego.
`settings.autosave-minutes`	`5`	Guardado async de datos; 0 lo desactiva.
`settings.starting-rank`	`aprendiz`	Rango inicial para nuevos jugadores.
`settings.reset-prestige-on-reset`	`false`	Reset de prestigio con `/sranks reset`.
`permissions.require-rank-permission`	`false`	Activa el nodo automático por rango.
`vault.sync-group`	`true`	Cambia el grupo de Vault al subir.
`vault.remove-old-group`	`true`	Retira el grupo anterior.
`rank-detection.mode`	`data`	`data`, `vault` o `permission`.
`compat.use-adventure`	`auto`	Usa Adventure si está disponible.
`compat.placeholderapi-in-text`	`true`	Resuelve PAPI en mensajes/GUI.
`compat.use-economy-format`	`true`	Usa el formato de la economía en la GUI.
`sounds.*`	modernos	Sonidos globales; `gui.yml` puede sobrescribirlos.
`top.size` / `cache-seconds`	`10` / `60`	Tamaño y caché del top.
`commands.rankup-command.enabled`	`false`	Activa `/rankup` dinámico.
`commands.ranks-mode`	`gui`	`gui` o `text`.
`commands.prestiges-mode`	`gui`	`gui` o `text`.

Mensajes

messages.yml está agrupado por contexto: general, rankup, prestige, info, ranks, prestiges, top, help, admin, gui y editor. Los títulos y action bars de rankup/prestige también se configuran ahí. Si una clave falta, se usa el default del JAR; nunca se sobrescribe tu archivo.

Precedencia de overrides

Si un rango tiene una entrada en editor.yml, sus campos mandan sobre rankups.yml. Para volver al YAML base, usa “Restablecer override” en el editor o elimina la entrada de editor.yml y ejecuta /sranks reload.

Integraciones

Vault y progreso del jugador

Vault es opcional, pero aporta dinero para requisitos/recompensas y, si el proveedor lo permite, cambio de grupo al subir de rango.

Función	Comportamiento
Dinero	Requisitos y recompensas usan la economía registrada en Vault.
Grupos	Con `vault.sync-group: true`, cambia el grupo primario al subir.
Detección	`rank-detection.mode: vault` sincroniza al entrar con el grupo primario.
Fallback	Si el proveedor no soporta grupos, usa comandos de recompensa.

YAML

# Si tu proveedor de Vault no cambia grupos, esto es 100% fiable:
rewards:
  commands:
    - "lp user {PLAYER} parent set {RANK}"

Proveedores de grupos

LuckPerms suele funcionar mediante Vault, pero algunos setups no registran el proveedor de grupos. SRanks detecta hasGroupSupport(); si no está disponible, no rompe el rankup: solo omite el cambio de grupo y deja que tus comandos lo hagan.

Tiempo de juego

SRanks mide el tiempo por sí mismo: sesión actual + acumulado persistido.
No usa estadísticas de vanilla que cambiaron de nombre en 1.13.
Se consolida cada settings.playtime-tick-seconds.
Se guarda cada settings.autosave-minutes, al salir, al subir y al apagar.
El tiempo empieza a contar desde la primera sesión que ve SRanks.

Datos y top

Cada jugador tiene un YAML en playerdata/<uuid>.yml con rango, prestigio y segundos jugados. El top lee esos archivos de forma async y cachea el resultado. Los datos de jugadores online se superponen al archivo para que el top esté actualizado.

Async I/OAutosave Top con cachéGuardado configurable

Desarrollo

Compilar y probar

El proyecto Maven genera un JAR único. Los tests unitarios cubren el motor de formato, los YAML, requisitos, serialización del editor y defaults de mensajes.

BASH

mvn clean test
mvn clean package

# Resultado:
# target/SRanks-1.0.0.jar

Requisito	Detalle
JDK de compilación	21 o superior (el proyecto usa `--release 8`).
Java en runtime	Java 8+ para 1.7.10–1.21.x; Java 25+ para 26.x.
Spigot/Paper	1.7.10 hasta 26.x.
Dependencias de build	Spigot API 1.16.5, VaultAPI 1.7, PlaceholderAPI 2.11.6, Adventure 4.17 (provided).
Dependencias de runtime	Ninguna obligatoria además del servidor; Vault/PAPI/LuckPerms opcionales.

Matriz de pruebas realizada

Entorno	Resultado
Paper 1.7.10 + Java 8	Arranque, configs, comandos, datos y `/rankup` dinámico.
Paper 1.8.8 + Java 8	GUI legacy, editor, clics, paginación, recompensas y prestigios.
Paper 1.21.4 + Java 26	GUI, Adventure, hex, PlaceholderAPI, rankup y prestige.
Paper 26.3 + Java 26	Carga, comandos, `/rankup` dinámico y Adventure.
Vault 1.7.3 + economía de prueba	Depósito de recompensa de dinero en un rankup.

Checklist rápida

1) El plugin arranca sin errores. 2) /sranks help responde. 3) La GUI abre y pagina. 4) Un rankup con requisitos cumple y descuenta. 5) Las recompensas llegan. 6) /sranks editor guarda y persiste. 7) /sranks reload no rompe nada.

El build actual ejecuta 34 tests y termina sin fallos. La GUI/editor de 26.3 no se pudo automatizar con bot por el protocolo, pero sí se validaron carga, clases, comandos y Adventure.

Transparencia

Limitaciones reales

Estas son las restricciones que debes conocer antes de montar el plugin en producción. Están documentadas para evitar sorpresas.

Dinero y Vault

Las recompensas/requisitos de dinero necesitan Vault y una economía. Sin proveedor, se avisa y se omiten solo esas partes.

Grupos de Vault

El cambio de grupo depende del proveedor. Si no implementa grupos, usa comandos de recompensa (LuckPerms, etc.).

Ítems serializados

El editor guarda el ítem exacto para la misma versión del servidor. Para portabilidad entre versiones, usa comandos.

Alcance del editor

No crea/elimina rangos, no edita gui.yml, messages.yml ni la config global. Eso sigue en YAML.

1.7 y formato

Sin hex ni Adventure. Los gradientes degradan al primer color. El glow muestra encantamiento porque no existe ItemFlag.

Títulos largos

El cliente limita la longitud visible del título de inventario. Usa títulos cortos y placeholders compactos.

Requisitos de ítems

Se comparan por material y data. No se exige nombre/NBT exacto; para eso usa un requisito de placeholder.

PlaceholderAPI en 26.3

Algunas versiones antiguas de PAPI fallan al arrancar en 26.3 por su propio parser. SRanks sigue sin PAPI.

Más notas

Playtime: no importa estadísticas históricas de vanilla; empieza con SRanks. Top: lee YAML en async y cachea; para redes muy grandes, una base de datos sería el siguiente paso. /rankup: si otro plugin ya usa ese nombre, SRanks no lo pisa. PAPI 26.3: usa una build compatible. 1.7: el servidor debe correr Java 8+; el JAR es bytecode 8.

Ayuda

Preguntas frecuentes

He subido de rango pero no me han dado el dinero.

Revisa que Vault esté instalado y que exista un proveedor de economía. Si no lo hay, SRanks avisa en consola y omite solo el dinero; los comandos/ítems sí se entregan. Con Vault activo, comprueba que la cantidad sea mayor que 0.

No existe /rankup.

Por defecto está desactivado. Añade commands.rankup-command.enabled: true a config.yml y ejecuta /sranks reload. Si otro plugin ya usa /rankup, SRanks no lo reemplaza; usa /sranks.

El editor no guarda mis cambios.

Comprueba que tienes sranks.admin.editor o sranks.admin. Los cambios se guardan en editor.yml; si el archivo no es escribible, revisa permisos. Después de guardar, SRanks recarga el rank manager automáticamente.

¿Dónde están los cambios del editor?

En plugins/SRanks/editor.yml. Es una capa de overrides para no destruir los comentarios de rankups.yml/prestiges.yml. Para volver al YAML base, usa “Restablecer override”.

¿Cómo doy permisos con LuckPerms?

Usa los nodos de la sección Permisos. Por ejemplo: lp user Nombre permission set sranks.use true y lp user Nombre permission set sranks.admin.editor true. El permiso por rango se concede con el nodo configurado en el rango o con sranks.rankup.<id>.

¿Por qué no aparecen los mensajes nuevos?

Los archivos existentes no se sobrescriben. SRanks combina los defaults del JAR para las claves que falten en messages.yml. Si una clave no aparece, revisa que el YAML no esté corrupto y ejecuta /sranks reload.

¿Cómo cambio la GUI?

Edita gui.yml: título, filas, relleno, borde, sonidos, rank-slots, plantillas y botones. Los ítems sin slot son plantillas; los que tienen slot son fijos. Puedes sobrescribir la plantilla de un rango con gui-item.

¿Cómo hago que un ítem custom se entregue como recompensa?

El editor in-game tiene “Añadir ítem de la mano”. Guarda el ítem serializado (nombre, lore, NBT, custom model data, encantamientos). Para configurarlo a mano, usa items: con material, amount, name, lore, etc.

¿Por qué PAPI no resuelve placeholders?

Comprueba que PlaceholderAPI esté instalado y que compat.placeholderapi-in-text esté en true. En 26.3, algunas versiones antiguas de PAPI fallan por su propio parser; usa una build compatible.

Historial

Changelog 1.0.0

Primera versión pública del SRanks reescrito. Fecha: 2026-10-30.

1.0.02026-10-30 · primera release pública

Añadido

Rangos y prestigios configurables, con requisitos combinables y recompensas completas.
GUI paginada con cabecera “tu rango actual”, indicador de página, estados, lore por estado y sonidos.
Editor in-game para metadatos, requisitos, recompensas, comandos e ítems custom.
Apariencia por estado para rangos/prestigios, selector de ítems y cabezas Base64.
Comando opcional /rankup con los mismos subcomandos que /sranks.
PlaceholderAPI, Vault, grupos de Vault y permisos compatibles con LuckPerms.
Un JAR Java 8 para 1.7.10–26.x, con degradación de formato y materiales.
Persistencia async, autosave, top cacheado y overrides en editor.yml.

Corregido

commands acepta cadena o lista; items acepta mapa o lista.
El dinero se lee desde rewards.money y desde el nivel superior.
Un ítem/comando fallido ya no cancela el resto de recompensas.
La economía de Vault se reintenta si carga después que SRanks.
Requisitos/recompensas de prestigios definidos como lista se parsean correctamente.
Tamaños/slots del editor corregidos para evitar errores fuera de rango.

Cambiado

El permiso explícito de un rango se exige siempre; el toggle global solo activa el nodo automático.
Los messages.yml existentes reciben las claves nuevas del editor desde los defaults.
/rankup está desactivado por defecto y se registra dinámicamente si el nombre está libre.

SRanks

Todo lo que puedes hacer

Un JAR para todo

Rangos y prestigios

Requisitos combinables

Recompensas reales

GUI configurable

Editor in-game

Permisos y LuckPerms

Rendimiento

Un JAR, muchas versiones

Instalación en 5 minutos

Archivos que se crean

Comandos

Comando opcional /rankup

Permisos y LuckPerms

Con LuckPerms

Rangos y prestigios

Ejemplo de rango

Campos de un rango

Ejemplo de prestigio

Detección del rango

Requisitos

Tipos disponibles

Operadores de placeholder

Formato lista

Recompensas

Campos de ítem

Placeholders de recompensa

GUI configurable

Cabecera y páginas

Variantes por estado

Reglas de la plantilla

Acciones

Estados visuales

Ítems y multi-versión

GUI de prestigios

Placeholders de GUI

Editor in-game

Qué puedes editar

Flujo rápido

Atajos

Cabezas Base64 y ítems custom

Overrides: editor.yml

Formato, colores y gradientes

Degradación automática

Placeholders

Placeholders internos en mensajes y GUI

Archivos y configuración

Claves principales de config.yml

Mensajes

Vault y progreso del jugador

Tiempo de juego

Datos y top

Compilar y probar

Matriz de pruebas realizada

Limitaciones reales

Dinero y Vault

Grupos de Vault

Ítems serializados

Alcance del editor

1.7 y formato

Títulos largos

Requisitos de ítems

PlaceholderAPI en 26.3

Preguntas frecuentes

Changelog 1.0.0

Añadido

Corregido

Cambiado

Comando opcional `/rankup`

Overrides: `editor.yml`

Claves principales de `config.yml`