vJourney

Turn your server's quest system into a native Minecraft experience.

vJourney lets you create fully custom quest trees that live inside Minecraft's own advancement menu — no external GUIs, no extra commands for players to memorize. Just open advancements and play.

---

✦ What is vJourney?

vJourney is a Paper plugin that uses Minecraft's built-in advancement screen as a quest board. You define quests in simple YAML files, connect them into branching trees, and players progress through them naturally — all inside the familiar advancement interface they already know.

Every quest can have three visual states: blocked, in progress, and completed — each with its own description, so players always know what to do next.

---

✦ Features

• Visual quest trees built on the native advancement menu — no external GUIs
• Branching paths with parent/child hierarchy, multi-parent convergence, and hidden branches that reveal themselves as players progress
• Three frame styles — task, goal, and challenge — to distinguish quest types visually
• Rich trigger system supporting mob kills, item holding, region entry, BetonQuest tags and points, PlaceholderAPI values, permission nodes, and more
• Progress counters with live display in the quest tooltip
• Persistent or state-based completions — quests can lock in permanently or react to changing conditions
• Announcements — local chat, global chat, title, actionbar, and toast notifications, fully configurable per quest
• Custom icons with support for custom model data (ItemsAdder / Nexo compatible)
• Multiple tabs — organize quests into independent categories, each with its own icon, background, and display order
• Vanilla advancements can be hidden so only your quests are shown
• Bilingual — ships with en_US and pt_BR out of the box

---

✦ How It Works

You create a .yml file inside plugins/vJourney/categories/. Each file is one tab in the advancement menu. Inside it, you define quests and connect them with parent links to form a tree.

[Arrive at the Village] ──► [Villager's Request] ──┬──► [The Mine Problem]  ──┐
                                                    │                          ├──► [Village Council]
                                                    └──► [Lost Harvest]      ──┘

Players see the full tree, track their progress in each quest's tooltip, and unlock new branches as they complete objectives. Hidden branches can reveal secret paths, side quests, and surprise rewards.

---

✦ Trigger System

Quests complete automatically when their trigger condition is met. Built-in triggers include:

Trigger	What it detects
mob_kill	Kill a specific mob type N times
mythicmob_kill	Kill a MythicMobs mob by internal name
item_hold	Hold a specific item in your main hand
region_enter	Enter a WorldGuard region
bqtag / bqpoint	BetonQuest tag or point threshold
placeholder	Any PlaceholderAPI placeholder matching a value
permission	Player has a specific permission node

Soft dependencies are detected automatically — triggers only activate for plugins that are actually installed.

---

✦ Requirements

Dependency	Type
Paper 1.21+	Required
UltimateAdvancementAPI 3.0.0-beta-2	Required
WorldGuard	Optional
MythicMobs	Optional
BetonQuest	Optional
PlaceholderAPI	Optional
LuckPerms	Optional

---

✦ Quick Setup

1. Drop vJourney.jar and UltimateAdvancementAPI.jar into your plugins/ folder
2. Start the server — a working example category is generated automatically
3. Copy or edit the example file to create your first quest tree
4. Run /vjr reload to apply changes live, no restart needed

📖 Full documentation — syntax reference, all triggers, positioning guide, and complete examples — is available on the Wiki.