Skip to main content

Joining Friends

  • Updated

This article covers how to invite friends to your singleplayer world and troubleshoot connection issues.

 

Intended Audience: Players who want to play with friends without setting up a dedicated server.

Network Requirements: Friend joins rely on UPnP and direct connections, which don't work on all networks. If you experience issues, see Troubleshooting or skip directly to Alternative Solutions like Tailscale or dedicated server hosting.

Early System: This feature is still maturing. We are actively improving it, but expect that it won't work flawlessly for everyone yet.

 

Share codes contain your IP address. Never post them publicly, paste them in public chats, or show them on stream. Only share codes directly with people you trust.

 

Contents

 

How It Works

Hytale allows you to open your singleplayer world to friends without running a dedicated server. When you enable friend joins, Hytale:

  1. Uses UPnP (Universal Plug and Play) to automatically configure your router
  2. Generates a share code containing connection information
  3. Friends paste the share code to connect directly to your game

The share code contains encrypted connection candidates including your local network addresses, public IP (via UPnP), and any VPN addresses (like Tailscale). The joining client tries each candidate to find a working connection.

 

Hosting a World

  1. Load into your singleplayer world
  2. Press ESC to open the pause menu
  3. Click Online Play
  4. Toggle Allow Other Players to Join to ON
  5. (Optional) Set a Password to restrict access
  6. (Optional) Toggle Include Password in Share Code to embed the password
  7. Click Save

After saving, Hytale performs UPnP negotiation with your router. Once complete:

  • A share code appears in the text field
  • Connection status shows below (e.g., "Connected via UPnP")
  • NAT Type displays your network configuration

Click Copy to Clipboard and send the code to your friends.

 

Joining a Friend's World

  1. From the main menu, go to Servers
  2. Click Join via Code
  3. Paste the share code
  4. Enter the password if required and not embedded
  5. Click Connect

The client attempts each connection candidate in priority order until one succeeds.

 

Troubleshooting

Share Code Not Generated

Symptom: After clicking Save, no share code appears or you see an error.

Causes and Fixes:

Cause

Fix
UPnP disabled on router Log into your router admin panel and enable UPnP
Router doesn't support UPnP See Manual Port Forwarding or Alternative Solutions
Multiple routers (Double NAT) Enable UPnP on all routers, or connect your PC directly to the main router
Firewall blocking UPnP Allow Hytale through Windows Firewall

 

Friend Cannot Connect

Symptom: Share code generated successfully, but friend gets connection timeout or failure.

Causes and Fixes:

Cause

Fix
CGNAT (Carrier-Grade NAT) Your ISP shares one public IP among multiple customers. UPnP port mapping won't work. See Alternative Solutions
Firewall blocking inbound Allow Hytale through Windows Firewall for both private and public networks
UPnP mapping expired Re-save Online Play settings to refresh the mapping
Antivirus interference Temporarily disable or add Hytale as exception
ISP blocking game ports Contact ISP or use Tailscale

 

How to Check for CGNAT

Your ISP may use Carrier-Grade NAT, meaning you share a public IP with other customers. UPnP cannot work in this scenario.

  1. Open PowerShell
  2. Run: tracert -d 8.8.8.8
  3. Check the first few hops

If the first hop is a public IP (not 192.168.x.x, 10.x.x.x, or 172.16-31.x.x), you likely have a direct connection. If you see multiple private IP ranges before reaching public addresses, you're behind CGNAT or Double NAT.

You can also compare:

  • Your router's WAN IP (shown in router admin panel)
  • Your public IP (search "what is my IP" in a browser)

If these don't match, you're behind CGNAT.

Manual Port Forwarding

If UPnP fails but you have a direct public IP:

  1. Note the port shown in your Online Play settings (default: varies per session)
  2. Log into your router admin panel
  3. Find Port Forwarding settings
  4. Create a rule forwarding the UDP port to your PC's local IP
  5. Re-save Online Play settings

IPv6 Connectivity

The share code includes IPv6 addresses when available. If your friend has IPv6 connectivity, they may connect directly even if UPnP fails. Both players need working IPv6 from their ISP for this to work.

 

Alternative Solutions

Try Having Your Friend Host

The simplest fix when you can't host: have your friend create the world and invite you instead. Different network configurations mean one player may be able to host while another cannot.

