# PROMPT MAESTRO — VERTEX FRAMEWORK 0.1.0
## 1. DESCRIPCIÓN DEL PROYECTO
Quiero que desarrolles desde cero un plugin de Minecraft llamado **Vertex Framework**, diseñado como un framework modular para crear sistemas, eventos, comandos, variables y automatizaciones mediante archivos de configuración.
La característica principal del proyecto será disponer de un motor propio que pueda interpretar y ejecutar una selección de scripts de Skript y configuraciones de Conditional Events sin necesidad de instalar esos plugins originales en el servidor.
El proyecto debe ser funcional, estable, ligero y fácil de ampliar en futuras versiones.
No quiero únicamente una demostración, una plantilla vacía ni pseudocódigo. Quiero un plugin real, con todas las funciones iniciales implementadas.
## 2. ESPECIFICACIONES TÉCNICAS
- Nombre: Vertex Framework.
- Versión: 0.1.0.
- Plataforma: Paper 1.20.1.
- Compatibilidad adicional: Spigot 1.20.1 cuando las API utilizadas lo permitan.
- Lenguaje: Java 17.
- Sistema de construcción: Maven.
- Paquete principal: `com.vertexframework`.
- Clase principal: `com.vertexframework.VertexFramework`.
- Comando principal: `/vertex`.
- Permiso administrativo: `vertex.admin`.
- Archivo final: `VertexFramework-0.1.0.jar`.
No cambies estas especificaciones sin una razón técnica importante.
## 3. ARQUITECTURA GENERAL
Organiza Vertex Framework mediante módulos independientes.
El proyecto debe contar inicialmente con estos módulos:
1. Core: sistema principal del framework.
2. Commands: comandos y permisos.
3. Config: carga y gestión de archivos YAML.
4. Variables: variables globales, locales y persistentes.
5. Actions: ejecución de acciones.
6. Conditions: evaluación de condiciones.
7. Events: sistema de eventos internos.
8. VertexSkript: intérprete de archivos `.sk`.
9. VertexEvents: intérprete de configuraciones de Conditional Events.
10. Placeholders: sustitución de variables y placeholders.
11. ScriptManager: registro, carga, descarga y recarga de scripts.
12. Diagnostics: registro de errores y diagnóstico del sistema.
Evita duplicar responsabilidades y reutiliza los componentes compartidos.
El sistema debe permitir incorporar módulos nuevos en el futuro sin reconstruir toda la arquitectura.
## 4. ESTRUCTURA DE ARCHIVOS
Al iniciar por primera vez, el plugin debe crear automáticamente una estructura semejante a esta:
plugins/VertexFramework/
- config.yml
- messages.yml
- variables.yml
- actions.yml
- scripts/
- skript/
- conditional-events/
- logs/
- cache/
Los archivos deben generarse con valores predeterminados y comentarios explicativos.
No sobrescribas archivos existentes durante el inicio normal.
Las carpetas deben permitir que un administrador añada archivos manualmente y que el plugin los detecte sin necesidad de recompilarlo.
Los errores de un archivo no deben impedir que se carguen los demás archivos válidos.
## 5. COMANDOS PRINCIPALES
Implementa los siguientes comandos:
- `/vertex`: información general.
- `/vertex help`: ayuda.
- `/vertex version`: versión instalada.
- `/vertex info`: estado de los módulos.
- `/vertex reload`: recarga de configuraciones.
- `/vertex variables`: lista de variables registradas.
- `/vertex variable `: consulta de una variable.
- `/vertex variable set `: establece una variable.
- `/vertex variable remove `: elimina una variable.
- `/vertex scripts`: información del sistema de scripts.
- `/vertex scripts list`: lista los archivos detectados.
- `/vertex scripts reload`: recarga los scripts.
- `/vertex scripts reload skript`: recarga los archivos `.sk`.
- `/vertex scripts reload events`: recarga los archivos de Conditional Events.
- `/vertex scripts test `: valida un archivo sin ejecutar sus acciones.
- `/vertex scripts errors`: muestra los errores recientes.
- `/vertex scripts info`: muestra estadísticas de carga.
- `/vertex scripts enable `: activa un archivo.
- `/vertex scripts disable `: desactiva un archivo.
Todos los comandos administrativos deben comprobar `vertex.admin`.
Implementa mensajes configurables, validación de argumentos y autocompletado.
No registres comandos duplicados.
## 6. SISTEMA DE VARIABLES
Implementa un gestor de variables propio.
Debe admitir:
- Texto.
- Números enteros.
- Números decimales.
- Booleanos.
- Variables asociadas a jugadores cuando corresponda.
Debe permitir crear, modificar, consultar, eliminar y persistir variables.
Las variables persistentes deben conservarse después de reiniciar el servidor.
Incluye placeholders internos como:
- `%player%`: jugador actual cuando exista un contexto de jugador.
- `%server_name%`: nombre configurado del servidor.
- `%vertex_version%`: versión del framework.
- `%variable_nombre%`: valor de una variable personalizada.
Implementa la sustitución de placeholders de forma centralizada para que todos los módulos puedan utilizarla.
Si un placeholder no existe, evita errores y aplica un comportamiento documentado.
No confundas las variables propias de Vertex con todas las variables existentes en el lenguaje Skript. La compatibilidad con la sintaxis original debe implementarse expresamente.
## 7. SISTEMA DE ACCIONES
Crea un sistema compartido de acciones que pueda utilizarse desde los scripts y los eventos YAML.
Implementa inicialmente:
- MESSAGE: mensaje privado.
- BROADCAST: mensaje global.
- CONSOLE_COMMAND: comando de consola.
- PLAYER_COMMAND: comando de jugador.
- SET_VARIABLE: establecer una variable.
- ADD_VARIABLE: sumar a una variable numérica.
- REMOVE_VARIABLE: restar de una variable numérica.
- WAIT: esperar una cantidad de ticks.
- CANCEL_EVENT: cancelar un evento cuando sea compatible.
- ACTION_SEQUENCE: ejecutar varias acciones ordenadamente.
Las acciones deben tener acceso al contexto correspondiente, como jugador, evento, mundo y variables.
Las esperas no deben bloquear el hilo principal.
Todas las operaciones de Bukkit deben ejecutarse en el hilo adecuado.
Controla las tareas pendientes cuando se desactive un script o se apague el servidor.
Evita ejecuciones infinitas y errores por valores incorrectos.
## 8. MOTOR VERTEXSKRIPT
Implementa un intérprete propio denominado `VertexSkript`.
Su objetivo es leer archivos `.sk`, analizar su sintaxis y ejecutar las instrucciones compatibles sin instalar Skript.
No implementes un sistema que simplemente busque palabras dentro del archivo. Crea un parser estructurado que pueda reconocer eventos, bloques indentados, condiciones, expresiones y acciones.
### 8.1. Sintaxis inicial
Prioriza las siguientes construcciones:
- `on join:`
- `on quit:`
- `on chat:`
- `on death:`
- Eventos básicos de interacción.
- `command /nombre:`
- `trigger:`
- `send "mensaje"`
- `broadcast "mensaje"`
- `execute console command "comando"`
- Condiciones `if` y `else`.
- Comparaciones de texto y números.
- Comprobaciones básicas de permisos.
- Variables globales como `{vertex.prueba}`.
- Variables locales compatibles con el contexto.
- Asignaciones `set`.
- Operaciones numéricas básicas.
- `wait`.
- Cancelación de eventos compatibles.
Implementa cada construcción realmente antes de declararla compatible.
### 8.2. Ejemplos de referencia
El motor debe poder ejecutar archivos como este cuando las instrucciones mostradas estén implementadas:
```vb
on join:
send "&aBienvenido, %player%"
command /vertexprueba:
trigger:
set {vertex.prueba} to 1
if {vertex.prueba} is 1:
send "&aLa variable funciona"
```
Estos ejemplos son una especificación del comportamiento deseado, no una excusa para simular su ejecución.
### 8.3. Parser y diagnóstico
El intérprete debe:
- Reconocer bloques mediante indentación.
- Validar la estructura del archivo.
- Identificar instrucciones desconocidas.
- Informar del número de línea.
- Detectar errores de sintaxis.
- Evitar que un archivo incorrecto detenga todo el plugin.
- Mantener una lista de instrucciones admitidas.
- Separar el análisis sintáctico de la ejecución.
Los errores deben aparecer en la consola y estar disponibles mediante los comandos administrativos.
### 8.4. Comandos de scripts
Permite declarar comandos personalizados en archivos `.sk`.
Registra los comandos al cargar los scripts y evita duplicados después de una recarga.
Si una declaración entra en conflicto con un comando ya existente, informa del problema y no sobrescribas comandos de otros plugins.
### 8.5. Alcance de compatibilidad
No intentes reproducir todo Skript en la versión 0.1.0.
Implementa un subconjunto pequeño, útil y verificable.
La arquitectura debe permitir añadir nuevas instrucciones, eventos, expresiones y condiciones en versiones posteriores.
No anuncies compatibilidad con addons ni funciones externas que no estén implementados.
## 9. MOTOR VERTEXEVENTS
Implementa un intérprete independiente para configuraciones YAML de Conditional Events.
Este módulo debe funcionar sin el plugin Conditional Events original.
Antes de implementar el formato, consulta documentación y ejemplos reales de las versiones pertinentes para Minecraft 1.20.1.
No inventes la estructura oficial de sus archivos.
Determina qué eventos, condiciones y acciones utiliza el formato original y crea un parser que admita un subconjunto real de esas estructuras.
Prioriza:
- Identificadores de eventos.
- Tipos de eventos.
- Condiciones.
- Múltiples condiciones.
- Acciones.
- Mensajes privados y globales.
- Comandos de consola.
- Comandos de jugador.
- Variables.
- Placeholders.
- Filtros por jugador.
- Activación y desactivación.
- Secuencias de acciones.
- Cancelación de eventos cuando sea compatible.
Utiliza la estructura y semántica reales de Conditional Events cuando estén documentadas.
Si una función requiere un plugin externo, no simules que funciona sin él.
### Ejemplo conceptual
Este ejemplo sirve únicamente para ilustrar el resultado deseado:
```yaml
events:
vertex_bienvenida:
type: player_join
actions:
default:
- 'message: &aBienvenido al servidor'
```
No asumas que este formato coincide exactamente con el original. Verifica la sintaxis oficial y proporciona ejemplos funcionales basados en el formato realmente soportado.
Si una configuración original necesita una función no implementada, indica qué parte falta.
## 10. SISTEMA DE EVENTOS COMPARTIDO
Los dos motores deben reutilizar un sistema interno de eventos, condiciones y acciones.
No dupliques toda la lógica entre VertexSkript y VertexEvents.
Implementa un registro centralizado de eventos y acciones, con un contexto de ejecución que permita acceder al jugador, al evento y a las variables.
Evita registrar listeners duplicados y crea mecanismos para desactivar scripts, cancelar tareas y liberar recursos.
Los dos motores deben poder utilizarse simultáneamente.
## 11. RECARGA Y VALIDACIÓN
Implementa un sistema de recarga en caliente.
Al recargar:
1. Detecta los archivos.
2. Analiza su contenido.
3. Valida la sintaxis.
4. Prepara la nueva representación ejecutable.
5. Sustituye las versiones anteriores cuando la nueva carga sea válida.
6. Evita registros duplicados.
7. Conserva las variables persistentes.
8. Informa de los archivos correctos e incorrectos.
Siempre que sea posible, conserva la última versión válida de un archivo si la nueva versión contiene errores.
El comando `/vertex scripts test ` debe validar el archivo sin ejecutar comandos, enviar mensajes ni producir efectos secundarios.
No reinicies el servidor automáticamente.
## 12. CONFIGURACIÓN
Implementa una configuración clara y editable.
`config.yml` debe incluir:
- Opciones generales.
- Activación de cada motor.
- Carga automática.
- Depuración.
- Límites de ejecución.
- Persistencia.
- Comportamiento ante errores.
`messages.yml` debe contener todos los mensajes del framework.
`variables.yml` debe guardar las variables persistentes.
Los archivos de scripts deben estar separados por motor.
Utiliza códigos de color tradicionales de Minecraft, como `&a`, `&c`, `&e` y `&7`.
No codifiques directamente los mensajes en las clases Java cuando deban ser configurables.
## 13. SEGURIDAD
Considera los scripts como código de confianza administrado por el propietario del servidor.
- Protege los comandos administrativos.
- Valida las rutas de los archivos.
- No permitas que un archivo acceda arbitrariamente a otras carpetas.
- No utilices ejecución arbitraria de código Java.
- Controla las tareas pendientes.
- Limita secuencias excesivas.
- Evita recursiones infinitas.
- Gestiona errores por archivo.
- Ejecuta las operaciones de Bukkit en el hilo adecuado.
- No permitas que un jugador normal modifique o recargue scripts.
- No ejecutes comandos administrativos sin el contexto adecuado.
## 14. TECNOLOGÍA Y DEPENDENCIAS
Utiliza Java 17, Maven y la API correspondiente a Paper 1.20.1.
El proyecto debe incluir:
- `pom.xml`.
- `plugin.yml`.
- Clase principal.
- Clases de los módulos.
- Archivos YAML predeterminados.
- Ejemplos de scripts.
- Pruebas automatizadas cuando sea posible.
- Documentación.
No añadas Skript ni Conditional Events como dependencias obligatorias.
No copies código de terceros sin comprobar sus licencias.
La compatibilidad debe implementarse mediante un motor propio que reproduzca las funciones admitidas.
## 15. PRUEBAS
Antes de entregar el proyecto, comprueba:
- Que compila con Java 17.
- Que Maven genera el JAR.
- Que los archivos de configuración se crean correctamente.
- Que los comandos funcionan.
- Que las variables se guardan y recuperan.
- Que un script válido se analiza y ejecuta.
- Que un script inválido genera un error claro.
- Que las configuraciones YAML válidas se interpretan.
- Que un YAML incorrecto no detiene el plugin.
- Que la recarga no duplica comandos ni listeners.
- Que las tareas pendientes se limpian correctamente.
- Que las funciones implementadas funcionan en un servidor de prueba cuando el entorno lo permita.
No afirmes que has probado algo que solamente has compilado.
## 16. DOCUMENTACIÓN
Incluye una guía en español que explique:
- Cómo instalar el plugin.
- Cómo compilar el proyecto.
- Dónde colocar los scripts.
- Cómo crear eventos.
- Cómo utilizar las variables.
- Cómo recargar los archivos.
- Cómo revisar errores.
- Qué sintaxis se admite.
- Qué instrucciones todavía no se admiten.
- Qué diferencias existen respecto a los plugins originales.
## 17. ENTREGA
Genera el proyecto completo y organizado.
Si tu entorno permite crear archivos, escribir código y ejecutar Maven, hazlo directamente.
No entregues solamente una explicación de cómo se podría desarrollar.
No crees interfaces vacías ni clases que aparenten implementar funciones que realmente no funcionan.
Ejecuta la compilación, corrige los errores y entrega `VertexFramework-0.1.0.jar` si puedes generarlo.
Si no puedes compilar, proporciona todo el código fuente y los pasos exactos para compilarlo localmente.
No afirmes que existe un JAR si no se ha generado realmente.
## 18. PRIORIDADES DE DESARROLLO
Para evitar que el proyecto se vuelva demasiado grande o inestable, trabaja en este orden:
**Fase 1:** estructura del plugin, configuración, comandos, permisos y variables.
**Fase 2:** sistema compartido de eventos, condiciones y acciones.
**Fase 3:** intérprete básico de Skript con ejemplos funcionales.
**Fase 4:** intérprete de configuraciones de Conditional Events basado en documentación real.
**Fase 5:** recarga, validación, diagnóstico y pruebas.
**Fase 6:** documentación, compilación y entrega final.
No te detengas después de crear la estructura inicial. Continúa hasta completar todas las fases que permita tu entorno.
Si no puedes completar alguna fase, entrega lo que realmente funciona, explica la limitación y deja el proyecto preparado para continuar.
**RESULTADO FINAL:** Vertex Framework 0.1.0 debe ser un plugin funcional y modular para Minecraft 1.20.1, con comandos, variables, acciones y un motor propio que permita ejecutar una selección real de scripts de Skript y configuraciones de Conditional Events sin instalar los plugins originales.