AxoKoth

Ganador al terminar por duracion

Si el KOTH termina por duracion y nadie llego a la meta, AxoKoth puede premiar al jugador o equipo con mayor progreso actual. Esta opcion viene activada por defecto.

Ejemplo comun: required-points: 200, points-per-second: 1.0 y event-duration-seconds: 120. En ese caso nadie puede llegar a 200 puntos antes de que termine el evento.

capture:
  mode: "POINTS"
  required-points: 100
  points-per-second: 1.0
  event-duration-seconds: 180
  award-highest-progress-on-timeout: true

• Baja required-points si quieres eventos cortos.
• Sube event-duration-seconds si la meta es alta.
• Sube points-per-second si quieres capturas mas rapidas.
• Desactiva award-highest-progress-on-timeout si solo quieres ganador cuando alguien llega a la meta.

Comandos de recompensa recomendados

Para comandos de consola usa [CONSOLE] o escribe el comando directo. Para ConditionalEvents se recomienda [CE].

rewards:
  winner:
    mode: "ALL"
    actions:
      - "[CONSOLE] give <player> diamond 5"
      - "[CE] Koth_Pantano player:<player>"
      - "[MESSAGE] <green>Ganaste el KOTH <koth_name>."

Despues de editar rewards.yml, usa /axokoth reload. Si acabas de instalar o actualizar ConditionalEvents, reinicia el servidor.

Placeholders de hologramas

Si AxoHologram muestra un placeholder escrito literalmente, revisa que PlaceholderAPI este instalado y que el placeholder no tenga un % extra.

Reemplaza <id> por el ID real del KOTH, por ejemplo %axokoth_timeleftf_<id>%.

Valores cuando el KOTH esta inactivo

Los valores que se muestran cuando el KOTH esta inactivo o finalizado se pueden personalizar para evitar textos como N/A o ceros que no se vean bien.

placeholders:
  inactive-number-value: "0"
  inactive-percentage-value: "0.0"
  inactive-percentage-formatted-value: "0.0%"
  inactive-time-value: "0"
  inactive-time-formatted-value: "0s"

Instalacion

1. Descarga AxoKoth desde la pagina de modrinth
2. Coloca el archivo .jar descargado dentro de la carpeta plugins/ de tu servidor.
3. Reinicia el servidor para generar los archivos de configuracion.
4. Edita los archivos necesarios y usa /axokoth reload para recargar cambios de configuracion.

Si instalas o actualizas dependencias como PlaceholderAPI, AxoHologram o ConditionalEvents, reinicia el servidor para que Paper vuelva a leer las dependencias.

Archivos principales

• plugins/AxoKoth/config.yml - configuracion general, captura, bossbar, hologramas y protecciones.
• plugins/AxoKoth/koths.yml - regiones, centros, horarios y ajustes por KOTH.
• plugins/AxoKoth/rewards.yml - recompensas del ganador y participantes.
• plugins/AxoKoth/database.yml - almacenamiento local o SQL.
• plugins/AxoKoth/languages/ - mensajes e idiomas.
• plugins/AxoKoth/menus/ - menus visuales.

Primer KOTH

1. Usa /axokoth wand para recibir la varita de seleccion.
2. Marca la posicion 1 y posicion 2 con clic izquierdo y derecho.
3. Crea el evento con /axokoth create <id>.
4. Define el centro con /axokoth setcenter <id>.
5. Mueve el holograma con /axokoth holo <id> move.
6. Inicia el evento con /axokoth start <id>.

Crear y editar eventos

Captura por puntos

En modo por puntos, quien controla el KOTH suma puntos por segundo. Gana al llegar a la meta.

capture:
  mode: "POINTS"
  required-points: 100
  points-per-second: 1.0
  points-decay-per-second: 1.0
  award-highest-progress-on-timeout: true
  reset-on-leave: false
  progress-mode: "PAUSE"

• Con owner-type: "PLAYER", cada jugador conserva sus propios puntos.
• Con TEAM, CLAN o FACTION, los puntos se comparten por grupo.
• Si el evento se detiene o termina, los puntos visibles vuelven a cero.

Captura por tiempo

capture:
  mode: "TIME"
  required-seconds: 300

Este modo es util cuando quieres que un jugador o equipo mantenga la zona durante una duracion fija.

Bossbar por cercania

bossbar:
  enabled: true
  color: "RED"
  overlay: "PROGRESS"
  progress: true
  progress-mode: "TIME"
  visibility: "NEARBY"
  range-blocks: 48
  permission: ""
  title: "<red><bold>KOTH:</bold> <white><koth_name> <gray>- <yellow><remaining_time>s"

visibility acepta NEARBY, PARTICIPANTS, WORLD o ALL. progress-mode acepta TIME para mostrar duracion restante o CAPTURE para mostrar progreso de captura.

Resaltado del capturador

El jugador que captura puede verse resaltado para los demas con armadura de cuero falsa. El capturador no la ve y su inventario real no cambia.

