Referencia de configuración

config.yml es la superficie de control que pertenece al operador. ReferralTrack nunca reemplaza en silencio un archivo personalizado. Cuando cambia la versión del esquema, el plugin conserva el original como config.yml.bak-v<old>, escribe la nueva referencia completa en config.new-v<new>.yml, actualiza solo la marca de versión del archivo activo e informa de las rutas que faltan al arrancar. Los valores predeterminados incluidos de Bukkit mantienen operativas las opciones nuevas hasta que el operador las copie o personalice.

El acceso administrativo usa nodos de permiso granulares de Bukkit y funciona con LuckPerms sin OP ni dependencia obligatoria de una API. Consulta Comandos y permisos; referraltrack.admin sigue siendo el padre con acceso total.

Sistemas principales #

• database: conexión SQLite o MySQL/MariaDB y tiempos acotados del pool. Mantén las credenciales en privado.
• referral: política de reclamación, orígenes conocidos, códigos personales, validación, límites de recompensa, comandos, hitos y atribución de retención.
• campaigns: interruptor del motor, zona horaria y fechas de campaña independientes, filtros, códigos, multiplicadores, recompensas e hitos. Consulta Campañas.
• fraud: interruptor del motor de riesgo, umbral de revisión del personal y señales de cuenta/tiempo de juego. Consulta Revisión de fraude.
• discord: rutas de webhook opcionales, informes, intervalo de actualización de estadísticas en vivo, campos de embed con marca y URL HTTPS seguras de medios/botones. Un bot completo de Discord no forma parte de esta versión.
• integrations.developer-api: registro en el ServicesManager de Bukkit de la API asíncrona de solo lectura. events.pre-claim y events.claim-result controlan de forma independiente los dos eventos públicos de reclamación; desactivar la API desactiva ambos. Consulta API para desarrolladores.
• text-formatting: activa de forma independiente el formato MiniMessage y los códigos antiguos con ampersand. Los degradados, el arcoíris, el color RGB y las etiquetas de estilo reconocidos de MiniMessage pueden convivir con & y &#RRGGBB; los marcadores ordinarios entre ángulos se mantienen literales.
• player-interface: selecciona AUTO, INVENTORY o DIALOG. AUTO usa la API nativa de diálogos de Java de Paper cuando existe y, si no, abre el inventario independiente. Los anchos del cuerpo y los botones del diálogo, las columnas, el comportamiento de pausa/escape y la política de reserva están acotados y son configurables. El texto del diálogo y las cuatro etiquetas de botón están localizados en dashboard.dialog-*. /referral inventory abre siempre el menú independiente.
• player-feedback.claim: controles del título, subtítulo, barra de acción, sonido y partículas de la reclamación. Cada canal tiene su propio interruptor; los tiempos del título, el volumen/tono del sonido y el número/desplazamiento/velocidad de las partículas están acotados. La animación de partículas admite las formas acotadas BURST, RING y HELIX con fotogramas, intervalo, radio y altura configurables. Los valores no válidos de sonido, partículas o animación fallan sin ruido con un diagnóstico que se emite una sola vez.
• onboarding: guía del primer arranque, validación automática de solo lectura y número máximo de hallazgos notificados. /referraltrack validate comprueba los límites de la base de datos y el pool, la identidad del referido y las restricciones de recompensa, los umbrales de validación y fraude, los horarios de informes, los nodos de red pasivos y Discord activado pero sin configurar. Informa de rutas y expectativas seguras, nunca de valores secretos configurados.
• velogrowth: interruptor de la clasificación de calidad, muestra mínima, tamaño de la clasificación, ventana de evaluación y seis pesos relativos. El volumen bruto solo determina la elegibilidad. La validación, la seguridad frente a rechazos, la seguridad de riesgo y la retención madura D1/D7/D30 contribuyen a la puntuación de 0–100; las cohortes inmaduras se omiten y cada dato de entrada se muestra con /referraltrack growth.
• campaign-guard: interruptor de la comprobación previa de activación, ventana de «termina pronto», aviso de multiplicador de recompensa, número máximo de comandos, gravedad de la economía ausente y umbrales de dinero configurables por reclamación y por total estimado. La estimación total usa exposure.expected-claims. Los hallazgos críticos bloquean la activación de la campaña y el encendido del motor; las advertencias siguen visibles sin cambiar la campaña en silencio.
• reward-rescue: permiso del personal, tamaño de la lista, umbrales de antigüedad de pendientes/atascadas e intentos manuales máximos. /referraltrack rescue es de solo lectura salvo que retry o cancel incluya confirm y un motivo imprimible. Las filas en procesamiento nunca se reintentan automáticamente porque Vault o un comando de consola puede haberse ejecutado ya antes de un fallo. Consulta Reward Rescue.
• settings: propiedad del seguimiento/entrega para redes, identidades ignoradas y limpieza de retención.
• menu: todos los tamaños de inventario incluidos, ranuras, materiales, títulos, lore, capacidades de página, navegación, visualización de la hora del historial de recompensas y aspecto de la barra de progreso.

