SIEC, NIE SERWER — TWOJA KRONIKA ZOSTAJE. Reframe the product from "a DonutSMP-style server" to "your persistent Polish Minecraft NETWORK ACCOUNT, where status is what you ACHIEVED (carved in stone forever), not the number in your balance." One event-sourced MySQL-authoritative identity (Konto Sieciowe) synced live over NATS makes every server one designed world: quests, jobs (profesje), pass tier, rank and a permanent dated hall-of-fame (Kronika) follow you everywhere, so leaving any single server means abandoning your whole account. The flex inverts DonutSMP's duplicatable "ile masz" into uncopyable, unbuyable "czego dokonałeś" — communal Polish-folklore deeds (Mistrz Sezonu, Pogromca Smoka Wawelskiego) earned by PLAYING, at Polish prime time, by people who play together. Every engagement reward is account-bound (Żetony) and capped, so the 44.8B dupe scar becomes a trust differentiator instead of a recurring catastrophe.

Manufacture a daily "reason to log in TONIGHT": lift D1/D7/D30 retention and session length by giving every player 3 daily + 1 weekly objectives that route them through the network's signature loops, rewarded via a forgiving login streak (Płomień Serii) — while being mathematically incapable of feeding the economy enough to re-enable a 44.8B-style abuse.

Pętla

1) Daily 04:00 Europe/Warsaw rollover (single authoritative cron on the proxy/"konto" service) generates a per-player deterministic set of 3 dailies + (Mon-only) 1 weekly from weighted pools, seeded by hash(uuid + dayEpoch) so it is reproducible and not client-trusted. 2) Player performs normal gameplay → backend plugin increments progress against active contracts via Folia-safe event listeners (block-break/kill/fish/job-event on the OWNING region thread, EntityScheduler — never world-scanning). 3) Progress deltas are written optimistically to a local in-memory counter and flushed to shared MySQL via an idempotent UPSERT; completion publishes a NATS message so every other backend the player might hop to sees the updated state instantly. 4) On reaching the target the contract auto-completes (or requires a /zlecenia claim if config claim_mode=manual), awards Żetony + contributes to the weekly meta + increments the day's streak-eligibility flag. 5) At rollover, completing >=1 contract that day banks the streak; completing 0 consumes a Tarcza (freeze) if available, else the streak drops one tier (soft decay, not zero). Loop length: ~10-25 min of directed play per day to clear all 3 dailies; weekly is a 5-7 day slow-burn.

Doświadczenie gracza

A player logs in and sees a proxy actionbar/title: "Tablica Zleceń odświeżona — 3 nowe zlecenia czekają!" They walk to the Cechmistrz NPC at spawn (sense-of-place, not a faceless menu) or type /zlecenia. The GUI (double chest, 54 slots) shows: row 1 = 3 daily contracts as item icons with progress lore bars (e.g. "Wyrąb 64 drewna — 41/64"), row 3 = 1 weekly contract, plus a Płomień Serii indicator (blaze powder icon "Seria: 7 dni 🔥"), a single free Reroll button (emerald, "Odśwież zlecenie — 1 darmowe dziś"), and a claim-all button. Contracts auto-progress from events the player already fires (block break, mob kill, fish catch, job action) with a subtle actionbar tick "Zlecenie: Górnik — 50/100". On completion: a sound (ENTITY_PLAYER_LEVELUP), a toast, and Żetony + streak credit land instantly and sync across every server. Daily contracts are vocation-tagged (Kontrakty Fachowca: drwal/górnik/rybak/łowca) so finishing them also feeds job XP, tying the daily loop into the long-term jobs loop. Missing a day FREEZES the streak (Tarcza, Duolingo-style) rather than resetting it to zero, so the player never feels punished into churning. The whole thing works identically whether they are on survival, the island server, or a minigame backend — it is their account, not a server feature.

Nagrody

Reward currency is EXCLUSIVELY Żetony — a tagged, NON-TRADEABLE, account-bound soft currency that can only buy cosmetics (Szafa), QoL/convenience, reroll tokens, and streak-freeze insurance (Tarcza). Duped tradeable Money can NEVER buy quest/streak rewards, structurally quarantining the next dupe. Reward curve (per contract, tuned, server-capped): EASY daily = 15 Żetony, MEDIUM = 30, HARD = 60; full 3/3 daily clear ≈ 75-105 Żetony + a small all-clear bonus (25) = ~100-130/day. WEEKLY contract = 250 Żetony + 1 Tarcza (streak freeze) + a seasonal cosmetic shard. Vocation-tagged dailies additionally grant capped job-XP (feeds AuraSkills/UniverseJobs), never money. Streak milestones (Płomień Serii) pay escalating but BOUNDED bonuses: day 3 = +20 Żetony, day 7 = +50 + 1 Tarcza, day 14 = cosmetic trail unlock, day 30 = exclusive seasonal tag "Wytrwały", day 100 = prestige aura — all cosmetic/utility, zero tradeable value. HARD DAILY CEILING: a single account can earn at most ~150 Żetony/day from quests + ~300/week from weekly = a transparent, advertised cap (also a "wyczerp dzienny limit zanim reset" hook). Żetony have a global wealth-scaling sink path (cosmetic prices, reroll costs) so even maxed daily earners face diminishing buying power. Optional tiny tradeable-Money trickle ONLY on the weekly (e.g. 5k Money) is gated behind the daily ceiling and is negligible vs the player market.

Anty-abuse

Designed defensively around the known 44.8B dupe. Layers: (1) CURRENCY QUARANTINE — quests pay ONLY non-tradeable account-bound Żetony (+ capped job-XP), never tradeable Money, so even a perfect exploit yields cosmetics, not market-breaking wealth. (2) HARD DAILY/WEEKLY CEILINGS — max_zetony_per_day=150 enforced inside the awarding SQL transaction via SUM over the append-only quest_ledger; impossible to exceed regardless of how many contracts/servers fire. (3) SERVER-SIDE CLAMP — progress is incremented with `LEAST(target, progress+delta)` in SQL, so it can never overshoot the target and a contract can complete at most once (UNIQUE idempotency key uuid+day_epoch+slot). (4) DELTA TRIPWIRES — per-event progress capped (per_contract_progress_rate_limit=64); any single delta > reject_progress_if_delta_gt=256 is dropped and logged to a Grafana/Loki alert (catches autoclicker bursts, packet spoofing, and the "impossible jump" signature a dupe would produce). (5) PRESENCE GATING — progress only counts when the authoritative presence signal (Strażnik Obecności) says the player is genuinely present; AFK pools, autoclickers and alt-armies earn nothing. (6) DETERMINISTIC SERVER-SEEDED SETS — contract sets are generated by the konto-service from hash(uuid+dayEpoch+secret); the client never proposes objectives or rewards, so there is nothing to spoof. (7) REROLL SINK — escalating Żeton reroll costs (50/100/200) prevent reroll-spam farming. (8) RATE-LIMITED CLAIMS — claim/reroll go through the single authoritative writer with a row lock; no read-modify-write race across backends. (9) CONSERVATION AUDIT — a nightly job reconciles SUM(quest_ledger) per day against expected ceilings and flags anomalies (the live money-conservation tripwire pattern). (10) NEWBIE/ALT FRICTION — accounts below playtime/vocation thresholds get lower caps; first-day accounts cannot claim the weekly. Net: the system is mathematically incapable of being the faucet that re-enables a 44.8B event.

Sync sieci

Network-wide sync uses the existing v5 plumbing (shared MySQL + NATS), with a single authoritative writer to avoid the multi-server race conditions that enabled past abuse. Architecture: a lightweight "konto-service" (can live on the proxy/Travertine side or as a standalone JVM) owns the rollover cron (one place, Europe/Warsaw 04:00) and is the ONLY component that generates/expires contract sets — backends never generate, they only report progress. Data model (MySQL, InnoDB, utf8mb4): quest_contracts(uuid, day_epoch, slot, contract_id, target, progress, completed, claimed, PRIMARY KEY(uuid,day_epoch,slot)) ; quest_streak(uuid, current_days, tier, freezes, last_completed_epoch, banked) ; quest_ledger(id, uuid, day_epoch, zetony_awarded, source, ts) — append-only audit for the daily cap + tripwires. Progress flow: backend listener computes a delta → optimistic local counter → idempotent UPSERT `progress = LEAST(target, progress + ?)` (DB-side clamp prevents over-award even under concurrent writes) → on transition to completed, write ledger row in the SAME transaction (atomic award) → publish NATS subject `zlecenia.progress.<uuid>` and `zlecenia.complete.<uuid>` so any other backend the player is on refreshes its cached view and the GUI updates live. Because progress is clamped server-side in SQL and the daily Żeton award is enforced by SUM(quest_ledger.zetony_awarded WHERE day_epoch=today) < max_zetony_per_day inside the awarding transaction, two backends double-firing the same completion cannot double-pay (idempotency key = uuid+day_epoch+slot, UNIQUE). NATS is used for liveness/UX only; MySQL is the source of truth, so a NATS hiccup degrades to "GUI updates on next open" not "lost or duplicated rewards". Reroll and claim actions route through the konto-service via a NATS request/reply (or direct DB transaction with row lock) so only one node mutates the set. Threading: Canvas/Folia overworld — all Bukkit reads/writes happen on the region thread via EntityScheduler/GlobalRegionScheduler; ALL DB and NATS I/O is dispatched to an async executor (never block a region/tick thread). Each event listener captures only primitive deltas, hands off to async, and any resulting player-facing feedback (toast/sound) is scheduled back onto the player's EntityScheduler.

Budowa

Custom plugin, NOT a marketplace quest plugin — rationale: (a) the reward currency MUST be the bespoke non-tradeable Żetony and integrate with the existing Voyager economy + Kody patterns; (b) it must be the single-authoritative-writer over the existing NATS + shared MySQL v5 plumbing (off-the-shelf plugins assume single-server or their own backend); (c) it must be Folia/Canvas-correct (EntityScheduler, async I/O) which most quest plugins are not; (d) avoiding a Donut*-branded/any generic plugin is itself the anti-clone stance. Reuse where cheap: model the objective-pool YAML and GUI conventions on BattlePass/Tasks-Quests (Folia-safe 4.9.3+) as a reference, and reuse the network's existing NATS client, MySQL pool, presence signal (Strażnik Obecności), and AuraSkills/UniverseJobs job-XP API for the vocation tags. Modules: konto-service rollover+generation (1), backend event-listener+progress module (Folia-aware) (2), MySQL DAO with idempotent clamped UPSERT + ledger (3), NATS pub/sub adapter (4), /zlecenia GUI + Cechmistrz NPC (5), Żeton award + cap enforcement (6), streak engine + Tarcza (7). Stack: JDK21, Paper 26.1.2 backends, Canvas/Folia overworld region-thread discipline, Travertine proxy for broadcasts. Build/test with the COPYFILE_DISABLE=1 tar rule for deploys.

codzienne-zlecenia.yml (sketch):

settings:
  rollover_time: "04:00"            # Europe/Warsaw, single authoritative cron on konto-service
  timezone: "Europe/Warsaw"
  daily_count: 3
  weekly_enabled: true
  weekly_reset_day: MONDAY
  claim_mode: AUTO                  # AUTO | MANUAL (manual = must press claim in /zlecenia)
  free_rerolls_per_day: 1
  reroll_costs: [50, 100, 200]      # escalating Żeton cost after free one; index = nth paid reroll
  reroll_cost_currency: "ZETONY"

caps:                               # DEFENSIVE — hard ceilings, see antiAbuse
  max_zetony_per_day: 150
  max_zetony_per_week: 300          # from weekly track only, separate bucket
  max_job_xp_per_day: 5000
  per_contract_progress_rate_limit: 64   # max progress delta accepted per single event flush
  reject_progress_if_delta_gt: 256       # tripwire: drop+log impossible jumps

streak:
  freeze_item: "TARCZA_SERII"
  max_stored_freezes: 3
  soft_decay_tiers_on_miss: 1       # never reset to 0
  tiers: { 1: ISKRA, 3: PLOMIEN, 7: OGNISKO, 14: POZAR, 30: WIECZNY_OGIEN }
  milestone_rewards:
    3:   { zetony: 20 }
    7:   { zetony: 50, freezes: 1 }
    14:  { cosmetic: "trail_iskry" }
    30:  { cosmetic: "tag_wytrwaly" }
    100: { cosmetic: "aura_wieczny_ogien" }

pools:
  daily:
    - id: drwal_drewno
      vocation: DRWAL
      difficulty: EASY               # EASY|MEDIUM|HARD -> reward tier
      weight: 10
      objective: { type: BLOCK_BREAK, match: "#minecraft:logs", amount_range: [48, 96] }
      reward: { zetony: 15, job_xp: 200 }
      name: "Leśny Urobek"
      desc: "Wyrąb {amount} drewna"
    - id: gornik_deepslate
      vocation: GORNIK
      difficulty: MEDIUM
      weight: 10
      objective: { type: BLOCK_BREAK, match: "minecraft:deepslate", amount_range: [128, 256] }
      reward: { zetony: 30, job_xp: 400 }
      name: "Głębinowy Fach"
      desc: "Wykop {amount} bloków deepslate"
    - id: rybak_polow
      vocation: RYBAK
      difficulty: EASY
      weight: 8
      objective: { type: FISH_CATCH, amount_range: [10, 20] }
      reward: { zetony: 15, job_xp: 200 }
      name: "Połów Dnia"
      desc: "Złów {amount} ryb"
    - id: lowca_zombie
      vocation: LOWCA
      difficulty: MEDIUM
      weight: 8
      objective: { type: ENTITY_KILL, match: "minecraft:zombie", time_window: NIGHT, amount_range: [20, 40] }
      reward: { zetony: 30, job_xp: 400 }
      name: "Nocne Polowanie"
      desc: "Pokonaj {amount} zombie po zmroku"
    - id: pve_miniboss
      difficulty: HARD
      weight: 4
      requires_feature: MYTHICMOBS
      objective: { type: MYTHIC_KILL, match: "StrachPustkowi", amount_range: [1, 1] }
      reward: { zetony: 60 }
      name: "Pogromca"
      desc: "Pokonaj mini-bossa: Strach Pustkowi"
    - id: social_klan
      difficulty: MEDIUM
      weight: 3
      requires_feature: CECH
      objective: { type: CONTRACT_WITH_CLANMATE, amount_range: [1, 1] }
      reward: { zetony: 35 }
      name: "Towarzysz"
      desc: "Ukończ zlecenie wspólnie z członkiem klanu"
  weekly:
    - id: weekly_gornik_glebia
      difficulty: HARD
      weight: 5
      objective: { type: BLOCK_BREAK, match: "#minecraft:base_stone_overworld", amount_range: [3000, 5000] }
      reward: { zetony: 250, freezes: 1, season_shard: 1 }
      name: "Wielkie Wydobycie"
      desc: "Wykop {amount} bloków kamienia w tym tygodniu"

scaling:
  vocation_level_bias: true          # bias pool + amount_range upward by player's top vocation lvl
  newbie_grace_below_level: 10       # never serve HARD to sub-10 accounts

gui:
  rows: 6
  title: "&6Tablica Zleceń &7(&e04:00&7)"
  layout: { daily_slots: [11,13,15], weekly_slot: [31], reroll_slot: [48], claim_slot: [50], streak_slot: [4] }

all_clear_bonus: { zetony: 25 }

