Home

CustomEventEngine

CustomEventEngine (CEE) es un plugin para Paper/Spigot que permite definir y ejecutar eventos “territoriales” (por chunk y radios de chunks) usando un DSL en YAML.

• Los eventos se definen como archivos .yml dentro de plugins/CustomEventEngine/events/.
• Cada ejecución crea un runtime asociado a un chunk origen y puede “ocupar” múltiples chunks según el scope.
• El flujo del evento se modela como una secuencia de nodos (flow.nodes) con acciones, delays, loops, etc.

Índice rápido

• Instalación
• Quickstart
• Comandos
• Configuración
• DSL: Visión general · Referencia completa
• Desarrollo: Arquitectura · Persistencia · Extender (API)

Requisitos

• Servidor: Paper/Spigot API 1.20+ (el proyecto compila contra paper-api:1.20.4).
• Java: 21.
• Dependencias opcionales:
  • PlaceholderAPI (softdepend). Se usa si está instalada.

Qué resuelve CEE

• Programar eventos por intervalo o por triggers basados en eventos Bukkit (join, death, weather, etc.).
• Ejecutar lógica por chunks (con locking) evitando superposición entre eventos.
• Manejar variables por evento (locales) y variables globales (controladas por definición).
• Persistir estados de ejecución en runtime.json.

Conceptos clave (modelo mental)

• EventDefinition: lo que escribes en YAML.
• EventRuntime: una ejecución concreta de un evento en un chunk.
• Chunk locks: el runtime ocupa un conjunto de chunks; otro runtime no puede iniciar si hay ocupación.
• Scope: define cómo se “expande” el conjunto de chunks ocupados a partir del chunk origen.
• Target: cómo se elige el chunk objetivo cuando el trigger no trae una localización.

Flujo de datos (alto nivel)

flowchart LR
  YML[events/*.yml] --> Loader[EventLoader]
  Loader --> Defs[EventDefinition]
  Defs --> Engine[EventEngine]
  Engine --> Triggers[Triggers registrados]
  Triggers -->|disparo| Start[StartEvent]
  Start --> Runtime[EventRuntime]
  Runtime --> Scheduler[RuntimeScheduler]
  Scheduler --> Actions[Actions/Flow]
  Runtime --> Persist[PersistenceManager]
  Persist --> runtimejson[runtime.json]

Loading

Archivos principales

• plugins/CustomEventEngine/config.yml — configuración global.
• plugins/CustomEventEngine/messages.yml — mensajes de comandos.
• plugins/CustomEventEngine/events/*.yml — eventos del DSL.
• plugins/CustomEventEngine/runtime.json — snapshot de runtimes (persistencia).

Primeros pasos

Sigue Quickstart para crear tu primer evento y ejecutarlo manualmente.

Troubleshooting rápido

• Si un evento no inicia y ves “chunk ocupado”: revisa el scope y si existe un runtime activo en el chunk.
• Si un trigger por intervalo no dispara: verifica scheduler.tick-interval y si el evento está habilitado por su trigger.
• Si necesitas limpiar estados: usa los comandos purge descritos en Comandos.