Skip to content

FAQ

Jump to bottom
Fed43 edited this page Oct 10, 2026 · 1 revision

FAQ

Frequently asked questions about MineAlphaProxy.

General

What is MineAlphaProxy?

MineAlphaProxy is a Minecraft proxy server written from scratch in Java. It sits between players and backend servers, forwarding player connections. It has its own plugin API and bundles ViaProxy for multi-version client support.

Is it a fork of Velocity or BungeeCord?

No. MineAlphaProxy is an independent implementation. No code was copied from Velocity or BungeeCord. It uses a Velocity-compatible API layer only for plugin compatibility - similar to how OpenJDK implements the Java specification without being a fork of Oracle JDK.

What Minecraft versions does it support?

  • Backend server: 1.20.2 or newer (Paper recommended)
  • Client versions: 1.7.2 to 26.3 - through the built-in ViaProxy

See ViaProxy for details.

What license is it under?

MIT License. You can use, modify, and redistribute it - even commercially. See the LICENSE file.

Is it stable?

No. The current version is 1.0.1-ALPHA. It runs, handles premium and cracked clients, supports plugins, and works with modern forwarding. But it is not battle-tested for large networks yet. Use it for small-to-medium servers or testing.

Installation

How do I install it?

See the Installation page for step-by-step instructions.

What Java version do I need?

Java 21 or newer. Get it from https://adoptium.net/temurin/releases/?version=21.

It runs on Windows / Linux / macOS?

Yes. MineAlphaProxy is pure Java - it runs anywhere with Java 21 installed.

How much RAM does it need?

Rule of thumb: 512 MB + 1 MB per concurrent player.

  • 10 players: ~600 MB
  • 50 players: ~1 GB
  • 100 players: ~1.5 GB
  • 500 players: ~4 GB

Set heap explicitly:

java -Xms1G -Xmx4G -jar MineAlphaProxy-1.0.1-ALPHA.jar

Can I run it on a shared host?

Yes, if the host allows custom JARs and outbound/inbound ports. You need:

  • A port (default 25577)
  • A port for ViaProxy (default 25576)
  • Ability to upload custom JAR

Configuration

Where is the config file?

core.yml in the same folder as the JAR. It is auto-created on first run. Full reference: Configuration.

Can I use my existing velocity.toml?

Yes. On first launch, if core.yml does not exist and velocity.toml is present, MineAlphaProxy imports its settings automatically.

Can I use my existing BungeeCord config.yml?

Yes. Same mechanism - if config.yml from BungeeCord is present, it is imported.

How do I change the port?

Edit core.yml:

bind:
  port: 25578

Restart the proxy.

How do I change the MOTD?

Edit core.yml:

bind:
  motd: "§aWelcome to my server!"

Legacy § color codes and the %proxy_name% placeholder are supported. Reload with reload in the console.

Can I have different MOTDs on different ports?

Not yet. One MOTD for all connections. Multi-listener support is planned for a future version.

How do I switch the language?

In core.yml:

language: "en"

Available: en, ru. Add your own by creating lang/<code>.yml and setting language to it.

Networking

What ports does MineAlphaProxy use?

Port Purpose Configurable
25577 Proxy (direct) Yes, in core.yml
25576 ViaProxy No, hardcoded

Which port should players connect to?

Port 25576 - through ViaProxy. It works with any client version.

Connecting directly to 25577 only works if the client version exactly matches the backend version.

Can I change the ViaProxy port?

Not through core.yml. To change it, edit ViaProxyLauncher.java in the source and rebuild:

ViaProxyLauncher.start(25576, config.bind.port, logger);

Change 25576 to your desired port.

Do I need to open both ports in the firewall?

Yes - 25576 (ViaProxy) and 25577 (proxy) must be reachable.

Or use a reverse proxy (nginx, HAProxy) to terminate TLS and forward to 25576 on localhost.

Can I run MineAlphaProxy behind Cloudflare?

Cloudflare proxies HTTP/HTTPS, not Minecraft. Use Cloudflare Spectrum (paid) or TCPShield for DDoS protection in front of the proxy.

Forwarding

What is modern forwarding?

A mechanism to pass the player's real IP, UUID, and skin from the proxy to the backend. Required for any proxy - without it, backends see every player as coming from 127.0.0.1.

Full details: Modern Forwarding.

Do I need to configure forwarding on the backend?

Yes. On the backend's paper-global.yml:

proxies:
  velocity:
    enabled: true
    online-mode: true
    secret: "YOUR_SECRET_FROM_FORWARDING_SECRET_FILE"

Where do I find the secret?

In forwarding.secret next to the proxy JAR. It contains a single hex line. Copy it into the backend's paper-global.yml.

Can I disable forwarding?

Yes - set in core.yml:

forwarding:
  mode: "none"

But the backend will see 127.0.0.1 for every player and generate offline UUIDs. Not recommended for production.

Does forwarding work with cracked clients?

Yes. Modern forwarding passes the UUID the client sent - either the real Mojang UUID (premium) or an offline UUID (cracked). Backends handle both.

For security with cracked clients, install an auth plugin (see below).

"Unable to verify player details"

