Rewards
Descripción general
Rewards mantiene una cola por jugador con las recompensas que se han ganado pero aún no se han recogido. En lugar de dar un objeto o ejecutar un comando en el acto, metes una recompensa en la cola. El jugador la recoge más tarde desde un menú, cuando está conectado y tiene sitio en su inventario. No se pierde nada si el jugador está desconectado o tiene el inventario lleno cuando se concede la recompensa.
Una recompensa es una plantilla que defines una sola vez (una definición de recompensa: objeto de visualización, lore, ranuras libres necesarias, acciones que ejecutar al reclamar). Concederla añade un pequeño registro a la cola; reclamarla elimina el registro y activa las acciones de TypeWriter que enlazaste a la definición. Como el efecto de la reclamación es una lista de acciones de TypeWriter, una recompensa puede dar objetos, dinero, un paso de misión o cualquier otra cosa que TypeWriter pueda activar.
La cola se almacena en un único artefacto. Cuando la extensión MySQL proporciona Redis, se avisa a los servidores que comparten el mismo almacenamiento de que recarguen el artefacto después de cada guardado, de modo que una recompensa concedida en un servidor se puede reclamar en otro.
Características
- Reclamación diferida: las recompensas esperan en la cola hasta que el jugador las reclama.
- Definiciones de recompensa: una plantilla reutilizable por tipo de recompensa, con objeto de visualización, nombre, lore y un requisito de ranuras libres.
- Acciones de reclamación: una reclamación activa cualquier lista de acciones de TypeWriter en lugar de un comando de consola.
- Menú de reclamación independiente: un inventario paginado con ranuras de recompensa, ranura de información, botones de página, reclamación en bloque y botón de volver.
- Botones integrables: las ranuras de recompensa y un botón de reclamación en bloque pueden colocarse en cualquier página de GUI mediante tipos de botón.
- Entregas con cron:
btc_give_rewardpuede conceder una recompensa como máximo una vez por periodo de cron y por jugador (recompensas diarias o semanales). - Evento de reclamación: una entrada de evento se dispara en cada reclamación con el id de la recompensa, datos personalizados y contadores.
- Hecho de recuento de pendientes y placeholders: usa la cola en criterios, scoreboards y menús.
- Antispam: un cooldown de 500 ms entre reclamaciones del mismo jugador.
Instalación
- Instala la extensión GUI (su nombre de plugin en la compilación es
GuiAndDialogs) y la extensión MySQL, ambas declaradas como dependencias de Rewards. Redis solo se usa para la actualización entre servidores y no se necesita en un solo servidor. - Coloca el JAR de Rewards en
plugins/Typewriter/extensions/y reinicia el servidor. - Opcionalmente, instala MiniPlaceholders para usar los placeholders
rewardsen texto MiniMessage.
Primeros pasos
Da una recompensa diaria por iniciar sesión que los jugadores recojan desde un menú.
- En el panel web de TypeWriter, abre una página estática y añade un Rewards Artifact. Añade solo uno: los placeholders y los botones integrados usan el primero que encuentran.
- Añade una entrada Rewards Config (también solo una) para ajustar los mensajes y la disposición del lore de las recompensas.
- Añade una Reward Definition. Establece
rewardIdendaily_login,sourceendaily_login, elige undisplayItemy enlaza las acciones que entregan la recompensa enonClaimActions. - Crea una acción Give Reward. Enlaza el
artifacty lareward, activauseCrony establececronExpressionen0 0 0 * * *para una vez al día. Actívala desde un evento de entrada o un NPC. - Crea una acción Open Rewards Menu con el mismo
artifacty actívala desde un comando o un NPC. - Publica. Un jugador que active la entrega obtiene una recompensa pendiente; al hacer clic en ella en el menú, la reclama.
Usa Has Pending Rewards en un criterio para mostrar una notificación solo mientras el jugador tenga algo que recoger.
Cómo funciona
La cola almacena solo el rewardId, el momento de la concesión y los datos personalizados. El objeto que se muestra en el menú y las acciones que se ejecutan se leen siempre de la definición en el momento de mostrar o reclamar. Una recompensa en cola cuya definición se ha eliminado no se muestra y no se puede reclamar.
Menús
Las recompensas se pueden mostrar de dos maneras que comparten la misma lógica de reclamación.
Menú independiente. Open Rewards Menu abre su propio inventario con rows de 1 a 6. Las recompensas pendientes rellenan rewardSlotsConfig en orden (un rango, o una lista explícita de ranuras cuando useRange está desactivado). Cuando hay más recompensas que ranuras, el menú se pagina con los previousPageButton y nextPageButton opcionales. Los opcionales infoSlot, bulkClaimButton y backButton admiten números de ranura, un objeto, un nombre MiniMessage y lore. backButton.command se ejecuta como el jugador (sin la barra inicial); déjalo vacío para simplemente cerrar el menú. Las ranuras vacías se rellenan con backgroundItem cuando está definido. Los números de ranura van de 0 (arriba a la izquierda) a 8 en la primera fila, luego de 9 a 17, y así sucesivamente.
Botones en cualquier página de GUI. En un menú de GUI, establece el buttonType de un objeto en uno de los marcadores de Rewards. El objeto que configuras conserva su posición y su estilo; en las ranuras de recompensa se sustituye por el propio objeto de visualización de la recompensa.
| Tipo de botón | Comportamiento |
|---|---|
rewards_button:REWARD_SLOT#<n> | Muestra la n-ésima recompensa pendiente del espectador (contando desde 0); el clic izquierdo la reclama. Pasada la última recompensa, la ranura queda vacía. |
rewards_button:BULK_CLAIM | El clic izquierdo reclama todas las recompensas pendientes para las que el jugador tenga sitio. |
Reglas de reclamación, en ambos modos:
- La recompensa necesita
requiredInventorySlotsranuras vacías en el inventario del jugador (0 significa que no se comprueba). Si no hay suficiente sitio, la reclamación se rechaza y se envíainventoryFullMessage. - Una reclamación activa los
onClaimActionsde la definición y después dispara todas las entradas de evento Reward Claimed. Una reclamación en bloque va de la última recompensa en cola a la primera y dispara el evento una sola vez con el id de recompensabulk_claim. - Los mensajes de éxito y de reclamación en bloque proceden de la entrada Rewards Config. Para los botones integrados, se usa la primera entrada Rewards Config que se encuentre.
El lore de un objeto de recompensa se construye a partir del additionalLore de la definición, después un separador y las líneas de origen y de ranuras libres, y por último un consejo de cierre; las etiquetas proceden de la entrada Rewards Config.
Placeholders
Expansión de MiniPlaceholders rewards, utilizable en texto MiniMessage como etiquetas.
| Placeholder | Devuelve |
|---|---|
<rewards_pending> | Número de recompensas pendientes del jugador. |
<rewards_pending:rewardId> | Número de recompensas pendientes con este rewardId. |
<rewards_source:source> | Número de recompensas pendientes cuya definición tiene este source (sin distinguir mayúsculas). Las recompensas con una definición eliminada no se cuentan. |
<rewards_claimed_total> | Número de recompensas que el jugador ha reclamado en total. |
El id de la recompensa es un argumento de la etiqueta: escribe <rewards_pending:daily_login>, no <rewards_pending_daily_login>. Todos los placeholders no devuelven nada si no existe ningún Rewards Artifact.
Entradas
7 entradas, generadas a partir del código fuente de la extensión.
Acciones2
- BTC Give RewardAdds a reward to a player's pending queue (with optional cron scheduling)
- BTC Open Rewards MenuOpens the rewards queue menu for a player
Eventos1
- BTC Reward Claimed EventTriggered when a player successfully claims a reward
Hechos1
- BTC Has Pending RewardsReturns the count of pending rewards for a player
Artefactos1
- BTC Rewards ArtifactStores pending rewards and claim history for all players
Manifiestos2
- BTC Reward DefinitionDefines a reward type that can be given and claimed by players
- BTC Rewards ConfigGlobal configuration for the rewards system (sounds, toasts, messages)
Resolución de problemas
El menú no se abre y el registro dice que la extensión GUI no está instalada. btc_open_rewards_menu necesita la extensión GUI en tiempo de ejecución. Instálala y reinicia. La acción tampoco hace nada, con una advertencia, cuando su campo artifact está vacío.
Give Reward no hace nada. El registro muestra una advertencia cuando la acción no tiene artifact, no tiene reward o cuando la definición enlazada tiene un rewardId vacío. Rellena los tres campos.
Una recompensa con cron solo se concede una vez. Con useCron activado, el momento de la última concesión se almacena por jugador y por entrada de acción. La siguiente concesión solo se produce después de la siguiente vez que la expresión cron coincida a partir de ese momento. Prueba con una expresión corta o usa una entrada de acción distinta por cada calendario.
Una recompensa pendiente es invisible o no se puede reclamar. El menú omite las recompensas en cola cuya definición no se encuentra por rewardId. No cambies el rewardId de una definición después de haber concedido recompensas.
Reclamación rechazada con el mensaje de inventario lleno. El jugador tiene menos ranuras vacías que requiredInventorySlots. Ten en cuenta que la comprobación cuenta todas las ranuras vacías del objeto de inventario del jugador, incluidas las de armadura y mano secundaria.
Los avisos emergentes (toasts), los sonidos, noRewardsMessage y onClaimFailActions no tienen efecto. Estos campos existen en Rewards Config y en Reward Definition, pero el código de esta versión nunca los lee. Solo se aplican los mensajes de reclamación, de inventario lleno y de reclamación en bloque, y la disposición del lore.
Las recompensas no aparecen en otro servidor. La actualización entre servidores depende de Redis de la extensión MySQL y de que ambos servidores lean el mismo almacenamiento de artefactos. Sin Redis, cada servidor solo ve su propia copia hasta que se reinicia.