Navis - Sistema de Guía Direccional Contextual

Navis es un plugin para servidores Minecraft (Paper/Spigot) que muestra guías direccionales contextuales para ayudar a los jugadores a navegar, completar tutoriales o llegar a ubicaciones clave. Se basa en reglas con condiciones evaluadas en tiempo real, acciones configurables y renderizado de flechas mediante ProtocolLib.

Descripción General

Motor de reglas basado en condiciones lógicas (and, or, not).
Acciones configurables al iniciar, acercarse o llegar al objetivo.
Renderizado de flechas con ProtocolLib y estilos configurables.
Sistema de traducciones con cambio dinámico de idioma, fallback y pluralización básica.

Requisitos del Sistema

Java 21
Paper/Spigot 1.20.4+
ProtocolLib 5.4.0+
PlaceholderAPI (opcional)

Instalación

Compila el proyecto:
```
./gradlew build
```
Copia el archivo generado en build/libs/ a la carpeta plugins/.
Inicia o reinicia el servidor.
Verifica la consola por “Navis has been enabled successfully!”.

Configuración

config.yml

Archivo principal de configuración.

debug: false
language:
  default: "en"
  fallback: "en"
model-debugger:
  enabled: true
  permissions:
    admin: "navis.admin"
    edit: "navis.model.edit"
  modules:
    selection: true
    manipulation: true
    export: true
  export-path: "models/.exported/"
  autosave:
    enabled: true
    interval: 300

guides.yml

Define guías con objetivos, condiciones y acciones.

guides:
  tutorial:
    target:
      world: "world"
      x: 100.5
      y: 65.0
      z: -200.5
      radius: 2.0
    priority: 10
    exclusive: true
    condition:
      has_permission: "navis.tutorial"
    actions:
      on_start:
        - type: message
          text: "&e¡Sigue la flecha hacia el tutorial!"
        - type: sound
          sound: UI_BUTTON_CLICK
      on_proximity:
        - radius: 10.0
          actions:
            - type: title
              title: "&e¡Estás cerca!"
              subtitle: "&7A menos de 10 bloques"
      on_arrival:
        - type: stop_tracking

Condiciones disponibles

has_permission: requiere permiso.
- has_permission: "perm" o has_permission: { permission: "perm" }
distance_greater_than: distancia mínima.
- distance_greater_than: 50 o distance_greater_than: { distance: 50 }
time_played_less_than: tiempo jugado menor a un valor.
- time_played_less_than: "1h" o time_played_less_than: { time: "1h" }
Composición lógica: and, or, not

Acciones disponibles

message: envía mensaje al jugador (text).
sound: reproduce sonido (sound, volume, pitch).
title: muestra título (title, subtitle, fadeIn, stay, fadeOut).
action_bar: muestra texto en action bar (text).
stop_tracking: detiene el rastreo actual.

styles.yml

Define estilos de flecha para el rastreador.

styles:
  default:
    custom_model_data: 1001
    item: ARROW
    scale: 1.0
  modern:
    custom_model_data: 1002
    item: SPECTRAL_ARROW
    scale: 0.8