See Troubleshooting → Unable to verify player details.

Clients

Can premium and cracked clients play together?

Yes. Both connect normally:

  • Premium - client sends real Mojang UUID
  • Cracked - client sends offline UUID

However, without an auth plugin, cracked players can impersonate premium names. Use an auth plugin like SimpleLogin, SecurePlayer, or similar.

Can Bedrock (mobile, console) clients connect?

Yes - through ViaBedrock, which is bundled inside ViaProxy. Java players see Bedrock players as regular Java accounts.

Test this feature before opening it to players - Bedrock support is complex.

Which client versions can connect?

1.7.2 to 26.3. See ViaProxy.

Clients older than 1.7.2 (like Beta 1.7.3) may work but are not tested.

Can I limit which versions are allowed?

Not yet. All supported versions are accepted. Version whitelisting is planned.

Plugins

What plugin APIs are supported?

Two:

Folder API
MineAlphaPlugins/ Own MineAlpha API
VelocityPlugins/ Velocity compatibility layer

How do I install a plugin?

  1. Download the plugin's .jar file
  2. Place it in the correct folder:
    • MineAlpha plugins → MineAlphaPlugins/
    • Velocity plugins → VelocityPlugins/
  3. Restart the proxy
  4. Check the console log for Loaded ... plugin: <name>

Where can I download plugins?

The official collection: https://github.com/MineAlphaStudio/MineAlphaPlugins

Will my old Velocity plugin work?

Maybe. Simple plugins (events, basic commands) usually work. Complex plugins that use:

  • Brigadier commands
  • Plugin messaging
  • Custom Velocity internals
  • NMS injection

...will likely fail with NoClassDefFoundError.

Check the console after loading for errors.

Can I write my own plugin?

Yes. See Writing Plugins - a complete guide with examples.

My plugin fails to load with NoClassDefFoundError

The plugin uses an API class that MineAlphaProxy does not implement. Two options:

  1. Check if a MineAlpha version exists
  2. Report the missing class: https://github.com/MineAlphaStudio/MineAlphaProxy/issues

Support

Where do I get help?

How do I report a bug?

Open an issue with:

  1. Full console log (from startup to error)
  2. Your core.yml (redact forwarding.secret)
  3. MineAlphaProxy version
  4. Java version (java -version)
  5. OS
  6. List of loaded plugins
  7. Steps to reproduce

Redact IPs and secrets before posting.

Will there be a Discord server?

Planned for after the first stable release.

Can I contribute?

Yes. Pull requests are welcome:

  • Bug fixes
  • Documentation improvements
  • New plugins
  • Translations

For large changes, open an issue first to discuss.

Is there a paid version?

No. MineAlphaProxy is free and open source under MIT license.

Development

How do I build from source?

git clone https://github.com/MineAlphaStudio/MineAlphaProxy.git
cd MineAlphaProxy
./gradlew clean build

Output: build/libs/MineAlphaProxy-1.0.1-ALPHA.jar.

Do I need ViaProxy to build?

No. ViaProxy is optional. Without libs/ViaProxy.jar, the build still succeeds - just no multi-version support at runtime.

Download ViaProxy from: https://github.com/ViaVersion/ViaProxy/releases

What Java version is required to build?

Java 21 for the toolchain. The build output targets Java 17 bytecode for compatibility.

How is the code structured?

See the main repository. Main packages:

Package Purpose
com.minealphaproxy Core (MineAlphaProxy, BuildInfo)
com.minealphaproxy.network Netty pipeline, protocol handling
com.minealphaproxy.config Config loading and validation
com.minealphaproxy.command Console commands
com.minealphaproxy.plugin Plugin loaders
com.minealphaproxy.api Public plugin API
com.minealphaproxy.compat.velocity Velocity compatibility layer
com.minealphaproxy.compat.viaproxy ViaProxy child process

Can I use it in my own project?

Yes, under MIT license. You can:

  • Fork it
  • Modify it
  • Use it commercially
  • Ship it as part of your product

Just keep the copyright notice.

Will there be a Maven/Gradle artifact?

Planned after 1.0.1. The goal is to publish the API package to Maven Central so plugin developers can use:

compileOnly("com.minealphaproxy:api:1.0.1")

Until then, use compileOnly(files("path/to/MineAlphaProxy.jar")).

Roadmap

What's next?

Planned for 1.1.0:

  • Player server switching (/server, /send) - real implementation
  • PlayerChatEvent fired to plugins
  • Permissions API (LuckPerms-compatible)
  • Plugin configuration helper

1.2.0 and later:

  • Tab completion for console commands
  • Command tab completion for players
  • Multi-listener support (multiple ports, different MOTDs)
  • Maven artifact publication
  • Config hot-reload improvements

Notes

Something feels missing

Open an issue: https://github.com/MineAlphaStudio/MineAlphaProxy/issues

Include "FAQ" in the title.

This page helped

Star the repository: https://github.com/MineAlphaStudio/MineAlphaProxy

Want a new feature

Open an issue with a feature request label. Describe:

  • What the feature should do
  • Why you need it
  • How you imagine it working

Next Steps

Clone this wiki locally