Overview

Awaiting approval v1.0

Platforms

Paper, Purpur, Folia

Minecraft

1.21.11 or 26.2

Java

21

Required

None

Optional

PlaceholderAPI, MariaDB or MySQL

VelorJourney guides new players through your server and shows you how many of them come back. It is a standalone onboarding and retention system: every integration is optional.

Requirements: Java 21 and a Paper, Purpur or Folia server running Minecraft 1.21.11 or 26.2. PlaceholderAPI and a MariaDB or MySQL server are optional.

First start #

1. Put the VelorJourney jar in the server's plugins folder.
2. Start the server once.
3. Edit plugins/VelorJourney/config.yml, the language files and the files in journeys/.
4. Run /journey validate to check your edits, then /journey reload to apply them.
5. Run /journey doctor to verify storage.

/journey validate reads the files on disk exactly as a reload would and names the file and the problem when something is wrong. It changes nothing. /journey reload is all-or-nothing: if any file is invalid it is refused and the running configuration stays in service.

GUI titles, text and icon materials are configurable. The dashboard uses a consistent background, explanatory lore, completion rates and explicit no-data states instead of exposing internal message keys.

Storage #

SQLite is ready without setup and is the default. To share data between servers, set storage.type: MYSQL and fill in the storage.mysql section. It works with MariaDB (tested with 11.8) and with MySQL-compatible servers. The database account only needs to create tables and read, insert, update and delete rows in its own database. Storage changes need a restart; ordinary configuration, language and journey changes reload live.

Database access runs on its own thread. A connection attempt gives up after 5 seconds and a query after 15, so an unreachable database cannot freeze the server. Progress that could not be saved stays in memory and is written again when the database answers, including the progress of players who left in the meantime. If the server itself is stopped while the database is still unreachable, progress that was not written yet is lost.

If the database cannot be reached when the server starts, or the login is refused, VelorJourney logs the reason and stays disabled until the next restart. Nothing is written to your configuration or data.

Set journeys.enabled: false to run VelorJourney as an analytics-only installation. Active time, player and retention tracking continue, while automatic enrollment, progress signals and player journey menus stop. Existing progress is kept and resumes when journeys are enabled again.

In the game #