VirtualHostCommandPlugin: Virtual Hosts for Minecraft Servers

What Is the VirtualHostCommandPlugin?

If you run a Minecraft server with multiple worlds or game modes, you know the challenge of directing players to the right place right from the moment they join. The VirtualHostCommandPlugin (often called VHostPlugin) solves this elegantly. It’s a Bukkit-compatible plugin that listens to the hostname a player used to connect to your server and then executes custom commands, sets a specific MOTD, or even displays a unique server icon based on that hostname. Think of it like Apache virtual hosts, but for Minecraft.

How It Works

When a player connects to your server, the client sends the exact address they typed (or the domain they clicked). The plugin captures that hostname—whether it’s a domain like hub.yourserver.com or a raw IP—and matches it against rules you define in a configuration file. If a match is found, the plugin runs a list of commands you’ve specified, optionally filtered by the world the player is currently in. You can also customize the server’s MOTD and icon for each virtual host, giving every subdomain its own personality.

Key Features at a Glance

• Hostname-based command execution: Run any console command when a player joins via a specific domain or IP.
• World filtering: Use ifInWorld and ifNotInWorld regex conditions to apply commands only when the player is (or isn’t) in a certain world.
• Dynamic MOTD and server icon: Show different messages and icons in the server list depending on the hostname pinged (works best on PaperMC).
• Placeholder support: Use %player%, %hostname%, and %port% in commands for personalized actions.
• Case-insensitive matching: Hostname detection ignores capitalization, so Hub.Example.com and hub.example.com are treated the same.
• Lightweight and focused: No bloat—just a single purpose plugin that integrates seamlessly with Bukkit, Spigot, and Paper.

Configuration Walkthrough

After placing the plugin JAR in your server’s plugins folder and restarting, you’ll find a config.yml inside plugins/VirtualHostCommandPlugin. The structure is straightforward. Here’s a typical setup:

vhosts:
  hub:
    hostname: hub.myworld.com
    ifNotInWorld: "^world_hub"
    commands:
      - gamemode %player% survival
      - mv tp %player% world_hub
      - msg %player% Welcome to the hub!
  pvp:
    hostname: pvp.myworld.com
    commands:
      - gamemode %player% survival
      - mv tp %player% world_pvp
      - msg %player% Prepare for battle!
  example_ip:
    hostname: "123.45.67.89"
    motd: "&aWelcome to the private server!"
    icon: server-icon-example.png
    commands:
      - msg %player% You connected via IP.

Each entry under vhosts defines a virtual host. The hostname field is mandatory and can be a domain, subdomain, or IP address. The plugin uses a “starts-with” match, so example.com will also match example.com:25565. The commands list runs in order when a player joins through that hostname. You can use ifInWorld or ifNotInWorld to restrict execution to players already in a specific world (useful for cross-world teleportation chains). The motd and icon options let you override the server’s ping response, but keep in mind that not all server implementations supply the hostname during the ping event. PaperMC includes a workaround that the plugin leverages to fetch the correct hostname, so MOTD and icon per vhost work reliably there.

Practical Use Cases

Imagine you run a network with a central hub and several minigame worlds. By pointing hub.example.com and pvp.example.com to the same server IP, you can automatically teleport players to the right world the moment they log in. No need for signs, portals, or manual commands. You can also greet players with a custom message that mentions the domain they used, reinforcing your branding. For servers that share a single IP but want to appear as distinct servers in the multiplayer list, the MOTD and icon feature creates that illusion—each subdomain shows its own description and thumbnail.

Another clever application is region-based routing. If you have players from different communities connecting via different CNAME records, you can set language-specific welcome messages or apply different game rules. The plugin’s simplicity makes it a powerful tool for server networks, RPG realms, or even just a creative and survival hybrid setup.

Getting the Plugin onto Your Server

Installation is as simple as dropping the JAR into your server’s plugins directory, but if you prefer a more streamlined approach, the foxygame.net launcher makes the process even smoother. This modern, flexible launcher lets you browse and install plugins like VirtualHostCommandPlugin directly from its menu, so you can skip manual downloads and focus on configuring your virtual hosts right away. Whether you’re managing a small private server or a large network, having a convenient tool to handle mods and plugins saves time and reduces errors.

For those who prefer the traditional route, you can grab the latest build from the distribution folder of the project’s GitHub repository (cgaffga/mc-vhost). Just place the JAR in your server’s plugins folder, restart, and edit the generated config.yml. The plugin requires no additional dependencies and works out of the box on CraftBukkit, Spigot, and Paper.

Important Notes and Limitations

• Bedrock / Geyser compatibility: If you use Geyser to allow Bedrock clients, the proxy does not forward the hostname by default. You must set forward-hostname: true in Geyser’s config.yml. Even then, Geyser supplies only the IP address, so each domain must resolve to a distinct IP for vhost detection to work with Bedrock players.
• Ping event hostname: Many server implementations do not include the hostname in the server list ping event. This means MOTD and icon per vhost may not always display correctly. PaperMC users benefit from a built-in workaround that the plugin uses to retrieve the hostname during pings, making the feature functional on that platform.
• Command order: Commands run sequentially. If you teleport a player to a new world, subsequent commands will execute in that new world’s context, which is usually what you want.
• Regex in world filters: The ifInWorld and ifNotInWorld fields accept Java regular expressions. Anchor them with ^ and $ if you need an exact match, or use partial patterns for flexibility.

Why Choose VirtualHostCommandPlugin?

In a landscape filled with massive all-in-one plugins, this tool stands out for its focused design. It doesn’t try to manage your worlds, handle permissions, or replace your proxy—it simply reacts to the hostname and runs commands. That minimalism means fewer conflicts, easier debugging, and a lighter footprint. For server admins who already use Multiverse, BungeeCord, or a similar setup, the VirtualHostCommandPlugin adds a layer of smart routing without complicating your existing infrastructure.

Whether you’re building a multi-world hub, offering different experiences under one IP, or just want to greet players based on how they found your server, this plugin delivers. Its configuration is human-readable, its placeholders make commands dynamic, and the optional MOTD/icon features let you polish your server’s public face. Give it a try, and you’ll wonder how you ever managed without virtual host logic in Minecraft.