Stellar Protect

Bienvenida

StellarProtect es un sistema avanzado de registro de datos para servidores de Minecraft, diseñado para ayudarte a monitorear y revisar cada acción que ocurre en tu mundo. Desde la rotura de bloques, el acceso a cofres, hasta PvP y mucho más. StellarProtect lo registra todo con un enfoque en el rendimiento y la eficiencia.

Características Clave

✅ Registro detallado de las acciones de los jugadores.
⚙️ Arquitectura multihilo que evita afectar el hilo principal del servidor.
🧪 Estabilidad comprobada en servidores con más de 200 jugadores en línea.
🧩 Compatible con versiones desde Minecraft 1.8 hasta 1.21.7.
💬 Comunidad activa con soporte continuo a través de Discord.
⚡ Soporte a Folia nativamente tenemos soporte a folia.

Configuración

StellarProtect permite una configuración altamente ajustable para adaptarse al rendimiento del servidor, tipos de base de datos y necesidades de logging. A continuación se explican las principales secciones del archivo config.yml.

Opciones de depuración

Estas opciones controlan si el plugin genera mensajes extra durante su funcionamiento. Útiles para desarrollo o detección de problemas.

debugs:
  log: false          # Activa salida de logs internos
  save: false         # Muestra información detallada del guardado
  extras: false       # Depura funciones adicionales del sistema

Optimización del rendimiento

Permite controlar cuántos recursos se usan y cómo se gestionan los datos en segundo plano.

optimizations:
  maxCores: 4                    # Núcleos máximos usados para multihilo
  save-period: 15                # Segundos entre guardados automáticos
  batch-size: 200                # Acciones antes de forzar guardado
  max-logs-per-location: 10      # Máximo de registros por bloque
  time-for-cache-clear: 15       # Minutos antes de limpiar cache interna
  days-to-keep-logs: 15          # Días que se mantienen los logs
  delete-old-period: 15          # Cada cuánto eliminar logs antiguos (en minutos)
  clean-placed-cache-period: 30  # Cada cuánto limpiar bloques colocados (segundos)
  item-save-period: 30           # Cada cuánto guardar ítems indexados

Aumentar los valores puede mejorar el rendimiento pero puede afectar precisión temporal.

Configuración de base de datos

Puedes elegir entre h2, mysql o mongodb. Por defecto se usa h2, ideal para servidores pequeños o locales.

databases:
  type: "h2"  # Opciones: h2, mysql, mongodb

  h2:
    database: StellarProtect

  mysql:
    host: localhost
    port: 3306
    database: StellarProtect
    user: admin
    password: 123456

  mongodb:
    host: localhost
    port: 27017
    database: StellarProtect
    user: admin
    password: 123456

Recomendación: si usas MySQL o MongoDB en producción, configura usuarios con acceso limitado.

Seguimiento avanzado

Activa el seguimiento de líquidos como agua o lava, útil para detectar griefing ambiental.

advanced:
  liquid-tracking: true  # Habilita el rastreo de líquidos colocados

Tipos de logs

Puedes activar o desactivar el registro de acciones específicas por mundo, e incluso limitar ciertos tipos de bloques o comandos.

logs:
  block_break:
    enabled: true
    worlds: 
      - all
    disable_types:
      - none
  command:
    enabled: true
    worlds: 
      - all
    disable_types:
      - /login
      - /register
  etc:
    enabled: true
    worlds: 
      - all
    disable_types:
      - none

✅ Usa worlds: all para aplicar en todos los mundos.
❌ Usa disable_types: tipo1, tipo2 para ignorar bloques o comandos específicos.

Comandos

El comando base /sp agrupa múltiples herramientas administrativas, de inspección y mantenimiento del plugin.

Subcomando	Descripción
`/sp lookup`	Busca acciones pasadas registradas en el sistema.
`/sp inspect`	Activa el modo de inspección de bloques.
`/sp purge`	Elimina datos antiguos de los registros.
`/sp debug`	Activa/desactiva información de depuración del plugin.
`/sp memory`	Muestra estadísticas de uso de memoria del plugin.
`/sp version`	Muestra la versión actual instalada del plugin.
`/sp restore`	Restaura las acciones en un radio o tiempo

`/sp lookup`

Busca acciones realizadas por jugadores, como romper/colocar bloques o interactuar con cofres.

/sp lookup [filtros...]

Filtro	Ejemplo	Descripción
`action:`	`a:block_place,block_break`	Filtra por acciones
`page:`	`p:1-10`	Muestra otra pagina o cambia la cantidad maxima de logs por pagina.
`time:`	`t:1h`	Muestra los registros con menos de una hora de antiguedad
`radius:`	`r:10`	Muestra los a 10 bloques de distancia de ti
`user:`	`u:user1,user2,=natural`	Muestra los logs causados por usuarios o eventos.

