Configuration

The configuration file is located in plugins/ViaVersion/config.yml. It uses the YAML Syntax. The config is split into sections, you can see these by looking at the comments prefixed with #.

A quick reminder on YAML:

• Boolean means it can either be true or false, (true being on and false being off).

• String means that it is a sentence or words surrounded by "", for example message: "Hello world!"

• Integer means that it is a number, for example: limit: 10

• Integer List means that it can be empty, [] or have as many values as desired, [10, 20, 30]

• Map means that it has a string key followed by a colon then the value, eg. {hello:1, world:2} 
  
  

Global Options

These options affect all versions, even when it isn't being handled by ViaVersion.

check-for-updates - default: true (Boolean)

This option indicates whether we should check for updates when the server boots and when an operator logs in, this can be a huge benefit to ensure that bugs are fixed as soon as new versions are available. We use update.viaversion.com to handle checking for updates, so ensure that it is allowed through your firewall if you wish to use this feature.

Note: this was renamed from checkforupdates so you have to adjust the new setting to match the value of the old one

send-supported-versions - default: false (Boolean)

When a client sends a ping request to your server, for example viewing the Minecraft server list should we send extra information telling them what versions are supported? We suggest only using this if you use some third party software to handle what servers a client can connect to. 

block-protocols - default: [] (Integer List)

This allows you to block certain versions from logging into your server, every Minecraft version has a special number assigned to it called a Protocol Version. You can view a list of them here and find a generator here. For example, if you wanted to block 1.10 Minecraft you can see from that list that the number is 210. You would then change your config to, block-protocols: [210] , you can then add as many protocols as required separated by a comma if you wish to block more.

block-versions- default: [] (String List)

This allows you to block certain versions from logging into your server, it is similar to block-protocols but allows you to use version names like "1.17" or "<1.17". For example ["<1.17"] would block allow versions less than 1.17. The less than operator and greater than operator are both supported for these versions. See here for a generator

block-disconnect-msg - default: "You are using an unsupported Minecraft version!" (String)

When the condition above for blocking a certain version is met, what should the client be kicked with? This message will appear on their disconnect screen when they are kicked for using a blocked version. You can use Minecraft Colour codes here.

reload-disconnect-message - default: "Server reload, please rejoin!" (String)

If you use ProtocolLib we are unable to reload the plugin without crashing the server with players connected, to protect against this we kick players. Here you can select what message is sent to them on reload, furthermore you should really use a Plugin Manager instead of /reload due to memory leaks. You can use Minecraft Colour codes here.

Settings for logging behavior. When debugging issues, we may ask you to change some of these. Most of these are disabled by default to prevent log spam from bad user input.

logging.log-blocked-joins – default: false (Boolean)
Whether to log more info about kicks due to blocked protocol versions to the console.

logging.log-entity-data-errors – default: true (Boolean)
Whether to log errors during entity data conversion.

logging.log-text-component-conversion-errors – default: false (Boolean)
Whether to log errors during text component conversion.

logging.log-other-conversion-warnings – default: false (Boolean)
Whether to warn for other issues when converting items, blocks, or other data between server and client.

logging.max-error-length – default: 1500 (Integer)
Maximum length of error messages in the console.

config-version – default: 1 (Integer)
Used for auto updating config files. Do not touch! (Only for reference)
init-config-version – default: 1 (Integer)
Used for auto updating config files. Do not touch! (Only for reference)

migrate-default-config-changes – default: true (Boolean)
Whether to update config values that were left on their default to newly changed defaults. Recommended to keep enabled.

send-player-details – default: true (Boolean)
If enabled, ViaVersion will send the native player version to the server on connect via a plugin message. See the wiki for more info.

send-server-details – default: true (Boolean)
If enabled, ViaVersion will send the native server version to a player on connect via a plugin message. See the wiki for more info.

Global Packet Limiter Options

When building ViaVersion we came across a lot of issues with exploits where people could send lots of packets and crash a server (Just as a general Minecraft fault). To combat this we included a simple packet limiting system, which should work out of the box.

Note: Setting 'max-per-second' or 'sustained-max-per-second' to -1 will disable the individual limit.

packet-limiter.enabled - default: true (Boolean)

Enable or disable the ViaVersion packet limiter

packet-limiter.max-per-second - default: 800 (Integer)

The maximum packets a client can send per second.

packet-limiter.max-per-second-kick-message - default: "You are sending too many packets!" (String)

When a player sends more than the limit above what should the kick message be. You can use Minecraft Colour codes here, as well as %pps which will be replaced with their current packets per second.