Wydłużyć sesję i podnieść retencję D1/D7/D30 przez nadanie graczowi długoterminowego "horyzontu" (kilkutygodniowa fabuła z cliffhangerami), który wymusza powroty i przeprowadza go przez WSZYSTKIE serwery sieci — czyniąc opuszczenie pojedynczego serwera równoznacznym z porzuceniem całego konta. Jednocześnie zbudować najgłębszą fosę anty-klon wobec DonutSMP: klon nie ma NPC, fabuły, lochów ani lore, a "treść (nie kod) jest tym, czego konkurent nie skopiuje". KPI sukcesu: +20% mediany długości sesji u graczy z aktywnym questem, D7 retencja graczy którzy ukończyli Prolog ≥2x bazowej, ≥40% MAU z ≥1 aktywnym łańcuchem.

Pętla

PĘTLA SESYJNA (cel: wydłużyć "jeszcze jedno zadanie"): 1. Wejście → /kroniki lub auto-prompt pokazuje aktywne zadanie + [Wskaż drogę]. 2. Realizacja kroku (typy: BREAK_BLOCK, KILL_MOB/BOSS, REACH_REGION, TALK_NPC, DELIVER_ITEM, JOB_LEVEL [integracja z profesjami], DUNGEON_CLEAR, PVP_ARENA, VISIT_ISLAND, COLLECT_FISH). Postęp liczony WYŁĄCZNIE z eventów, które gracz i tak generuje — zero skanowania świata (Folia-safe). 3. Krok ukończony → natychmiastowy feedback + auto-przejście do następnego kroku tego samego rozdziału (bez pauzy — to utrzymuje flow). 4. Rozdział ukończony → nagroda account-bound + CLIFFHANGER w dialogu NPC ("...ale Smok jeszcze śpi. Wróć, gdy księżyc będzie w pełni — za 18 godzin") → świadoma zachęta do powrotu. 5. Pewne kroki mają COOLDOWN/GATE czasowy lub wymagają innego serwera → naturalnie rozkłada kampanię na tygodnie i rozprowadza graczy po sieci. PĘTLA TYGODNIOWA: nowy rozdział lub "Zlecenie Kronikarza" (cotygodniowy quest poboczny powiązany z eventami live-ops) odblokowuje się co tydzień — appointment play w polski prime-time. Akt finałowy domyka się eventem sieciowym world-bossa (Smok Wawelski) nad NATS. DLACZEGO TO RETENCYJNE: stały, rosnący "horyzont" (niedokończona fabuła to otwarta pętla psychologiczna), bramki czasowe wymuszające powroty (D1/D7), rozgałęzienia dające powód do drugiego przejścia (D30+/nowy sezon), oraz przymus zwiedzenia całej sieci (podnosi concurrency wielu serwerów naraz).

Doświadczenie gracza

PIERWSZE 90 SEKUND (onboarding): po pierwszym wejściu na hub gracz dostaje na ekranie title "Kroniki Pustkowi" i hologram nad NPC "Stary Kronikarz Borzywoj" tuż przy spawnie. Klik PPM na NPC otwiera okno dialogowe (Adventure chat z klikalnymi [Tak, słucham] / [Później]) — to jest jednocześnie tutorial wayfindingu: Borzywoj tłumaczy serwery przez fabułę ("Pustkowia rozdarły się na krainy — Osada na overworldzie, Krwawe Wzgórza gdzie leje się krew, Podziemia, Archipelag..."). Prolog (rozdział 0) to 4 mikro-zadania uczące sterowania: złam 10 bloków → zabij 3 moby → sprzedaj coś na /bazar → wejdź portalem na drugi serwer. Każdy krok kończy się soczystym feedbackiem (dźwięk, partykle, pasek postępu w bossbarze). PRZEPŁYW DŁUGOTERMINOWY: kampania to AKT (np. "Akt I: Przebudzenie Smoka"), akt dzieli się na ROZDZIAŁY (rozdział = 1 serwer-temat, 3-6 zadań), rozdziały bywają ROZGAŁĘZIONE — w pewnym węźle gracz wybiera frakcję ("Stań po stronie Strażników Świtu albo Dzieci Mroku"), co odblokowuje inny wariant kolejnego rozdziału, inny tytuł i inny finałowy kosmetyk. Wybory są trwałe (zapisane w MySQL), więc gracze porównują ścieżki — napędza to dyskusje na Discordzie i ponowne przejścia na drugą stronę w nowym sezonie. GUI: /kroniki otwiera "Księgę" (inventory GUI, Bedrock/Geyser-friendly — duże ikony, brak hover-only tekstu): lewa strona = mapa aktów (zamknięte rozdziały zaszarzone), prawa = aktywne zadanie z opisem fabularnym, licznikiem postępu i przyciskiem [Wskaż drogę] (odpala compass/partykuły do następnego NPC lub portalu). Bossbar pokazuje postęp bieżącego kroku gdy gracz go realizuje. Po ukończeniu rozdziału — pełnoekranowy title + wpis do "Kroniki" (permanentna ściana sław przy spawnie z datowanymi tytułami: "Borzywoj, Pogromca Utopców, Sezon I"). PUNKTY STYKU MIĘDZYSERWEROWE: gdy quest każe iść na inny serwer, kliknięcie [Wskaż drogę] kieruje do portalu; po przejściu przez proxy postęp jest już zsynchronizowany (gracz NIE musi nic klikać ponownie) — NATS dostarczył stan zanim zdążył dojść do NPC. To "magiczny moment": fabuła płynnie przechodzi między światami, czego klon z jednym serwerem nie zrobi.

Nagrody

FILOZOFIA: status zdobyty, nie kupiony — odwrotność DonutSMP. ŻADNA nagroda nie jest zbywalną walutą Money (twarda kwarantanna duperów). WALUTY/TYPY NAGRÓD: 1. Żetony Kronikarza — tagowana, NIEZBYWALNA waluta-punkty (tabela ledger, append-only). Wydawane wyłącznie w "Sklepie Kronikarza" na kosmetyki/QoL, nigdy wymienialne na Money. Duped Money nie kupi niczego prestiżowego. 2. Kosmetyki: smugi/aury, kapelusze, tytuły w tabie, wpisy w "Szafie Sezonowej". Finał rozdziału/aktu → ekskluzywny, "never-again" kosmetyk (FOMO + status lojalności). 3. Tytuły fabularne: "Pogromca Utopców", "Wybraniec Świtu" — widoczne nad głową/w tabie, datowane sezonem w Kronice. 4. QoL account-bound: dodatkowy /home, kosmetyczny pet-towarzysz, dostęp do strefy (klucz fabularny), NIGDY raw power/spawnery/eq do PvP. 5. Mikro-utility (świadomie "super minor", w duchu profesji): np. +1 do limitu działek, drobny kosmetyczny efekt narzędzia — bez wpływu na ekonomię/PvP balance. KRZYWA NAGRÓD (przykład Akt I, Żetony Kronikarza): - Prolog: 50 Ż + tytuł "Wędrowiec" (każdy ma poczuć progres natychmiast). - Rozdz 1-3: 75 / 100 / 150 Ż + drobny kosmetyk co rozdział. - Rozdz 4-5 (PvP/lochy, trudniejsze): 250 / 350 Ż + smuga. - Rozdz 6 / finał aktu (world-boss): 500 Ż + EKSKLUZYWNY tytuł + aura "Pogromca Smoka" (sezonowa, nigdy nie wraca). Suma sezonu ~1500 Ż — Sklep Kronikarza wyceniony tak, że ukończenie 1 aktu kupuje ~2-3 znaczące kosmetyki (poczucie wyboru, nie wszystko za darmo). SINK: Żetony to sink same w sobie (znikają przy zakupie — brak inflacji, bo nie krążą między graczami). Dodatkowo część finałowych kosmetyków wymaga "spalenia" Żetonów + rzadkiego dropu fabularnego z bossa (łączy z gospodarką deflacyjną). ANTY-P2W: premium track sezonowej Przepustki (jeśli sprzężony) daje tylko KOSMETYCZNE warianty tych samych nagród + ewentualnie "wskazówki"/skip-cooldown za drobną opłatę — nigdy fabuła ani power za płatność. Żetonów NIE da się kupić.

Anty-abuse

PROJEKT DEFENSYWNY (pamięć o dupie 44.8 mld): 1. ROZDZIAŁ NAGRÓD OD WALUTY: questy NIGDY nie wypłacają zbywalnej Money. Wyłącznie Żetony Kronikarza — tagowane, NIEZBYWALNE, wydawalne tylko w Sklepie Kronikarza na kosmetyki/QoL. Nawet gdyby ktoś zdupował postęp questa, nie zamieni go na gospodarkę. To strukturalna kwarantanna. 2. IDEMPOTENCJA NAGRÓD (token_grants UNIQUE): każda wypłata za grant_key="campaign:chapter:complete" w transakcji z INSERT do token_grants. Powtórka → 1062 → pomiń. Niemożliwe podwójne przyznanie tej samej nagrody (re-log, race między serwerami, replay NATS, restart w trakcie). 3. POSTĘP TYLKO Z REALNYCH EVENTÓW GRACZA: liczniki rosną wyłącznie z BlockBreak/EntityDeath/itp. które gracz faktycznie generuje — zero skanowania świata, zero trust-the-client. Anti-farm: integracja ze "Strażnikiem Obecności" (sygnał realnej obecności) — kroki BREAK/KILL ignorowane gdy gracz oznaczony jako AFK/autoclicker. Bloki położone-i-zbite nie liczą się (flaga placed-by-player jak w anti-cheat), by nie dało się farmić DELIVER/BREAK z pętli. 4. TWARDE LIMITY (config caps): - max_tokens_per_day (np. 800) — dzienny sufit przyznanych Żetonów per gracz; nadwyżka odrzucana + log. - max_chapter_completes_per_day — limit ukończeń rozdziałów/dobę (blokuje masowe przemiały alt-farm). - task_progress_rate_limit_per_min — sufit inkrementów/min (łapie autoclicker/dupe-spam eventów). - cooldown/gate_hours egzekwowany server-side z MySQL timestamp (nie z zegara klienta). 5. WALIDACJA WĘZŁÓW: bramki (job_level, chapter_done, server) sprawdzane autorytatywnie po stronie serwera z DB w momencie próby ukończenia — nie z lokalnego cache klienta. Wybór frakcji ostateczny (UPDATE ... WHERE branch_id IS NULL, jak setReferrerIfAbsent w Kody) — brak przełączania tam i z powrotem dla podwójnych nagród obu ścieżek. 6. TRIPWIRE / OBSERWOWALNOŚĆ: token_ledger jest append-only → łatwy audyt. Alert (Grafana/Loki) gdy: gracz przekracza X% dziennego capa, gdy SUM(delta) per gracz rośnie szybciej niż teoretyczne max sezonu, gdy ten sam grant_key próbowany >N razy (sygnał exploitu/replay). "Conservation check": suma przyznanych Żetonów sieciowo nie może przekroczyć (liczba_graczy × teoretyczny_max_sezonu) — dzienny job porównawczy. 7. ANTY-ALT: nagrody account-bound + powiązanie z Kody/kontem; podejrzane klastry altów (ta sama IP/zachowanie kończące identyczne kroki w sekundach) flagowane do ręcznej rewizji, nie auto-ban. Prolog daje mało Żetonów (50) by alt-farm Prologu był nieopłacalny. 8. SANITYZACJA INPUTU: wszystkie wartości z YAML i NATS walidowane (Zod-podobnie / ręcznie) przy ładowaniu; nieznany typ kroku/material → quest dezaktywowany z logiem, nie crash. Treść NATS traktowana jako niezaufana (podpis/whitelist subjectów, ignorowanie pól spoza schematu).

Sync sieci