Cada frase visible para jugadores o personal está en lang/<language>.yml; se incluyen cinco idiomas completos. Las claves de traducción personalizada que faltan recurren al inglés incluido sin sobrescribir el archivo de idioma personalizado.

El texto de la reacción a la reclamación se localiza mediante feedback.claim-title, feedback.claim-subtitle y feedback.claim-action-bar. Los marcadores admitidos son {player}, {source} y {status}. La mecánica visual y de audio permanece en player-feedback.claim, de modo que los operadores pueden cambiar la presentación sin editar las traducciones.

Reglas de seguridad de los menús #

Los tamaños de inventario deben ser múltiplos de 9 entre 9 y 54. Las ranuras empiezan en cero y deben caber en el inventario configurado. Los campos de material aceptan materiales de Bukkit y las referencias HEADDB:<id>, HDB:<id> y hdb-<id> al estilo DeluxeMenus cuando HeadDatabase está instalado y cargado. Los plugins ausentes, los ID desconocidos y los materiales no válidos recurren a un material integrado seguro con una advertencia en la consola. Los valores numéricos fuera de rango se acotan y se diagnostican. Las listas de ranuras descartan las entradas no válidas y duplicadas; si no queda ninguna, se usa el diseño integrado seguro.

menu.player-dashboard.progress controla la ranura de progreso, el material, la longitud (1–40), los glifos y los colores. reward-history-button controla su botón de entrada.

menu.reward-history controla su tamaño de inventario, las ranuras de contenido ordenadas, el máximo de filas (1–45), los materiales de en cola/procesando/entregada/cancelada, los controles de vacío/atrás/cerrar, el patrón de fecha de Java y la zona horaria. Usa SYSTEM para la zona horaria del host o un ID IANA como Europe/Istanbul.

menu.admin-dashboard y menu.admin-review controlan los tamaños, las ranuras de página ordenadas, los materiales de estado/riesgo y cada ranura de navegación/control. Su capacidad de página efectiva es el número de ranuras de contenido válidas, así que la paginación sigue siendo coherente con los diseños personalizados.

Evita asignar dos acciones a la misma ranura: se verá el objeto escrito en último lugar y eso puede dejar otra acción inaccesible. Después de cualquier edición del diseño, ejecuta /referraltrack reload, revisa los diagnósticos de la consola y abre manualmente los menús de jugador y de personal antes de pasar a producción.

Preajustes y secretos #

Consulta Preajustes y temas antes de aplicar /referraltrack install <preset> confirm. Los preajustes nunca modifican las credenciales de la base de datos, los tokens ni las URL de webhook. /referraltrack doctor, las exportaciones y las interfaces no exponen esos valores. Guarda las copias de seguridad fuera de raíces web descargables públicamente y restringe el acceso al sistema de archivos a la cuenta del servicio de Minecraft.

Temas #

Consulta Preajustes y temas antes de aplicar /referraltrack theme <theme> confirm. La vista previa del tema es de solo lectura; la instalación confirmada crea una copia de seguridad exacta y cambia solo las rutas de presentación documentadas de menús/progreso/reacción a la reclamación. Nunca cambia datos de recompensas, campañas, permisos, base de datos ni secretos.