Tutorial

Configuration guide

Step-by-step walkthrough of every important WujaRift setting — language, arena, challenge UX, instant waves, events, and rewards. Tuned for SMP operators.

1. Where files live

After first start, everything is under plugins/WujaRift/. Edit YAML → run /rift reload (or restart). Missing locale keys are merged from the JAR automatically; stale gui.yml without a Language button is migrated on reload.

• config.yml — language, auto-events, arena, challenge, waves, DB, hooks
• messages_en.yml / messages_pl.yml — all UI & chat text (MiniMessage)
• events/*.yml — invasion presets (waves, boss, abilities)
• relics.yml, rewards.yml, gui.yml — loot, economy, menu layouts

2. Language (EN / PL)

Set the active UI locale with top-level language: en or language: pl (also mirrored under settings.language). Switch live without restart:

• /rift admin → click Language (cycles EN ↔ PL, reopens GUI fully localized)
• /rift lang en or /rift lang pl (admin)

Player menus, relics GUI, admin GUI, chat, titles, and challenge strings all follow the active locale. Prefer editing messages_*.yml over hardcoding English in gui.yml.

3. Arena zone

Under settings.arena you contain players and mobs around the rift spawn while an event runs.

settings:
  arena:
    enabled: true
    size: 25              # full width / diameter
    shape: square         # square | circle
    height: 16            # ±Y from rift; 0 = ignore vertical
    contain-mobs: true
    contain-players: true
    lock-on-enter: true
    leave-action: teleport
    leave-handling: countdown   # instant | countdown | off (v1.1)
    leave-countdown-seconds: 10
    fail-action: eject
    eject-distance-blocks: 5
    eject-block-reentry: true
    border-particles: true
    logout-policy: keep-locked

• Casual SMP: size 25–35, lock-on-enter true, leave-handling countdown
• Open field: size 40–50 circle, or disable contain-players
• Bypass: permission wujarift.arena.bypass · see also Arena leave modes

4. Challenge start (first hit)

When a player first damages any rift-tagged mob (wave or boss), WujaRift can show a title + optional bossbar. Fully YAML-driven:

challenge:
  enabled: true
  trigger: first-rift-mob-hit
  only-once-per-rift: true
  clear-on-death: false
  clear-on-rift-end: true
  title:
    enabled: true
    fade-in: 10
    stay: 40
    fade-out: 10
  actionbar:
    enabled: false
  bossbar:
    enabled: true
    color: RED
    style: SOLID
    progress-mode: waves   # waves | boss-health | static
    shared: true

Edit title / subtitle / bossbar text in challenge.* keys inside messages_en.yml and messages_pl.yml.

5. Instant next wave (clear-to-advance)

Waves no longer wait on long fixed timers. When all wave-tagged mobs of the current wave die, the next wave starts after a tiny configurable delay (default: immediate).

waves:
  inter-wave-delay-ticks: 0   # 0 = next tick after clear
  max-wait-ticks: 0           # 0 = disabled; optional force-advance
  announce-wave: true
  announce-chat: true
  announce-title: false
  boss-delay-ticks: 0         # after last wave; -1 = use event YAML seconds

• Snappy fights: keep inter-wave-delay-ticks: 0 and boss-delay-ticks: 0
• Breathing room: set inter-wave to 20–40 ticks (~1–2s)
• Event YAML delay-seconds on wave 1 still delays the first spawn; later waves advance on clear

6. Scheduler & limits (SMP defaults)

# Preferred in 1.1 — opt-in multi-rule scheduler
scheduler:
  enabled: true
  min-players: 1
  skip-if-rift-active: true
  announce-countdown-seconds: 60
  rules:
    - id: evening
      enabled: true
      type: interval
      interval-seconds: 2700
      events: [nether_breach, void_incursion]
      worlds: [world]
      location-mode: near-random-player

# Legacy (used when scheduler.enabled is false)
settings:
  auto-events:
    enabled: true
    interval-seconds: 1800
    chance: 1.0
    near-players: true
  limits:
    max-concurrent-rifts: 1
    rift-timeout-seconds: 900
    global-cooldown-seconds: 300

For a calm SMP: one concurrent rift, 5–10 minute cooldown, ~45 minute rule interval. See Event scheduler. Blacklist nether/end if you only want overworld tears.

7. Events, rewards, relics

Tune difficulty in events/*.yml (mob counts, health multipliers, boss HP/phases). Wire Vault money and relic chances in rewards.yml. Relic definitions live in relics.yml. See also the Events and Relics docs pages, plus ready-made snippets on Example configs.

8. Verify after changes

1. /rift lang pl → open /rift and /rift admin — labels should be Polish
2. /rift start nether_breach → hit a rift mob → challenge title + bossbar
3. Clear a wave → next wave should appear almost immediately
4. Walk the border → arena push/teleport if enabled