ViaLegacy/README.md

ViaLegacy

ViaVersion addon to add support for EVERY Minecraft server version (Classic, Alpha, Beta, Release).

ViaLegacy is not usable by itself as a standalone software, as it is an addon for ViaVersion which adds more protocol translators. ViaLegacy is intended to be implemented in a ViaVersion based protocol translator.

If you are looking to implement ViaLegacy in your own software you can start by reading the Usage section.
If you just want to use ViaLegacy yourself you can check out some projects which implement it in the Projects section.

Supported Server protocols

• Classic (c0.0.15 - c0.30 including CPE)
• Alpha (a1.0.15 - a1.2.6)
• Beta (b1.0 - b1.8.1)
• Release (1.0.0 - 1.7.10)

The lowest supported client version from which ViaLegacy can translate is 1.7.2.

Projects implementing ViaLegacy

• ViaProxy: Standalone proxy which uses ViaVersion to translate between Minecraft versions. Allows Minecraft 1.7+ clients to join to any version server.
• ViaFabricPlus: Fabric mod for the latest Minecraft version with QoL fixes and enhancements to the gameplay.

Releases

Gradle/Maven

To use ViaLegacy with Gradle/Maven you can use the ViaVersion maven server:

repositories {
    maven { url "https://repo.viaversion.com" }
}

dependencies {
    implementation("net.raphimc:ViaLegacy:x.x.x") // Get latest version from releases
}

<repositories>
    <repository>
        <id>viaversion</id>
        <url>https://repo.viaversion.com</url>
    </repository>
</repositories>

<dependencies>
    <dependency>
        <groupId>net.raphimc</groupId>
        <artifactId>ViaLegacy</artifactId>
        <version>x.x.x</version> <!-- Get latest version from releases -->
    </dependency>
</dependencies>

Jar File

If you just want the latest jar file you can download it from GitHub Actions or the ViaVersion Jenkins.

Usage

ViaLegacy requires you to have an already functional ViaVersion implementation for your platform. If you don't have one you can check out ViaLoader for an abstracted and simplified, but still customizable implementation. You can also go to the other ViaVersion repositories and look at their server and proxy implementations.

Base Implementation

Note: In case you use ViaLoader you can skip "ViaLegacy platform implementation" and "Loading the platform" as ViaLoader already does that for you.

ViaLegacy platform implementation

To get started you should create a class which implements the ViaLegacy platform interface. Here is an example:

public class ViaLegacyPlatformImpl implements ViaLegacyPlatform {

    public ViaLegacyPlatformImpl() {
        this.init(this.getDataFolder());
    }

    @Override
    public Logger getLogger() {
        return Via.getPlatform().getLogger();
    }

    @Override
    public File getDataFolder() {
        return Via.getPlatform().getDataFolder();
    }

}

This is a very basic implementation which just uses the ViaVersion logger and data folder.

Loading the platform

After you have created your platform implementation you should load it in your ViaVersion implementation. Here is an example:

Via.getManager().addEnableListener(ViaLegacyPlatformImpl::new);

Make sure to add the enable listener before the Via manager is initialized (((ViaManagerImpl) Via.getManager()).init();).

It is also highly recommended to increase the max protocol path size of ViaVersion. The default value is 50 which means there can't be more than 50 protocols in one pipeline. This can get exceeded by ViaLegacy. You can increase the path size by adding the following lines after the Via manager is initialized:

Via.getManager().getProtocolManager().setMaxProtocolPathSize(Integer.MAX_VALUE); // Allow Integer.MAX_VALUE protocols in the pipeline
Via.getManager().getProtocolManager().setMaxPathDeltaIncrease(-1); // Allow unlimited protocol path size increase
((ProtocolManagerImpl) Via.getManager().getProtocolManager()).refreshVersions(); // Refresh the version paths

Implementing the netty changes

ViaLegacy requires you to make some changes to your netty pipeline where ViaVersion is being added into the pipeline. ViaLegacy needs to have custom netty handlers in the pipeline which handle <= 1.6.4 connections. This is required due to the way how <= 1.6.4 (called pre-netty protocol) protocol differs.

To implement the changes you should add something similar to the following lines to your netty pipeline (After the ViaVersion handlers are added):

if (serverTargetVersion.olderThanOrEqualTo(LegacyProtocolVersion.r1_6_4)) { // Only add those handlers if the server version is <= 1.6.4
    // You can either add a codec (if your pipeline is built for that)
    channel.pipeline().addBefore("length-codec", "vialegacy-pre-netty-length-codec", new PreNettyLengthCodec(user));
    // or two seperate netty handlers
    // channel.pipeline().addBefore("length-decoder", "vialegacy-pre-netty-length-prepender", new PreNettyLengthPrepender(user));
    // channel.pipeline().addBefore("length-encoder", "vialegacy-pre-netty-length-remover", new PreNettyLengthRemover(user));
}

