> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/minekube/gate/llms.txt
> Use this file to discover all available pages before exploring further.

# Modded Server Support

> Use Gate with Fabric and NeoForge modded Minecraft servers with Velocity modern forwarding

# Modded Server Support

Gate provides excellent compatibility with modded Minecraft servers including **Fabric** and **NeoForge**. This guide will help you set up Gate to work seamlessly with your modded servers using Velocity modern forwarding.

## Overview

Gate implements the same forwarding protocols as Velocity, providing comprehensive support for modded servers:

### Forwarding Modes Supported

* **Velocity modern forwarding** - Secure binary format with MAC authentication (Minecraft 1.13+)
* **Legacy BungeeCord forwarding** - Compatible with older versions and servers
* **BungeeGuard forwarding** - Enhanced security over legacy forwarding
* **No forwarding** - Basic proxy functionality without player data forwarding

<Info>
  For complete details on player information forwarding, see the [Velocity documentation](https://docs.papermc.io/velocity/player-information-forwarding/).
</Info>

## Fabric Server Setup

Gate works with Fabric out of the box, but you should add support for player info forwarding and modded content compatibility.

### Required Mods

#### FabricProxy-Lite (For Velocity Forwarding)

* **Purpose**: Enables Velocity modern forwarding for Fabric servers
* **Download**: [FabricProxy-Lite on Modrinth](https://modrinth.com/mod/fabricproxy-lite)
* **Requires**: [Fabric API](https://modrinth.com/mod/fabric-api) (dependency)

<Warning>
  Always download the mod version that matches your Minecraft server version. Check the compatibility table on the mod page.
</Warning>

#### CrossStitch (Recommended for Modded Content)

* **Purpose**: Improves support for Minecraft features extended by mods (custom argument types, etc.)
* **Download**: [CrossStitch on Modrinth](https://modrinth.com/mod/crossstitch)
* **Maintained by**: Velocity project (official)

### Configuration

<Steps>
  <Step title="Configure Fabric server">
    Edit `server.properties`:

    ```properties theme={null}
    server-port=25566
    online-mode=false
    motd=Fabric Server with Gate Proxy
    ```
  </Step>

  <Step title="Configure FabricProxy-Lite">
    Create or edit `config/FabricProxy-Lite.toml`:

    ```toml theme={null}
    hackOnlineMode = false
    hackEarlySend = false
    hackMessageChain = false
    disconnectMessage = "This server requires you to connect with Gate."
    secret = "your-secret-key-here"
    ```

    <Tip>
      If the config file doesn't appear after restart, you can use environment variables:

      ```bash theme={null}
      export FABRIC_PROXY_SECRET="your-secret-key-here"
      export FABRIC_PROXY_HACK_ONLINE_MODE=false
      export FABRIC_PROXY_HACK_EARLY_SEND=false
      export FABRIC_PROXY_HACK_MESSAGE_CHAIN=false
      ```
    </Tip>
  </Step>

  <Step title="Configure Gate">
    Edit your Gate `config.yml`:

    ```yaml theme={null}
    config:
      bind: 0.0.0.0:25565
      servers:
        fabric-server: localhost:25566
      try:
        - fabric-server
      forwarding:
        mode: velocity
        velocitySecret: 'your-secret-key-here'
      status:
        motd: |
          §bGate Proxy with Fabric
          §eVelocity Forwarding Enabled
    ```
  </Step>

  <Step title="Install mods and start">
    1. Install FabricProxy-Lite and CrossStitch in the server's `mods/` folder
    2. Ensure Fabric API is installed (required dependency)
    3. Start Gate, then start your Fabric server
  </Step>
</Steps>

<Warning>
  The `secret` in FabricProxy-Lite.toml **must match** the `velocitySecret` in Gate's config.yml.
</Warning>

## NeoForge Server Setup

Gate works with NeoForge servers using the Proxy-Compatible-Forge mod for Velocity modern forwarding.

### Required Mods

#### Proxy-Compatible-Forge (For Velocity Forwarding)

* **Purpose**: Enables Velocity modern forwarding for NeoForge servers
* **Download**: [Proxy-Compatible-Forge on GitHub](https://github.com/adde0109/Proxy-Compatible-Forge/releases)
* **Supports**: NeoForge 1.16.5 - 1.20.x+

<Warning>
  Ensure you download the correct mod version for your NeoForge server version. Check the releases page for compatibility.
</Warning>

### Configuration

<Steps>
  <Step title="Configure NeoForge server">
    Edit `server.properties`:

    ```properties theme={null}
    server-port=25567
    online-mode=false
    motd=NeoForge Server with Gate Proxy
    ```
  </Step>

  <Step title="Configure Proxy-Compatible-Forge">
    Create or edit `config/pcf-common.toml`:

    ```toml theme={null}
    #Modern Forwarding Settings
    [modernForwarding]
        forwardingSecret = "your-secret-key-here"

    [commandWrapping]
        #List of argument types that are not vanilla but are integrated into the server
        moddedArgumentTypes = ["livingthings:sampler_types"]
    ```
  </Step>

  <Step title="Configure Gate">
    Edit your Gate `config.yml`:

    ```yaml theme={null}
    config:
      bind: 0.0.0.0:25565
      servers:
        neoforge-server: localhost:25567
      try:
        - neoforge-server
      forwarding:
        mode: velocity
        velocitySecret: 'your-secret-key-here'
      status:
        motd: |
          §bGate Proxy with NeoForge
          §eVelocity Forwarding Enabled
    ```
  </Step>

  <Step title="Install mod and start">
    1. Install Proxy-Compatible-Forge in the server's `mods/` folder
    2. Start Gate, then start your NeoForge server
  </Step>
</Steps>

## Multi-Server Setup

You can run both Fabric and NeoForge servers behind the same Gate proxy:

```yaml theme={null}
config:
  bind: 0.0.0.0:25565
  servers:
    fabric-server: localhost:25566 # Fabric server
    neoforge-server: localhost:25567 # NeoForge server
    vanilla-server: localhost:25568 # Vanilla server
  try:
    - fabric-server
    - neoforge-server
    - vanilla-server
  forwarding:
    mode: velocity
    velocitySecret: 'shared-secret-key'
  status:
    motd: |
      §bGate Multi-Server Network
      §eFabric • NeoForge • Vanilla
```

<Info>
  All servers in a network should use the same `velocitySecret` for consistency.
</Info>

## Comparison Table

| Feature                   | Fabric           | NeoForge               |
| ------------------------- | ---------------- | ---------------------- |
| **Forwarding Mod**        | FabricProxy-Lite | Proxy-Compatible-Forge |
| **Required Dependency**   | Fabric API       | None                   |
| **Recommended Addon**     | CrossStitch      | -                      |
| **Velocity Forwarding**   | ✅ Yes            | ✅ Yes                  |
| **Configuration Format**  | TOML             | TOML                   |
| **Environment Variables** | ✅ Supported      | ❌ Not supported        |

## Troubleshooting

<AccordionGroup>
  <Accordion title="Connection Refused">
    **Possible causes:**

    * Server not running on configured port
    * Firewall blocking connections
    * Server startup errors

    **Solutions:**

    1. Check server ports with `netstat -tlnp | grep java`
    2. Verify firewall allows connections: `sudo ufw status`
    3. Check server logs for startup errors
  </Accordion>

  <Accordion title="Forwarding Issues">
    **Symptoms:**

    * "Failed to verify username" errors
    * Players kicked during login
    * UUID conflicts

    **Solutions:**

    1. **Secret mismatch** - Ensure `velocitySecret` matches in both Gate and mod configs
    2. **Online mode** - Must be `false` on backend servers when using forwarding
    3. **Mod compatibility** - Verify the forwarding mod supports your server version
  </Accordion>

  <Accordion title="Mod Compatibility Issues">
    **Incompatible Mods:**

    * **NeoVelocity 1.2.4** - Incompatible with NeoForge 21.8.x
    * **NeoForwarding 1.3.0** - Only supports older NeoForge versions

    **Solution:**
    Use Proxy-Compatible-Forge instead for modern NeoForge versions.
  </Accordion>
</AccordionGroup>

## Security Considerations

When running modded servers:

* **Use Velocity forwarding** when possible for better security than legacy forwarding
* **Configure firewalls** to block direct access to backend servers (only allow from Gate IP)
* **Keep secrets private** - Never commit `velocitySecret` to version control
* **Regular updates** - Keep Gate and mods updated for security patches

<Warning>
  Never use the same `velocitySecret` across different networks or environments (dev/prod).
</Warning>

## Getting Help

If you encounter issues:

1. **Check the logs** - Both Gate and server logs often contain helpful error messages
2. **Verify versions** - Ensure compatibility between Gate, server version, and mods
3. **Community support** - Join the [Gate Discord](https://minekube.com/discord) for general questions
4. **Report bugs** - For reproducible bugs with logs and steps, use [Gate GitHub Issues](https://github.com/minekube/gate/issues)

<Info>
  This guide covers the most common modded server setups. For specific mod compatibility questions, consult the mod's documentation or community.
</Info>