MODEL: MySQL = jedyne źródło prawdy (authoritative), NATS = warstwa powiadomień/cache-invalidation (nigdy źródło prawdy). Wzorzec event-sourced, idempotentny — tak jak milestones_awarded w Kody (INSERT z unique key = brak podwójnych nagród). SCHEMAT MySQL (DB v5_kroniki, utf8mb4): - player_campaign (uuid, campaign_id, current_chapter, branch_id, status, updated_at; PK uuid+campaign_id) — bieżący stan. - task_progress (uuid, campaign_id, task_id, progress INT, goal INT, done TINYINT, updated_at; PK uuid+campaign_id+task_id) — liczniki kroków. - chapter_completions (uuid, campaign_id, chapter_id, completed_at; PK uuid+campaign_id+chapter_id) — IDEMPOTENTNY zapis ukończeń (jak milestones_awarded). - token_ledger (id BIGINT AUTO, uuid, delta INT, reason VARCHAR, source_server, ts; INDEX uuid) — APPEND-ONLY księga Żetonów; saldo = SUM(delta) lub zmaterializowane w player_tokens z wierszem-strażnikiem. - token_grants (uuid, grant_key VARCHAR UNIQUE-per-uuid, ts; PK uuid+grant_key) — DEDUPLIKACJA nagród: grant_key = "akt1:r1_cien:complete". Przyznanie Żetonów = INSERT do token_grants W TEJ SAMEJ TRANSAKCJI co wpis do ledger; duplikat (errno 1062) → nagroda już wydana, pomiń. To kluczowa bariera anty-dup. SYNC PRZEZ NATS: - Subject v5.kroniki.progress.<uuid> — publikowany po każdej zmianie stanu; inne backendy invalidują lokalny cache gracza. - Subject v5.kroniki.handoff.<uuid> — proxy/serwer źródłowy publikuje TUŻ przed przejściem gracza portalem ("idę na osada, current_chapter=r1_cien"); serwer docelowy pre-fetchuje stan z MySQL ZANIM gracz dojdzie do NPC → "magiczny moment" płynnej fabuły. - Subject v5.kroniki.boss.<campaign> — event finałowego world-bossa: jeden trigger operatora fan-out do wszystkich backendów (wspólny bossbar HP, nagrody wg progu kontrybucji). - WAŻNE: NATS dostarcza "podpowiedź odśwież się", ale autorytatywny odczyt zawsze z MySQL. Utrata wiadomości NATS = co najwyżej krótkie opóźnienie cache, nigdy utrata/podwojenie postępu (bo prawda w DB + idempotencja grantów). SPÓJNOŚĆ PRZY RÓWNOLEGŁOŚCI (gracz na 2 serwerach alt-ami / race): wszystkie inkrementy task_progress przez atomowy UPDATE ... SET progress=LEAST(goal, progress+?) WHERE ... (server-side, nie read-modify-write w pluginie). Ukończenie kroku i nagroda zawsze za bramką token_grants UNIQUE. Logout-login flush: stan zapisywany na bieżąco (per event, debounce'owany), nie tylko przy quit — przeżywa crash serwera.

Budowa

CUSTOM PLUGIN "Kroniki" — fork sprawdzonego wzorca Kody (NIE kupować Donut*-brandowanego questa = to byłoby bycie klonem; gotowe BattlePass/Tasks-Quests z Polymart NIE robią rozgałęzionej fabuły NPC ani sieciowego sync przez NATS+MySQL, więc rdzeń i tak trzeba pisać). STOS (jak Kody): JDK21, Paper API provided scope, maven-shade-plugin z relokacją sterownika MariaDB (mówi protokołem MySQL) do pl.minecraft.kroniki.libs.mariadb. Połączenia per-operacja, wszystkie wyłącznie na AsyncScheduler. Klient NATS (jnats) również shaded+relocated. OGRANICZENIA WĄTKOWE (Folia/Canvas overworld jest wielowątkowy, regionised ticking): - Kontekst encji/bloku (odczyt z eventu) zbierany NA WĄTKU REGIONU (listenery BlockBreak/EntityDeath odpalają się na właściwym wątku regionu). - MySQL → ZAWSZE AsyncScheduler (nigdy na wątku regionu — blokujące IO). - Akcje na graczu/encji po async (spawn partykuł, give kosmetyk, teleport) → wracać przez Entity.getScheduler() (EntityScheduler) dla tego gracza, NIE Bukkit.getScheduler (ten nie istnieje na Folii w starym sensie). - Komendy konsolowe nagród (np. perm/give) → GlobalRegionScheduler (jak milestoneCmds w Kody). - Czat/Adventure (dialogi, bossbar, title) → bezpieczne z dowolnego wątku. - Liczniki postępu: inkrement w pamięci na wątku regionu z eventu, ale ŹRÓDŁO PRAWDY to atomowy UPDATE w MySQL przez async (debounce, np. flush co N zmian lub co 5s) — by nie zgubić postępu przy crashu i nie hamować ticka. - Backendy nie-Folia (Paper 26.1.2: lochy, wyspy, PvP) używają tych samych API (Folia API jest nadzbiorem zgodnym na Paperze) — jedna baza kodu działa wszędzie. NPC: zalecane Citizens (jeśli Folia-zgodny w wersji docelowej) albo lekki własny hologram+interakcja przez PacketEvents/ProtocolLib (klik = wywołanie eventu interakcji). Dialog GUI: natywne Inventory GUI (Bedrock/Geyser-friendly), bez bibliotek hover-only. KAMPANIE: data-driven YAML (jak wyżej), ładowane i walidowane przy starcie i /kroniki reload — projektant fabuły pisze treść bez kompilacji. Silnik kroków = mapa typ→handler (BREAK_BLOCK, KILL_MOB, REACH_SERVER...), łatwo rozszerzalny. INTEGRACJE: hooki do systemu profesji (job_level gate), Kody (konto/anty-alt), bazaru (flagi sprzedaży przez NATS), Strażnika Obecności (anti-AFK), Zgłoszeń (raport buga w queście). Sklep Kronikarza wydaje permy przez LuckPerms API — UWAGA: zgodnie z regułą zespołu NIE modyfikować LuckPerms bezpośrednio, używać wyłącznie publicznego API do nadania węzła, nigdy ręcznych zmian w wspólnej konfiguracji. WALIDACJA PRZED WDROŻENIEM: build JDK21, test na pojedynczym backendzie (hub) → dwa backendy (sync NATS) → pełny rollout. Polski tekst przez polish-content-validator. Deploy wzorcem deploy_kody.py.

Definicje kampanii w plikach YAML (data-driven, hot-reloadowalne przez /kroniki reload — wzorzec greload/Kody). Postęp gracza WYŁĄCZNIE w MySQL. Przykład:

# campaigns/akt1_przebudzenie.yml
campaign:
  id: akt1_przebudzenie
  display: "&6Akt I: Przebudzenie Smoka"
  season: 1
  active: true                  # archiwizacja: false po sezonie (przechodni, bez sezon. kosmetyków)
  start_chapter: prolog

chapters:
  prolog:
    display: "&eProlog: Wędrowiec"
    server: hub                 # krok wykonalny na tym backendzie; null = dowolny
    npc_start: borzywoj
    tasks:
      - id: p_break
        type: BREAK_BLOCK
        material: ANY_LOG
        amount: 10
        bossbar: "Wyrąb 10 kłód  &7({progress}/{goal})"
      - id: p_kill
        type: KILL_MOB
        mob: ZOMBIE
        amount: 3
      - id: p_sell
        type: COMMAND_FLAG       # ustawiany przez inny plugin po sprzedaży na /bazar (event NATS)
        flag: bazar.first_sale
      - id: p_portal
        type: REACH_SERVER
        target: osada
    on_complete:
      tokens: 50
      title: "Wedrowiec"
      next: r1_cien
      cliffhanger: false

  r1_cien:
    display: "&eRozdzial I: Cien nad Osada"
    server: osada
    npc_start: swietomir
    requires: { chapter_done: prolog }
    tasks:
      - { id: r1_logs, type: DELIVER_ITEM, item: OAK_LOG, amount: 32, to_npc: swietomir }
      - { id: r1_kill, type: KILL_MOB, mob: PILLAGER, amount: 15 }
    on_complete:
      tokens: 150
      cosmetic: smuga_switu
      cliffhanger: "&7Smok jeszcze spi... wroc za &e18 godzin&7."
      gate_hours: 18                 # bramka czasowa
      next: r2_rozdroze

  r2_rozdroze:
    display: "&eRozdzial II: Rozdroze"
    server: krwawe_wzgorza
    requires: { chapter_done: r1_cien, job_level: { gornik: 15 } }   # bramka systemowa
    decision:                         # WEZEL ROZGALEZIENIA
      prompt: "Komu zaufasz?"
      branches:
        swit:  { display: "Straznicy Switu", title: "Wybraniec Switu", next: r3a_swit }
        mrok:  { display: "Dzieci Mroku",   title: "Sluga Mroku",     next: r3b_mrok }

rewards_shop:                         # Sklep Kronikarza — sink Zetonow
  smuga_switu_premium: { cost_tokens: 300, type: COSMETIC, bound: true }
  extra_home:          { cost_tokens: 500, type: PERM, node: "essentials.sethome.multiple.+1" }

caps:                                 # ANTY-ABUSE (patrz anti-abuse)
  max_tokens_per_day: 800
  max_chapter_completes_per_day: 6
  task_progress_rate_limit_per_min: 120

# config.yml (połączenia — wzorzec Kody)
database: { host: "...", port: 3306, name: v5_kroniki, user: "...", pass: "..." }
nats:     { url: "nats://...", subject_prefix: "v5.kroniki" }
server_id: osada                      # tożsamość backendu (z env/proxy)

Lengthen sessions and lift D1/D7/D30 retention by giving every player a persistent, network-wide "I'm THE górnik" mastery identity that survives logouts and server-hops, while breaking the DonutSMP-clone identity. Rewards are time-invested status (titles, badges, access, cosmetics) and an account-bound currency — never tradeable money — turning the 44.8B dupe scar into a trust differentiator.

Pętla

Do an action you already enjoy → server validates it on the owning region thread → award vocation XP + a small non-tradeable Żeton (capped/hr+/day) → XP ticks the boss-bar → cross a threshold = level up → level grants a perk (ability / recipe / zone access / tiny % boost) + maybe a Polish rank title → the perk makes the same action slightly more rewarding, gently accelerating the next loop → at L100, Odrodzenie rebirth resets level for permanent unbuyable prestige, restarting the climb. Per-hour Żeton cap creates a "cap out before logging" session-extender; the multi-week level curve is the long-horizon return reason. Vocation-tagged daily quests and clan-treasury cuts wire this loop into the daily and social loops; skill-gated zones pull players across servers.

Doświadczenie gracza

First session: spawn NPC "Cechmistrz Borut" opens a clean "Wybierz swój fach" GUI (Bedrock/Geyser get a forms fallback — no chat-only flows). Hold up to 2 active vocations (3 with premium pass), swap once/24h so it's a real identity choice. Eight launch vocations: Górnik, Drwal, Rybak, Farmer, Łowca, Kowal (craft/smithing/anvil), Handlarz (villager trades + Bazar sales), Alchemik (brew/enchant). Moment-to-moment: each relevant action pops a throttled actionbar "+Górnik 12 XP" (batched ~1/s, never per-block) and ticks a boss-bar; a level fires a localized title "Awans! Górnik — poziom 23" + sound and silently grants the next perk. No spam. Identity payoff: Polish rank titles, a colored tab/nametag badge, a lobby "Tablica Mistrzów" hologram showing the network's top player per vocation updated live over NATS, and at cap an Odrodzenie rebirth for a permanent star + tool-skin. Perks are deliberately underwhelming alone but compound into felt expertise and unlock ACCESS (skill-gated zones) which is the real pull. /zawody opens the hub (vocations, levels, XP-to-next, perks, daily Żetony vs cap, prestige tab); /zawody top <fach> shows leaderboards; all readable on Bedrock.

Nagrody

Three non-money channels, dupe-contained. (1) XP→Levels→Perks: super-minor, hard-capped — double-drop chance +0.25%/level capped +15% (and capped by an hourly economic-value ceiling), Bazar sell bonus capped +5% on that vocation's player-market goods only (never NPC sinks), short on-cooldown active abilities (only 3 equippable slots), plus recipes and skill-gated ZONE ACCESS where the real motivation lives. (2) Żetony Fachu: account-bound currency, tiny per-action rate, hard-capped/hr+/day, spent only on cosmetics/convenience (tool skins, trails, titles) — never power. (3) Prestige/status: Odrodzenie rebirth gives a permanent star, tool-skin token, one micro-passive (+1%/prestige, capped +5%, still under the global hourly cap) and a dated Tablica Mistrzów entry; top-N per vocation earn an elite seasonal trail money cannot buy. Curve front-loads early levels for the D1 dopamine, then stretches to months for the D30 horizon.

Anty-abuse

Designed defensively because of the prior 44.8B dupe. Vocations must NEVER be a money faucet or a dupe laundromat. 1) NO TRADEABLE MINTING. Vocations never create Money in the Voyager economy DB. The only currency they mint is Żetony Fachu — account-bound, non-tradeable, non-droppable, stored in a separate table. A duped Money balance cannot buy a single vocation title; vocation prestige is structurally outside the exploitable economy. This is the core containment. 2) SERVER-SIDE EVENT VALIDATION ONLY. XP is granted strictly from authoritative server events (BlockBreakEvent with getDrops, PlayerFishEvent CAUGHT state, EntityDeathEvent with valid killer, CraftItemEvent, BrewEvent) on the owning region thread. Never from client packets, never from periodic world scans (also Folia-illegal). Player-placed-then-broken blocks are tagged (PDC / placed-block set) and grant ZERO XP/Żetony — kills the place-and-break cobble/sapling exploit. 3) HARD CAPS, ENFORCED IN SQL: Żetony per-hour (400) and per-day (2500); bonus-drop economic value per hour (1500 base units) so even a maxed +15% double-drop cannot flood goods; XP-per-hour soft cap (beyond 12k/hr XP gain halves) to blunt macro/autoclicker farms. Caps are checked with conditional UPDATEs in MySQL so concurrent multi-server crediting cannot exceed them. 4) DIMINISHING RETURNS on identical actions (decay to 0.25x after 8 identical actions/min) — defeats AFK water-aqueduct fishing macros, sugarcane/bamboo towers, and 1-block cobble loops without banning them. 5) PRESENCE GATE. Hook the network "Strażnik Obecności" anti-AFK signal: no genuine-presence signal → XP and Żeton accrual paused. AFK pools, alt armies, and autoclickers earn nothing. 6) APPEND-ONLY LEDGER + TRIPWIRES. Every award is a row in zawody_ledger (idempotency_key UNIQUE). A scheduled conservation check sums minted Żetony vs accrual rules per window; any account exceeding mathematically-possible earnings (the next-dupe signature) is flagged to staff in minutes (Grafana/Loki alert) and its accrual auto-frozen pending review. Because XP/Żetony are append-only and capped, a future exploit is contained to one season's vocation cosmetics, never the real economy. 7) IDEMPOTENCY ON SYNC. Duplicate NATS deliveries or server-hop races cannot double-credit (UNIQUE idempotency_key). Rollbacks are possible by replaying/reverting ledger rows. 8) PERK CEILINGS. Sell bonus applies ONLY to player-market (Bazar) sales of that vocation's own goods, capped +5%, never to infinite NPC sinks — so it cannot be combined with an NPC sell-wand to print money.

Sync sieci

NETWORK-WIDE SYNC over the existing v5 plumbing (NATS + shared MySQL), one authoritative account: DATA MODEL (shared MySQL, the source of truth — never trust the client): - zawody_player (uuid PK, last_seen) — one row per player. - zawody_vocation (uuid, vocation, xp BIGINT, level INT, prestige INT, active BOOL, slot_abilities JSON, PRIMARY KEY(uuid,vocation)). - zawody_ledger (id BIGINT PK AUTO, uuid, vocation, delta_xp INT, delta_zetony INT, source ENUM, server_id, region_thread_id, ts, idempotency_key UNIQUE) — append-only, the anti-dupe spine and audit trail. - zawody_zetony (uuid PK, balance BIGINT, earned_today INT, earned_hour INT, window_reset_ts) — account-bound currency, not in the Voyager economy DB at all. - zawody_leaderboard_cache (vocation, uuid, level, prestige, rank) — refreshed periodically for holograms. WRITE PATH: XP/Żeton awards are computed on the OWNING server's region thread (Folia/Canvas) but the DB write is dispatched to an async executor (never block the region thread on JDBC). Each award is an idempotent UPSERT keyed by idempotency_key (uuid+source+monotonic action seq) so a retry/duplicate NATS delivery can never double-credit. The DB enforces caps with a conditional UPDATE (e.g. only add Żetony if earned_hour+delta <= cap) — the cap is enforced in SQL, not just in memory, so two servers crediting concurrently cannot both pass the ceiling (last-writer reads authoritative remainder). SYNC PATH (NATS): on level-up / prestige / rank change / leaderboard delta, the owning server publishes a compact event to subjects like zawody.level.<uuid>, zawody.prestige.<uuid>, zawody.lb.<vocation>. Other backends subscribe and update their in-memory cache + holograms + tab badges in real time. When a player switches servers (proxy = Travertine), the target server does an authoritative DB read on join (not a NATS-state trust) and hydrates the session; NATS is for live cross-server REACTIONS (leaderboard overtakes, "Wielki Mistrz X just prestiged" broadcasts), MySQL is for STATE. This split means a missed NATS message degrades gracefully (cache is slightly stale, corrected on next read) and never corrupts the account. CONCURRENCY: a player is realistically on one backend at a time; alts/duplicate sessions are resolved by the proxy. The ledger's UNIQUE idempotency_key plus SQL-side cap checks make even a race (e.g. fast server-hop) safe. Writes are batched (flush every ~2s or N events) to keep MySQL load sane at concurrency.

Budowa

Buy a Folia-NATIVE skills engine as the per-server XP/level/perk substrate (AuraSkills or UniverseJobs — NOT Jobs Reborn, which is not Folia-safe and breaks on the Canvas regionised overworld) and author all 8 Polish vocation definitions, XP tables, ranks, abilities and the super-minor boost tuning yourself in config. Write a CUSTOM companion plugin "Zawody-Sync" (JDK21, Paper 26.1.2, Folia/Canvas-aware) for the parts no off-the-shelf plugin provides: one MySQL-authoritative account, NATS live cross-server level/prestige/leaderboard events, a separate account-bound Żetony wallet quarantined from the Voyager economy, and an append-only ledger with SQL-enforced caps + conservation tripwires. Threading: handle gameplay events on the owning region thread, do all JDBC + NATS on async/global schedulers (HikariCP), never block the region thread; use Folia Region/EntityScheduler for any follow-up world/entity touch; no world-scanning. Reuse PlaceholderAPI (tab/nametag badges), DecentHolograms-Folia (Tablica Mistrzów), Geyser forms fallback for Bedrock GUIs. Phase v1 (4 vocations + MySQL persistence + caps + Żetony) → v2 (NATS sync + holograms + remaining vocations + abilities) → v3 (Odrodzenie prestige + skill-gated zones + clan hook + tripwires).

