Il sistema di sfide
definitivo per Paper

Installazione

L'installazione di ChallengesX richiede meno di 5 minuti.

1. Copia il JAR

Scarica ChallengesX-2.0.jar e copialo nella cartella plugins/ del tuo server Paper.

2. Primo avvio

Avvia il server. ChallengesX genererà automaticamente tutti i file di configurazione in plugins/ChallengesX/.

plugins/ChallengesX/
├── config.yml          # configurazione principale
├── achievements.yml    # definizione achievements
├── battlepass.yml      # livelli e ricompense battlepass
├── quests.yml          # definizione quest
├── shop.yml            # shop punti
├── challenges/
│   ├── vanilla.yml
│   ├── lifesteal.yml
│   └── ...             # un file per ogni server-mode
└── lang/
    ├── messages_it.yml
    ├── messages_en.yml
    └── ...             # 8 lingue incluse

3. Configura

Apri config.yml e imposta almeno il server-mode corretto per il tuo server. Salva e usa /cx reload senza riavviare.

Configurazione

Tutto il comportamento del plugin è controllato da config.yml. Zero valori hardcodati.

Server Mode

Determina quale set di sfide viene caricato. Supporta anche modalità combinate.

server-mode: VANILLA
# oppure lista combinata:
# server-mode: [LIFESTEAL, VANILLA]

Progressione XP

progression:
  xp-per-challenge: 50
  xp-multiplier:
    EASY:       0.5
    NORMAL:     1.0
    HARD:       2.0
    LEGENDARY:  5.0
  daily-first-bonus: 1.5
  streak-multiplier:
    enabled: true
    increment-per-challenge: 0.1
    max-multiplier: 2.5

Challenges

Le sfide sono il cuore del plugin. Ogni categoria ha la sua rotazione automatica.

Categorie

Difficoltà

• EASY — moltiplicatore XP ×0.5
• NORMAL — moltiplicatore XP ×1.0
• HARD — moltiplicatore XP ×2.0
• LEGENDARY — moltiplicatore XP ×5.0

Struttura di una challenge

esempio_sfida:
  name: "Cacciatore Esperto"
  description: "Uccidi 50 zombie"
  category: DAILY
  difficulty: HARD
  type: KILL_MOB
  target: ZOMBIE
  amount: 50
  xp: 150
  rewards:
    - type: MONEY
      amount: 500
    - type: COMMAND
      command: "give %player% diamond 3"

Battlepass

Sistema a doppia corsia ispirato a Brawl Stars. Si avanza completando qualsiasi challenge.

Corsie

Progressione

Ogni challenge completata assegna punti XP. Al raggiungimento di 1000 XP (configurabile) si sale di livello nel battlepass, sbloccando le ricompense del livello raggiunto.

Permessi

• challengesx.battlepass.premium — accesso corsia premium
• challengesx.battlepass.use — accesso GUI battlepass

Quest System

Quest narrative con step sequenziali, rami multipli e scelte del giocatore.

Struttura

Ogni quest è composta da step. Ogni step può avere più rami (branches) tra cui il giocatore deve scegliere, rendendo ogni playthrough potenzialmente diverso.

quest_esempio:
  name: "Il Viandante"
  description: "Una storia di sopravvivenza"
  steps:
    - id: step_1
      type: KILL_MOB
      target: SKELETON
      amount: 10
      branches:
        - id: branch_a
          condition: "kills >= 10"
          next_step: step_2a
        - id: branch_b
          condition: "time_elapsed > 300"
          next_step: step_2b

Comandi

• /quests — apri la quest board
• /quests info <id> — dettagli quest
• /quests abandon <id> — abbandona quest attiva

Maestria

Sistema di progressione cosmetica basato su giorni qualificanti reali. Non legato a donazioni.

Come funziona

Un "giorno qualificante" viene contato solo se il giocatore soddisfa tutte e tre le condizioni:

• Almeno 1 kill PvP nel giorno
• Almeno 30 minuti di gioco attivo
• Non essere stati uccisi da un giocatore

Tier e Rank (28 gradi totali)

Comandi

• /maestria — profilo personale
• /maestria top — leaderboard globale
• /maestria info <giocatore> — profilo di un altro giocatore (admin)

Party System

Crea gruppi per completare sfide cooperative e condividere il progresso.

Funzionamento

I party permettono a più giocatori di lavorare insieme sulle stesse sfide. Il progresso viene sommato tra tutti i membri attivi del party.

Comandi Party

Comandi

Tutti i comandi disponibili nel plugin.

Giocatori

Admin (op)

Permessi

Tutti i permessi disponibili. I permessi default: true sono attivi per tutti i giocatori.

Integrazioni

ChallengesX rileva automaticamente i plugin compatibili e attiva le integrazioni.

PlaceholderAPI

Sono disponibili le seguenti placeholder per usare i dati di ChallengesX in altri plugin:

%challengesx_points%          → punti totali giocatore
%challengesx_completed%       → sfide completate oggi
%challengesx_rank%            → posizione in classifica
%challengesx_battlepass_level%→ livello battlepass attuale
%challengesx_maestria_rank%   → rank Maestria visualizzato
%challengesx_maestria_days%   → streak days Maestria

DiscordSRV

Quando un giocatore completa una challenge HARD o LEGENDARY, viene inviata automaticamente una notifica nel canale Discord configurato.

ItemsAdder

Usato per le icone del sistema Maestria (namespace rankicons) e per icone custom nelle GUI. Il pack deve essere presente in ItemsAdder per visualizzare le icone correttamente.

Storage

Tre backend di storage supportati. Cambiare tipo richiede una migrazione manuale dei dati.

YAML (default)

I dati vengono salvati in file .yml per ogni giocatore. Ottimo per server piccoli, nessuna dipendenza esterna.

SQLite

Database file-based, nessun server richiesto. Raccomandato per la maggior parte dei server.

storage:
  type: SQLITE
  auto-save-minutes: 5

MySQL

Raccomandato per reti BungeeCord/Velocity con database condiviso.

storage:
  type: MYSQL
  mysql:
    host: localhost
    port: 3306
    database: challengesx
    username: root
    password: "tua_password"