SekiDesu01/hytale-f2p
1
0
Fork 0
mirror of https://git.sanhost.net/sanasol/hytale-f2p synced 2026-02-26 11:41:49 -03:00
Code Issues Packages Projects Releases Wiki Activity
Files
5bd52f09dbc23b1a4a70a56516376f71efa49413
hytale-f2p/SERVER.md

13 KiB
Raw Blame History

Hytale F2P Server Guide

Play with friends online! This guide covers both easy in-game hosting and advanced dedicated server setup.

DOWNLOAD SERVER FILES HERE: https://discord.gg/MEyWUxt77m

Part 1: Playing with Friends (Online Play)

The easiest way to play with friends - no manual server setup required!

How It Works

  1. Start the game via F2P Launcher
  2. Click "Online Play" in the main menu
  3. Share the invite code with your friends
  4. Friends enter your invite code to join

The game automatically handles networking using UPnP/STUN/NAT traversal.

Network Requirements

For Online Play to work, you need:

  • UPnP enabled on your router (most routers have this on by default)
  • Public IP address from your ISP (not behind CGNAT)

Common Issues

"NAT Type: Carrier-Grade NAT (CGNAT)" Warning

If you see this message:

Connected via UPnP
NAT Type: Carrier-Grade NAT (CGNAT)
Warning: Your network configuration may prevent other players from connecting.

What this means: Your ISP doesn't give you a public IP address. Multiple customers share one public IP, which blocks incoming connections.

Solutions:

  1. Contact your ISP - Request a public/static IP address (may cost extra)
  2. Use a VPN with port forwarding - Services like Mullvad, PIA, or AirVPN offer this
  3. Use Radmin VPN or Playit.gg - Create a virtual LAN with friends (see below)
  4. Have a friend with public IP host instead

"UPnP Failed" or "Port Mapping Failed"

Check your router:

  1. Log into router admin panel (usually 192.168.1.1 or 192.168.0.1)
  2. Find UPnP settings (often under "Advanced" or "NAT")
  3. Enable UPnP if disabled
  4. Restart your router

If UPnP isn't available:

  • Manually forward port 5520 UDP to your computer's local IP
  • See "Port Forwarding" section below

"Strict NAT" or "Symmetric NAT"

Some routers have restrictive NAT that blocks peer connections.

Try:

  1. Enable "NAT Passthrough" or "NAT Filtering: Open" in router settings
  2. Put your device in router's DMZ (temporary test only)
  3. Use Radmin VPN as workaround

Workarounds for NAT/CGNAT Issues

Option 1: playit.gg (Recommended)

Free tunneling service - only the host needs to install it:

  1. Download playit.gg and run it - Connect your account from the terminal (do not close it when playing on the server)
  2. Add a tunnel - Select "UDP", tunnel description of "Hytale Server", port count 1, and local port 5520
  3. Start the tunnel - You'll get a public address like xx-xx.gl.at.ply.gg:5520
  4. Share the address - Friends connect directly using this address

Works with both Online Play and dedicated servers. No software needed for players joining.

Option 2: Radmin VPN

Creates a virtual LAN - all players need to install it:

  1. Download Radmin VPN - All players install it
  2. Create a network - One person creates, others join with network name/password
  3. Host via Online Play - Use your Radmin VPN IP instead
  4. Friends connect - They'll see you on the virtual LAN

Both options bypass all NAT/CGNAT issues. But for Windows machines only!

Option 3: Tailscale

It creates mesh VPN service that streamlines connecting devices and services securely across different networks. And works crossplatform!!

  1. All member's are required to download Tailscale on your device. [Once installed, Tailwind starts and live inside your hidden icon section in Windows, Mac and Linux]
  2. Create a common tailscale account which will shared among your friends to log in.
  3. Ask your host to login in to thier tailscale client first, then the other members.
Host
  1. Open your singleplayer world
  2. Go to Online Play settings
  3. Re-save your settings to generate a new share code
