Common Issues

This page contains all common issues and their solutions, starting with connection issues. Please read fully and if you still need help feel free to DM me @Mattiefm or join the discord.

Networking & Connection Guide

This section covers everything about how the multiplayer mod connects players, what connection methods exist, why connections fail, and how to fix every known issue. Read the section relevant to your problem, or read the whole thing for a full understanding.

How the Multiplayer Mod Connects Players

The Fear & Hunger Multiplayer Mod is peer-to-peer (P2P). There is no central game server that players connect to. Instead, one player acts as the Host and other players connect directly to them as Clients. The mod supports two connection methods: PeerJS (WebRTC) and TCP Direct Connect (Fallback).

Connection Flow Overview

1. The Host clicks "Host Game" in the multiplayer menu. The mod opens a connection and generates a connection code.
2. The Host shares the connection code with friends (via Discord, text message, etc.).
3. The Client clicks "Join Game" and pastes the connection code into the "Connection Key" field.
4. The client's game establishes a direct connection to the host.
5. Once connected, both players appear in the lobby. The host clicks "Start Game" to begin.

Connection Methods Explained

Method 1: PeerJS / WebRTC (Default)

This is the default and recommended connection method. It uses a technology called WebRTC (Web Real-Time Communication) through a library called PeerJS.

How it works:

1. Broker Server: When you host, the mod contacts the PeerJS broker server (a free public server at 0.peerjs.com). This server does NOT relay your game data. It only helps the two players find each other by exchanging connection information. Think of it as a matchmaker — once players are introduced, the broker steps aside.
2. STUN/TURN Servers: After the broker introduces the two peers, the mod uses STUN and TURN servers to establish the actual connection:
   • STUN (stun:stun.l.google.com:19302): Helps each player discover their own public IP address and the type of NAT (Network Address Translation) they are behind. This is used in most successful connections.
   • TURN (turn:eu-0.turn.peerjs.com:3478 and turn:us-0.turn.peerjs.com:3478): If a direct connection fails (usually due to strict NAT/firewall), the data is relayed through a TURN server. This is slower but works through most firewalls.
3. Direct P2P: Once the handshake completes, data flows directly between the two players' computers. The broker and STUN servers are no longer involved.

Connection Code Format:

The connection code you share is a Base64-encoded PeerJS ID. It looks like a random string of letters and numbers. It does not contain your IP address directly — the broker server handles the IP mapping behind the scenes.

Pros:

• Does not expose your IP address to the other player (the broker handles the mapping).
• Works through most NAT configurations automatically thanks to STUN/TURN.
• No port forwarding required in most cases.
• Easiest to use — just share the code and connect.

Cons:

• Requires the PeerJS broker server to be online for the initial connection.
• May fail on very restrictive networks (corporate, university, some mobile hotspots).
• If both the STUN and TURN servers are unavailable or blocked, connection will fail.
• Slightly higher latency if the connection is being relayed through a TURN server.

Method 2: TCP Direct Connect (Fallback)

TCP Direct Connect is the fallback connection method. It bypasses PeerJS entirely and creates a raw TCP socket connection between the host and client on port 6878 (by default).

How it works:

1. The Host's game starts a TCP server listening on port 6878.
2. The mod attempts to detect the host's public IP address automatically using DNS lookup (OpenDNS) or HTTP fallback (AWS CheckIP).
3. The connection code displayed is a Base64-encoded IP address with port and a random suffix (e.g., 203.0.113.50:6878_a1b2 encoded).
4. The Client decodes the code and connects directly to that IP and port via TCP.
5. A handshake is exchanged to identify the client, then data flows directly over TCP.

Connection Code Format:

The TCP connection code, when decoded, looks like an IP address: 203.0.113.50:6878_a1b2. The mod auto-detects whether a code is an IP address or a PeerJS ID and switches modes accordingly.

When TCP is used:

• Manually: You can toggle TCP mode using the "TCP: ON/OFF" button in the host menu.
• Automatically by host: If the PeerJS broker does not respond within 10 seconds, the host automatically switches to TCP.
• Automatically by client: If the connection code looks like an IP address, the client automatically enables TCP mode.

Pros:

• Does not depend on any external broker, STUN, or TURN servers.
• Works when PeerJS is completely down or blocked.
• Can offer lower latency on local networks (LAN play).
• Useful for playing on networks that block WebRTC (some corporate/school networks).