zawody.yml (Folia-safe, all tunables hot-reloadable via greload-equivalent; no values hardcoded):

settings:
  max-active-vocations: 2          # premium pass = 3
  swap-cooldown-hours: 24
  bedrock-forms-fallback: true     # Geyser GUI
xp:
  curve: "80 * L^1.45"             # parsed at load; cap level below
  level-cap: 100
  identical-action-window-sec: 60
  identical-action-decay:         # anti-AFK diminishing returns
    after: 8                       # 8 identical actions/min
    multiplier: 0.25
    recover-per-sec: 0.05
caps:                              # ANTI-ABUSE (see guardrails)
  zetony-per-hour: 400             # account-bound currency hard ceiling/hr
  zetony-per-day: 2500
  bonus-drop-value-per-hour: 1500  # max base-unit worth of perk drops/hr
  xp-per-hour-soft: 12000          # beyond this, XP gain *0.5 (afk/macro guard)
perks:
  double-drop-per-level-pct: 0.25
  double-drop-cap-pct: 15.0
  sell-bonus-cap-pct: 5.0          # player-market only, this vocation's goods
  ability-slots: 3
prestige:
  enabled-at-level: 100
  permanent-doubledrop-per-prestige-pct: 1.0
  permanent-doubledrop-cap-pct: 5.0
  reclimb-xp-discount-per-prestige: 0.10   # max 0.5
vocations:
  gornik:
    display: "Górnik"
    ranks: { 1: "Nowicjusz", 10: "Czeladnik", 25: "Towarzysz Fachu", 50: "Mistrz", 75: "Arcymistrz", 100: "Wielki Mistrz Górnictwa" }
    xp-sources:
      block-break:
        STONE: 1
        IRON_ORE: 5
        DEEPSLATE_DIAMOND_ORE: 30
        ANCIENT_DEBRIS: 40
    abilities:
      zyla: { unlock-level: 5, effect: "haste:1", duration-sec: 30, cooldown-sec: 240, display: "Żyła" }
    zone-access: { 15: "kopalnia_gleboka", 50: "stratum_diamentowe" }
  drwal:
    display: "Drwal"
    xp-sources: { block-break: { OAK_LOG: 2, DARK_OAK_LOG: 3, CHERRY_LOG: 3 } }
  rybak:    { display: "Rybak",    xp-sources: { fish-catch: { COD: 3, SALMON: 6, TREASURE: 25 } } }
  farmer:   { display: "Farmer",   xp-sources: { harvest: { WHEAT: 2, CARROTS: 2, MELON: 1 } } }
  lowca:    { display: "Łowca",    xp-sources: { mob-kill: { ZOMBIE: 3, SKELETON: 3, WITHER_SKELETON: 20 } } }
  kowal:    { display: "Kowal",    xp-sources: { craft: { IRON_PICKAXE: 4, NETHERITE_AXE: 40 }, smithing-use: 12 } }
  handlarz: { display: "Handlarz", xp-sources: { villager-trade: 5, bazar-sale: 3 } }
  alchemik: { display: "Alchemik", xp-sources: { brew: { potion: 8 }, enchant: 6 } }
messages:                          # Polish copy WITH diacritics
  choose-prompt: "&eWybierz swój fach u Cechmistrza!"
  level-up: "&6Awans! &e{vocation} &7— poziom &a{level}"
  rank-up: "&6Zostałeś &e{rank}&6!"
  cap-hour: "&7Osiągnąłeś godzinny limit Żetonów Fachu. Wróć później!"
  prestige: "&dOdrodziłeś się! &7{vocation} — Odrodzenie {roman}"
  swap-cooldown: "&cFach możesz zmienić raz na 24h. Pozostało: {time}"

messages.yml lives separately so copywriters edit Polish without touching logic.

Increase session length and D1/D7/D30 retention by giving players a visible, always-progressing "I'm earning toward something right now" layer, while moving identity away from DonutSMP — boosts reward TIME PLAYED and mastery, are cosmetic/utility only (cannot be bought, cannot affect PvP, cannot mint currency), and are uniform across the whole network so leaving any one server means abandoning your whole live stack.

Pętla

PLAY an action (mine/fish/farm/quest) -> the owning job/quest/streak module emits a "grant boost" intent -> WzmocnieniaCore validates it server-side (presence check, source cooldown, daily grant ledger) -> writes one append-only row to MySQL boost_grants and recomputes the player's capped active stack -> publishes the new stack over NATS subject `v5.boost.stack.<uuid>` -> every backend the player could be on applies the SAME effective multipliers -> the boost visibly accelerates the next chunk of grinding (faster job XP, better gather luck, more comfort) -> that faster progress completes the next contract/streak tick -> which grants the next boost. The loop is deliberately short (a boost lasts 15-30 min of ACTIVE play) so there is always a near-term "keep playing to not waste it / keep playing to chain the next one" pull, but capped so it can never snowball.

Doświadczenie gracza

A player opens /wzmocnienia (alias /boosty) and sees a clean GUI of their ACTIVE buffs with live countdowns, plus a passive "Stała Premia" panel showing the tiny permanent perks their job mastery has unlocked. Buffs arrive as small, frequent, celebrated drops: finish a daily contract -> "+15% Doświadczenie Zawodowe na 20 min"; hit a 7-day login streak -> "Tarcza Skupienia: -10% głodu na 30 min"; górnik reaches Mistrz -> permanent "Wprawne Ręce: +5% szansy na podwójny urobek (twardy limit)". Bedrock/Geyser players get the same via a forms-based menu (no hover tooltips). Crucially everything is framed as comfort and speed of the GRIND, never as winning a fight: there is NO damage boost, NO defense boost, NO speed-in-combat, NO extra hearts. A small actionbar pip ("◈ x3 aktywne") follows the player across servers so the stack feels alive and portable. Active boosts pause (do not burn) while the player is offline or flagged AFK, so logging in always feels rewarding rather than punishing missed time.

Nagrody

Boosts are the reward and they are strictly utility/cosmetic. Categories and their HARD aggregate caps (sum across ALL active sources, enforced at apply-time): JOB_XP max +40%; GATHER_LUCK (double-drop/rare-node chance) max +15 percentage points; VANILLA_XP (orb XP) max +30%; COMFORT (hunger/saturation reduction, mild haste WHILE mining only, faster own-plot crop growth) max +25%; FORTUNE_FISH (treasure weight) max +20%; SELL_BONUS capped at a token +5% AND paid only in non-tradeable Żetony, never into tradeable Money. A GLOBAL ceiling caps the multiplicative product within each category so two maxed sources overlap rather than stack past the cap. Permanent mastery perks are even smaller (e.g. +5% double-drop) and ALSO count against the same category cap, so maxed permanent + maxed temp lands exactly on the cap, never beyond. BANNED forever: combat damage, armor/defense, PvP movement speed, max-health/hearts, knockback, in-combat regen, and any direct currency mint — this is the structural guarantee boosts never decide a fight or inflate the economy.

Anty-abuse

Designed defensively around the prior ~44.8B dupe — the rule is "the server never trusts a client, an in-memory counter, or a single NATS delivery." Guardrails: (1) IDEMPOTENT APPEND-ONLY LEDGER — every grant is INSERT into boost_grants with a UNIQUE idempotency_key derived from (uuid, source_type, source_id, time-bucket); a redelivered NATS message or a double-firing event collapses to one row, so boosts cannot be duplicated by replay. (2) SINGLE WRITER PER PLAYER — the proxy elects one authoritative ledger-writer backend per online player; all other backends apply read-only stacks, eliminating cross-server write races (the class of bug that enabled the currency dupe). (3) PER-SOURCE / PER-DAY GRANT BUDGET — boost_grant_budget caps how many of each source a player can receive per day; exceeding it is rejected and logged as a tripwire. (4) APPLY-TIME CLAMP — the effective stack is recomputed and CLAMPED to category caps every time it is applied; an invariant check asserts no boost_active row's summed magnitude exceeds its cap, and any violation is auto-revoked and alerted (target: zero violations). (5) PRESENCE-GATED BURN — boosts decrement only while Strażnik Obecności confirms genuine presence, killing autoclicker/AFK-pool/water-macro farming. (6) NON-TRADEABLE / NO-MINT — boosts never mint Money; the only currency they touch is account-bound Żetono via a token +5% sell bonus, so even a hypothetical boost exploit cannot inflate the tradeable economy or be laundered. (7) FULL AUDIT TRAIL — boost_grants is the immutable record; every grant/revoke is queryable for forensic replay, and conservation/anomaly tripwires (grants over budget, idempotency collisions, blocked redeliveries, cap violations, Żetony mint rate) are instrumented as KPIs so the NEXT exploit is caught in minutes, not after 44.8B.

Sync sieci

Network-wide via shared MySQL (authority) + NATS (live propagation) on the v5 stack. A player's boost stack is global: MySQL boost_grants/boost_active is the single source of truth; on login/server-switch the destination backend reads boost_active and applies the identical capped stack, so the buffs you earned on survival are live on PvP, minigames, anywhere. Real-time changes flow over NATS: a grant intent is published to `v5.boost.grant` (request/reply, must be acked by the elected writer), the writer performs the idempotent INSERT, recomputes the capped stack once, and fans the authoritative result out on `v5.boost.stack.<uuid>`; every backend subscribed for that player applies it on the player's EntityScheduler. The proxy (Travertine) assigns exactly one ledger-writer backend per online player to serialize writes and prevent the cross-server race that caused the 44.8B dupe; failover re-elects on disconnect. Expiry is computed from active-play accounting (presence-gated), and because timestamps/active-ms live in MySQL, a server hop or crash never loses or double-counts remaining boost time. Admin `v5.boost.revoke` can pull a boost network-wide instantly. This makes the product feel like one persistent network account: your live boost stack follows you, and leaving any single server means abandoning the whole stack.

Budowa

Custom Folia-aware plugin "WzmocnieniaCore" (JDK21, Paper 26.1.2 API), NOT a bought "boost" plugin. BUY the content emitters you already planned — UniverseJobs or AuraSkills (Folia-native) for vocations and BattlePass/Tasks-Quests (Folia-safe 4.9.3+) for quests/streaks — and have them call WzmocnieniaCore via a thin internal API/event rather than granting effects themselves, so ALL caps, ledgers and sync live in one authoritative place. Architecture: (1) MySQL is the single source of truth — append-only `boost_grants` (id, uuid, source_type, source_id, category, magnitude_bp, duration_active_ms, granted_at, idempotency_key UNIQUE) + derived `boost_active` snapshot + per-day `boost_grant_budget` (uuid, day, source_type, count) for grant-rate ceilings. Never trust a client or in-memory counter — every grant is an idempotent INSERT keyed by idempotency_key so a NATS redelivery or a double-fire cannot double-grant (this is the direct lesson of the 44.8B dupe). (2) NATS subjects: `v5.boost.grant` (intent, request/reply with ack), `v5.boost.stack.<uuid>` (authoritative recomputed stack fan-out), `v5.boost.revoke` (admin/anti-abuse). One backend is elected ledger-writer per player (proxy-assigned) to serialize writes; others apply read-only stacks. (3) Folia/Canvas threading: the survival overworld is regionised multi-threaded — NEVER world-scan and NEVER touch a player from an arbitrary thread. All boost application/expiry runs on that player's EntityScheduler; grant intents are emitted from the block-break/fish/kill/quest events the player already fires (which run on the owning region thread); MySQL and NATS I/O run OFF the main/region threads on an async executor, hopping back to the EntityScheduler to apply effects. Effects implemented as: job/quest XP multipliers via the emitter's API; GATHER_LUCK/FORTUNE_FISH via drop-event modification on the region thread; COMFORT haste via a short re-applied PotionEffect scoped to mining only; crop growth via per-plot metadata, not a global ticker. Active-time accounting is server-side: boosts decrement only while Strażnik Obecności reports genuine presence. Effort split roughly: schema+ledger+idempotency 25%, NATS sync+writer election 25%, Folia-safe effect application 25%, GUI (Java + Bedrock forms) + Polish copy + emitter wiring 25%.

# WzmocnieniaCore/config.yml  (Paper 26.1.2, JDK21, Folia-aware)
network:
  ledger-writer-election: proxy   # proxy assigns one authoritative writer per player
  nats:
    grant-subject: "v5.boost.grant"          # request/reply, must be acked
    stack-subject-prefix: "v5.boost.stack."  # + uuid, authoritative fan-out
    revoke-subject: "v5.boost.revoke"
  mysql:
    table-grants: boost_grants        # append-only, UNIQUE(idempotency_key)
    table-active: boost_active        # derived snapshot, never hand-edited
    table-budget: boost_grant_budget  # per uuid/day/source grant-rate ceiling

presence:
  require-signal: true                # Strażnik Obecności must confirm presence
  pause-when-afk: true                # boosts pause, do not burn, while AFK/offline

# HARD aggregate caps — sum of ALL active sources, clamped at apply-time
categories:
  JOB_XP:       { cap_bp: 4000, model: percent }     # +40%
  VANILLA_XP:   { cap_bp: 3000, model: percent }     # +30%
  GATHER_LUCK:  { cap_bp: 1500, model: points }      # +15 pp double-drop chance
  FORTUNE_FISH: { cap_bp: 2000, model: points }      # +20 pp treasure weight
  COMFORT:      { cap_bp: 2500, model: percent }     # +25% (mining-only haste/hunger)
  SELL_BONUS:   { cap_bp: 500,  model: percent, payout: ZETONY_ONLY } # +5%, non-tradeable
global:
  max-active-per-category: 6          # overlap, never add past cap
  max-active-total: 12
  combat-effects-allowed: false       # ENFORCED: no damage/armor/speed/hearts/knockback/regen

# Rarity scales duration/magnitude modestly, NEVER past category cap
rarities:
  POSPOLITE:  { mult: 1.0 }
  NIEZWYKLE:  { mult: 1.2 }
  RZADKIE:    { mult: 1.5 }
  EPICKIE:    { mult: 2.0 }

sources:
  DAILY_CONTRACT:  { category: JOB_XP,     base_bp: 1500, active_ms: 1200000, per_day_max: 3 }
  STREAK_7:        { category: COMFORT,    base_bp: 1000, active_ms: 1800000, per_day_max: 1 }
  WORLD_BOSS:      { category: GATHER_LUCK, base_bp: 500,  active_ms: 1800000, per_day_max: 2 }
  MASTERY_MISTRZ:  { category: GATHER_LUCK, base_bp: 500,  permanent: true }   # counts vs cap

messages:
  prefix: "&8[&6Wzmocnienia&8] "
  granted: "&aZdobyto wzmocnienie: &f{name} &7({magnitude} na {duration})"
  capped:  "&eOsiągnięto limit kategorii &f{category}&e — nowe wzmocnienie nakłada się, nie sumuje ponad limit."
  paused:  "&7Twoje wzmocnienia są wstrzymane (jesteś AFK) — nie marnują się."
  expired: "&7Wygasło wzmocnienie: &f{name}"
# Example active buff names (proper diacritics):
#   "Doświadczenie Zawodowe", "Tarcza Skupienia", "Wprawne Ręce",
#   "Szczęście Górnika", "Błogosławieństwo Wisły", "Sytość Wędrowca"

