Hytale Guides

Guide

How to Set Up a Whitelist on Your Hytale Server

How to Set Up a Whitelist on Your Hytale Server

Setting up a whitelist on your Hytale server is the most effective way to ensure only approved players can access your world, providing a secure and controlled environment for private communities, friends, or specific groups. This mechanism acts as a digital bouncer, checking every incoming player against a predefined list before granting entry.

Understanding Hytale Server Whitelisting

A whitelist is an access control feature for your Hytale server that restricts connections to a pre-approved list of player accounts. When enabled, any player attempting to join the server whose account is not on this list will be denied access. This is invaluable for preventing unauthorized entry, mitigating griefing, and maintaining a focused community experience.

How Whitelisting Works

At its core, a Hytale server’s whitelist functions by checking the identity of a connecting player against its internal list of allowed users. If the player’s unique identifier (typically their Hytale username or a Universally Unique Identifier, UUID) matches an entry on the whitelist, they are permitted to join. If not, their connection is rejected with an appropriate message. Server administrators or operators, however, usually possess inherent permissions that allow them to bypass the whitelist, ensuring they can always access and manage the server.

Hytale servers are designed with a “server-first architecture,” meaning core server settings, including whitelist configurations, are managed through dedicated configuration files and server commands. Changes made via console or in-game commands are typically applied immediately, eliminating the need for a server restart in most cases.

Step-by-Step Guide: Setting Up a Whitelist Using Commands (Recommended)

The most straightforward and recommended method for managing your Hytale server’s whitelist is through console commands or in-game commands if you have administrator privileges. This method is generally safer and less prone to errors than manual file editing.

Accessing Server Commands

You can execute whitelist commands in one of two primary ways:

  • Server Hosting Panel Console: If you are using a third-party hosting provider, they will almost certainly offer a web-based control panel. Within this panel, you’ll find a “Console” or “Terminal” tab where you can type commands directly into your server.
  • In-game: If you are logged into your Hytale server as an administrator (also known as an operator), you can type these commands directly into the game chat. To do this, open the chat window (usually by pressing / or Enter) and prepend the command with a forward slash (/). For example, to enable the whitelist, you would type /whitelist enable.

Essential Whitelist Commands

Here are the key commands you’ll use to manage your Hytale server’s whitelist:

1. Enable the Whitelist

This command activates the whitelist feature, immediately restricting server access to only whitelisted players.

  • Command: whitelist enable or whitelist on
  • Confirmation: You should see a message confirming, “Whitelist enabled!”

2. Disable the Whitelist

This command deactivates the whitelist, allowing any player to join the server, regardless of whether they are on the whitelist.

  • Command: whitelist disable or whitelist off
  • Confirmation: The server will confirm with, “Whitelist disabled!”

3. Add a Player to the Whitelist

This command adds a specific player to your server’s whitelist, granting them permission to join when the whitelist is active.

  • Command: whitelist add <username>
  • Usage Example: To add a player named “HytaleFanatic”, you would type whitelist add HytaleFanatic.
  • Confirmation: A message like “Added HytaleFanatic to the whitelist!” indicates success.

4. Remove a Player from the Whitelist

This command removes a specific player from your server’s whitelist, revoking their permission to join when the whitelist is active.

  • Command: whitelist remove <username>
  • Usage Example: To remove “HytaleFanatic”, you would type whitelist remove HytaleFanatic.
  • Confirmation: The server will confirm the removal.

5. List All Whitelisted Players

This command displays a list of all players currently on your server’s whitelist.

  • Command: whitelist list
  • Output: The console or chat will show a list of whitelisted usernames.

6. Check Whitelist Status

This command tells you whether the whitelist is currently enabled or disabled on your server.

  • Command: whitelist status
  • Output: The server will respond with “Whitelist is currently enabled” or “Whitelist is currently disabled.”

7. Clear All Whitelisted Players

This command removes all players from the whitelist, leaving it empty. Use this with caution, as it will prevent everyone (except administrators) from joining if the whitelist is enabled.

  • Command: whitelist clear
  • Confirmation: The server will confirm that the whitelist has been cleared.

Advanced Method: Manual File Editing (Use with Extreme Caution)

While using commands is the preferred method, the whitelist can also be managed by directly editing the server’s configuration files. This method is more prone to errors and should only be attempted by experienced users who understand JSON file structures. Always back up your server files before attempting manual edits.

1. Stop Your Hytale Server

This step is absolutely critical. Never attempt to edit server configuration files like whitelist.json while the server is running. Doing so can lead to your changes being overwritten, data corruption, or the server failing to start correctly.

2. Locate the whitelist.json File

Navigate to your Hytale server’s root directory. The whitelist.json file is typically located there, alongside other configuration files such as config.json and permissions.json.

3. Edit the File with a Text Editor

Open whitelist.json using a plain text editor (e.g., Notepad, VS Code, Sublime Text). Do not use word processors like Microsoft Word.

  • Enable the Whitelist: Look for the "enabled" key and set its value to true to activate the whitelist. If you want to disable it, set it to false.
  • Add Players: Within the "list" array (represented by square brackets []), add the unique identifiers (UUIDs) of the players you wish to whitelist. Each UUID must be enclosed in double quotation marks and separated by commas.

An example whitelist.json might look like this:

{
  "enabled": true,
  "list": [
    "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
    "11111111-2222-3333-4444-555555555555"
  ]
}

Note: You will need to find the UUIDs for the Hytale accounts you wish to whitelist. Hytale’s official website or third-party tools might provide a way to look these up based on usernames once the game is fully released and its identity system is finalized.

4. Save and Restart

Save the modified whitelist.json file and then start your Hytale server. The changes will take effect upon startup.

Important Tips for Whitelisting

  • Combine with a Server Password: For an extra layer of security, consider setting a server password in addition to a whitelist. This means players must be both whitelisted and know the correct password to join.
  • Use Commands for Instant Changes: Whenever possible, use the console or in-game whitelist commands. These changes are applied immediately without needing a server restart, making player management much more efficient.
  • Maintain JSON Validity: If you opt for manual file editing, always double-check that your JSON syntax is correct. Missing commas, unclosed brackets, or incorrect quotation marks can prevent your server from starting or correctly applying the whitelist.
  • Administrator Bypass: Remember that server operators and administrators are typically exempt from whitelist restrictions. They can always join the server, even if their account is not explicitly on the whitelist.

Common Mistakes and Uncertainties

While setting up a whitelist is generally straightforward, there are a few pitfalls and areas of uncertainty to be aware of:

whitelist.json vs. Permissions System

There has been some discussion regarding the underlying mechanics of Hytale’s whitelist. Some sources suggest that in later development stages, the direct editing of a whitelist.json file might be abstracted or superseded by a more comprehensive permissions system (e.g., using a permission node like hytale.server.join). While the command-line interface (whitelist add, whitelist enable, etc.) is expected to remain consistent and functional, the exact role and direct editability of whitelist.json could evolve. For this reason, relying on the official server commands is generally the most future-proof and reliable approach.

  • Editing While Running: As emphasized, attempting to manually edit whitelist.json or any other server configuration file while the server is active is a common and critical error. Always stop the server first.
  • Incorrect Player Identifiers: When manually editing whitelist.json, it is crucial to use a player’s UUID, not their username. Using a username in the file will prevent that player from being whitelisted correctly. The command-line interface, however, typically accepts usernames for convenience, handling the UUID lookup behind the scenes.

By following these guidelines, you can effectively secure your Hytale server and cultivate the private community experience you desire.