capture-visuals:
  enabled: true
  armor:
    enabled: true
    color: "GREEN"

El color acepta nombres como GREEN, VERDE, RED, BLUE o valores hex como #00ff00.

Horarios por KOTH

Los horarios viven dentro de cada KOTH en koths.yml. Si no existe la seccion, AxoKoth la agrega desactivada al recargar.

schedule:
  enabled: true
  announcements:
    - seconds-before: 300
    - seconds-before: 60
  times:
    - days: [MONDAY, TUESDAY, WEDNESDAY]
      time: "20:00"
    # Tambien puedes usar:
    # - interval-minutes: 120

Horarios locales por jugador

El scheduler usa la zona horaria principal para calcular los inicios, pero los placeholders locales pueden mostrarse en la zona horaria del jugador segun su idioma de cliente.

schedule:
  timezone: "America/Monterrey"
  display:
    time-format: "yyyy-MM-dd HH:mm z"
    timezone-by-locale:
      es_ES: "Europe/Madrid"
      es_AR: "America/Argentina/Buenos_Aires"
      es_MX: "America/Mexico_City"
    timezone-labels:
      Europe/Madrid: "Spain"
      America/Argentina/Buenos_Aires: "Argentina"
      America/Mexico_City: "Mexico"

Para hologramas usa <next_start_local_time> y <next_start_timezone>, o sus equivalentes PlaceholderAPI.

Hologramas por KOTH

Al crear o recargar un KOTH, AxoKoth puede generar un holograma con el mismo ID del KOTH para que el administrador lo personalice.

• Con AxoHologram: plugins/AxoHologram/holograms/<id>.yml
• Con sistema interno: plugins/AxoKoth/holograms/<id>.yml

El sistema interno renderiza placeholders por jugador, util para mostrar horarios de Espana, Argentina o Mexico segun el idioma del cliente. Si usas AxoHologram, instala PlaceholderAPI para que las lineas con %axokoth_*% se actualicen correctamente.

Comandos de holograma

Lineas recomendadas

lines:
  - "<gradient:#FF1744:#9C27B0><bold><koth_name></bold></gradient>"
  - "<gray>Estado: <white><koth_status>"
  - "<gray>Capturando: <white><capture_player>"
  - "<gray>Progreso: <yellow><capture_progress><gray>/<yellow><capture_required> <white><capture_unit>"
  - "<gray>Tiempo: <white><remaining_time>"
  - "<gray>Inicio: <white><next_start_local_time> <dark_gray>(<next_start_timezone>)"

Grupos de recompensa

• winner se ejecuta al ganador.
• participation se ejecuta a los participantes que no ganaron.
• Cada KOTH puede elegir sus propios grupos de ganador y participacion.
• El modo ALL ejecuta todas las acciones.
• El modo RANDOM ejecuta una accion aleatoria del grupo.

Grupos por KOTH

En koths.yml puedes apuntar cada evento a grupos de rewards.yml. Si no se define nada, se usan winner y participation.

koths:
  koth_principal:
    rewards:
      - "koth_principal_winner"
    participation-rewards:
      - "koth_principal_participation"

Acciones disponibles

Ejemplo con ConditionalEvents

rewards:
  winner:
    mode: "ALL"
    actions:
      - "[CE] Koth_Pantano player:<player>"
      - "[SOUND] UI_TOAST_CHALLENGE_COMPLETE 1 1"

Tambien puedes usar comandos directos como /ce call Koth_Pantano player:%player%.

Permisos de jugador

Permisos administrativos

Bypass

• axokoth.admin.bypass.capture evita que el jugador sea candidato de captura.
• axokoth.admin.bypass.restrictions permite saltar restricciones dentro de regiones activas.

AxoKoth API

Esta seccion es para desarrolladores que quieren leer o controlar AxoKoth desde otro plugin de Paper/Folia.

La API publica vive en com.axokoth.api. Permite consultar KOTHs, leer snapshots de estado, iniciar o detener eventos, consultar progreso, registrar proveedores de equipo, registrar acciones de recompensa y agregar placeholders internos.

Agregar AxoKoth como dependencia

Agrega JitPack como repositorio y compila contra AxoKoth. Para plugins Paper se recomienda compileOnly o provided para no empaquetar AxoKoth dentro de tu jar.

dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        mavenCentral()
        maven { url 'https://jitpack.io' }
    }
}

dependencies {
    compileOnly 'com.github.Axolotle154:AxoKoth:2.0.6'
}

dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        mavenCentral()
        maven { url = uri("https://jitpack.io") }
    }
}

dependencies {
    compileOnly("com.github.Axolotle154:AxoKoth:2.0.6")
}

<repositories>
    <repository>
        <id>jitpack.io</id>
        <url>https://jitpack.io</url>
    </repository>
</repositories>

<dependency>
    <groupId>com.github.Axolotle154</groupId>
    <artifactId>AxoKoth</artifactId>
    <version>2.0.6</version>
    <scope>provided</scope>