If you have an existing world to share:

  1. Find your world save in %appdata%\Hytale\saves\
  2. Send the world folder to your friend
  3. They import it and host

Using Tailscale

Tailscale creates a peer-to-peer VPN tunnel between devices using WireGuard. It bypasses NAT and firewall issues entirely.

Setup: 

Once connected, Hytale automatically detects Tailscale addresses and includes them in the share code. These appear as connection candidates with addresses like 100.x.x.x or fd7a:115c:a1e0::*.

Why Tailscale Works:

  • Establishes direct peer-to-peer connections
  • Punches through most NAT configurations
  • Falls back to relay servers if direct connection fails
  • Encrypted WireGuard tunnel
  • Free for personal use

After both players have Tailscale running:

  1. Re-save your Online Play settings to generate a new share code
  2. The new code includes Tailscale addresses as high-priority candidates
  3. Share the code with your friend

Dedicated Server

For persistent worlds or more than a few friends, consider a dedicated server. This provides:

  • Better performance (server isn't also rendering the game)
  • Persistent uptime when you're offline
  • More configuration options
  • Reliable connectivity without NAT issues

Option 1: Rent from a Hosting Provider

The easiest solution is renting a server from a game server provider such as the ones we "Launch Verified":

These providers handle all the networking, hardware, and maintenance. Servers are online 24/7 and accessible from anywhere without UPnP or port forwarding concerns. Most offer one-click Hytale installation and automatic updates.

Option 2: Self-Host

If you prefer running your own hardware, see the Server Manual for setup instructions.

 

Technical Details

Share Code Format

The share code is a Base64-encoded, compressed JSON structure containing:

{
  "HostName": "PlayerName",
  "HostUuid": "...",
  "ServerName": "World Name",
  "Password": "optional",
  "ExpiresAt": "2026-01-09T01:50:03Z",
  "Candidates": [
    {"Type": "Host", "Address": "192.168.1.100", "Port": 52102, "Priority": 1000},
    {"Type": "Host", "Address": "100.86.150.116", "Port": 52102, "Priority": 1000},
    {"Type": "UPnP", "Address": "82.12.145.33", "Port": 52102, "Priority": 900},
    ...
  ]
}
  • Host candidates: Direct IP addresses (local network, IPv6, Tailscale)
  • UPnP candidates: Public IP via router port mapping
  • Priority: Higher values tried first (1000 > 900)

The client iterates through candidates by priority, attempting connection to each until one succeeds.

Connection Priority

When connecting, candidates are tried in this typical order:

  1. Local network addresses (fastest, same network)
  2. Tailscale/VPN addresses (reliable, punches through NAT)
  3. IPv6 addresses (direct if both have IPv6)
  4. UPnP public IP (requires successful port mapping)

Security Notes

  • Share codes contain your IP addresses - only share with trusted friends
  • Codes expire (see ExpiresAt in the code)
  • Passwords add a layer of protection but the code itself reveals network info
  • Consider using Tailscale for an additional encrypted layer

 

Future Improvements

We're working to make friend joins more reliable across different network configurations.

Planned Enhancements

Better IPv6 Support

IPv6 eliminates NAT entirely, allowing direct connections between players. We plan to improve IPv6 detection and prioritization so players with IPv6 connectivity can connect without relying on UPnP.

NAT Hole Punching

NAT hole punching (also called UDP hole punching) allows two players behind NAT to establish a direct connection by coordinating through a third-party server. We're exploring adding this as a connection method, which would work in many cases where UPnP fails.

Why No Relay Servers?

Some games provide relay servers that forward traffic between players who can't connect directly. We've decided not to offer this for friend joins.

The Cost Problem

Relay servers must handle the full bandwidth of gameplay traffic for every connected session. Unlike matchmaking or authentication servers that handle small bursts of data, relay servers need sustained bandwidth for as long as players are connected. Providing this globally at scale would require significant ongoing infrastructure costs.

A Better Investment

Rather than spending on relay infrastructure with inherent latency and capacity limits, that money is better invested in a dedicated server. For the same cost as running relay infrastructure, you get:

  • 24/7 availability (not dependent on the host being online)
  • Better performance (dedicated resources, optimized routing)
  • No relay latency overhead
  • Support for more players

If direct connections don't work for your situation, we recommend the solutions in Alternative Solutions - particularly Tailscale for free peer-to-peer connectivity, or a hosted dedicated server for the best experience.

Related articles