In case you use ViaLoader and the VLPipeline (or the VLLegacyPipeline), you don't need to make these modifications anymore, as the VLPipeline/VLLegacyPipeline already does it automatically.

Implementing the platform specific providers

The platform specific providers are all optional (except for EncryptionProvider and GameProfileFetcher) and only required if you want to use the features which require them.
To implement a provider you can simply call Via.getManager().getProviders().use(TheNameOfTheProvider.class, new YouImplementationOfThatProvider()); after the Via manager is initialized.

EncryptionProvider

The encryption provider is used to encrypt the connection to the server if the server version is 1.2.5 - 1.6.4.
Those servers enable the encryption at a different point in the login process than >= 1.7.2 servers. This means that your platform must not encrypt the connection when receiving the LoginKey packet from the server, but instead store the key and encrypt the connection when the method in the provider is invoked.
If your platform supports online mode authentication you also should not always do a joinServer request when receiving the LoginKey packet, but only when userConnection.get(ProtocolMetadataStorage.class).authenticate is true.

GameProfileFetcher

The game profile fetcher is used to fetch the game profile of a player if the server version is <= 1.7.10. This is required because the game profile or UUID of players is not sent by the server in <= 1.7.10. The GameProfileFetcher is only used when legacy-skin-loading or legacy-skull-loading is set to true in the config. If you don't plan to use those options you don't need to implement this provider. Here is an example implementation using the Steveice10 AuthLib:

public class AuthLibGameProfileFetcher extends GameProfileFetcher {

    private static final SessionService sessionService = new SessionService();
    private static final ProfileService profileService = new ProfileService();

    @Override
    public UUID loadMojangUUID(String playerName) throws ExecutionException, InterruptedException {
        final CompletableFuture<com.github.steveice10.mc.auth.data.GameProfile> future = new CompletableFuture<>();
        profileService.findProfilesByName(new String[]{playerName}, new ProfileService.ProfileLookupCallback() {
            @Override
            public void onProfileLookupSucceeded(com.github.steveice10.mc.auth.data.GameProfile profile) {
                future.complete(profile);
            }

            @Override
            public void onProfileLookupFailed(com.github.steveice10.mc.auth.data.GameProfile profile, Exception e) {
                future.completeExceptionally(e);
            }
        });
        if (!future.isDone()) {
            future.completeExceptionally(new ProfileNotFoundException());
        }
        return future.get().getId();
    }

    @Override
    public GameProfile loadGameProfile(UUID uuid) throws ProfileException {
        final com.github.steveice10.mc.auth.data.GameProfile inProfile = new com.github.steveice10.mc.auth.data.GameProfile(uuid, null);
        final com.github.steveice10.mc.auth.data.GameProfile mojangProfile = sessionService.fillProfileProperties(inProfile);

        final GameProfile gameProfile = new GameProfile(mojangProfile.getName(), mojangProfile.getId());
        for (com.github.steveice10.mc.auth.data.GameProfile.Property prop : mojangProfile.getProperties()) {
            gameProfile.addProperty(new GameProfile.Property(prop.getName(), prop.getValue(), prop.getSignature()));
        }
        return gameProfile;
    }

}

OldAuthProvider

The old auth provider is used to authenticate the player if the server version is <= 1.2.5 and has online mode enabled. This is required as <= 1.2.5 servers do not enable encryption at all and authenticate at a different point in the login process.
The implementation of this provider requires the implementer to be able to send a joinServer request to the mojang servers using the supplied server hash.
The default implementation of this provider simply throws an Exception indicating that online mode is not supported by this implementation.

AlphaInventoryProvider

The alpha inventory provider is used to get/set the inventory contents of the player if the server version is <= Alpha 1.2.6. This is required as <= Alpha 1.2.6 servers handle the inventory fully clientside and the client is expected to send the whole inventory contents to the server when it changes anything.
The default implementation of this provider uses an inventory tracking system which tracks the inventory contents of the player.

ClassicWorldHeightProvider

The classic world height provider is used to get the maximum world height the client is able to handle. Classic server worlds can be up to 1024 blocks high, but <= 1.16.5 client can't handle worlds higher than 256 blocks. The implementation of this provider requires the implementer to be able to determine the maximum supported world height of a given client.
The default implementation of this provider states that the client supports 128 blocks high worlds.

Implementing this provider to have worlds higher than 256 blocks requires heavy modification of ViaVersion code which the implementer has to do on their own. For a reference implementation you can take a look at how ViaProxy implements it.

ClassicMPPassProvider

The classic MP pass provider is used to get the MP pass (Authentication token) of a player if the server version is <= Classic 0.30. This is required for joining classic servers with enabled online mode.
The implementation of this provider requires the implementer to be able to get the MP pass of a given player.
The default implementation of this provider simply returns "0" which indicates to the server that the client does not have a valid MP pass.
For a reference implementation you can take a look at how ViaProxy implements it.

Contact

If you encounter any issues, please report them on the issue tracker.
If you just want to talk or need help implementing ViaLegacy feel free to join the ViaVersion Discord.