Maximise concurrent players, session length, and D1/D7/D30 by giving every player exactly one always-on reason to log in TODAY (streak + 3 dailies), one reason to come back THIS WEEK (weekly Kronika + profesja milestone), and one reason to stay the whole SEASON (Przepustka + permanent Kronika wall). Differentiate hard from DonutSMP: rewards are mastery/cosmetic/utility and account-bound, never raw tradeable currency — the flex becomes "what you've earned and how complete your account is", not "your balance". Turn solo churn into a structured habit loop with forgiving streaks (no punishing reset-to-zero) and a season horizon that contains any future dupe to a single 6-week window.

Pętla

ONE loop, three nested clocks, all funnelling into the season rail: DAILY CLOCK (resets 04:00 Europe/Warsaw, the natural low-traffic trough): 1. Login -> SILNIK fires LOGIN event -> streak advanced (or frozen, never zeroed if a Tarcza is held) -> daily board (3 quests + cached reroll token) regenerated from a deterministic seed (date + uuid) so it is identical on every backend without coordination. 2. Play -> ZRODLA emit EngagementEvents (block/fish/kill/quest-tick) -> SILNIK matches them to active daily objectives AND to the player's 2 chosen profesje in the SAME pass. 3. Objective complete -> ledger event grants PS + PX; profesja XP grants on the same event. Finishing all 3 dailies grants a daily-complete bonus and increments the streak's "active day" flag. WEEKLY CLOCK (resets Monday 04:00): 4. Completing dailies and profesja checkpoints advances the Kronika Tygodnia quest-line (a stateful, ordered chain). It cannot be finished by grinding one trivial action — steps explicitly require "ukończ N dni" and "osiągnij lvl X profesji", chaining day-to-day play. 5. Weekly completion -> large PX chunk + guaranteed cosmetic shard + entry into the weekly Liga snapshot. SEASONAL CLOCK (fixed 6-week season): 6. ALL PX from daily/weekly/profesja/quest-line sources accrues into the Przepustka. Crossing a tier grants that tier's free (and, if owned, premium) reward slot. 7. Season end -> SILNIK runs the finalize job: snapshot leaderboards, engrave Kronika wall, archive the season's ledger, soft-reset profesja levels to a prestige-banked baseline, rotate map theme. New season seed published over NATS to every backend simultaneously. The glue: a single EngagementEvent can, in one atomic SILNIK pass, tick a daily objective + level a profesja + advance the weekly chain + add Przepustka XP — so the player feels every action push four bars at once. That multiplicative feedback is the retention engine and the thing scattered plugins can't produce.

Doświadczenie gracza

FIRST SESSION: on join, a one-line actionbar + a single chest GUI (/szlak) titled "Twój Szlak — Sezon I: Bursztynowy Szlak". Three slots glow: "Zadania na dziś (0/3)", "Twoje profesje (wybierz 2)", "Przepustka — poziom 0". Bedrock/Geyser players get the identical GUI (chest-form, no custom model required) plus a /szlak text fallback that prints the same state, so controller/touch users are first-class. DAILY: player logs in -> toast "Plomień Serii: 4 dni! Wróć jutro, nie zgaś go." -> opens /szlak -> sees 3 dailies, e.g. "Wykop 64 bloki kamienia (górnik)", "Złów 10 ryb (rybak)", "Pokonaj 15 potworów". Each is tagged with a profesja, so completing it ALSO levels that profesja and feeds Przepustka XP. One free reroll per day if a quest is unfun; further rerolls cost PS. Finishing all 3 pops "Dzienna seria ukończona +150 PX, +200 PS" and bumps the streak. WEEKLY: a multi-step "Kronika Tygodnia" quest-line (5-7 steps) that requires the player to complete dailies and hit profesja checkpoints across the week — "Ukończ 4 dni zadań", "Osiągnij 25 lvl drwala", "Wygraj 1 wydarzenie". It pays a big PX chunk + a guaranteed cosmetic shard. Profesja milestones (every 10 levels) drop on their own cadence so there is always a near-term bar filling. SEASONAL: the Przepustka has ~60 tiers over 6 weeks. Free track gives utility (PS, cosmetic shards, keys, profesja boosts). Premium track (bought once with real money or earned via play-streak grant) adds extra cosmetic/QoL slots per tier — never power. At season end the grind soft-resets, the map gets a new theme WITHOUT a brutal full wipe, and the player's name + season rank + feats are engraved permanently into the Kronika wall at spawn ("Mistrz Sezonu I: Bursztynowy Szlak"). Missed seasonal cosmetics grey out in /kolekcja forever — compounding FOMO and loyalty-as-status. THE FEELING: "to jest MOJE konto, widoczne na każdym serwerze, i rośnie odkąd gram — a nie odkąd płacę." Cross-server: walk through a portal from survival to PvP and the scoreboard/holograms already show your updated streak, profesja levels and Przepustka tier, because the delta propagated over NATS before you finished loading.

Nagrody

CURRENCY MODEL (dupe-defensive core): TWO new account-bound rails, both non-tradeable, both impossible to hand to another player, both ledger-backed: - Punkty Szlaku (PS): soft reward currency. Spent ONLY on rerolls, cosmetic unlocks, profesja respecs, streak insurance (Tarcza). Cannot be converted to Voyager Money. Duped Money therefore buys NOTHING in this system. - Przepustka XP (PX): pure progression points, spendable on nothing — they only advance the season tier. Earned ONLY from gameplay objectives. Raw Voyager Money is NEVER granted by this system. This is the structural inversion of DonutSMP's faucet. REWARD CURVE (tuned for a 45-60 min median session, ~6 week season): - Daily: 3 quests at ~50/60/70 PX and ~60/80/100 PS; daily-complete bonus +150 PX / +200 PS. A focused player clears dailies in ~25-35 min -> ~400 PX/day. - Weekly Kronika: ~600-900 PX + 1 guaranteed cosmetic shard + 1 rare key. - Profesja milestones (every 10 lvls): +100 PX + a tool-skin or micro-perk unlock at 50/100. - Season: ~60 tiers, tier N costs roughly 250 + 18*N PX (gentle ramp). A daily-active player who also does weeklies finishes the free track around week 5, leaving a comfortable buffer — NOT a grind wall, NOT trivially fast. Premium-only slots add cosmetics on already-earned tiers. - Streak (Plomień Serii): milestones at 3/7/14/30/100 days -> cosmetic trail tiers + PS lump + a free Tarcza at 7/30. A missed day with a Tarcza held = streak FROZEN (not reset); without one, streak drops one tier, never to zero. Pure Duolingo break-protection. WHAT REWARDS ARE: cosmetic shards (-> /szafa wardrobe: trails, hats, tags, pets), profesja tool-skins, account-bound keys, tiny capped profesja boosts (e.g. +3% double-drop chance, hard-capped per hour), streak titles, and the permanent Kronika engraving. Premium pass = MORE cosmetic/QoL slots, faster reroll cooldown, an extra daily reroll — explicitly never more PS-per-quest, never more PX, never power. This keeps the whole thing non-P2W and clip-worthy: the cool stuff is earned. ANTI-DEGENERACY: one free reroll/day (costed after) kills the "everyone grinds the single easiest quest" pattern; per-source hourly PS/PX ceilings (see antiAbuse) cap any farm; rewards being account-bound means a dupe or an alt army produces cosmetics on a throwaway account and nothing tradeable.

Anty-abuse

Designed against the known 44.8B dupe class. Principle: this system NEVER mints tradeable value, and every grant is capped, idempotent, and audited. 1. NON-TRADEABLE BY CONSTRUCTION: PS and PX live only in v5_szlak, are account-bound, have no give/pay/trade command, and cannot convert to Voyager Money. A dupe of Money buys nothing here; a dupe of PS would require breaching this DB directly. There is no item-form, so no item dupe vector. 2. EXACTLY-ONCE LEDGER: every grant inserts into szlak_ledger(uuid, idem_key UNIQUE, source, amount_ps, amount_px, ts). Duplicate idem_key -> 1062 -> skipped (Kody's proven pattern). Replays, double-fires, NATS redelivery all collapse to one grant. 3. ATOMIC CAP GUARDS (no read-modify-write race): hourly/daily counters live in szlak_caps(uuid, window_bucket, ps_used, px_used). A grant is: UPDATE szlak_caps SET ps_used = ps_used + ? WHERE uuid=? AND window_bucket=? AND ps_used + ? <= :cap. If 0 rows affected, the cap is hit and the grant is refused server-side. The client can never request more than the cap allows because the DB itself enforces it in one statement. Caps: 4000 PS/h, 1500 PX/h, 20000 PS/day, 9000 PX/day (config-tunable per season). 4. PRESENCE / ANTI-FARM (Strażnik Obecności): profesja/daily progress only counts from events tied to genuine player action (block actually broken by player, fish actually reeled, mob actually killed by player). No tick-based world-scanning means no AFK/autoclicker farm of a timer. Per-action profesja XP is tiny and the per-hour PX cap throttles any macro to a ceiling, making alt-army/autoclicker farms produce capped cosmetics on throwaway accounts — economically pointless. 5. SEASON CONTAINMENT: a hard 6-week reset means any undiscovered exploit is bounded to one season's PX/PS and erased at finalize. The permanent Kronika wall stores only NAMES/RANKS/FEATS (no balances), so it can't be inflated by an exploit. 6. CONSERVATION TRIPWIRES: a scheduled audit job (async, every 5 min) recomputes each online player's PS/PX from the ledger SUM and compares to the cached balance; any drift logs a WARN with uuid + delta to Loki (existing Grafana stack) — the same "catch the next dupe in minutes" posture the brief demands. Negative balances are impossible (grants are append-only; spends are checked-and-decremented in one guarded UPDATE that refuses to go below zero). 7. NO CLIENT TRUST: the GUI/scoreboard are pure projections; clicking buy/reroll sends an intent, the server validates PS balance + cooldown + cap atomically before committing. Reroll cost and the one-free-per-day are enforced by a row in szlak_caps, not the client.

Sync sieci

MySQL is the durable source of truth; NATS is the live nervous system. No backend ever trusts another's in-memory state. WRITE PATH (authoritative-writer = whichever backend processed the action): 1. EngagementEvent handled locally -> SILNIK computes deltas under the per-player hourly/daily caps (caps enforced by an atomic UPDATE that includes the cap as a WHERE-clause guard, see antiAbuse). 2. SILNIK writes to the ledger table with an idempotency_key = sha1(uuid|source|objective|period_bucket). INSERT ... ; on duplicate-key (1062/23000) the grant is SKIPPED — identical to Kody's awardNewMilestones pattern. This makes every grant exactly-once even under at-least-once NATS redelivery or a double-fire. 3. The committed delta is published to NATS subject szlak.account.<uuid>.delta as {uuid, ps, px, profesja, newStreak, seq}. seq is a per-player monotonic counter from MySQL so receivers can detect/order/drop stale deltas. READ / SYNC PATH: 4. Every backend subscribes to szlak.account.*.delta. On receipt it updates ONLY presentation state for online players (scoreboard, holograms, /szlak GUI cache) — it does NOT re-derive balances. If the player isn't online locally, the delta is ignored; the next backend the player visits loads authoritative state from MySQL on join. 5. szlak.season.event broadcasts season start/finalize and the new daily/weekly SEED so all backends regenerate identical boards. Daily quest selection is deterministic: seed = hash(season_key | date | uuid) -> no cross-server coordination needed, every server independently computes the SAME 3 quests for a player. 6. szlak.leaderboard.tick (throttled, ~10s) feeds lobby holograms (top drwal/górnik/Przepustka). JOIN HANDSHAKE: on PlayerJoin (region thread) -> async load account row + active objectives + streak from MySQL (single pooled connection) -> hydrate local cache -> render GUI. Because the row is authoritative, walking server-to-server is seamless: the delta usually arrives before load completes; if not, the MySQL read backstops it. FAILURE MODES: if NATS is down, writes still commit to MySQL (durability preserved) and live cross-server presentation just lags until reconnect — never double-grants, never loses progress. If MySQL is briefly unreachable, the SILNIK buffers EngagementEvents in a bounded in-memory queue per player (dropping silently past a cap, logged) and flushes on reconnect; the idempotency key guarantees a flushed-then-redelivered event still grants once.

Budowa

BUILD CUSTOM — do not buy. This is the network's identity layer and must be Folia-correct, NATS-native, and dupe-defensive; off-the-shelf BattlePass/Jobs plugins (a) aren't all Folia-safe (Jobs Reborn is NOT), (b) mint or assume tradeable currency, and (c) can't share one account/ledger across the v5 NATS+MySQL fabric. Reuse the proven Kody scaffolding rather than greenfield. STACK: JDK21, Paper 26.1.2 API, single Maven module pl.minecraft.szlak, maven-shade-plugin shading + relocating the MariaDB JDBC driver to pl.minecraft.szlak.libs.mariadb (exact Kody convention — speaks MySQL). Add the NATS java client (io.nats:jnats), also shaded/relocated. plugin.yml: folia-supported: true, api-version '1.21'. THREADING (Folia/Canvas overworld is regionised multi-threaded — the load-bearing constraint): - ZRODLA listeners (BlockBreak/PlayerFish/EntityDeath) fire on the OWNING REGION thread. They do the minimum: read the event's data, build an EngagementEvent, hand it to the SILNIK via getAsyncScheduler().runNow(). They NEVER scan the world or touch other regions' entities. - ALL MySQL + NATS I/O runs on getAsyncScheduler() (Kody pattern), backed by a HikariCP pool (config pool-size) — NOT Kody's per-operation open(), because this plugin is high-traffic. - ANY reward that dispatches a console command (e.g. give a crate key, apply an LP temp perk) MUST go through getGlobalRegionScheduler().run() — Kody already does exactly this for reward commands on Folia; reuse verbatim. - Reading/altering a player's inventory or opening the GUI is scheduled on that player's EntityScheduler, never assumed to be the main thread. DATA MODEL (v5_szlak, utf8mb4_unicode_ci): tables szlak_account (uuid, name, current_season, ps, px, season_tier, streak, last_active_date, tarcze, seq), szlak_profesje (uuid, profesja, level, xp, prestige), szlak_objectives (uuid, scope DAILY|WEEKLY, def_id, progress, target, period_bucket, done), szlak_ledger (idem_key UNIQUE — the dupe firewall), szlak_caps (uuid, window_bucket, ps_used, px_used), szlak_kronika (season, uuid, name, rank, feat) — the permanent wall, balances never stored here. DEPLOY: clone the Kody tooling (deploy_szlak.py + provision_szlak_db.py modelled on the existing Kody scripts), inject DB + NATS passwords per backend at deploy, greload on the proxy isn't needed (this is a backend plugin), restart-free reloads via /szlak admin reload for config. PHASING (ship value early, contain risk): - M1 (foundation): KONTO + ledger + caps + /szlak GUI + streak + dailies on ONE survival backend. Proves the dupe-safe rail end-to-end. (This alone is a shippable D1/D7 win.) - M2: profesje (the owner's idea) + daily tags + per-action XP, still single-server. - M3: NATS sync + cross-server account hydration + lobby holograms (Konto Sieciowe). - M4: Przepustka (dual-track) + weekly Kronika quest-line + season finalize/reseed + Kronika wall. Each milestone is independently live; the system compounds rather than requiring a big-bang launch.

One plugin, config split into files under /plugins/Szlak/. Password injected per-server at deploy (Kody convention), never committed.

# config.yml
database:
  host: "10.64.0.1"        # v5 shared MySQL (Kody convention)
  port: 3306
  name: "v5_szlak"
  user: "v5_szlak_user"
  password: ""             # injected per-server at deploy, NIE commitowac
  pool-size: 6             # HikariCP — pooled, unlike Kody's per-op open()