Usuario Especial	Descripción
`=natural`	Acciones hechas por la naturaleza.
`=fire`	Provocados por fuego (como incendios naturales).
`=water`	Relacionados con el agua (como flujo o colocación).
`=lava`	Relacionados con lava.
`=ice_melt`	Por derretimiento de hielo.
`=snow_fall`	Por caída de nieve.
`=lightning`	Causados por rayos.
`=dripstone`	Relacionados con estalactitas/estalagmitas.
`=piston`	Causados por pistones.
`=explosion`	Provocados por explosiones a.
`=redstone`	Causados por mecanismos de redstone .
`=gravity`	Causados por caída de bloques por gravedad.
`=dispenser`	Relacionados con dispensadores .
`=observer`	Activados por observadores .
`=decay`	Por descomposición natural (como hojas).
`=portal`	Relacionados con portales.
`=entity_id`	Puedes filtrar tambien por el tipo de entidad. EntityType

/sp lookup t:1h r:20 p:3, u:InsiderAnh,User333 a:chat...

`/sp inspect`

Activa el modo inspección el cual en esencia al dar click derecho a un bloque te aparecerán los logs para ese bloque en especifico con el nombre del jugador que ejecuto la acción.

`/sp purge`

Si tienes muchos logs pasados puedes usar este comando para borrarlos pero debes tener cuidado porque esta accion es irreversible.

/sp purge t:30d r:20, u:InsiderAnh,User333 a:block_use,block_place

`/sp restore`

/sp restore [filtros...]

Filtro	Ejemplo	Descripción
`time:`	`t:1h`	Restaura las acciones por tiempo atras.
`radius:`	`r:10`	Restaura las acciones por radio

/sp restore t:1h r:20

Permisos

StellarProtect utiliza un sistema de permisos granular para controlar el acceso a sus comandos.

Lista de Permisos

Permiso	Descripción
`stellarprotect.default`	Acceso básico para jugadores normales (si aplica).
`stellarprotect.admin`	Permite acceso total a todos los comandos y funciones.
`stellarprotect.lookup`	Permite usar `/sp lookup` para buscar acciones.
`stellarprotect.inspect`	Permite usar `/sp inspect` en bloques y contenedores.
`stellarprotect.purge`	Permite usar `/sp purge` para borrar registros.
`stellarprotect.memory`	Permite usar `/sp memory` para ver uso de memoria.
`stellarprotect.rollback`	Permite usar `/sp restore` y otras funciones de rollback.

DeveloperAPI

StellarProtect proporciona una API pública extremadamente simple y directa para desarrolladores de plugins. Su objetivo en esta versión BETA es ofrecer una forma inmediata de registrar acciones comunes como bloques colocados, destruidos, mensajes de chat y comandos, sin necesidad de una configuración compleja.

Objetivo de la API

Registrar acciones personalizadas con una sola línea de código.
Ligera y directa, sin dependencias externas.
Respeta las optimizaciones y filtros definidos en config.yml (por tipo de bloque o comando).
Ideal para testeo o integración básica con otros plugins (como minijuegos, protección de regiones, etc.).

Clase Principal

public class StellarProtectAPI

Todas las funciones son estáticas y se pueden usar directamente sin crear instancias.

Métodos disponibles

`logPlace(Player player, Block block, boolean ignoreSkip)`

Registra que un jugador colocó un bloque.

StellarProtectAPI.logPlace(player, block, false);

ignoreSkip = true ignora la lógica de exclusión de config.yml (disable_types).
No registra si el jugador no está autenticado por StellarProtect.

`logBreak(Player player, Block block, boolean ignoreSkip)`

Registra la destrucción de un bloque.

StellarProtectAPI.logBreak(player, block, false);

`logChat(Player player, String message, boolean ignoreSkip)`

Registra un mensaje de chat.

StellarProtectAPI.logChat(player, "¡Hola mundo!", false);

`logCommand(Player player, String command, boolean ignoreSkip)`

Registra un comando usado por el jugador.

StellarProtectAPI.logCommand(player, "/spawn", false);

¿Por qué tan simple?

StellarProtect está diseñado con un enfoque modular, lo que permite a desarrolladores acceder fácilmente a la capa de logging sin preocuparse por la estructura interna o almacenamiento. A pesar de ser la versión 0.0.1 BETA, la API ya es estable para su propósito, y:

Valida internamente el PlayerProtect para evitar errores.
Filtra entradas automáticamente según la configuración del servidor.
Guarda las acciones en caché para ser procesadas asincrónicamente, mejorando el rendimiento.

Futuras mejoras previstas

Eventos asincrónicos (ActionLoggedEvent, RollbackCompletedEvent, etc.).
Soporte para loguear otras entidades y ubicaciones sin necesidad de Player.
Resultados personalizados o callbacks después de loguear.

Ejemplo completo de uso

@EventHandler
public void onBlockPlace(BlockPlaceEvent event) {
    StellarProtectAPI.logPlace(event.getPlayer(), event.getBlockPlaced(), false);
}

Nota: Esta API está en fase beta y puede cambiar en futuras versiones. Se recomienda revisar el changelog antes de actualizar.

Comunidad y Retroalimentación

Este es un proyecto en crecimiento. Agradecemos tus sugerencias, comentarios y apoyo, ya sea dejando una reseña o participando en nuestra comunidad de Discord.

¡Juntos podemos seguir mejorándolo!