We can also kick them if they repeatedly send too many packets over a longer period of time.
E.g. if a player sends over 150 packets per second for 4 out of 7 seconds, we kick them.

packet-limiter.sustained-max-per-second - default: 150 (Integer)

The maximum packets per second a client can send over a longer period of time.

packet-limiter.sustained-period-seconds - default: 7 (Integer)

Period to track in seconds.

packet-limiter.sustained-threshold - default: 4 (Integer)

The number of seconds within the interval that the client can exceed the limit before being kicked.

packet-limiter.sustained-kick-message - default: "You are sending too many packets, :(" (String)

Limits the size of packets in kilobytes sent per second.

packet-size-limiter.enabled - default: false (Boolean)

Enable or disable the ViaVersion packet size limiter

packet-size-limiter.max-per-second - default: -1 (Integer)

packet-size-limiter.max-per-second-kick-message - default: "You are sending too large packets!" (String)

packet-size-limiter.sustained-max-per-second - default: -1 (Integer)

packet-size-limiter.sustained-period-seconds - default: 5 (Integer)

packet-size-limiter.sustained-threshold - default: 3 (Integer)

packet-size-limiter.sustained-kick-message - default: "You are sending too large packets, :(" (String)

Bungee/Velocity Options

BungeeCord/Velocity is very different to our other platforms we support as it's a proxy. This means we have to do some fancy stuff to work out what version the internal servers are to connect your users to. On large networks, some of our most basic options may be inefficient for your setup and you may want to revert to doing things using our manual methods.

By their name these options are only available on BungeeCord / Velocity.

bungee-ping-interval / velocity-ping-interval - default: 60 (Integer)

To be able to get the versions of servers on your network we send them a ping list (like the Minecraft server list in your client), this option indicates how long to check the protocol. You can set this to -1 to disable pinging. (You will still be able to use /viaversion probe though!)

bungee-ping-save / velocity-ping-save- default: true (Boolean)

If this option is enabled and the above ping-interval is enabled, when the protocol version is not the same as what's in the config it will add/replace it. You could use this to initially populate your config with values then disable the above ping-interval.

bungee-servers / velocity-servers - default: (Integer Map)

Example

The default will be filled with the lowest version your proxy can handle. You can view a list of them here. The key is the BungeeCord / Velocity server name from your config.yml and the integer is the protocol version from the previous link.

When a client connects to a server ViaVersion will gather the protocol in the following order:

1. If the server is in servers config, use the protocol version provided there.

2. If pinging is enabled, use the last pinged protocol version for the server.

3. Use the default key under the config.

4. Fallback to the lowest version the server can handle. (Should never happen)

Multiple Versions Options

These options affect multiple versions.

register-userconnections-on-join - default: true (Boolean)

Whether to make sure ViaVersion's UserConnection object is already available in the PlayerJoinEvent.
You may disable this for faster startup/join time if you are 100% sure no plugin requires this.

hologram-patch - default: false (Boolean)

In 1.9 and 1.11, certain height values for holograms were modified. If you used Armour Stands manually on your server this may not concern you but if you use a plugin such as Holographic Displays then your armour stands may appear higher than they should be to 1.9+ but also may be lower on 1.11+. To fix this you can enable this option.

hologram-y - default: -0.96 (Integer)

When the hologram-patch above is true, how much should be offset the hologram to 1.9 and above clients. Our experiments show that -0.96 works the best. For 1.11 this is inverted.

piston-animation-patch - default: false (Boolean)

Should we disable piston animation for 1.11/1.11.1 clients? In some cases when firing lots of pistons it crashes them.

quick-move-action-fix - default: false(Boolean)

Due to changes in Minecraft in 1.12 shift double click does not work properly for some items, this patch enables sending extra info to fix this (only works on 1.8-1.11.2 bukkit based servers).

team-colour-fix - default: true (Boolean)

Due to changes in Minecraft in 1.13 nametag colour is based on team colour and not prefix, this fix changes it so it's the last colour from prefix.

disable-1_13-auto-complete - default: false (Boolean)

1.13 has a new tag complete which may trigger kicked for spam on Spigot, you can disable it completely with this option.

1_13-tab-complete-delay - default: 0 (Integer)

Introduces a tick delay (20 ticks per second) to tab completion, if another request happens within the ticks it will be cancelled. This can be used to allow tab complete but not frequently, eg. 100 ticks  being one completion every 5s.

serverside-blockconnections - default: false (Boolean)