nats:
  url: "nats://10.64.0.1:4222"
  password: ""             # injected at deploy
  subject-prefix: "szlak"
timezone: "Europe/Warsaw"  # daily reset 04:00, weekly Mon 04:00
reset:
  daily-hour: 4
  weekly-day: MONDAY
season:
  id: 1
  key: "bursztynowy_szlak"
  name: "Sezon I: Bursztynowy Szlak"
  starts: "2026-07-01T00:00:00"
  ends: "2026-08-12T04:00:00"
  pass-tiers: 60
  tier-base-px: 250
  tier-step-px: 18         # cost(N) = base + step*N
caps:                       # ANTI-ABUSE: hard ceilings, server-authoritative
  ps-per-hour: 4000
  px-per-hour: 1500
  ps-per-day: 20000
  px-per-day: 9000
  reroll-free-per-day: 1
  reroll-cost-ps: 250
streak:
  tarcza-cost-ps: 1500
  free-tarcza-at: [7, 30]
  tiers: {3: Iskra, 7: Płomień, 14: Ognisko, 30: Pożoga, 100: "Wieczny Żar"}

# professions.yml  (boosts are SUPER MINOR + per-hour capped)
profesje:
  gornik:
    display: "Górnik"
    levels-source: BLOCK_BREAK
    blocks: [STONE, DEEPSLATE, IRON_ORE, DIAMOND_ORE]
    px-per-action: 1
    perks:
      double-drop-chance: { per-level: 0.0008, cap: 0.05 }   # max +5%
      sell-bonus: { per-level: 0.0005, cap: 0.03 }           # max +3%, capped/h
    milestone-every: 10
    odrodzenie-title: "Arcygórnik"
  drwal:
    display: "Drwal"
    levels-source: BLOCK_BREAK
    blocks: [OAK_LOG, SPRUCE_LOG, BIRCH_LOG]
    px-per-action: 1
  rybak: { display: "Rybak", levels-source: FISH, px-per-action: 2 }
  lowca: { display: "Łowca", levels-source: MOB_KILL, px-per-action: 2 }

# quests.yml  (daily pool — server picks 3/day by deterministic seed)
dziennie:
  pool:
    - id: kamien_64
      tag: gornik
      desc: "Wykop 64 bloki kamienia"
      type: BLOCK_BREAK
      target: { material: STONE, amount: 64 }
      reward: { px: 50, ps: 60 }
    - id: ryby_10
      tag: rybak
      desc: "Złów 10 ryb"
      type: FISH
      target: { amount: 10 }
      reward: { px: 60, ps: 80 }
    - id: potwory_15
      tag: lowca
      desc: "Pokonaj 15 potworów"
      type: MOB_KILL
      target: { amount: 15 }
      reward: { px: 70, ps: 100 }
  complete-all-bonus: { px: 150, ps: 200 }

# chronicle.yml  (weekly quest-line — ordered, gated steps)
kronika_tygodnia:
  id: "s1_w3"
  steps:
    - { desc: "Ukończ zadania w 4 dni", type: DAILY_DAYS, target: 4 }
    - { desc: "Osiągnij 25 lvl dowolnej profesji", type: PROFESJA_LEVEL, target: 25 }
    - { desc: "Pokonaj Smoka Wawelskiego", type: BOSS, target: "smok_wawelski" }
  reward: { px: 800, shard: "bursztyn_szard", key: "rzadka" }

# pass.yml  (per-tier free/premium slots — rewards only, never power)
przepustka:
  tiers:
    1:  { free: { ps: 200 },                 premium: { cosmetic: "smuga_iskra" } }
    10: { free: { key: "rzadka" },           premium: { cosmetic: "kapelusz_gornik" } }
    25: { free: { boost: "drop_30m" },       premium: { pet: "borsuk" } }
    60: { free: { title: "Wędrowiec Szlaku" }, premium: { cosmetic: "smuga_bursztyn_elite" } }

Make minecraft.pl's v5 network unmistakably NOT a DonutSMP clone via ONE bold signature mechanic, while maximizing concurrent players, session length, and D1/D7/D30 retention. The signature is "TWOJA KRONIKA" (Your Chronicle) wrapped around a Polish-folklore seasonal model: instead of DonutSMP's flat, never-resetting "biggest balance wins" flex, identity is built from a PERMANENT, network-wide hall-of-fame of dated feats earned by PLAYING (never paying), driven by a co-op world-boss the whole network fights together at Polish prime time. The flex inverts: on Donut you flex a number that can be duped; here you flex carved-in-stone deeds (Mistrz Sezonu, pogromca Smoka Wawelskiego) that no amount of currency or a dupe can buy. Positioning line: "Na DonutSMP liczy się ile masz. U nas liczy się czego dokonałeś — i to zostaje na zawsze."

Pętla

DAILY: log in -> Chronicle Wall reminds you others are advancing -> check /kronika for this season's near-complete deeds -> play your preferred loop (mining/PvP/jobs/fishing) which auto-progresses deed counters tracked from events you already fire (block-break, kill, fish) -> claim any completed deed -> deed is etched network-wide instantly via NATS, your name flashes on the lobby wall. APPOINTMENT (3-4x/week, 20:00 CET): network-wide Przebudzenie world-boss spawns on all backends at once -> warp + fight a single shared-HP boss -> earn contribution-bracket reward + chance at the rare seasonal "Pogromca" deed -> clip-worthy communal moment. SEASONAL (~7 weeks): chase a themed deed set + climb the Liga ladder -> season finale boss -> soft-reset grind, PERMANENT bank of all deeds into legacy wall dated with the theme. The three cadences nest: dailies feed the season, the season feeds the permanent legacy, and the boss is the recurring social heartbeat a US-timezone clone structurally cannot serve to Poles.

Doświadczenie gracza

A player joins lobby and immediately sees the SCIANA KRONIKI (Chronicle Wall) — a holographic wall of named, dated deeds of other players ("Bartek221 — Pogromca Smoka Wawelskiego — Sezon II", "kasia_pl — Mistrzyni Wydobycia — 1000h"). It signals: this is a place where what you DO is remembered forever, run by real people, alive right now. They open /kronika and see their own (empty) page with locked slots: deeds to earn this season + a permanent legacy section that never wipes. Three to four times a week at 20:00 Warsaw, a network-wide bossbar appears on EVERY backend (lobby, survival, nether, end) simultaneously over NATS: "PRZEBUDZENIE: Smok Wawelski powstaje za 5 minut". Players on any server warp to the survival arena; the boss has ONE shared HP bar synced across the whole network. Casuals deal chip damage and still earn a contribution-bracket reward; sweats compete for the top-damage "Pogromca" deed. Whether you solo-grind, PvP, or just farm, your meaningful acts get etched into your Kronika. Seasons run ~7 weeks with a Polish folklore theme (Bursztynowy Szlak, Noc Kupaly); at season end the competitive grind soft-resets but every earned deed banks PERMANENTLY into your legacy wall with the season's date and theme. You never lose the emotional payoff — you lose only the treadmill. The promise that defeats churn: "leaving this server means abandoning a permanent record of everything I ever did across the whole network."

Nagrody

Reward curve is deliberately NON-MONETARY to contain the 44.8B dupe risk: NO deed, boss kill, or season payout EVER grants tradeable currency. Three reward currencies, all account-bound and non-tradeable: (1) Czyny/Deeds — the permanent etched feats (the core flex), (2) Punkty Chwaly (Glory Points) — soft account-bound points spent only in the /szafa cosmetic wardrobe, (3) cosmetic unlocks (trails, titles, tab badges, boss trophies). Early curve is generous for D1/D7: first 5 deeds are easy ("zaloguj sie 3 dni z rzedu", "wydobadz 500 blokow", "zadaj 1 obrazenie bossowi") so a new player etches their first permanent deed inside session 1 — instant identity hook. Mid curve (D7-D30) requires the seasonal grind + boss participation. Top curve is prestige-gated and time-gated: "Mistrz Sezonu" (top of Liga), "Pogromca Smoka" (top-10 boss damage), "Tysiac Godzin" (1000h played) — visibly out-class anything a wallet can buy. Boss rewards use CONTRIBUTION BRACKETS not last-hit (every participant who dealt >=1% gets a guaranteed bracket reward; top damagers get the rare deed), so casuals AND sweats both get paid and nobody is excluded. Crucially: because rewards are cosmetic/status and account-bound, a future dupe cannot purchase prestige — the most valuable things on the server are mathematically un-buyable and un-dupable.

Anty-abuse

Designed defensively around the known 44.8B dupe. (1) NO reward path emits tradeable currency — deeds/boss/season payouts grant only account-bound, non-tradeable Czyny/Punkty Chwaly/cosmetics, so the most valuable status on the server is mathematically un-buyable and a future dupe cannot purchase prestige (structural quarantine, not a patch). (2) MySQL deed_events is append-only with a unique idempotency_key (player+deed+season) -> a deed can never be double-granted on reconnect, NATS redelivery, or replay; grants are server-authoritative, never client-trusted increments. (3) Hard rate caps: per-player per-hour deed-progress ceiling + Punkty Chwaly daily cap to defeat autoclicker/AFK/macro farming; counters only advance from genuine gameplay events, never timers. (4) Strażnik Obecności presence gate: boss-damage and deed credit require a recent authentic-interaction signal, killing AFK-pool/water-macro/alt-army farming of the communal boss. (5) Boss has ONE authoritative HP on one region thread; remote servers forward damage but cannot mutate HP -> no cross-server damage duplication; per-player boss-damage is clamped per tick to stop packet-spam inflation. (6) Contribution brackets cap top-bracket size and use share-of-total (not raw), so a single exploiter can't drain a fixed pool. (7) Full audit trail: every grant is a dated ledger row queryable for live conservation-of-deeds tripwires, so the NEXT anomaly is caught in minutes, and any bad season can be contained/rolled back without touching permanent legacy.

Sync sieci

