Pets
Descripción general
Pets añade compañeros coleccionables inspirados en EcoPets. Cada mascota se define una sola vez en el panel web (una Pet Definition), y cada jugador posee copias de ella. Una mascota se entrega como un objeto ficha: al hacer clic derecho en la ficha, la mascota se añade al menú de compañeros del jugador. Desde el menú, el jugador activa una mascota cada vez, y esa mascota flota sobre su cabeza, camina a su lado o vuela a su alrededor.
Las mascotas ganan experiencia cuando su dueño mata mobs o cuando tu historia concede XP, y suben de nivel según una fórmula o una tabla que escribes tú. Una mascota puede tomar represalias contra los mobs que golpean a su dueño y puede tener varias skins que se desbloquean mediante criterios de TypeWriter.
Características
- Tres modos de visualización:
HEADflota sobre el jugador,GROUNDcamina a su lado yFLYse mantiene suspendida a una altura determinada. - Menú de compañeros: una GUI con una cuadrícula de mascotas poseídas, activación, ocultar y mostrar, detalles y skins.
- Objetos ficha: las mascotas pasan de un jugador a otro como objetos que conservan su nivel, XP, modo y skin.
- XP y niveles: una fórmula como
{level} * 100o una tabla explícita, con un nivel máximo. - XP por muertes y XP de historia: XP por cada mob muerto, además de una acción para conceder XP desde cualquier secuencia.
- Represalia: contraataque opcional contra los mobs que dañan al dueño, con daño por nivel.
- Skins: varias skins de NPC por mascota, cada una con criterios, prioridad e icono de menú.
- Permisos de ranura: bloquea ranuras del menú tras permisos para vender ranuras de compañero adicionales.
- Placeholders: nombre, nivel, XP, estado y propiedad de la mascota activa, de una ranura o de cualquier mascota.
- Compatibilidad con modelos: las mascotas terrestres y voladoras usan cualquier definición de entidad, incluidos los modelos de ModelEngine.
Instalación
- Instala la extensión GUI, que dibuja los menús.
- Opcional: instala ModelEngine y la extensión de TypeWriter que expone tus modelos como definiciones de entidad, si las mascotas deben usar modelos animados.
- Coloca el JAR de Pets en
plugins/Typewriter/extensions/y reinicia el servidor. - Crea un artefacto Pet Storage para que se guarden las mascotas poseídas; consulta Primeros pasos.
Primeros pasos
Crea una primera mascota y entrégasela a un jugador:
- En el panel web de TypeWriter, abre una página estática y añade un artefacto Pet Storage. Sin él, la extensión registra "No pet_storage entry found" y nada persiste.
- Añade una Pet Definition. El propio
namede la entrada es el nombre visible de la mascota y suides el identificador de la mascota. - Elige
defaultMode. ParaHEAD, pega opcionalmente unatextureen base64 para la cabeza flotante. ParaGROUNDoFLY, establecenpcen una entrada de definición de entidad que se generará junto al jugador. - En
xp, establecemaxLevely, o bien unaformulaque use{level}(por ejemplo{level} * 100), o bien una listalevels. EstablecekillRewardpara el XP por cada muerte. - Opcional: marca
combat.enabledpara la represalia y personalizatoken(el objeto, su nombre y su lore, y un brillo). - Añade una acción Pets Open Menu, establece su
storageen tu artefacto Pet Storage y actívala desde un NPC, un objeto o un comando. - Publica y ejecuta
/pets give <pet> 1como jugador. Haz clic derecho en la ficha, abre después el menú y haz clic en la mascota para activarla.
Para conceder XP desde tu historia, añade una acción Pets Add XP con amount. Va a la mascota activa del jugador. Para controlar una mascota concreta, usa Pets State con pet y action.
No existe ninguna acción que desbloquee una mascota directamente. Una mascota llega a un jugador como un objeto ficha, mediante /pets give o mediante el botón "devolver a objeto" del menú. Ejecuta el comando desde una acción de comando de consola en una misión o una tienda para convertirlo en una recompensa desbloqueable.
Cómo funciona
Un jugador posee como máximo una mascota por definición. Solo hay una mascota activa a la vez: activar otra desactiva la primera. Las mascotas se guardan en segundo plano en el artefacto Pet Storage, y la mascota activa se restaura cuando el jugador entra.
Modos de visualización.
HEADmuestra la mascota sobre la cabeza del jugador aplicandoheadOffset. Sinpcestá definido, se usa esa entidad. En caso contrario, un soporte de armadura invisible lleva una cabeza de jugador contexture.GROUNDgenera elnpc(o el NPC de la skin seleccionada) unos bloques detrás del jugador y hace que lo siga.swimModedecide si nada en los líquidos:AUTOsigue las capacidades de la entidad, yALWAYSyNEVERlo fuerzan.FLYes igual queGROUND, pero la mascota se mantiene suspendidaflightHeightbloques por encima del jugador.
Si una mascota GROUND o FLY no tiene NPC (o ninguna de sus skins coincide), no se muestra y se registra una advertencia. Sobre cada mascota activa se muestra una etiqueta de nombre con el nivel. El modo procede de defaultMode cuando se crea la ficha por primera vez y permanece con esa instancia de mascota.
XP y niveles. Una mascota empieza en el nivel 1. Cada elemento de levels indica el XP total que debe haber alcanzado una mascota para un nivel, por ejemplo el nivel 2 con 100 XP y el nivel 3 con 250 XP. Los elementos explícitos prevalecen sobre la fórmula. La fórmula se evalúa sustituyendo {level} por el nivel que se quiere alcanzar, y admite + - * /, paréntesis y decimales. Una mascota sin ningún requisito para el siguiente nivel no sube de nivel.
Represalia. Con combat.enabled, una mascota activa y visible contraataca a cualquier mob que no sea jugador y dañe al dueño, tras un breve retraso y con un cooldown de 1,5 segundos por atacante. El daño es el damage del elemento más alto de levels que esté en el nivel de la mascota o por debajo. Si no hay ninguno, es 1,5 más 0,5 por cada nivel por encima de 1.
Skins. Cada elemento de skins apunta a una definición de NPC, una priority y criteria. La mascota usa la skin que eligió el jugador si sus criterios siguen cumpliéndose; si no, la skin de mayor prioridad cuyos criterios se cumplan. El campo npc de la definición es la skin de reserva. Un elemento de skin necesita un npc; de lo contrario se ignora.
Menús
La acción Pets Open Menu abre el menú de compañeros integrado, titulado "Compagnons". Cada mascota poseída es un icono de cabeza de jugador que muestra el nivel, el progreso de XP y el estado. El clic izquierdo activa o desactiva la mascota y el clic derecho abre su pantalla de detalle. La pantalla de detalle muestra las estadísticas y permite al jugador activar, elegir una skin (cuando la mascota tiene más de una), devolver la mascota a un objeto o volver atrás. Un botón en la esquina inferior izquierda muestra u oculta la mascota activa.
Los ajustes del menú son campos del objeto menu de la acción:
slots: números de ranura del inventario donde se muestran las mascotas. El valor por defecto son 21 ranuras en tres filas.lockedSlots: pares deslotypermission. Una ranura cuyo permiso no tiene el jugador muestra un marcador de bloqueo, y no se puede colocar ninguna mascota en ella.maxSlots: número máximo de slots usados (por defecto 21, mínimo 1): solo las primerasmaxSlotsentradas deslotsse disponen y pueden recibir una mascota nueva. Limita la disposición y cuántas mascotas puede obtener un jugador, no las que ya posee.rows: altura del menú, de 1 a 6.storage: el artefacto Pet Storage que se usará.
La disposición de slots del último menú abierto se guarda con los datos del jugador y decide qué slots puede ocupar un token. Una mascota que el jugador ya posee en un slot más allá de maxSlots (o fuera de la altura del menú) no se oculta: se muestra en una celda libre del menú, nunca en el botón de mostrar/ocultar, y sus clics siguen actuando sobre su propio slot. Si hay más mascotas así que celdas libres, las sobrantes siguen en propiedad del jugador y aparecen en la página Pets del menú Social compartido, que lista todas las mascotas poseídas; se registra una advertencia una vez por jugador.
Uso en tu propio menú. La extensión registra el prefijo de botón pets_button: para cualquier menú de GUI. Establece el buttonPrefix de un objeto en pets_button: y su buttonType en uno de estos valores:
buttonType | Muestra |
|---|---|
PET_ENTRY | La mascota en esa posición de la lista del jugador. El clic izquierdo la activa o desactiva y el clic derecho la selecciona para los objetos de detalle. |
PET_DETAIL_INFO | Nivel, XP y modo de la mascota seleccionada. |
PET_LEVEL_ENTRY | Un nivel de la mascota seleccionada con su requisito de XP y su estado. |
PET_DETAIL_REMOVE | Un botón que devuelve la mascota seleccionada a un objeto. |
PET_LIST_NAV, PET_DETAIL_NAV | Flechas de página para la lista de mascotas y la lista de niveles. |
Las ranuras también pueden ejecutar los comandos pet_menu: pet_menu activate <slot>, pet_menu deactivate <slot>, pet_menu toggle_visibility, pet_menu details <slot>, pet_menu skins <slot>, pet_menu select_skin <pet> <skin> y pet_menu remove <slot>.
Si UiCore está instalado, puede leer los compañeros del jugador para dibujar un HUD o una página de menú.
Los textos del menú, el lore de la ficha y la etiqueta sobre una mascota están en francés por defecto (por ejemplo "Niveau", "Compagnons"). Edita el name, el lore y el noSlotMessage de la ficha en cada mascota. Los demás textos del menú están fijados en el código.
Comandos
El permiso typewriter.pets es necesario para todos los subcomandos, junto con el permiso indicado. La mayoría de los subcomandos aceptan un selector de jugador opcional [target] tras sus argumentos para actuar sobre otra persona; sin él, actúan sobre quien lo ejecuta.
| Comando | Permiso | Descripción |
|---|---|---|
/pets open [target] | typewriter.pets.open | Abre el menú de compañeros. |
/pets activate <pet> [target] | typewriter.pets.activate | Activa una mascota poseída. |
/pets deactivate [target] | typewriter.pets.deactivate | Aleja la mascota activa. |
/pets show [target] | typewriter.pets.show | Vuelve a mostrar la mascota activa. |
/pets hide [target] | typewriter.pets.hide | Oculta la mascota activa. |
/pets remove <pet> [target] | typewriter.pets.remove | Elimina una mascota del menú del jugador. No se devuelve ningún objeto. |
/pets give <pet> <amount> [target] | typewriter.pets.give | Entrega de 1 a 64 objetos ficha. |
<pet> es el id o el nombre de una entrada Pet Definition. El comando sin argumentos /pets no hace nada en esta versión: usa /pets open.
Permisos
Ninguno se registra con un valor por defecto, por lo que solo los operadores los tienen salvo que los concedas con un plugin de permisos.
| Permiso | Concede |
|---|---|
typewriter.pets | El árbol de comandos /pets. |
typewriter.pets.open | /pets open. |
typewriter.pets.activate | /pets activate. |
typewriter.pets.deactivate | /pets deactivate. |
typewriter.pets.show | /pets show. |
typewriter.pets.hide | /pets hide. |
typewriter.pets.remove | /pets remove. |
typewriter.pets.give | /pets give. |
Permisos de lockedSlots | Desbloquean la ranura de menú correspondiente. Tú eliges los nombres. |
Placeholders
Pets expone una entrada de placeholder de TypeWriter, Pets Placeholder. Créala una sola vez. La etiqueta es <typewriter_ENTRY:...>, donde ENTRY es el nombre o el id en minúsculas de esa entrada, por ejemplo <typewriter_pets_placeholder:active:name> cuando la entrada se llama pets_placeholder.
| Ruta de argumentos | Devuelve |
|---|---|
active | Nombre de la mascota activa, vacío cuando no hay ninguna. |
active:name, active:id | Nombre e id de la mascota activa. |
active:level, active:xp, active:max_level | Nivel, XP y nivel máximo. |
active:next_xp | XP necesario para el siguiente nivel, Max en el nivel más alto. |
active:damage | Daño de represalia en el nivel actual. |
active:status | active o inactive. |
active:visibility | hidden o visible. |
active:mode | head, ground o fly. |
slot:<index>:name, id, level, xp, next_xp, max_level, damage, visibility, mode | Los mismos campos para la mascota de esa ranura del menú. |
slot:<index>:status | active, inactive o empty. |
pet:<id>:name, description, max_level, xp_per_kill, default_mode, combat, texture | Campos de una Pet Definition. |
pet:<id>:owned | true o false para el jugador. |
pet:<id>:level, xp, next_xp, visibility, mode, damage | La copia del jugador de esa mascota, vacío cuando no la posee. |
pet:<id>:status | active, inactive o unowned. |
Entradas
6 entradas, generadas a partir del código fuente de la extensión.
Acciones3
- Pets Add XPGrant experience to a pet
- Pets Open MenuOpen the pet selection menu
- Pets StateChange the state of a pet
Placeholders1
- Pets PlaceholderExpose companion placeholders
Artefactos1
- Pet StoragePersist companion data
Manifiestos1
- Pet DefinitionConfigure a companion pet
Resolución de problemas
Las mascotas se pierden tras un reinicio. No existe ningún artefacto Pet Storage, o la acción del menú no tiene storage. El registro muestra "No pet_storage entry found. Companion data will not persist until one is created."
La ficha dice que el menú está lleno. Todas las ranuras del menú están ocupadas o bloqueadas para ese jugador. Añade ranuras en slots o concede el permiso de una ranura bloqueada. El mensaje es el noSlotMessage de la ficha.
"Ce familier est déjà présent dans ton menu." Un jugador puede poseer una copia de cada mascota. No puede usar una segunda ficha de la misma definición.
Una mascota GROUND o FLY nunca aparece. El registro dice "Unable to summon ground pet". Establece npc en la definición, o da a al menos una skin un npc cuyos criterios coincidan con el jugador. Comprueba que la entrada de definición de entidad existe.
La mascota no sube de nivel. La mascota necesita un requisito para el siguiente nivel, ya sea un elemento de levels o una formula. Una fórmula que no se puede evaluar se trata como si no hubiera requisito. Comprueba que solo usa números, {level}, + - * / y paréntesis.
/pets no imprime nada. Usa /pets open. Todos los subcomandos necesitan typewriter.pets más su propio permiso, y estos permisos no se conceden por defecto.
Una skin aparece bloqueada ("???"). Sus criteria todavía no se cumplen. Prueba los hechos o las misiones de los que depende.