Cons:

• Exposes the host's IP address to anyone who receives the connection code. Only share TCP codes with people you trust.
• Requires port forwarding on the host's router if players are on different networks (not on the same LAN).
• The host's operating system firewall must allow inbound connections on port 6878.
• If the mod cannot detect the public IP (DNS and HTTP lookups fail), it will fall back to the local/private IP, which only works on the same local network.
• If port 6878 is already in use, the mod will automatically try the next port (6879, 6880, etc.) and will alert you. You must then forward that port instead.

TCP IP Warning:

The first time you enable TCP mode, the game will display a warning: "TCP directly reveals your IP — only send this code to trusted friends." You can choose to suppress this warning for future sessions.

Quick Comparison: PeerJS vs TCP

Not Connecting? Step-by-Step Troubleshooting

If you have been sent here by the game, your connection is taking longer than expected. Work through the following checklist in order. Each step resolves the most common cause before moving to the next.

Step 0: Check the Broker Server Status (PeerJS mode only)

The PeerJS broker server is a free public service that helps players find each other. If it is offline, PeerJS connections will not work until it comes back. This does not affect TCP Direct Connect.

If the broker is down: Wait 1-2 hours and try again, or switch to TCP Direct Connect (see the section below on how to enable it). If it stays down for more than a day, check the project Discord or message @Mattiefm.

Step 1: Verify the Connection Code

• Make sure the host clicked "Copy Code" in the host lobby and sent the full code to the client.
• The client must paste the code into the "Connection Key" field — NOT the "Username" field.
• Make sure no extra spaces, line breaks, or characters were added when copying/pasting.
• After pasting the code, press Enter to submit it. Do NOT press "Z" or other keys — some keybinds will type a letter into the field instead of submitting. If your accept key is bound to a letter key, the letter may be appended to the code and break it.
• If using TCP, make sure the host sent the code generated after enabling TCP mode, not an old PeerJS code.

Step 2: Ensure Both Players Are Using the Same Connection Method

• The host and client must be using the same connection method. If the host has TCP enabled, the code will be an IP-based code, and the client's game should auto-detect this and switch to TCP.
• If auto-detection is not working, you can see the mode in the host menu where it says "TCP: ON" or "TCP: OFF".
• If you are unsure, have the host generate a new code after confirming TCP is ON or OFF, and share that new code.

Step 3: Restart the Game

• Close Fear & Hunger completely (not just return to menu — close the game window).
• Have both the host and client restart the game.
• Have the host create a new lobby and generate a fresh code.

Step 4: Switch Who Is Hosting

• Networking issues are often caused by the host's network configuration. Have the other player try hosting instead.
• If Player A cannot host but Player B can, then Player A's network likely has restrictive NAT or firewall settings.

Step 5: Check Your PC Firewall

Your operating system's firewall may be blocking Fear & Hunger from accepting incoming connections.

Windows:

1. Open Windows Security → Firewall & network protection → Allow an app through firewall.
2. Click "Change settings", then "Allow another app...".
3. Browse to your Fear & Hunger Game.exe (or nw.exe / nwjs.exe in the game folder) and add it.
4. Ensure both Private and Public network checkboxes are enabled.
5. If you are using TCP mode, also make sure port 6878 (TCP) is not blocked. You can create an inbound rule in Windows Defender Firewall with Advanced Security for port 6878.

Mac / Linux:

• Ensure your firewall allows the game executable to accept inbound connections.
• On macOS, you may see a system prompt asking to allow incoming connections the first time — click "Allow".
• On Linux, check ufw or iptables rules if applicable.

Step 6: Check Your Router Firewall & NAT

Your home router also has a firewall and uses NAT (Network Address Translation) which can block incoming connections.

• PeerJS mode: Usually works without router changes due to STUN/TURN. If it still fails, your router may have "Strict NAT" (also called "Symmetric NAT"). Try enabling UPnP (Universal Plug and Play) in your router settings.
• TCP mode: You must port forward port 6878 on the host's router to the host's local IP address.
  1. Find your local IP: Open a command prompt and type ipconfig (Windows) or ifconfig / ip addr (Mac/Linux). Look for your IPv4 address (e.g., 192.168.1.50).
  2. Log into your router (usually at 192.168.1.1 or 192.168.0.1 in a browser).
  3. Find the Port Forwarding section (varies by router brand).
  4. Add a rule: External port 6878, Internal port 6878, Protocol TCP, Internal IP = your local IP.
  5. Save and restart the router if necessary.
