Crate

Cajas de botín con recompensas ponderadas, llaves virtuales, hitos y un minijuego de apertura eligiendo cartas.

Privadasv0.0.2Economía y crafteo

RequiereTypeWriter0.9BasicGUI

Creada para la red BornToCraft. Esta extensión está documentada como referencia y no se distribuye.

Soporte

Descripción general

Crate añade cofres de botín a tu servidor. Un crate tiene una lista de recompensas, cada una con una rareza, y los jugadores lo abren gastando una llave virtual. La recompensa ganadora se sortea en el servidor antes de que empiece cualquier animación, por lo que nada de lo que haga un jugador durante la apertura puede cambiar el resultado. Abrir un crate cuenta para los hitos, que pueden activar recompensas adicionales tras un número de aperturas.

Las recompensas son disparadores de TypeWriter, por lo que una recompensa puede dar un objeto, ejecutar un comando, conceder un cosmético o iniciar una secuencia. La apertura se muestra en el mundo delante del jugador: una vista previa de las recompensas en visualizaciones de objetos flotantes, o un minijuego de elegir cartas. Los menús permiten a los jugadores explorar los crates y las recompensas que puede dar cada uno.

La extensión se ejecuta en la versión BTC de TypeWriter (BTC Core, Paper/Folia) y se documenta aquí a modo de referencia.

Características

• Recompensas ponderadas: las rarezas tienen un peso, y la probabilidad de cada recompensa se muestra en los menús.
• Llaves virtuales: las llaves se cuentan por jugador en el artefacto de datos del crate, y se gasta una en cada apertura.
• Aperturas seguras: primero se reserva una llave y solo se gasta cuando se revela la recompensa; una desconexión, un tiempo de espera agotado o un reinicio la reembolsan.
• Hitos: activan recompensas adicionales tras un número de aperturas.
• Minijuego de cartas: el jugador da la vuelta a una de las cartas boca abajo de una cuadrícula, mientras que la recompensa ya está decidida.
• Vistas previas en el mundo: las recompensas flotan alrededor del jugador en layouts PAGINATED, FLEX o SIMPLE, con un NPC y un holograma opcionales.
• Menús: un menú global de crates y un menú de recompensas por crate, con marcos, paginación y botones personalizados.
• Estadísticas: aperturas, llaves, llaves usadas, última apertura e hito, disponibles como placeholders.

Instalación

1. Instala la extensión Basic de TypeWriter y la extensión GUI (GuiAndDialogs en la versión BTC). Crate no se cargará sin ellas.
2. Coloca el JAR de Crate en plugins/Typewriter/extensions/ y reinicia el servidor.
3. Concede a tu staff los permisos de la sección Permisos.

Primeros pasos

Crea un crate con tres recompensas y date una llave:

1. En el panel web de TypeWriter, abre una página de manifiesto y añade un artefacto Crate Data. Conserva el artifactId generado y usa un artefacto por crate.
2. Añade una entrada Crate. Establece dataArtifact en el artefacto y escribe el noKeyMessage.
3. En rarities, añade Common con peso 70 y Rare con peso 30.
4. En rewards, añade tres recompensas: para cada una establece una rarity, un item que se muestra en la vista previa, un name y, en action, un disparador que entregue la recompensa. Deja grantItem activado para entregar el item automáticamente, o desactívalo si la acción entrega el objeto por sí misma.
5. En rewardSlots, enumera las ranuras de inventario del menú de recompensas (contadas desde 0), por ejemplo 10-12. Un crate sin ranuras de recompensa se niega a abrirse.
6. En icon, establece la x y la y del crate en el menú global, un item y un name.
7. Añade una acción Open Crate que apunte al crate y actívala desde un NPC, un bloque o un objeto.
8. Publica y ejecuta /tw crate give <crate entry id> 5 y abre el crate. Usa /tw crate menu para explorar los crates.

Clics en las recompensas del menú de recompensas

En el menú de recompensas de un crate, hacer clic en una recompensa activa directamente la action de esa recompensa, sin gastar ninguna llave ni registrar estadísticas. No des acceso a los jugadores al menú de recompensas si la acción de una recompensa entrega algo valioso, o reserva el menú para el staff.

Entrega de llaves

Las llaves se añaden con /tw crate give <crate> <amount> [targets]. No hay ninguna acción específica para las llaves, pero una acción de comando puede ejecutar ese comando, por ejemplo desde la recompensa de una misión o desde una tienda.

Cómo funciona

La probabilidad de una recompensa es el peso de su rareza dividido por el peso total de todas las recompensas. Una recompensa cuya rareza no figura en rarities tiene un peso de 1. Cuando se revela la recompensa, se gasta la llave, suben los contadores de aperturas y de llaves usadas, se dispara cualquier hito superado, y después se entrega el objeto (si grantItem está activado) y se ejecuta la action de la recompensa. Un jugador solo puede tener una apertura a la vez.

Menús

• Menú global: se abre con /tw crate menu. Muestra un icono por crate, colocado en la x (0 a 8) y la y (0 a 5) del icono, y al hacer clic en un icono se abre el menú de recompensas de ese crate. Una entrada opcional Crate Main Menu define el tamaño, el título, el marco, los botones, los objetos por página y la columna reservada para las flechas de paginación.
• Menú de recompensas: se abre al hacer clic en un icono, o con la acción Open Crate Menu. Muestra las recompensas de rewardSlots, con su nombre, su lore y líneas opcionales de probabilidad y rareza (chanceLore y rarityLore, que usan {chance} y {rarity}). guiLayout es PAGINATED, FLEX (centrado, cuatro columnas) o SIMPLE. frameItem, itemsPerPage y paginationColumn ajustan el marco y la paginación, y buttons añade botones personalizados con una acción.

