Built-in ViaVersion
Understand how NusaGate installs and updates ViaVersion, and how to turn automatic updates or the built-in install off.
On this page
NusaGate ships with the official ViaVersion plugin, so players on newer Minecraft versions can join your network without an extra download. This page explains how the built-in copy is installed and updated, and how to manage it yourself if you prefer.
What is included
- The NusaGate JAR contains the official ViaVersion plugin for Velocity (version 5.12.1 at the time of the 2.0.0 release).
- On first start, NusaGate checks the file's checksum and installs it as
plugins/ViaVersion.jarbefore plugins load. It works during that very first start, without downloading anything. - After that, ViaVersion is a normal Velocity plugin with its own settings and commands.
- Both Free and PRO include it.
ViaVersion lets players with a newer game version join servers that run an older supported version. It does not promise support for every Minecraft version.
How automatic updates work
Automatic updates are on by default for the copy that NusaGate installed.
- NusaGate checks the official ViaVersion project at startup and every 6 hours.
- Only newer stable releases made for Velocity are accepted. Pre-releases, downgrades and releases that need another plugin are skipped.
- Every download is checked (checksum, size, plugin ID and version) before it is used.
- An update found while the proxy is running waits for the next startup. NusaGate never restarts the proxy or reloads ViaVersion on its own.
- The previous JAR is kept as a backup. If the new version does not start properly, the previous one is restored on the next startup and that version is skipped.
- If the network fails or a download is invalid, your installed ViaVersion keeps working.
NusaGate leaves your own files alone. A ViaVersion JAR you installed yourself is not managed, and a managed file that you changed or removed is not touched.
Settings
The built-in ViaVersion is controlled in nusagate.yml. These are the defaults:
admin-integration:
built-in-plugins:
auto-install-viaversion: true
auto-update-viaversion: true
viaversion-update-check-hours: 6| Setting | Meaning |
|---|---|
auto-install-viaversion | Install the bundled ViaVersion on first setup. |
auto-update-viaversion | Keep the NusaGate-installed copy updated from official stable releases. |
viaversion-update-check-hours | How often to check for updates while running, from 1 to 168 hours. |
Changes to these settings take effect after a full proxy restart, not after /ng reload.
Turn off automatic updates
- Open
nusagate.ymland setauto-update-viaversion: false. - Restart the proxy.
ViaVersion stays installed and keeps working. From now on you update it yourself by replacing the JAR in plugins while the proxy is stopped.
Skip the built-in install
If ViaVersion already runs on your backend servers, you may not want it on the proxy as well.
- Before the very first start, set
auto-install-viaversion: falseinnusagate.yml. - To manage everything by hand later on, set both
auto-install-viaversionandauto-update-viaversiontofalse.
Neither setting removes a ViaVersion JAR that is already in plugins. To remove it, stop the proxy and delete the JAR yourself. A plugin you removed on purpose is not reinstalled automatically.
Files and recovery
All updater data is kept in plugins/.nusagate-bundled/:
| File | Purpose |
|---|---|
viaversion-update.properties | Update state, including a version that failed and is now blocked. |
viaversion-pending.jar | A checked update waiting for the next startup. |
viaversion-previous.jar | The previous working JAR, kept outside the active plugin folder. |
ViaVersion-5.12.1-source.zip | Source files for the bundled release. |
Stop the proxy before you restore any file by hand. A failed version stays blocked until a newer version appears. Always test updates together with the other plugins on your network.
Next steps
- Known issues: plugin compatibility on the proxy.
- Module map: the rest of
admin-integrationand other sections. - Commands and permissions: reload and diagnostics commands.