• If the game told you a different port was used (e.g., "port 6878 was taken, the next free available port was 6879"), forward that port instead.

Step 7: WiFi Hotspot / Mobile Data Issues

Mobile hotspots and cellular networks frequently use Carrier-Grade NAT (CGNAT), which makes direct connections extremely difficult or impossible.

• If you are on a mobile hotspot, try switching to a regular WiFi / wired connection.
• If you must use a hotspot, try using a VPN (see below). A VPN can sometimes bypass CGNAT by routing traffic through a VPN server that has a proper public IP.
• Another option: have the person on the hotspot be the Client (not the Host), as connecting outbound is easier than accepting inbound connections on CGNAT.

Step 8: VPN Troubleshooting

VPNs can both help and hurt connectivity:

• VPN helps when: Your ISP or network has strict NAT/CGNAT, or blocks WebRTC/TCP ports. A VPN routes your traffic through a server with a proper public IP, potentially bypassing these restrictions.
• VPN hurts when: The VPN itself blocks P2P connections, adds too much latency, or interferes with the attempt to detect your public IP. Some free VPNs actively block peer-to-peer traffic.
• Try both states: If you have a VPN, try connecting with it ON and with it OFF. See which works.
• If using a VPN with TCP mode, the other player will see the VPN server's IP, not your real IP.

Step 9: Antivirus / Security Software

• Some antivirus programs (Norton, Kaspersky, Bitdefender, etc.) have their own firewalls that work independently of the Windows firewall.
• Temporarily disable the antivirus firewall to test if it is the cause. If it is, add Fear & Hunger as an exception.
• Check if your antivirus has a "gaming mode" or "do not disturb" mode that relaxes firewall restrictions.

Step 10: Try TCP Direct Connect

If PeerJS simply will not connect (broker down, WebRTC blocked, strict campus/corporate network), switch to TCP:

1. On the Host menu, click the "TCP: OFF" button to toggle it to "TCP: ON".
2. The first time you do this, you will see a warning that TCP exposes your IP address. Acknowledge it.
3. Wait for the new connection code to generate. Copy and share it with the client.
4. The client pastes the new code and joins. The client's game should auto-detect the TCP code format.
5. Remember: TCP mode requires port 6878 to be forwarded on the host's router for internet play (not needed for LAN).

Step 11: Try PeerJS Mode (if you were on TCP)

If TCP is not working for you, switch back to PeerJS:

1. On the host menu, click "TCP: ON" to toggle it to "TCP: OFF".
2. A new PeerJS code will be generated. Share it with the client.
3. PeerJS does not require port forwarding for most users.

Step 12: University / Corporate / Public WiFi Networks

These networks frequently block P2P connections of all kinds. Common restrictions:

• WebRTC entirely blocked (PeerJS will fail).
• All non-standard ports blocked (TCP on 6878 will fail).
• Only HTTP/HTTPS traffic allowed (port 80/443).
• P2P traffic detected and throttled/dropped by Deep Packet Inspection.

Solutions:

• Use a VPN to tunnel all traffic through an encrypted connection that bypasses network restrictions.
• If possible, use a personal mobile hotspot instead of the campus network.
• Try having both players use the same VPN service and connect via PeerJS mode.

Step 13: Reinstall the Mod / Game

• If nothing else works, try a clean reinstall of the multiplayer mod.
• Verify your game files are decrypted properly (see the Install Guide).
• Re-download the latest release and install it fresh.

Step 14: Ask in the Discord

If you have exhausted all the above steps, join the project Discord and ask for help. Provide the following information:

• What connection method you tried (PeerJS, TCP, or both).
• Whether the broker server status shows online.
• What network type you are on (home WiFi, university, mobile hotspot, VPN, etc.).
• Whether you tried switching who is host.
• Any error messages you saw (check the game console with F12 or F8 if available).
• Your operating system (Windows, Mac, Linux).

Known Connection Error Messages & What They Mean

