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.jar before 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.

  1. NusaGate checks the official ViaVersion project at startup and every 6 hours.
  2. Only newer stable releases made for Velocity are accepted. Pre-releases, downgrades and releases that need another plugin are skipped.
  3. Every download is checked (checksum, size, plugin ID and version) before it is used.
  4. An update found while the proxy is running waits for the next startup. NusaGate never restarts the proxy or reloads ViaVersion on its own.
  5. 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.
  6. 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
SettingMeaning
auto-install-viaversionInstall the bundled ViaVersion on first setup.
auto-update-viaversionKeep the NusaGate-installed copy updated from official stable releases.
viaversion-update-check-hoursHow 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

  1. Open nusagate.yml and set auto-update-viaversion: false.
  2. 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.

  1. Before the very first start, set auto-install-viaversion: false in nusagate.yml.
  2. To manage everything by hand later on, set both auto-install-viaversion and auto-update-viaversion to false.

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/:

FilePurpose
viaversion-update.propertiesUpdate state, including a version that failed and is now blocked.
viaversion-pending.jarA checked update waiting for the next startup.
viaversion-previous.jarThe previous working JAR, kept outside the active plugin folder.
ViaVersion-5.12.1-source.zipSource 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

Nusa product documentation · NusaGateFree & PRO editions

Loading the index…