In 1.13 Mojang changed block connections to be handled by the server, because of this we need to calculate the connections required for blocks (this includes across chunks), this feature will have performance impact as additional calculations may be required when handling fences, panes, doors etc.

block-connection-method - default: packet (String, Either world or packet)

Due to the way block connections work, we offer a packet-level version and a block level version which will use internals in your server to calculate the blocks to connect. It's worth noting that only packet is available on proxy software and the overhead of the packet-level block connections is significantly bigger (more memory and more processing). However, the world mode may be unstable on some server software and cause crashes depending on the server software (though no fatal world losses have been reported).

reduce-blockstorage-memory - default: false (Boolean)

Due to the overhead of storing blocks we offer the option to reduce this by not storing non-important blocks. When this option is enabled fences, glass panes etc. won't connect to solid blocks.

flowerstem-when-block-above - default: false (Boolean)

This is a block connections option where flower stems are used for decorative purposes, enabling them will stop us from connecting them.

vine-climb-fix - default: false (Boolean)

Vines that are not connected to blocks will be mapped to air, otherwise 1.13+ can climb them.

change-1_9-hitbox - default: false (Boolean)

This changes the 1.9+ player's hitboxes so that there are no knockback bugs that occur when players' are sneaking.

change-1_14-hitbox - default: false (Boolean)

This changes the hitbox so that 1.14+ players can sneak under blocks, this may allow players to be missed by projectiles.

truncate-1_14-books - default: false (Boolean)

The page limit is now greater in 1.14 so this will limit pages at 50 instead of 100 (As some anti-exploit software may kick players).

fix-infested-block-breaking - default: true (Boolean)

Infested blocks are instantly breakable in future clients making them unable to be broken on older servers, this changes them back to stone.

fix-low-snow-collision - default: false (Boolean)

1.13 doesn't have collision for 1 layer of snow, this will send 2 layers of snow to have a similar effect.

fix-non-full-blocklight - default: true (Boolean)

Fixes 1.14 clients having a light value of 0 for non full blocks

fix-1_14-health-nan - default: true (Boolean)

Fixes walk animation not being shown when the health is set to Float.NaN

use-1_15-instant-respawn - default: false (Boolean)

Should 1.15+ clients be respawned instantly without showing the death screen.

ignore-long-1_16-channel-names - default: true (Boolean)

Should plugin channel names with more than 32 characters be ignored, CraftBukkit had this limit hardcoded until 1.16, so it is assumed that any software running ViaVersion has it.

forced-use-1_17-resource-pack - default: false (Boolean)

1.17 clients will be forced to accept a resource-pack on connection, where they disconnect if they decline.

resource-pack-1_17-prompt - default: '' (String)

1.17 clients will be displayed this message upon join.

cache-1_17-light - default: true (Boolean)

Caches light until chunks are unloaded to allow subsequent chunk update packets as opposed to instantly uncaching when the first chunk data is sent.
Only disable this if you know what you are doing.

armor-toggle-fix - default: true (Boolean)

Force-update 1.19.4+ player's inventory when they try to swap armor in a pre-occupied slot.

map-1_16-world-names - default: (String Map)

Example

Get the world names which should be returned for each vanilla dimension

translate-ocelot-to-cat - default: false (Boolean)

If disabled, tamed cats will be displayed as ocelots to 1.14+ clients on 1.13 servers. Otherwise, ocelots (tamed and untamed) will be displayed as cats.

enforce-secure-chat - default: false (Boolean)
Determines the value sent to 1.19+ clients on join if currently not accessible by ViaVersion.

It is not recommended to fake this value if your server is running 1.19 or later, as 1.20.5 clients have stricter chat handling and may get kicked otherwise.

handle-invalid-item-count - default: false (Boolean)

Handles items with invalid count values (higher than max stack size) on 1.20.3 servers.

hide-scoreboard-numbers default: false (Boolean)

Hides scoreboard numbers for 1.20.3+ clients on older server versions.

fix-1_21-placement-rotation default: true (Boolean)

Fixes 1.21+ clients on 1.20.5 servers placing water/lava buckets at the wrong location when moving fast, NOTE: This may cause issues with anti-cheat plugins.

cancel-swing-in-inventory default: true (Boolean)

If enabled, cancel swing packets sent while having an inventory opened on 1.15.2 and below servers. This can cause false positives with anti-cheat plugins.

1.9 & 1.10 clients on 1.8 servers options

This options only apply to you if you use a 1.8 server, these enable consistent visuals / gameplays across future versions where features have changed.

prevent-collision - default: true (Boolean)