"NOT CONNECTED, Taking longer than expected..."

Appears after 15 seconds of the client lobby being open without a connection. This is a warning, not a failure. The connection may still succeed. If it persists for more than a minute, the connection has likely failed.

"NOT CONNECTED!"

Appears after 25 seconds. The connection has almost certainly failed. The game will automatically open the connection help page. Follow the troubleshooting steps above.

"Please wait for connection to broker"

The host is waiting for the PeerJS broker server to assign an ID. If this message stays for more than 10 seconds, the broker may be unreachable. The mod will automatically switch to TCP after 10 seconds if the broker doesn't respond.

"Error getting ID"

The mod was unable to get an ID from the PeerJS broker. This means the broker is likely down or unreachable. Switch to TCP mode.

"port 6878 was taken, the next free available port was XXXX"

(TCP mode) Another application or a previous instance of the game is already using port 6878. The mod automatically found the next available port. If you are port forwarding, update your router rule to forward the new port number shown.

"UNABLE TO DETECT PUBLIC IP" / "Falling back to Local Private IP"

(TCP mode) The mod tried to detect your public IP address via DNS (OpenDNS) and HTTP (AWS CheckIP), but both failed. This usually means you have no internet connection, or your network blocks those services. The code generated will only work for LAN play (same local network). For internet play, you will need to manually find your public IP (search "what is my IP" in a browser) and share it along with the port to your friend.

"TCP directly reveals your IP — only send this code to trusted friends."

This is a safety warning shown the first time you enable TCP mode. The TCP connection code contains your IP address. Only share it with people you trust.

"Failed to connect to host after multiple attempts"

The client tried to connect to the host 5 times (with 2-second intervals and 5-second timeouts each) and all attempts failed. The host is either unreachable, the code is wrong, or a firewall/NAT is blocking the connection.

Special Connection Scenarios

LAN Play (Same Local Network)

If both players are on the same local network (same WiFi, same house), connections are much easier:

• PeerJS: Works normally, the connection will be routed locally after the broker introduces the peers.
• TCP: Works without port forwarding. The local IP in the code is sufficient to connect. You do not need internet for this.

Playing Across the Internet (Different Networks)

• PeerJS: Usually works out of the box. STUN discovers public IPs, and TURN relays if needed.
• TCP: Requires port forwarding on the host's router. The host must forward port 6878 to their local machine.

Local Co-Op (Two Instances on the Same PC)

See the Local CO-OP section below for instructions on running two instances on one machine.

Reconnecting After a Disconnect

• If you get disconnected mid-game, go to the Join menu. The "Reconnect" button will be enabled if the mod has a previous connection to try.
• If Reconnect doesn't work, have the host check if their lobby is still active. The client may need to re-enter the connection code.
• In some cases, the host may need to restart the lobby entirely and generate a new code.

Quick Connection Checklist

Technical Details (Advanced)

This section is for users who want deeper understanding or are debugging non-standard setups.

PeerJS Configuration