</dependency>

resolvers += "jitpack" at "https://jitpack.io"

libraryDependencies += "com.github.Axolotle154" % "AxoKoth" % "2.0.6" % "provided"

:repositories [["jitpack" "https://jitpack.io"]]

:dependencies [[com.github.Axolotle154/AxoKoth "2.0.6" :scope "provided"]]

Declarar AxoKoth en tu plugin

Si tu plugin necesita AxoKoth para funcionar, declaralo como dependencia requerida en paper-plugin.yml:

dependencies:
  server:
    AxoKoth:
      load: BEFORE
      required: true
      join-classpath: true

Si tu plugin puede funcionar sin AxoKoth, dejalo opcional:

dependencies:
  server:
    AxoKoth:
      load: BEFORE
      required: false
      join-classpath: true

Para un plugin.yml legacy:

depend: [AxoKoth]

o, si es opcional:

softdepend: [AxoKoth]

Obtener la API

La forma directa usa AxoKothProvider:

import com.axokoth.api.AxoKothAPI;
import com.axokoth.api.AxoKothProvider;
import org.bukkit.plugin.java.JavaPlugin;

public final class MyPlugin extends JavaPlugin {

    private AxoKothAPI axoKoth;

    @Override
    public void onEnable() {
        axoKoth = AxoKothProvider.get(this);
    }
}

Si AxoKoth es opcional, usa getOptional(this):

AxoKothProvider.getOptional(this).ifPresent(api -> {
    getLogger().info("Hook con AxoKoth listo. API " + api.apiVersion());
});

Obtener la API con ServicesManager

Tambien puedes resolverla desde el ServicesManager de Bukkit/Paper.

import com.axokoth.api.AxoKothAPI;
import org.bukkit.plugin.RegisteredServiceProvider;

RegisteredServiceProvider<AxoKothAPI> registration =
        getServer().getServicesManager().getRegistration(AxoKothAPI.class);

AxoKothAPI axoKoth = registration == null ? null : registration.getProvider();

Consultar KOTHs

Para leer estado runtime usa KothSnapshot. Es una vista inmutable pensada para otros plugins.

import com.axokoth.api.KothSnapshot;

axoKoth.getKothSnapshot("spawn").ifPresent(snapshot -> {
    String status = snapshot.status().name();
    int progress = snapshot.progress();
    int required = snapshot.requiredProgress();
    double percent = snapshot.progressPercentage();
    int participants = snapshot.participantIds().size();
});

Tambien puedes listar KOTHs activos:

for (KothSnapshot snapshot : axoKoth.activeKoths()) {
    getLogger().info(snapshot.displayName() + " esta activo.");
}

Controlar eventos

axoKoth.startKoth("spawn");
axoKoth.pauseKoth("spawn");
axoKoth.resumeKoth("spawn");
axoKoth.stopKoth("spawn");
axoKoth.resetKoth("spawn");

Estos metodos devuelven true si el cambio se aplico. Si el KOTH no existe o esta mal configurado, la API puede lanzar una excepcion igual que los comandos administrativos.

Registrar placeholders internos

Los placeholders registrados por API funcionan en textos internos de AxoKoth: mensajes, menus, recompensas, webhooks, bossbar y hologramas internos.

axoKoth.registerPlaceholder("my_plugin_status", context -> {
    return "online";
});

Uso dentro de textos de AxoKoth:

<my_plugin_status>

Acciones de recompensa custom

Puedes registrar una accion nueva para usarla desde rewards.yml.

axoKoth.registerRewardAction("MY_ACTION", (player, koth, argument) -> {
    player.sendMessage("Reward custom: " + argument);
});

Uso:

rewards:
  winner:
    mode: "ALL"
    actions:
      - "[MY_ACTION] valor personalizado"

Metodos principales

Eventos Bukkit disponibles

• KothStartEvent
• KothStopEvent
• KothCaptureStartEvent
• KothCaptureProgressEvent
• KothCaptureCancelEvent
• KothContestedEvent
• KothWinEvent
• KothRewardEvent

@EventHandler
public void onKothWin(KothWinEvent event) {
    getLogger().info(event.winnerName() + " gano " + event.koth().displayName());
}

Archivos configurables

Anuncios

announcements:
  enabled: true
  permission: "axokoth.player.notifications"
  start: true
  finish: true
  stop: true
  winner: true

Los textos se editan desde los archivos de idioma.

Formato del top

placeholders:
  top-entry-format: "<name> - <points> puntos"
  wins-top-entry-format: "<name> - <wins> victorias"

Estos formatos afectan placeholders combinados como %axokoth_top_1_name_points% y %axokoth_wins_top_1_entry%.

Protecciones dentro del KOTH

• Bloqueo de colocar y romper bloques.
• Bloqueo de cubetas, explosiones, pistones, vuelo, elytra y comandos.
• Whitelist y blacklist de comandos dentro de regiones activas.
• Bypass administrativo para staff.