Los botones tienen un tipo (INFORMATION, NEXT, PREVIOUS, FILL) y una posición. Un botón FILL se copia en todas las ranuras vacías. Los marcadores crate_button: (CRATE_OPEN, CRATE_PREVIEW, CRATE_GLOBAL_BROWSE, CRATE_REWARD_SLOT, NAV_BACK, NAV_CLOSE) se ofrecen en el editor de GUI, pero en esta versión solo muestran un objeto de relleno.

Configuración

Crate no tiene ningún archivo de configuración. Todo se configura en entradas. Los datos de los jugadores están en el artefacto Crate Data: llaves, aperturas, llaves usadas, hora de la última apertura, hito y aperturas pendientes. Se escribe de forma asíncrona, y las aperturas pendientes que dejó un fallo se recuperan al arrancar (se reembolsa la llave).

Comandos

Todos los comandos son subcomandos del comando de TypeWriter, por lo que empiezan por /typewriter o /tw. <crate> es la entrada de un crate y se autocompleta.

Comando	Descripción	Permiso
/tw crate menu	Abre el menú global de crates.	typewriter.crate.menu
/tw crate open <crate>	Abre el crate usando una llave.	typewriter.crate.open
/tw crate give <crate> [targets]	Da una llave a ti mismo o a los jugadores seleccionados.	typewriter.crate.give
/tw crate give <crate> <amount> [targets]	Da varias llaves.	typewriter.crate.give
/tw crate remove <crate> [targets]	Quita una llave, solo si el jugador tiene una.	typewriter.crate.remove
/tw crate remove <crate> <amount> [targets]	Quita varias llaves, solo si el jugador tiene suficientes.	typewriter.crate.remove

El permiso base typewriter.crate protege todo el comando. La extensión registra un comando interno /cratemenu que usan los clics de los menús; no está pensado para escribirse.

Permisos

Permiso	Concede
typewriter.crate	Acceso al comando /tw crate.
typewriter.crate.menu	/tw crate menu.
typewriter.crate.open	/tw crate open.
typewriter.crate.give	/tw crate give.
typewriter.crate.remove	/tw crate remove.

Placeholders

Son etiquetas de MiniPlaceholders de la expansión crate. Sustituye id por el ID de entrada del crate. Un crate desconocido devuelve un valor vacío.

Placeholder	Devuelve
<crate_openings:id>	Número de aperturas de este crate por parte del jugador.
<crate_keys:id>	Llaves que tiene el jugador.
<crate_keys_used:id>	Llaves que ha gastado el jugador.
<crate_last_open:id>	Hora de la última apertura, en milisegundos desde el 1 de enero de 1970.
<crate_milestone:id>	El hito más alto alcanzado.

En hologramLines, usa en su lugar los tokens {openings}, {keys}, {last_open} y {milestone}.

Entradas

6 entradas, generadas a partir del código fuente de la extensión.

Acciones2

• Open CrateOuvre une caisse
• Open Crate MenuOuvre le menu d'une caisse

Artefactos1

• Crate ArtifactDonnées de caisse

Manifiestos3

• CrateDéfinition d’une caisse
• Crate Main MenuApparence du menu principal
• Crate Minigame CardsMini-jeu Caisse : Cartes

Resolución de problemas

"This crate is not configured correctly". El crate no superó la validación, y el registro del servidor enumera los motivos: no hay recompensas, un peso de rareza no válido (debe ser mayor que cero), no hay rewardSlots o hay ranuras fuera del rango 0 a 53 o duplicadas, un botón o un icon fuera de la cuadrícula de 9 por 6, o hitos en cero aperturas o duplicados. Las mismas comprobaciones se ejecutan al arrancar y escriben una advertencia.

El jugador recibe el noKeyMessage. El jugador no tiene ninguna llave de ese crate, o el crate no tiene dataArtifact. Da llaves con /tw crate give y comprueba el enlace del artefacto.

"You are already opening a crate". Hay una apertura en curso para ese jugador. Termina cuando se revela la recompensa o el jugador se desconecta.

Las estadísticas y las llaves no cambian tras una apertura. Solo cambian cuando se revela la recompensa. Si el jugador se fue o el servidor se detuvo antes, se reembolsa la llave y los contadores se quedan igual.

La vista previa no muestra nada o muestra recompensas equivocadas. La vista previa usa el item de cada recompensa. Las recompensas con un item vacío se omiten, y preview.maxVisibleRewards limita cuántas se muestran a la vez. preview.distance y los desfases *Location mueven la visualización.

El minijuego de cartas no se inicia. Enlaza una entrada Crate Minigame: Cards en el campo minigame del crate. Sus columns llegan hasta 10 y sus rows hasta 10, y cardCount está limitado a 100.

Se entrega una recompensa dos veces. Deja grantItem activado solo cuando la action no entregue también el objeto.

Extensiones relacionadas

• GUI: motor de menús usado para los menús de los crates.