• Broker: Public PeerJS cloud broker at 0.peerjs.com
• STUN Server: stun:stun.l.google.com:19302 (Google's free STUN server)
• TURN Servers: turn:eu-0.turn.peerjs.com:3478 (Europe), turn:us-0.turn.peerjs.com:3478 (US), credentials: peerjs/peerjsp
• SDP Semantics: unified-plan

TCP Direct Connect Configuration

• Default Port: 6878 (TCP)
• Port Retry: If 6878 is in use, the mod retries 3 times, then tries the next port (6879, 6880, ...) up to 10 port increments.
• Public IP Detection: First tries DNS (OpenDNS resolver at 208.67.222.222/208.67.220.220 resolving myip.opendns.com), falls back to HTTP GET to http://checkip.amazonaws.com. Both have a 3-second timeout.
• Handshake: On TCP connect, the client sends a JSON {"type":"HANDSHAKE","peerId":"..."} message. The host validates this before accepting the connection.
• Data Format: Newline-delimited JSON over TCP.

Auto-Fallback Behavior

• If the host is in PeerJS mode and the broker does not assign a peer ID within 10 seconds, the mod automatically switches to TCP and reopens the connection.
• This auto-switch only happens once per session (tracked by fallbackAutoSwitched flag).
• If the user manually sets a preference (TCP ON or OFF), auto-switching is disabled and the user's choice is respected.
• On the client side, if the pasted code looks like an IP address (e.g., 192.168.1.5:6878_abc), TCP mode is automatically enabled.

Client Retry Logic

• When a client tries to connect: each attempt has a 5-second timeout.
• If connection fails (timeout, error, or immediate close), the client retries up to 5 times with a 2-second delay between attempts.
• Total maximum wait before final failure: approximately 35 seconds (5 attempts × 7 seconds each).

Network Packet Rate

• The mod limits outgoing packets to 50 packets per second by default (configurable).
• Movement packets are sent immediately (not queued). Critical game-state packets (battle events, switches, etc.) are sent with redundancy (up to 4 extra copies at staggered intervals) and deduplication on the receiver side.

Getting UnStuck

• In all recent releases of the multiplayer mod there exists a help button in your escape menu. This provides you with many options for fixing issues. Tping to spawn and blood portals to get unstuck and other stuff.
• the unstuck button. In the help menu there is a button titled "unstuck" and it can be bound to a keybind. This is a button designed to help break out of any blocking issues If you cannot move, if you cannot interact, if you are stuck in a cutscene, press the button and try to leave and reload the area.
• Dev Tools. The devtools mod provides the ability to phase step, teleport to key locations, and spawn in lost items, if you are encountering too many bugs, please play with dev tools and quick saves on such that you can save frequently and fix lost progress
• Most bugs can be broken out of with a combination of saving/loading or using dev tools phase step. If you get stuck try to phase step, save/load etc... In combination with the unstuck button it is rare that you cannot recover a run from a bug.

Girl costume Error

Please see this discord thread: https://discord.com/channels/1148766509406093342/1170411865759817888

File Decrypter link

In the readme of the discord server: https://discord.gg/PAUddX5g2x

How do I trade items

use the drop menu, drop an item and let your friend pick it up

How do marriages work

currently marraiges are overworld only, player's get merged and movement combined, in combat they fight seperately as though they both formed marraiges with npcs.

Difficulty

There is an entire tab in the config for scaling of enemies, you can configure most things that you would need for Difficulty. By default this mod increases enemy health by 1.3 1 +.2 number of players. All of this can be configured. IN THE CONFIG MENU ENSURE TO HIT ENTER AFTER EDITING A FIELD.

remove the big "allies" and "viewing" tabs from combat scene

On the first page of the config menu for this mod. just change true to false.

Body blocking

config option on first page of config menu

local CO-OP

Misc

All solutions below assume you have the DevTools mod active as it provides tools that will allow you to fix a lot. I cannot connect, ensure that you are copying the correct code, ensure you are copying the code into the connection-key field and not the username field. Make sure you are copying just the code itself and nothing else, ensure the host has sent you the current code. I pressed 'N' and I got an error: N is a debug keybind that is sometimes useful for fixing major bugs, it tries to teleport you to another player in the server. Just try not to press it for the time being. I pressed Other key and something bad happened, you probably pressed something that is a keybind for something, open your keybinds and unbind it or just don't click it. some tiles are moving around the map when they shouldn't be. This occurs sometimes and most of the time is purely cosmetic, I know how to fix it, it is just more effort than I want to spend on a visual bug I am on a different vairant of the map than a friend. you can try to press 'n' to teleport to the correct variant, and the vars taht control variant should sync eventually, for avoiding this in the future, just make sure the host loads into the game before anyone starts exploring the dungeons I am stuck in an event and cannot move, try to press 'n' or 'v' if either of those free you great, if not try to have another player run around you, stepping on traps or action tiles, if taht doesn't work you will need to restart, and then please file a bug report of where this occured There are multiple copies of an npc or an event is playing when another player triggered it IE: friend triggers legard event and it plays for both of you, just file a bug report of where it occurs I cannot see another player, shouldn't occur much, but hitting escape will reload you onto all other players screens so if you can't see someone ask them to open and close the menu Coin flip is stuck on my screen, press 'v' for phase step or reload the area and it will go away talk option for a player poped up in a menu: should not occur anymore, if you see this please tell me where it occured. "I am stuck somewhere and cannot move." Open your keybinds and bind "tp to spawn" to a key, then press that key, you should be teleported to the fortress spawn area, this might resolve you being stuck.