lang/*.yml

Paquetes de idioma en plugins/Navis/lang/.

meta:
  locale: en
plural_rules:
  one: one
  other: other
messages:
  guide:
    help:
      title: "§eNavis Guide Commands"

Guía de Uso Paso a Paso

Instala el plugin y arranca el servidor.
Edita guides.yml y crea tus reglas con objetivos, condiciones y acciones.
Ajusta estilos en styles.yml si deseas un modelo distinto.
Usa /guide reload para recargar guías y estilos.
Prueba el rastreo con /guide track <id> y alterna visibilidad con /guide toggle.
Si necesitas cambiar idioma, usa /guide lang set <locale>.

Comandos y Permisos

Comandos de guía

Comando raíz: /guide (alias /navis, /guides).

/guide help [subcomando] — muestra ayuda.
/guide reload — recarga configuración y guías.
/guide debug <jugador> — estado de evaluación de reglas.
/guide toggle — alterna visibilidad del rastreador.
/guide track <id> — rastrea una guía específica.
/guide stop — detiene el rastreo.
/guide tracker-style <style> — cambia el estilo del rastreador.
/guide tracker-style <jugador> <style> — cambia estilo a otro jugador.
/guide create <id> <x> <y> <z> [world] — crea guía básica.
/guide purge — elimina displays de rastreadores.
/guide gen-rp — genera resource pack de modelos.
/guide lang ... — administración de idiomas.

Permisos:

navis.use: uso básico.
navis.admin: administración.
navis.translate: gestión de traducciones.

Comandos de traducción

/guide lang list
/guide lang get [jugador]
/guide lang set <locale>
/guide lang set <jugador> <locale>
/guide lang edit <locale> <key> <valor>
/guide lang review [locale]
/guide lang history [locale] [key]
/guide lang reload

Comandos de pruebas de modelos

Comando raíz: /navis-tester (alias /model-tester).

/navis-tester help [subcomando]
/navis-tester info
/navis-tester load <archivo>
/navis-tester spawn [x] [y] [z]
/navis-tester despawn
/navis-tester bind player <nombre>
/navis-tester bind location <x> <y> <z>
/navis-tester unbind
/navis-tester rotate <axis> <grados> [absolute|relative]
/navis-tester reset-rotation
/navis-tester select <index>
/navis-tester move-part <x> <y> <z>
/navis-tester rotate-part <axis> <grados>
/navis-tester save

Permiso requerido: navis.admin.

Sistema de comandos

Navis utiliza el sistema de comandos nativo de Bukkit/Paper. No hay dependencias externas para registrar comandos. Si el descriptor de plugin no expone los comandos, Navis registra un fallback en tiempo de ejecución.

Estructura

Registro central: CommandRegistry
Comandos de guía: GuideCommand
Comandos de pruebas: TestingCommand
Definiciones de comandos: plugin.yml y paper-plugin.yml

Guía de mantenimiento

Para añadir un subcomando, agrega el caso correspondiente en onCommand y su autocompletado en onTabComplete.
Para nuevos permisos, actualiza plugin.yml, paper-plugin.yml y los mensajes de lang/*.yml.
Para nuevos comandos raíz, registra en CommandRegistry y declara en los archivos de plugin.
Mantén los mensajes de ayuda alineados con los textos de lang/*.yml.

API

NavisMain

Puntos de acceso principales:

static NavisMain getInstance()
GuideManager getGuideManager()
ModelManager getModelManager()
ConditionRegistry getConditionRegistry()
ActionRegistry getActionRegistry()
TranslationManager getTranslationManager()
TrackerEntityRegistry getTrackerEntityRegistry()

ConditionRegistry

Registro de condiciones:

void register(String key, ConditionFactory factory)
ConditionFactory getFactory(String key)

ActionRegistry

Registro de acciones:

void register(String key, ActionFactory factory)
ActionFactory getFactory(String key)

TranslationManager

Gestión de traducciones:

void load()
String translate(CommandSender sender, String key)
String translate(CommandSender sender, String key, Map<String, String> params)
String translate(CommandSender sender, String key, Map<String, String> params, Integer count, String context)
String resolveLocale(CommandSender sender)
String getPlayerLocale(Player player)
boolean setPlayerLocale(Player player, String locale)
Set<String> getAvailableLocales()
String getDefaultLocale()
String getFallbackLocale()
List<String> getMissingKeys(String locale)
boolean updateTranslation(CommandSender editor, String locale, String key, String value)
List<TranslationHistoryEntry> getHistory(String locale, String key)

Ejemplos Prácticos

Registrar una condición personalizada

NavisMain.getInstance()
    .getConditionRegistry()
    .register("has_level", args -> {
        int minLevel = Integer.parseInt(String.valueOf(args.get("value")));
        return (player, context) -> player.getLevel() >= minLevel;
    });

Registrar una acción personalizada

NavisMain.getInstance()
    .getActionRegistry()
    .register("bossbar", args -> {
        String text = String.valueOf(args.getOrDefault("text", ""));
        return (player, context) -> player.sendMessage(text);
    });

Usar traducciones con parámetros

TranslationManager i18n = NavisMain.getInstance().getTranslationManager();
String msg = i18n.translate(player, "guide.tracking.site", Map.of("id", "tutorial"));
player.sendMessage(msg);

Solución de Problemas

No aparece la flecha: verifica que ProtocolLib esté cargado y que el jugador tenga navis.use.
Las guías no se activan: revisa la sección condition en guides.yml y el nombre del mundo.
Cambios no aplican: usa /guide reload después de editar guides.yml o styles.yml.
Idioma inválido: asegúrate de que exista lang/<locale>.yml y usa /guide lang list.
Error al generar resource pack: revisa permisos del sistema de archivos y vuelve a ejecutar /guide gen-rp.

Changelog

[1.8.1-alpha] - 2026-02-23

Changed

Sistema de comandos nativo: migración desde CommandAPI para compatibilidad y sin dependencias externas.

Fixed

Registro de comandos con fallback cuando el descriptor no los expone.

[0.0.6-alpha] - 2026-02-14

Added

Sistema de traducciones con paquetes de idioma, fallback y edición en caliente.
Comandos completos de guía y administración usando CommandAPI.
Comandos de pruebas de modelos y herramientas de depuración.

Name		Name	Last commit message	Last commit date
Latest commit History 12 Commits
gradle		gradle
src		src
.gitattributes		.gitattributes
README.en.md		README.en.md
README.md		README.md
build.gradle		build.gradle
gradle.properties		gradle.properties
gradlew		gradlew
gradlew.bat		gradlew.bat
settings.gradle		settings.gradle

Uh oh!

Folders and files

Latest commit

History

Repository files navigation

Navis - Sistema de Guía Direccional Contextual

Índice

Descripción General

Requisitos del Sistema

Instalación

Configuración

config.yml

guides.yml

Condiciones disponibles

Acciones disponibles

styles.yml

lang/*.yml

Guía de Uso Paso a Paso

Comandos y Permisos

Comandos de guía

Comandos de traducción

Comandos de pruebas de modelos

Sistema de comandos

Estructura

Guía de mantenimiento

API

NavisMain

ConditionRegistry

ActionRegistry

TranslationManager

Ejemplos Prácticos

Registrar una condición personalizada

Registrar una acción personalizada

Usar traducciones con parámetros

Solución de Problemas

Changelog

[1.8.1-alpha] - 2026-02-23

Changed

Fixed

[0.0.6-alpha] - 2026-02-14

Added

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages