Skip to main content

​
Overview

The ViaVersion system allows clients running newer YSFlight versions to connect to servers running older versions. This enables server operators to maintain compatibility with a wider range of clients without updating their core YSFlight server.
ViaVersion is currently experimental. While it works in most cases, you may encounter issues with certain client-server version combinations.

​
How It Works

When a client connects to the proxy, Sakuya AC intercepts the version handshake and translates the client’s version to match the server’s expected version. This allows seamless communication between mismatched versions.

​
Configuration

​
Enabling ViaVersion

In your config.py, set the following variables:
config.py
# Your native YSFlight server version
YSF_VERSION = 20150425

# Enable version translation
VIA_VERSION = True
​
YSF_VERSION
int
required
The version of your native YSFlight server. This is the version that all client connections will be translated to.
This must match your actual YSFlight server version exactly. Incorrect values will cause connection failures.
​
VIA_VERSION
bool
default:"True"
Enables or disables the ViaVersion system.
  • True - Allow clients from different versions to connect
  • False - Only allow clients matching YSF_VERSION

​
Supported Versions

Sakuya AC has been tested with: Server Version:
  • YSFlight 20150425 ✓ Fully tested
Client Versions:
  • Post-20150425 versions are supported when VIA_VERSION = True
  • Specific tested client versions are not documented
While other server versions may work, only 20150425 is officially supported and tested.

​
Version Translation Process

The ViaVersion system uses the genViaVersion() function to generate version translation packets: 
def genViaVersion(username: str, finalVersion: int):
    """
    Generates Packets for porting the version
    """
    padding = 16-len(username)
    byteUserame = []
    for char in username:
        byteUserame.append(char.encode('ascii'))
    return pack("II16cI", 24, 1, *byteUserame+(padding*[b"\x00"]), finalVersion)

​
Packet Structure

The version translation packet contains:
FieldTypeDescription
Packet sizeunsigned intTotal packet size (24 bytes)
Command IDunsigned intCommand identifier (1)
Usernamechar[16]Client username (padded to 16 bytes)
Versionunsigned intTarget server version

​
Translation Flow

1

Client Initiates Connection

The client sends its version information during the initial handshake.
2

Proxy Intercepts Version

Sakuya AC intercepts the client’s version packet and reads the client version.
3

Generate Translation Packet

If VIA_VERSION = True, the proxy generates a new version packet using genViaVersion() with:
  • The client’s username
  • The server’s YSF_VERSION as the target version
4

Forward to Server

The translated packet is sent to the native YSFlight server, which sees the client as matching its version.
5

Establish Connection

The server accepts the connection, and the proxy maintains the session between client and server.

​
Limitations

​
Known Issues

If the client and server versions have significant protocol differences, you may experience:
  • Packet misalignment
  • Missing or corrupted game data
  • Unexpected disconnections
Solution: Test thoroughly with your specific version combination.
Clients using newer YSFlight versions won’t have access to features added after the server version:
  • New aircraft
  • Updated physics
  • Additional commands
Solution: This is expected behavior. The client must operate within the server’s capabilities.
Usernames are limited to 16 bytes due to the packet structure:
padding = 16-len(username)
Solution: Ensure usernames don’t exceed 16 characters.

​
Unsupported Scenarios

  • Downgrading client versions: ViaVersion translates clients to older server versions, not vice versa
  • Server versions before 20150425: Only 20150425 is tested and officially supported
  • Custom protocol modifications: If your YSFlight server uses modified protocols, ViaVersion may not work

​
When to Disable ViaVersion

Strict Version Control

If you want to ensure all players use the exact same YSFlight version for competitive fairness.

Protocol Issues

If you experience frequent disconnections or desyncs with newer clients.

Custom Server Mods

If your server uses custom protocol modifications that conflict with version translation.

Debugging

When troubleshooting connection issues, disable ViaVersion to rule it out as the cause.
To disable ViaVersion:
config.py
VIA_VERSION = False

​
Testing Version Compatibility

When enabling ViaVersion, follow this testing procedure:
1

Backup Your Configuration

Save a copy of your working config.py before enabling ViaVersion.
2

Enable ViaVersion

VIA_VERSION = True
3

Test Basic Connection

  1. Connect with a client matching your server version
  2. Verify normal gameplay works
  3. Check logs for errors
4

Test Newer Client Versions

  1. Connect with a newer YSFlight client
  2. Test core functionality:
    • Chat messages
    • Aircraft spawning
    • Flight controls
    • Weapon systems
  3. Monitor for desyncs or errors
5

Load Testing

Test with multiple clients of different versions connected simultaneously.
6

Monitor Logs

Enable debug logging to catch any version-related issues:
LOGGING_LEVEL = DEBUG

​
Troubleshooting

​
Clients can’t connect

Ensure YSF_VERSION in config.py exactly matches your YSFlight server:
# Check your YSFlight server version
# Usually found in server logs or config files

# In config.py
YSF_VERSION = 20150425  # Must match exactly
If VIA_VERSION = False, only clients with matching versions can connect:
# Allow all versions
VIA_VERSION = True

# Strict version matching
VIA_VERSION = False
Enable debug logging to see version translation details:
from logging import DEBUG
LOGGING_LEVEL = DEBUG
Look for version-related errors in the output.

​
Desync or corrupted data

If the client version is significantly newer than the server, protocol differences may cause issues.Solution: Either:
  • Update your YSFlight server to a newer version
  • Advise clients to use an older YSFlight version
  • Disable ViaVersion and enforce strict version matching
Different versions may have different packet structures.Solution: Monitor logs for packet errors and consider disabling ViaVersion if issues persist.

​
Performance issues

While minimal, version translation adds processing overhead.Solution: This overhead is negligible in most cases. If performance is critical, profile your server to identify bottlenecks.

​
Best Practices

  1. Test thoroughly - Always test with multiple client versions before deploying to production
  2. Monitor logs - Keep an eye on logs after enabling ViaVersion to catch early issues
  3. Document supported versions - Let your players know which client versions are tested and supported
  4. Have a fallback plan - Keep ViaVersion disabled configuration ready in case of issues
  5. Update gradually - If updating your server version, test ViaVersion at each step

​
Implementation Reference

The ViaVersion system is implemented in lib/YSviaversion.py. The core function is compact but critical:
lib/YSviaversion.py
from struct import pack

def genViaVersion(username: str, finalVersion: int):
    """
    Generates Packets for porting the version
    """
    padding = 16-len(username)
    byteUserame = []
    for char in username:
        byteUserame.append(char.encode('ascii'))
    return pack("II16cI", 24, 1, *byteUserame+(padding*[b"\x00"]), finalVersion)
Key points:
  • Username is encoded to ASCII and padded to 16 bytes
  • Packet format: II16cI (2 ints, 16 chars, 1 int)
  • Total packet size is fixed at 24 bytes
  • Command ID is always 1
  • finalVersion is the target server version from YSF_VERSION

​
Further Reading

Build docs developers (and LLMs) love

Get started for freeTalk to us