KSPlaceholder

KSPlaceholder es un motor de placeholders diseñado para servidores complejos donde múltiples plugins exponen tokens (%kseco_saldo%, %ksprotect_region%, %kschunk_progreso%, etc.). Ofrece un registro por namespace con separación clara entre claves exactas y prefijos dinámicos, caché por token con TTL, y un puente automático a PlaceholderAPI para no obligar a los usuarios a instalar los dos.

Características

• Namespaces separados — cada plugin registra sus tokens bajo su propio prefijo (kseco_, ksprotect_, kschunk_). Cero colisiones.
• Claves exactas + prefijos dinámicos — resuelve %plugin_saldo% como clave exacta o %plugin_top:5% como prefijo con argumento.
• Caché por token con TTL configurable — evita re-cálculos costosos. Cada namespace decide su política (o desactiva).
• Fallback — cuando ninguna clave/prefijo casa, un handler global de la expansión decide.
• Integración transparente con PlaceholderAPI — si PAPI está cargado, KSPlaceholder registra un puente automático. Los tokens %plugin_x% funcionan igual desde ambos motores.
• Herramientas de debug — /ksp list, /ksp info, /ksp parse, /ksp cache para diagnosticar qué namespace responde a qué.
• Async-safe — los resolvers deben ser puros (sin I/O). El motor puede resolver desde cualquier hilo.

Instalación

1. Descarga KSPlaceholder-1.0.0.jar.
2. Coloca el JAR en plugins/.
3. Coloca KSCore.jar.
4. Opcional: PlaceholderAPI.jar — KSPlaceholder se autopuentea.
5. Arranca el servidor.

Los plugins del ecosistema (KsEconomia, KSProtect, KSChunk, KSBoard) detectan automáticamente KSPlaceholder al arrancar y registran sus expansiones.

Requisitos
Requisito Versión mínima
Servidor Paper 1.21+ (api-version 26.2)
Java 21
KSCore 1.0-SNAPSHOT o superior
Dependencias
Plugin Tipo Rol
KSCore Requerida Framework
PlaceholderAPI Opcional Puente bidireccional automático
Comandos
Todos requieren permiso ksp.admin.

Comando Descripción
/ksp list Namespaces registrados con conteo de tokens
/ksp info <namespace> Detalles: claves exactas, prefijos dinámicos, fallback, TTL de caché
/ksp parse <texto> Resuelve el texto sobre ti (solo jugador)
/ksp test <jugador> <texto> Resuelve sobre un jugador online
/ksp reload Recarga config y catálogos internos
/ksp cache stats [ns] Estadísticas de la caché (global o por namespace)
/ksp cache clear [ns] Vacía la caché
Aliases: /ksplaceholder

Permisos
Permiso Default Descripción
ksp.admin op Todos los comandos administrativos
Uso desde otro plugin
Añade la dependencia soft en tu paper-plugin.yml:


La API vive en un módulo independiente. Otros plugins pueden compilar contra ella sin arrastrar KSCore.

Registrar una expansión

Resolver placeholders

Contrato del resolver

Reglas:

• El resolver corre en el hilo que llame a parse. Puede ser el hilo del servidor, pero también uno async (por ejemplo, desde KSBoard que resuelve el scoreboard en async).
• Nunca consultes BD ni hagas I/O en el resolver. Cachea el valor en memoria y devuélvelo desde ahí.
• Devolver null significa "este placeholder no aplica". El motor pasa a la siguiente variante (prefijo más corto, fallback) o deja el token intacto.
• El resultado se formatea después. Números decimales se recortan a la escala configurada, Boolean se traduce por el motor, el resto pasa por String.valueOf. No llames a String.valueOf manualmente.

Orden de resolución
Cuando el motor ve %namespace_algo%:

1. Busca namespace en el registro.
2. Intenta clave exacta algo (registrada con .add).
3. Si no, prefijo dinámico más largo que coincida (registrado con .dynamic).
4. Si tampoco, .fallback de la expansión.
5. Si nadie responde, deja %namespace_algo% en el texto — otro motor (como PAPI) puede intentarlo.

Puente PlaceholderAPI
Si PlaceholderAPI está cargado:

• Todos los tokens KS también funcionan bajo el motor PAPI: %kseco_saldo% en un plugin que sólo entienda PAPI se resuelve correctamente.
• Todos los tokens PAPI (%player_*%, %server_*%, expansiones instaladas) también funcionan bajo KSP.

Un plugin que dependa de KSP puede usar el token %luckperms_primary_group% sin importarle si viene de PAPI o de una expansión KS. El puente es transparente.

Debug
Situaciones típicas:

"Mi token %miplugin_x% no se resuelve".

/ksp list
/ksp info miplugin
/ksp parse "%miplugin_x%"
Comprueba que:

• El namespace aparece en list.
• La clave x aparece en info.
• El resolver no está devolviendo null (si devuelve null, el motor deja el token intacto).

"El valor está desactualizado".

/ksp cache clear miplugin
Fuerza recomputación. Si el problema persiste, el TTL puede ser demasiado alto:

.cache(Duration.ofSeconds(1)) // en lugar de 30 o similar
Rendimiento

• Registro con HashMap — lookup O(1) por namespace.
• Caché con ConcurrentHashMap<(uuid, ns, key), (valor, expira)> — segura desde cualquier hilo.
• El puente PAPI usa reflexión sólo una vez al arrancar; llamadas subsiguientes son directas.