In 1.9, players can now push each other. To prevent this when scoreboard teams are sent ViaVersion can set the collision to not happen so that the gameplay is balanced. (Plugins like ColoredTags use teams)

auto-team - default: true (Boolean)

Most servers don't use scoreboard plugins, in this case we send our own team to the player to prevent them colliding with other players. If you use a plugin like ColoredTags you should turn this off. Furthermore if you are having issues with Bungee and teams, consider turning it off too.

shield-blocking - default: true (Boolean) - Note: On BungeeCord the client will not be able to see them self blocking.

In 1.9, the blocking animation when you right click a sword was removed. It's not possible to simulate meaning 1.9 would not be able to see 1.8 blocking, as an alternative you can visually see these as shields. These do not change any game play and just allow 1.9 to see clients blocking and perform the blocking action with a sword themselves.

Disabling this will mean that 1.9 clients will not be able to see players blocking and will not be able to block properly.

no-delay-shield-blocking  - default: false (Boolean)

If this setting is active, the main hand is used instead of the off-hand to trigger the blocking of the player. With the main hand the blocking starts way faster. (Requires "show-shield-when-sword-in-hand" to be false)

show-shield-when-sword-in-hand - default: false (Boolean)

If this setting is active, the shield will appear immediately for 1.9+ when you hold a sword in your main hand. The shield disappears when you switch to another item. (Requires "shield-blocking" to be true)

simulate-pt - default: true (Boolean)

In 1.9, the player ticking is no longer triggered by the client sending packets. Therefore if we don't simulate sending them packets they won't be able to eat, use bows properly, drink potions. If you have a really simple server you can disable this but it's suggested that you do not.

nms-player-ticking - default: true (Boolean) - This feature is only available on Spigot / Sponge. (On BungeeCord it will use packet ticking)

To simulate player ticking we use NMS as an alternative to sending packets as sending packets can cause issues with anti-cheats. If you are experiencing TPS issues with ViaVersion it's suggested you try with this to false as it may reduce the effect on TPS. (Though it will still be there just not labelled as ViaVersion as it's internal server ticking)

bossbar-patch - default: true (Boolean)

In 1.9 bossbars are handled differently and sent via packets rather than using a mob. Should we automatically send the right packets to enable bossbars to work? You can disable this if you're having issues with too many boss bars appearing.

bossbar-anti-flicker - default: false (Boolean)

Due to the change in bossbars some plugins constantly update the health on the boss bar which may cause flickering, enabling this option will fix the health. However this will prevent the health from moving down and is not recommended unless you're having flickering issues.

use-new-effect-indicator - default: true (Boolean)

In 1.9, a new effect indicator was introduced in the top left of the screen. Enabling this option will allow players to see their active potion effects in the top left, this may be an advantage to 1.9+ players and you may wish to disable if you find this so.

use-new-deathmessages - default: false (Boolean)

In 1.9, death messages were added to the respawn screen. Enabling this option will allow players who died to see their death message on the respawn screen.

item-cache - default: true (Boolean) - This feature is only available on Spigot / Sponge. (On BungeeCord it will still work but be less efficient causing the server to send 1 extra packet)

In 1.9, packet changes to how items are used means that they aren't sent to the server. Item cache allows ViaVersion to save what items players are holding, this allows an efficient way of telling the server what items the player is using where it has been removed. Disabling this is not suggested as the alternative is looking up the item as the packet arrives which can cause latency and possibly lead to crashing a server.

replace-pistons - default: false (Boolean)

This option also affects 1.9/1.9.1 servers. In 1.10.1, Mojang introduced a way to ensure special blocks had data sent. This also introduced a crashing issue which meant when block 36 (extending piston special block) was sent it would crash the client. As a fail safe you can enable this option and we'll send the replacement id specified below instead. (This issue would only effect you if you use the special block 36)

replacement-piston-id - default: 0 (Integer)

When the previous option is enabled what block id should be sent instead, by default it is air 0 as block 36 is very similar to air.

left-handed-handling - default: true (Boolean)

This enables left hand to be used on 1.8 servers for newer clients.

chunk-border-fix default: false (Boolean)

Fix 1.9+ clients not rendering the far away chunks and improve chunk rendering when moving fast (Increases network usage and decreases client fps slightly)

cancel-block-sounds default: true (Boolean)

Tries to cancel block break/place sounds sent by 1.8 servers to 1.9+ clients to prevent them from playing twice

use-1_8-hitbox-margin default: true (Boolean)

If enabled, 1.21.11+ clients on 1.8 servers will get wider entity hitboxes when attacking with items