Network-wide by construction over the v5 stack (4 backends: lobby, overworld/survival-Canvas, nether, end + Travertine proxy). Shared MySQL is the single authoritative event-sourced store (append-only deed_events ledger + materialized player_chronicle). NATS subjects: kronika.deed.granted (fan-out -> lobby Chronicle Wall + every backend update the instant a deed is earned, so progress feels global no matter which server you're on), kronika.boss.spawn (one cron/operator trigger fans the Przebudzenie boss to ALL backends synchronously at 20:00 Europe/Warsaw), kronika.boss.tick (authoritative shared HP + top-N damage leaderboard, published by the single overworld region that owns the boss, consumed by all backends to render an identical bossbar). The boss has exactly ONE source of truth (the overworld region thread) — other servers display and forward local damage, never mutate HP. This makes the product "your persistent network account," not "a server": every meaningful act is remembered everywhere, instantly.

Budowa

CUSTOM core plugin "Kronika" (this is the signature moat — must be bespoke, never a Donut*-branded plugin or you ARE the clone by construction), reusing existing infra. Stack: JDK21, Paper 26.1.2 on lobby/nether/end, Canvas 1.21.11 (Folia-family, regionised multi-threaded ticking) on the survival overworld. THREADING IS THE #1 CONSTRAINT: the overworld ticks per-region on multiple threads, so all world/entity access MUST go through the FoliaScheduler abstraction already vendored in the existing plugins (com.cjcrafter:foliascheduler — confirmed in EventsSMP and cuy-voyager plugin.yml with folia-supported: true). Rules: deed counters increment from Bukkit events ON the owning region thread; never world-scan, never iterate online players for rewards. Use EntityScheduler for per-player entity work, RegionScheduler for the boss arena region, and the global/async scheduler ONLY for MySQL writes and NATS publishes (never touch world state off-thread). The world-boss runs on ONE designated server (survival overworld) inside one region via RegionScheduler; its shared HP is the single source of truth, mutated only on that region thread, with damage events from local players applied locally and the authoritative HP/leaderboard broadcast to other backends over NATS. PERSISTENCE: shared MySQL is authoritative and event-sourced — append-only deed_events ledger (player_uuid, deed_id, season_id, ts, idempotency_key) so a deed can never be double-granted on replay/reconnect; a materialized player_chronicle view for fast reads. SYNC: NATS subjects kronika.deed.granted (fan-out so the lobby wall + all backends update instantly), kronika.boss.tick (authoritative HP + top-N damage), kronika.boss.spawn (one operator/cron trigger fans the boss to all backends synchronously). REUSE: holographic Chronicle Wall via existing hologram/TAB stack; cosmetics via /szafa hooking existing cosmetic plugin; trigger schedule reuse the EventsSMP AUTO_EVENTS pattern but in TIMEZONE Europe/Warsaw (the existing config is America/New_York — that EN/US-timezone default is exactly the clone tell we invert). Deploy via the existing Pterodactyl deploy.py to all 4 backends + proxy. Build order: M1 deed engine + MySQL ledger + /kronika GUI (single-server) -> M2 NATS sync + lobby wall -> M3 network world-boss + contribution brackets -> M4 seasons + permanent legacy bank + /szafa rewards.

kronika.yml:
sezon:
  aktualny_id: 2
  nazwa: "Sezon II: Noc Kupały"
  motyw: "kupala"
  koniec: "2026-08-05T20:00:00+02:00"
boss_przebudzenie:
  wlaczony: true
  strefa_czasowa: "Europe/Warsaw"
  serwer_areny: "overworld"        # single source of truth (Canvas/Folia region)
  harmonogram: ["20:00:Wt", "20:00:Czw", "20:00:Sob"]
  ostrzezenie_minuty: 5
  hp_bazowe: 5000000
  hp_na_gracza_online: 40000        # scales with network concurrency
  max_obrazenia_na_tick: 2500       # anti packet-spam clamp
  wymagaj_obecnosci: true           # Strażnik Obecności gate
  nagrody_progi:                    # contribution brackets (share of total dmg)
    - {min_udzial: 0.01, punkty: 50}
    - {min_udzial: 0.05, punkty: 150}
    - {min_udzial: 0.10, punkty: 400, czyn: "smialek"}
  czyn_pogromca_top: 10             # top-10 damagers get "Pogromca Smoka"
czyny:
  pierwsze_kroki: {tier: "brazowy", cel: {typ: "login_streak", ile: 3}, punkty: 25}
  gornik:         {tier: "srebrny", cel: {typ: "break_block", ile: 10000}, punkty: 150}
  tysiac_godzin:  {tier: "mityczny", cel: {typ: "playtime_h", ile: 1000}, punkty: 1000, permanentny: true}
limity_antyabuse:
  postep_na_godzine_max: 5000        # per-player hourly deed-progress ceiling
  punkty_chwaly_dziennie_max: 600    # daily soft-currency cap
  tylko_zdarzenia: true              # counters advance ONLY from gameplay events, never timers
nats:
  subjects:
    deed_granted: "kronika.deed.granted"
    boss_spawn:   "kronika.boss.spawn"
    boss_tick:    "kronika.boss.tick"
mysql:
  tabela_ledger: "kronika_deed_events"   # append-only, UNIQUE(idempotency_key)
  widok_kronika: "kronika_player_view"   # materialized read model
nagrody:
  waluta_tradeable: false                # HARD RULE: never grant tradeable money

Maximize D1 retention (the single biggest lever — a new PL player decides in the first 10 minutes whether the server "is for them") and seed D7/D30 by ending the first session with the player already invested in a persistent network account, a named streak, an unfinished questline, and ideally a clan/party invite. Target: lift new-player D1 from a typical clone baseline of ~12-18% to 30%+, and ensure 70%+ of new players reach the "first meaningful goal" (first Żetony reward + first profession pick) within 10 minutes of first join.

Pętla

PER-STEP MICRO-LOOP (repeats 5× in the questline, then generalizes): trigger an in-world action the player would do anyway (place/break/interact/walk/claim) → plugin listens to the native Bukkit/Folia event ON THE OWNING REGION THREAD (never a world scan, never a poll) → validate the step is the player's CURRENT step and the action is genuine (presence-checked) → grant a small immediate reward (Żetony + sound + toast + sidebar tick) → advance step pointer in the per-player onboarding state machine → persist to MySQL + publish a NATS event so the player's progress is identical on every server. STATE MACHINE (authoritative, server-agnostic): each new player has one OnboardingProgress record: {uuid, step (0–5), startedAt, completedAt, claimedWeek1[], firstJoinServer}. The plugin is a finite state machine — only the current step's listener is "armed", so a player can't skip-claim or double-claim. Steps are idempotent: granting step N is a MySQL conditional UPDATE (... WHERE step = N-1) so a duplicated NATS message or a relog mid-step can never double-pay. THREADING (Folia/Canvas overworld is regionised, multi-threaded): all reward grants, inventory writes, and entity/NPC interactions happen via the player's EntityScheduler (Bukkit.getScheduler is unsafe on Folia). All DB I/O is dispatched to an async executor off any region thread; results that touch the player hop back onto that player's EntityScheduler. NATS publish/consume runs on its own thread; inbound messages that mutate game state are re-scheduled onto the target player's EntityScheduler. NO global tick scans — the entire system is event- and message-driven.

Doświadczenie gracza

THE FIRST 30 MINUTES, BEAT BY BEAT (all copy in PL with full diacritics): T+0s — FIRST PROXY LOGIN DETECTION. Proxy (Travertine) checks Konto Sieciowe in MySQL: no row = brand-new. Player is routed NOT to survival but to a dedicated calm "Przystań Przybyszów" (Newcomers' Haven) onboarding lobby/region (Paper server, no PvP, no economy). Title fades in: "Witaj na Pustkowiach, Wędrowcu." Subtitle: "Twoja wyprawa zaczyna się tutaj." A friendly NPC guide, "Przewodnik Borys" (Polish-flavored old wanderer), waves and a soft chat line appears. T+0–60s — THE HOOK (give value before asking anything). Before any tutorial text, the player INSTANTLY receives a visible reward: a starter kit (named "Tobołek Wędrowca" — Wanderer's Bundle: bread, a wooden tool set, 16 torches, a map item) AND 50 Żetony (account-bound soft currency) drop into their inventory with a bossbar + sound. Chat: "Borys: Weź to, przyda ci się. Reszta należy do ciebie — jeśli ją zdobędziesz." This front-loads dopamine in under a minute — the anti-"empty server" move. T+1–4min — QUESTLINE "PIERWSZA WYPRAWA" BEGINS (5 micro-steps, each ~30–90s, each rewards immediately). A clean sidebar (scoreboard) shows "Wyprawa: 1/5". Steps are diegetic, not a wall of GUI: 1. "Rozpal Ognisko" (Light a campfire) — teaches block place/interact. Reward: +10 Żetony, a firework + "Krok 1 ukończony!" toast. 2. "Wybierz swoje Rzemiosło" (Choose your profession) — opens the Profesje GUI (drwal/górnik/rybak/łowca/rolnik). Player picks 2. This is the KEY identity moment — it makes the player commit to a path in minute 3. Reward: profession unlocked at lvl 1 + "Zostałeś Czeladnikiem!" title. 3. "Pierwszy Zarobek" (First earnings) — do one action for your chosen profession (chop 5 logs / mine 5 stone / catch 1 fish). Teaches the job XP loop on the Folia overworld. Reward: +15 Żetony + first job-XP gain visibly ticks up. 4. "Tablica Zleceń" (Quest board) — walk to the physical board NPC, claim today's first daily Zlecenie. Teaches the daily heartbeat. Reward: streak started ("Płomień Serii: Dzień 1"), +10 Żetony. 5. "Wyrusz w Świat" (Set out into the world) — step into the portal to the real survival server. On arrival the questline COMPLETES. T+4–6min — COMPLETION + COMMITMENT. Big finale: title "PIERWSZA WYPRAWA UKOŃCZONA", fireworks, and the capstone reward: a cosmetic "Smuga Wędrowca" (Wanderer's trail, earned-only, never buyable) + 100 Żetony + a permanent entry written into their Kronika ("Ukończył Pierwszą Wyprawę — {date}"). Crucially, Borys's final line seeds the NEXT session and the social hook: "Borys: To dopiero początek. Wróć jutro — twoja seria czeka. A jeśli chcesz przetrwać Pustkowia, znajdź sobie Cech." A one-click "Dołącz do Discorda" button + a "Znajdź Cech / Drużynę" prompt appear. T+6–30min — SOFT-GUIDED FREE PLAY (the "first hour" net). The questline is done but a lightweight "Pierwszy Tydzień" checklist (separate, non-blocking, claimable over 7 days) now lives in /menu: e.g. "Osiągnij 5 lvl rzemiosła", "Ukończ 3 Zlecenia", "Odwiedź Bazar", "Zdobądź 500 Żetonów". A gentle objective marker points the player toward the nearest activity, but they are FREE. An "honest activity feed" hologram at spawn shows real recent network events ("Kuba ukończył Zlecenie", "Klan Żelaźni wykopał 10k bloków") so the server feels alive. If the player idles >3 min, Borys (now a /przewodnik command) offers a contextual nudge. BEDROCK/GEYSER PARITY: all GUIs use Bedrock-safe layouts (no hover-only tooltips; chest-menu fallbacks); all prompts are clickable AND have a /command equivalent. The questline never requires desktop-only precision. EMOTIONAL ARC: receive → belong → achieve → commit. The player leaves session 1 with (a) currency they earned, (b) an identity (Czeladnik drwal), (c) a streak they don't want to break, (d) an unfinished week-1 list, and (e) a reason to come back tomorrow and a nudge to find a clan. That is the retention hook closed in under 30 minutes.

Nagrody

ACCOUNT-BOUND ONLY. Every onboarding reward is one of: (a) Żetony — the tagged, NON-TRADEABLE soft currency (cannot be dropped, traded, /pay'd, or stored in player markets; lives in its own ledger table with append-only deltas); (b) a profession unlock; (c) an earned cosmetic (Smuga Wędrowca trail) flagged earned-source so it can never be sold or gifted; (d) a permanent Kronika record (pure status). NO raw Money, NO tradeable items beyond the trivial starter kit (low-value vanilla tools/food, value floored so it can't be farmed by reroll). Reward sizes are config constants, server-capped, and granted via idempotent conditional writes so no relog/dupe/NATS-replay can multiply them.

Anty-abuse