Friends
  1. Ensure Tailscale is connected
  2. Use the new share code to connect [To test your connection, ping the host's ipv4 mentioned in tailwind]

Part 2: Dedicated Server (Advanced)

For 24/7 servers, custom configurations, or hosting on a VPS/dedicated machine.

Quick Start

Step 1: Get the Server JAR

The server scripts will automatically download the pre-patched server JAR if it's not present.

Option A: Let the scripts download automatically (requires HYTALE_SERVER_URL to be configured)

Option B: Manually place HytaleServer.jar (pre-patched for F2P) in the Server directory:

  • Windows: %localappdata%\HytaleF2P\release\package\game\latest\Server
  • macOS: ~/Library/Application Support/HytaleF2P/release/package/game/latest/Server
  • Linux: ~/.hytalef2p/release/package/game/latest/Server

If you have a custom install path, the Server folder is inside your custom location under HytaleF2P/release/package/game/latest/Server.

Step 2: Run the Server

Windows:

cd scripts
run_server.bat

macOS / Linux:

cd scripts
./run_server.sh

The scripts will:

  1. Find your game installation automatically
  2. Download the pre-patched server JAR if needed
  3. Fetch session tokens from the auth server
  4. Start the server

Step 3: Connect Players

Share your server IP address with players. They connect via the F2P Launcher's server browser or direct connect.

Network Setup (Dedicated Server)

Local Network (LAN)

If all players are on the same network:

  1. Find your local IP: ipconfig (Windows) or ifconfig (Mac/Linux)
  2. Share this IP with players on your network
  3. Default port is 5520

Port Forwarding (Internet Play)

To allow direct internet connections:

  1. Forward port 5520 (UDP) in your router
  2. Find your public IP at whatismyip.com
  3. Share your public IP with players

Windows Firewall:

# Run as Administrator
netsh advfirewall firewall add rule name="Hytale Server" dir=in action=allow protocol=UDP localport=5520

Configuration

Environment Variables

Set these before running to customize your server:

Variable Default Description
HYTALE_SERVER_URL (placeholder) URL to download pre-patched server JAR
HYTALE_AUTH_DOMAIN sanasol.ws Auth server domain
HYTALE_BIND 0.0.0.0:5520 Server IP and port
HYTALE_AUTH_MODE authenticated Auth mode (see below)
HYTALE_SERVER_NAME My Hytale Server Server display name
HYTALE_GAME_PATH (auto-detected) Override game location
JVM_XMS 2G Minimum Java memory
JVM_XMX 4G Maximum Java memory

Example (Windows):

set HYTALE_SERVER_NAME=My Awesome Server
set JVM_XMX=8G
run_server.bat

Example (Linux/macOS):

HYTALE_SERVER_NAME="My Awesome Server" JVM_XMX=8G ./run_server.sh

Authentication Modes

Mode Description Use Case
authenticated Players log in via F2P Launcher Public servers
unauthenticated No login required LAN parties, testing
singleplayer Local play only Solo testing

RAM Allocation Guide

Adjust memory based on your system:

System RAM Players JVM_XMS JVM_XMX
4 GB 1-3 512M 2G
8 GB 3-8 1G 4G
16 GB 8-15 2G 8G
32 GB 15+ 4G 12G

Example for large server:

JVM_XMS=4G JVM_XMX=12G ./run_server.sh

Tips:

  • -Xms = minimum RAM (allocated at startup)
  • -Xmx = maximum RAM (upper limit)
  • Never allocate all your system RAM - leave room for OS
  • Start conservative and increase if needed

Server Commands

Once running, use these commands in the console:

Command Description
help Show all commands
stop Stop server gracefully
save Force world save
list List online players
op <player> Give operator status
deop <player> Remove operator status
kick <player> Kick a player
ban <player> Ban a player
unban <player> Unban a player
tp <player> <x> <y> <z> Teleport player

Command Line Options

Pass these when starting the server:

./run_server.sh [OPTIONS]
Option Description
--bind <ip:port> Server address (default: 0.0.0.0:5520)
--auth-mode <mode> Authentication mode
--universe <path> Path to world data
--mods <path> Path to mods folder
--backup Enable automatic backups
--backup-dir <path> Backup directory
--backup-frequency <mins> Backup interval
--owner-name <name> Server owner username
--allow-op Allow op commands
--disable-sentry Disable crash reporting
--help Show all options

Example:

./run_server.sh --backup --backup-frequency 30 --allow-op

File Structure

<game_path>/
├── Assets.zip                 # Game assets (required)
├── Client/                    # Game client
└── Server/
    ├── HytaleServer.jar       # Server executable (pre-patched)
    ├── HytaleServer.aot       # AOT cache (faster startup)
    ├── universe/              # World data
    │   ├── world/             # Default world
    │   └── players/           # Player data
    ├── mods/                  # Server mods (optional)
    └── Licenses/              # License files

Backups

Automatic Backups

./run_server.sh --backup --backup-dir ./backups --backup-frequency 30

Manual Backup

  1. Use save command or stop the server
  2. Copy the universe/ folder
  3. Store in a safe location

Restore

  1. Stop the server
  2. Delete/rename current universe/
  3. Copy backup to universe/
  4. Restart server

Troubleshooting

"Java not found" or "Java version too old"

Java 21 is REQUIRED (the server uses class file version 65.0).

Install Java 21:

  • Windows: winget install EclipseAdoptium.Temurin.21.JDK
  • macOS: brew install openjdk@21
  • Ubuntu: sudo apt install openjdk-21-jdk
  • Fedora: sudo dnf install java-21-openjdk
  • Arch: sudo pacman -S jdk21-openjdk
  • Download: adoptium.net/temurin/releases/?version=21

macOS: Set Java 21 as default:

export JAVA_HOME=$(/usr/libexec/java_home -v 21)
export PATH="$JAVA_HOME/bin:$PATH"

Add these lines to ~/.zshrc or ~/.bash_profile to make permanent.

"Game directory not found"

  • Download game via F2P Launcher first
  • Or set HYTALE_GAME_PATH environment variable
  • Check custom install path in launcher settings

"Assets.zip not found"

Game files incomplete. Re-download via the launcher.

"Port already in use"

./run_server.sh --bind 0.0.0.0:5521

"Out of memory"

Increase JVM_XMX:

JVM_XMX=6G ./run_server.sh

Players can't connect

  1. Server shows "Server Ready"?
  2. Using F2P Launcher (not official)?
  3. Port 5520 open in firewall?
  4. Port forwarding configured (for internet)?
  5. Try --auth-mode unauthenticated for testing

"Authentication failed"

  • Ensure players use F2P Launcher
  • Auth server may be temporarily down
  • Test with --auth-mode unauthenticated

Docker Deployment (Advanced)

For production servers, use Docker:

docker run -d \
  --name hytale-server \
  -p 5520:5520/udp \
  -v ./data:/data \
  -e HYTALE_AUTH_DOMAIN=sanasol.ws \
  -e HYTALE_SERVER_NAME="My Server" \
  -e JVM_XMX=8G \
  ghcr.io/hybrowse/hytale-server-docker:latest

See Docker documentation for details.

Server Settings Summary

Minimal Setup

./run_server.sh

Custom Memory

JVM_XMS=2G JVM_XMX=8G ./run_server.sh

Custom Port

HYTALE_BIND=0.0.0.0:25565 ./run_server.sh

LAN Party (No Auth)

./run_server.sh --auth-mode unauthenticated

Full Custom Setup

HYTALE_SERVER_NAME="Epic Server" \
HYTALE_BIND=0.0.0.0:5520 \
JVM_XMS=2G \
JVM_XMX=8G \
./run_server.sh --backup --backup-frequency 15 --allow-op

Getting Help

  • Check server console logs for errors
  • Test with --auth-mode unauthenticated first
  • Ensure all players have F2P Launcher
  • Join the community for support

Credits

Reference in New Issue View Git Blame Copy Permalink