DESIGNED DEFENSIVELY (the 44.8B dupe is the lens — assume every reward path will be attacked): 1. NON-TRADEABLE REWARDS ONLY. All payouts are Żetony (tagged ledger, cannot be /pay'd, dropped, traded, or market-listed) + earned-source cosmetics + status. Even if onboarding were fully exploited, NOTHING produced can enter the player Money economy or be sold — the blast radius of any onboarding exploit is contained to soft currency that only buys cosmetics/QoL. This is the single most important guardrail. 2. IDEMPOTENT CONDITIONAL WRITES. Every reward grant is `UPDATE onboarding_progress SET step=N, ... WHERE uuid=? AND step=N-1` and the Żetony credit is an append-only ledger insert keyed by (uuid, stepId) with a UNIQUE constraint. A duplicated NATS message, a relog mid-grant, a double-click, or out-of-order delivery can physically never pay twice (UNIQUE insert fails silently / conditional UPDATE affects 0 rows → no second credit). 3. LIFETIME ONE-SHOT PER ACCOUNT. onboarding can only ever run once per UUID (firstJoin/onboarded flag in Konto Sieciowe, network-wide). A veteran cannot replay it; deleting local files can't reset it (state is in shared MySQL). 4. ALT / FARM THROTTLE. Cap onboarding completions per IP per day (config, default 3) to blunt alt-army farming of the 185 Żetony + cosmetic. Combined with #1 this makes alt-farming worthless (non-tradeable output) AND rate-limited. 5. PRESENCE VALIDATION (Strażnik Obecności). Step rewards require the authoritative "genuine presence" signal — autoclicker/AFK-pool/macro completion of profession-action steps is rejected. Profession-action step counts only real, on-region-thread block/fish/kill events from the player, not world scans. 6. STARTER-KIT VALUE FLOOR. The kit is low-value vanilla (bread + wooden tools), so even unbounded reroll attempts yield nothing economically meaningful; kit items are bound where possible and never sellable to NPC for more than negligible value. 7. NO RAW MONEY, NO SCANS, NO CLIENT TRUST. Onboarding never grants Money/diamonds/spawners. Server is authoritative for every step transition; the client only sends actions, never claims of completion. No tick-scan that could be exploited by lag/region timing. 8. OBSERVABILITY TRIPWIRE. Emit metrics on Żetony minted by onboarding/hour and completions/hour; a sudden spike (e.g. > expected new-player rate) fires an alert (ties into your Grafana/Loki stack) — so the NEXT exploit is caught in minutes, the explicit lesson from 44.8B.

Sync sieci

CROSS-SERVER SYNC (v5: Travertine proxy + NATS + shared MySQL): SOURCE OF TRUTH = MySQL onboarding_progress (one row per account). NATS is the real-time mirror so any server reacts instantly; it is NEVER trusted as authoritative — every NATS-driven mutation is re-validated against MySQL with a conditional write. FLOW: 1. New login → proxy reads Konto Sieciowe (MySQL) async. New account → routes to Przystań + publishes `onboarding.started {uuid, ts}`. 2. As the player completes steps on whatever server they're on, that server does the authoritative conditional UPDATE (step = N WHERE step = N-1), then publishes `onboarding.step {uuid, step, rewardGranted:true}`. Other servers update any in-memory cache; they do NOT re-grant (the publisher already paid, idempotency key uuid:step dedupes replays). 3. MID-SESSION SERVER HOP: player leaves server A at step 3, joins server B. Server B loads onboarding_progress from MySQL on join, sees step=3, re-arms the step-4 listener. Progress is seamless — the "Konto Sieciowe" promise: your account, not the server, holds your progress. 4. COMPLETION publishes `onboarding.completed {uuid}` → consumers (Profesje, Płomień Serii, Przepustka, leaderboards) each react idempotently (e.g. streak service starts Day 1 only if not already started). Account flagged onboarded=true in Konto Sieciowe so it NEVER re-triggers anywhere. CONSISTENCY GUARANTEES: all grants idempotent + conditional, so duplicate delivery, out-of-order NATS messages, or a relog at the exact moment of a grant cannot double-pay or skip. If NATS is down, the system still works server-locally off MySQL (NATS is an accelerator, not a dependency) — degraded-mode safe.

Budowa

BUILD: CUSTOM plugin "raba-onboarding" + a thin proxy-side module — do NOT buy this. Rationale: it must be deeply wired into the EXISTING bespoke stack (Konto Sieciowe MySQL schema, NATS subjects, Żetony ledger, Profesje, Kody referral, Tablica Zleceń) that no marketplace plugin knows about; an off-the-shelf "tutorial/quest" plugin (e.g. BattlePass/Tasks-Quests, or a tutorial-NPC plugin) cannot create network-authoritative idempotent accounts or be Folia-correct against your Canvas overworld. Reuse where sane: hologram/NPC rendering via your existing display-entity tooling (BetterModel/DecentHolograms-equivalent, Folia-safe), GUI via an existing Folia-safe inventory lib, and the Profesje/Zlecenia GUIs you already build for those systems (onboarding just opens them). ARCHITECTURE / 5 PARTS: 1. Proxy module (Travertine): on PostLoginEvent, async-lookup Konto Sieciowe; if new → route to "Przystań Przybyszów" server instead of default; publish NATS `onboarding.started`. Greload-compatible. 2. Backend plugin (Paper, on the Przystań server + survival): the FSM, event listeners per step (BlockPlace, BlockBreak, PlayerFish, EntityDeath, board-interact, portal-enter), reward granters, NPC "Borys". 3. Persistence: MySQL tables (below) + Żetony ledger; all writes idempotent conditional UPDATEs. 4. NATS sync layer: subjects `onboarding.started/step/completed`, `account.created`; consumers re-schedule onto EntityScheduler. Idempotency key = uuid+step, deduped. 5. Content/config: YAML (below) holds copy, reward amounts, step definitions, profession list, week-1 tiles — so design tuning needs no recompile. FOLIA/THREADING CONSTRAINTS (must hold): JDK21, Paper 26.1.2, overworld = Canvas (Folia-family, regionised). Use `entity.getScheduler().run(...)` for anything touching a player/NPC; `Bukkit.getAsyncScheduler()` (or own pool) for DB/NATS; NEVER `Bukkit.getScheduler().runTask` (throws/UB on Folia). No cross-region entity access. Survival listeners must assume they fire on arbitrary region threads — capture only the firing player's context. NPC "Borys" on the Przystań is fine on Paper; if Przystań is ever Folia, schedule its interactions too. CROSS-SERVER (v5): the player can disconnect mid-onboarding on server A and reconnect to server B — because state is in MySQL + mirrored via NATS, server B re-arms exactly the right step. The questline is the SAME account-level progress everywhere; this is the "Konto Sieciowe" promise applied to onboarding. ANTI-ABUSE: see antiAbuse field. Core: idempotent conditional writes, non-tradeable rewards, presence validation, one-time-per-account lifetime gate, alt/farm throttles, starter-kit value floor.

# raba-onboarding/config.yml  (PL copy with diacritics; all tunable, no recompile)
onboarding:
  enabled: true
  haven-server: "przystan"            # proxy routes new players here
  survival-server: "swiat-1"          # portal target on final step
  idle-nudge-seconds: 180
  guide-npc-name: "&ePrzewodnik Borys"
  currency: "ZETONY"                  # tagged, non-tradeable ledger id
  starter-kit:                        # low value, floored to deter reroll-farming
    name: "&6Tobołek Wędrowca"
    items: ["BREAD:8","WOODEN_PICKAXE:1","WOODEN_AXE:1","TORCH:16","MAP:1"]
  hook-reward: { zetony: 50 }         # unconditional, T+0
  finale:
    zetony: 100
    cosmetic: "smuga_wedrowca"        # earned-source, non-tradeable
    kronika-entry: "Ukończył Pierwszą Wyprawę"
  professions: ["drwal","gornik","rybak","lowca","rolnik"]
  professions-to-pick: 2

  steps:
    - id: "ognisko"
      title: "&6Krok 1/5 &7— Rozpal Ognisko"
      hint:  "&7Postaw ognisko, aby je rozpalić."
      trigger: { type: BLOCK_PLACE, block: CAMPFIRE }
      reward: { zetony: 10 }
      toast: "&aKrok 1 ukończony! Ognisko płonie."
    - id: "rzemioslo"
      title: "&6Krok 2/5 &7— Wybierz swoje Rzemiosło"
      hint:  "&7Otwórz menu i wybierz 2 profesje: &e/profesje"
      trigger: { type: PROFESSION_CHOSEN }
      reward: { title: "&aZostałeś Czeladnikiem!" }
    - id: "zarobek"
      title: "&6Krok 3/5 &7— Pierwszy Zarobek"
      hint:  "&7Wykonaj 5 akcji swojej profesji."
      trigger: { type: PROFESSION_ACTION, count: 5 }
      reward: { zetony: 15 }
    - id: "zlecenia"
      title: "&6Krok 4/5 &7— Tablica Zleceń"
      hint:  "&7Podejdź do Tablicy i odbierz dzienne zlecenie: &e/zlecenia"
      trigger: { type: DAILY_CLAIMED }
      reward: { zetony: 10, start-streak: true }
    - id: "wyrusz"
      title: "&6Krok 5/5 &7— Wyrusz w Świat"
      hint:  "&7Wejdź w portal, aby rozpocząć przygodę."
      trigger: { type: PORTAL_ENTER, target: "swiat-1" }
      reward: {}                       # finale block fires on complete

  week-1:                              # drip, NON-blocking, claimed over 7 days
    - { id: "lvl5",     desc: "Osiągnij 5 lvl rzemiosła",  zetony: 50 }
    - { id: "zlec3",    desc: "Ukończ 3 Zlecenia",          zetony: 40 }
    - { id: "bazar",    desc: "Odwiedź Bazar",              zetony: 30 }
    - { id: "z500",     desc: "Zdobądź 500 Żetonów",        zetony: 60 }
    - { id: "cech",     desc: "Dołącz do Cechu",            zetony: 100 }
    on-complete: { tag: "&7[&aOsadnik&7]" }

anti-abuse:
  lifetime-once-per-account: true      # firstJoin flag in Konto Sieciowe
  max-onboarding-completions-per-ip-day: 3   # alt-farm throttle
  starter-kit-min-playtime-to-keep-seconds: 0  # kit is bound anyway
  require-presence-signal: true        # Strażnik Obecności gate on rewards
  reward-grant: "idempotent-conditional"   # UPDATE ... WHERE step = N-1

nats:
  subjects:
    started:   "onboarding.started"
    step:      "onboarding.step"
    completed: "onboarding.completed"
  dedupe-key: "uuid:step"              # drop replays

# --- MySQL (shared) ---
# CREATE TABLE onboarding_progress (
#   uuid BINARY(16) PRIMARY KEY,
#   step TINYINT NOT NULL DEFAULT 0,
#   started_at BIGINT, completed_at BIGINT,
#   first_join_server VARCHAR(32),
#   week1_claimed JSON,
#   INDEX(completed_at)
# );
# Żetony in existing ledger: zetony_ledger(uuid, delta, reason, ts, source)
#   -- append-only, reason='onboarding:<stepId>', source non-tradeable

Lift D1/D7/D30 retention and reactivate lapsed players by manufacturing a reason AND a reminder to return: "streak at risk", "daily reset / new daily quests live", "quest expiring", "your clan/event needs you", plus a tiered comeback bonus that scales with how long you were gone. Time the heaviest pings just before Polish prime time (19:00–21:00 CET) to lift concurrency when it matters most. Bridge retention to the existing Kody acquisition loop by reusing its account/code model for Discord linking.

Pętla

Fully event-driven, no per-tick scanning. (a) PRESENCE: on PlayerJoin/Quit + a 60s async heartbeat the plugin writes last_seen and an authenticity-gated "genuine session" flag (≥60s connected, moved/interacted, not AFK) to MySQL on getAsyncScheduler(); this updates the streak exactly once per Europe/Warsaw day-bucket, made idempotent by INSERT IGNORE into streak_days(uuid, day_bucket). (b) SCHEDULE: the notifier service runs a 5-min cron — SELECT linked players who are OFFLINE now with a trigger firing (streak grace window opening, daily reset 04:00 PL, a quest TTL crossing). (c) FAN-OUT: for real-time triggers (live boss/event start, clan war) the in-game plugin PUBLISHes a compact JSON hint on Redis channel powrot:trigger; the notifier (sole subscriber) re-checks MySQL truth, then DMs only OFFLINE linked members. (d) RETURN: on next genuine join the plugin computes the comeback tier, grants account-bound rewards via console commands on getGlobalRegionScheduler() (Folia rule), and marks the grant consumed in comeback_grants (idempotent). Loop: play → build streak/quests → (go offline) → timed reminder → return → reward → play.

Doświadczenie gracza

Link once: in game type /polacz to get a 6-digit code shown in #powiadomienia, or run /polacz <nick> mirroring Kody. Confirm DMs with a single Discord button (RODO/GDPR double opt-in). From then on, while OFFLINE the player gets at most ~2 well-timed messages/day, e.g.: "Hej Kuba! Twoja seria 6 dni gaśnie za 4 h — wskocz na chwilę, żeby ją uratować. Masz 1 Zamrożenie w zapasie. [Wbijam]" with a deep-link button. On a day a streak would break, a held "Zamrożenie" auto-spends to PAUSE the streak instead of resetting it (Duolingo-style, forgiving). On the next genuine login a clean chat/GUI summary shows streak status, what expired, and a "Powrót" reward if they were gone ≥3 days. Nothing is ever deleted silently — every message is framed as opportunity, never punishment. Players who ignore pings get auto-throttled to fewer sends (respectful). Players who never link still get in-game streak + quests, just no off-platform pings.

Nagrody

ALL re-engagement payouts are account-bound and tagged — never tradeable currency, never raw eco that can re-enter the market (direct answer to the 44.8B dupe). Currency reward is "Żetony Powrotu" credited to a dedicated append-only MySQL ledger, spendable ONLY in a sealed /powrot sklep for cosmetics/QoL (no gear, no sellable items). Comeback tiers by days-away: 3–6 dni = 50 Żetonów + "Witaj z powrotem" tag (7-day); 7–13 dni = 150 Żetonów + 1 Zamrożenie serii + cosmetic trail token; 14–29 dni = 400 Żetonów + a non-tradeable "Powracający" cosmetic crate key (cosmetics-only loot table); 30+ dni = 800 Żetonów + an exclusive "Tęskniliśmy" cosmetic that can NEVER be earned any other way. Streak-save reward is intangible: keeping the streak plus escalating cosmetic milestones at 3/7/14/30/100 days (titles, trails, tab badge). Daily-reset and quest-expiry pings carry NO direct reward — the reward is the in-game quest itself, keeping the ping honest rather than a faucet. Hard coded rules: at most ONE comeback grant per absence episode (PK uuid+episode_id), and total Żetonów minted per UUID per rolling 30 days is capped (config zetony.cap-30d, default 1500); all mints are append-only and reconciled nightly.

Anty-abuse

Designed against the known 44.8B dupe with defense-in-depth: (1) NO tradeable value leaves the system — re-engagement pays only account-bound Żetony (sealed cosmetic/QoL shop, nothing sellable) and account-bound cosmetics; duped Money can't buy any of it and these tokens can't become Money. (2) One-shot grants — comeback_grants PK(uuid, episode_id) guarantees exactly one welcome-back per absence; an "episode" opens only after a genuine session followed by ≥3 full day-buckets offline, so logout/login churn can't farm it. (3) Hard mint ceiling — zetony.cap-30d (default 1500) enforced at write time; the ledger is append-only and a nightly job reconciles SUM(ledger.delta) vs spendable balance and ALERTS on any drift — the exact conservation-of-currency tripwire that would have caught the 44.8B event in minutes. (4) Authenticity gate on streaks — a day counts only with ≥60s connected + movement/interaction + not AFK-flagged, killing autoclicker/alt-army streak farming by reusing a presence signal instead of trusting the client. (5) Alt/link abuse — one discord_id ↔ one uuid (UNIQUE uq_discord); Żetony are non-transferable, so alt-spinning yields only cosmetics on throwaway accounts, never economy value. (6) Notifier is read-mostly — it can SEND and write notify_log.clicked but has NO authority to mint Żetony or grant rewards; every economic write happens in-game through the plugin on a genuine join, so a leaked bot token cannot inflate the economy. (7) Rate/spam caps — max-pings-per-day + ignore-decay protect players and stop the system being a spam vector; deep-link clicks logged for funnel + abuse detection. (8) RODO/GDPR — double opt-in, store only Discord ID + UUID + optional push_sub; one /odlacz command purges link + push_sub.

Sync sieci

Authority = shared MySQL (10.64.0.1:3306, db v5_powrot), exactly the Kody model: every backend (overworld/lobby/nether/end) reads+writes the same rows, so presence/streak/Żetony are network-wide with zero per-server state. Idempotency is structural: streak increments are INSERT IGNORE into streak_days(uuid, day_bucket) so two servers seeing the same player the same day can't double-count; comeback grants are PRIMARY KEY(uuid, episode_id) so a welcome-back is awarded at most once per absence even if the player relogs across servers within seconds; Żetony are an append-only ledger reconciled to the balance nightly. Redis (10.64.0.1:6380, the EXISTING DonutEssentials instance) is a FAN-OUT HINT BUS ONLY — publish on powrot:trigger a tiny JSON {type, uuid?, ttl} for real-time events (live boss/event start, clan war, "your clan needs you"); the notifier service is the sole subscriber, and it re-checks MySQL truth before sending (still offline? still linked? under ping cap?). The Travertine proxy needn't be touched — a join/quit on any backend already lands in MySQL. Failure mode: if Redis is down nothing breaks — the 5-min MySQL cron still catches streak/daily/quest triggers; Redis only makes live triggers instant. The link table is shared too, so /polacz on any server links the global account. NOTE: the research digest says "NATS" but the deployed bus in this stack is Redis (verified via DonutEssentials RedisHandler at 10.64.0.1:6380) — design targets the real Redis; swapping to NATS later is a one-class change since it's only a hint transport.

Budowa

BUILD CUSTOM — two artifacts, reusing existing repo patterns wholesale. (1) Plugin "Powrot" (Maven, JDK21, Paper 26.1.2 API, Folia-aware) cloned structurally from Kody: same shaded+relocated MariaDB driver pl.minecraft.powrot.libs.mariadb.Driver, per-operation Connections opened ONLY on getAsyncScheduler(); ALL reward console commands dispatched on getGlobalRegionScheduler() (NEVER a region thread — mandatory on the Canvas/Folia overworld ce7f7a43 which ticks regions on many threads); player context (UUID/last location) read on the entity/region thread inside the event handler, then handed to async (the exact Kody/Zgloszenia split). Presence heartbeat = getAsyncScheduler().runAtFixedRate every 60s; authenticity gate from a throttled PlayerMoveEvent + interaction timestamp. Redis publish via Lettuce if DonutEssentials exposes it on classpath, else shade ioredis-equivalent jedis — publish on the async thread only. (2) Service "powrot-notifier" (Node 20 + TypeScript, discord.js v14, ioredis, mysql2) on the Mac Mini/Coolify, env-gated (empty DISCORD_TOKEN = disabled, same convention as Umami/Resend); it is the ONLY holder of the bot token and the ONLY component allowed to DM. It polls MySQL on a 5-min node-cron and SUBSCRIBEs Redis powrot:trigger. Web push is a later phase via the existing minecraft.pl web (VAPID + service worker); schema already carries a push_sub column so no migration later. Linking: extend Kody (or a thin shared link table) so /polacz writes uuid↔discord_id, reusing Kody's nick-as-code idea. Deploy via existing ptero.py with a new deploy_powrot.py mirroring deploy_kody.py (TARGETS overworld/lobby/nether/end; password injected from db_credentials.json key v5_powrot, never committed). NEVER restart servers to deploy without owner permission + a live player-count check — stage the jar and load on the next scheduled restart.

# config.yml — plugin Powrot (Folia-safe; JDK21; Paper 26.1.2)
database:
  host: "10.64.0.1"
  port: 3306
  name: "v5_powrot"
  user: "v5_powrot_user"
  password: ""            # injected per-deploy from db_credentials.json (v5_powrot), NIE commitowac
redis:
  host: "10.64.0.1"
  port: 6380              # istniejacy Redis (DonutEssentials)
  password: ""            # injected per-deploy
  channel: "powrot:trigger"
server-name: "overworld" # ustawiane per-serwer (jak w Zgloszenia)
presence:
  heartbeat-seconds: 60
  min-genuine-session-seconds: 60   # krotsze sesje nie licza serii (anty-bot)
  require-movement: true            # musi sie ruszyc / wejsc w interakcje
  day-timezone: "Europe/Warsaw"     # day-bucket = lokalna doba PL
streak:
  milestones:
    3:  ["lp user %player% permission settemp cosmetics.tag.iskra true 7d"]
    7:  ["powrotfreeze grant %player% 1", "cosmetics give %player% tag.plomien"]
    14: ["cosmetics give %player% trail.ognisko"]
    30: ["cosmetics give %player% trail.pozoga", "tab badge %player% pozoga"]
    100:["cosmetics give %player% animated.wieczny_plomien"]
  freeze-cap: 3                     # max trzymanych Zamrozen
comeback:                          # progi wg DNI nieobecnosci -> komendy konsolowe (account-bound!)
  "3":  { zetony: 50,  cmds: ["lp user %player% permission settemp cosmetics.tag.witaj true 7d"] }
  "7":  { zetony: 150, cmds: ["powrotfreeze grant %player% 1", "cosmetics give %player% trail.powrot"] }
  "14": { zetony: 400, cmds: ["crates givekey %player% powracajacy_cosmetic 1"] }
  "30": { zetony: 800, cmds: ["cosmetics give %player% exclusive.tesknilismy"] }
zetony:
  cap-30d: 1500            # twardy limit emisji na gracza / 30 dni (anty-dupe)
  shop-command: "powrotsklep"   # tylko kosmetyki/QoL, zero sellable
notify-triggers:           # co plugin PUBLISHuje na Redis dla notifiera (tylko hinty)
  daily-reset-hour: 4       # 04:00 PL — nowe Zlecenia
  quest-expiry-warn-hours: 3
  streak-grace-warn-hours: 4
anti-spam:
  max-pings-per-day: 2
  ignore-decay-after: 4     # po 4 zignorowanych pingach -> nizszy bucket czestotliwosci

# --- MySQL (CREATE TABLE IF NOT EXISTS, utf8mb4_unicode_ci, jak w Kody) ---
# players_presence(uuid CHAR(36) PK, name VARCHAR(16), last_seen BIGINT, last_genuine BIGINT,
#   streak INT DEFAULT 0, freezes TINYINT DEFAULT 0, last_day_bucket VARCHAR(10),
#   absence_started BIGINT NULL, ignored_pings INT DEFAULT 0, push_sub TEXT NULL)
# streak_days(uuid CHAR(36), day_bucket VARCHAR(10), PRIMARY KEY(uuid,day_bucket))  -- idempotentny inkrement
# link(uuid CHAR(36) PK, discord_id VARCHAR(32) NULL, opted_in TINYINT DEFAULT 0, linked_at BIGINT,
#   UNIQUE KEY uq_discord(discord_id))
# comeback_grants(uuid CHAR(36), episode_id BIGINT, tier INT, zetony INT, granted_at BIGINT,
#   PRIMARY KEY(uuid,episode_id))  -- DOKLADNIE jeden grant na epizod nieobecnosci
# zeton_ledger(id BIGINT AUTO_INCREMENT PK, uuid CHAR(36), delta INT, reason VARCHAR(32),
#   created_at BIGINT, INDEX idx_uuid_time(uuid,created_at))  -- append-only, nocna rekoncyliacja vs balans
# notify_log(uuid CHAR(36), kind VARCHAR(24), sent_at BIGINT, clicked TINYINT DEFAULT 0,
#   PRIMARY KEY(uuid,kind,sent_at))  -- dedupe + metryki lejka