Internet Play - daid/EmptyEpsilon GitHub Wiki

WORK IN PROGRESS!

EmptyEpsilon uses a dedicated server as a host, and players must connect to the server. While it's designed for local area network (LAN) play, where everyone connects to the same Wi-Fi and/or wired network in the same location, you can also host it for remote players over the internet. You can mix local and remote players in the same game.

For remote players to be able to connect to your EmptyEpsilon server over the internet, you must choose a server configuration method, then configure and start the server.

Table of contents

• Server configuration methods
  • Configure firewalls and port forwarding
  • Virtual private servers
  • Cloud compute services
  • Proxy servers
• Start the server
  • Server quickstart using options
  • Headless dedicated servers
• Connect players (clients)
• Troubleshooting
• Hosting your own master server (advanced)

Server configuration methods

There are several ways to configure and host EmptyEpsilon to allow players to connect over the internet, including:

• on your own system and home network, by configuring your system's firewall and network's port forwarding

  • Advantages: No additional cost, hardware, or services required
  • Disadvantages: Requires manual reconfiguration of your network and system to allow incoming internet connections; geographically distant players suffer additional lag

• on your own system, with players joining a virtual private network (VPN) that includes your server (to be documented)

  • Advantages: No additional hardware required, many VPN services are free for small groups, and port forwarding might not be required
  • Disadvantages: Requires additional services, and both you and your players must install software and/or configure systems to connect to your VPN; geographically distant players suffer additional lag

• on another internet-connected server, such as a virtual private server (VPS) or a cloud computing provider like Amazon Web Services (AWS)

  • Advantages: No changes required on your network, players can easily connect, and you can select a more centrally located server to balance lag
  • Disadvantages: Requires a remote server that can run EmptyEpsilon, which can cost money and might need additional configuration; no GM screen access unless the server supports a remote desktop

• on your own system, and using another internet-connected server as a reverse proxy server to which players connect

  • Advantages: No changes required on your network, players can easily connect, you retain GM screen access on your local system, and you can select a more centrally located server to balance lag
  • Disadvantages: Requires a remote server, which can cost money and might need additional configuration

Once you've configured your server, you can start the server.

Configure firewalls and port forwarding

To host a server from your own network and allow players to connect to it over the internet, you must configure your network to open and forward specific ports used by EmptyEpsilon.

How to configure this varies among firewall software and router hardware, and is beyond the scope of this document. Identify your home router and search for its manual or port forwarding instructions. For a general guide, see How to Set Up Port Forwarding.

From your router, forward these ports to the IP address or computer running the EmptyEpsilon server:

• TCP port number: 35666 (for LAN and Internet play)
• UDP port number: 35666 (used only for LAN discovery)

The server's firewall must also be configured to accept connections on those ports. The details of this process also depend on your operating system and version. Some common guides include:

• Windows 10 and 11 (expand the "Open or close a port" section)
• Ubuntu Server (alternative guide)
• macOS

Virtual private servers

A virtual private server (VPS) is a server made available on the internet by a service provider. Common VPS providers include Hetzner, DigitalOcean, and Vultr, but many more exist. Most charge you money to run a server, typically in increments of 1 hour to 1 month, and the price for a server capable of running EmptyEpsilon for most groups is typically as little as 2-5 USD or Euros per month. Since a VPS uses a full operating system, it can be time consuming to create, configure, install, and run EmptyEpsilon on them each time you want to play unless you automate the process or leave the server on at a cost while you aren't playing.

Virtual private servers most often run a Linux-based operating system. Some provide a remote desktop that allows you to host an EmptyEpsilon server with a graphical user interface, for example to host a game that uses the Game Master screen available only on the server. Others don't offer remote desktops, limiting them to use as headless dedicated servers or proxy servers.

Because these servers are hosted on the internet, they aren't subject to your local system's firewall or your network's port forwarding restrictions. This makes them easier for players to connect to. If your players are geographically dispersed, you can also choose a VPS provider with servers available in a central location to balance latency across all players, instead of players farther from you experiencing more lag than others.

For detailed instructions, see Internet Play ‐ Setting up a VPS host.

Cloud compute services

Cloud compute services allow you to run applications on their hardware and make them accessible over the internet. Common cloud compute providers include Amazon Web Services (AWS), Google Cloud Services (GCS), and Microsoft Azure. As opposed to a virtual private server, cloud compute services run only the application you specify instead of a full operating system, and they typically run only while that application is active. As such, these services can be more complex to configure than a VPS but can cost even less (or in some cases, nothing) to run.

For detailed instructions, see Internet Play ‐ Setting up cloud compute. (TODO)

Proxy servers

Proxy servers are servers that simply pass game data back and forth between clients and an EmptyEpsilon server. A proxy server requires few server resources, can make connecting without port forwarding and across firewalls easier, and can help scale EmptyEpsilon games up for a larger number of players by distributing server load.

You can run a proxy server locally, on a VPS, or on a cloud compute service. Using a VPS or cloud compute to run a reverse proxy server, which only forwards data between your local server and internet-connected players, can give you the benefits of running a local server without needing to configure firewalls and port forwarding.

For detailed instructions, see the Proxy Server documentation.

Start the server

After you've configured your server host, you can launch EmptyEpsilon on that host from its main menu and start it as a game server:

1. Launch EmptyEpsilon.

2. Click "Start server". This opens the server configuration screen.

3. Enter a server name, which appears to players who connect to it.

4. To prevent uninvited players from joining your game, enter an optional server password.

5. Enter an optional GM code, which is requried when opening the GM screen on the server. Use this if you plan on players also using the server itself to join a ship, since the GM screen allows for total control over the game.

   Development builds only: The GM code also locks privileged views, such as the Spectator, Top-Down, and Cinematic views, that can give players a tactical advantage and show things that aren't visible on player views.

6. Leave the default port set to 35666 if possible. If you change this port, you must also forward the new port on your router and open it on your firewall, and players must include the port number when connecting.

7. To announce and list your server publicly, set "List on master server" to "Yes".

   If your network's port forwarding and server firewall are correctly configured, this adds your server to the public list of available servers that loads when players click "Start client" on the main menu.

   If you choose to list your server on the master server, it's strongly suggested to set a server password. Otherwise, anyone who launches EmptyEpsilon while connected to the internet can join your game.

8. Click "Start server".

   Players should now be able to connect to the server. On the server, this opens the scenario selection screen.

9. Select a scenario, then click Start scenario to launch it or select its options.

   This opens the ship selection screen. On the server, you also have exclusive access to the Game master screen and can create new player ships.

Server quickstart using options

You can launch the server directly into a server with configured options by using the server_scenario option to specify a scenario script. Other networking-related preferences allow you to complete server configuration without needing to do so manually in the user interface.

In the server's options.ini, set:

server_scenario=scenario_00_basic.lua

Alternatively, to launch the server from the command line directly into the Basic scenario with default server and scenario options, run:

EmptyEpsilon server_scenario=scenario_00_basic.lua

In either case, EmptyEpsilon skips most of the server configuration steps, starts, and launches directly into the ship selection screen.

For details, see Preferences File#Networking options.

Headless dedicated servers

To run a dedicated server that doesn't require a graphical user interface, see Headless Dedicated Server. A headless server runs and connects players without using the EmptyEpsilon user interface, and launches directly into a running scenario to minimize GM intervention.

You can run headless servers on cloud-based virtual machines (AWS, Google Compute, VPS providers like DigitalOcean, etc.) that lack remote desktop displays, which can make hosting games easier since cloud-based servers don't require port forwarding.

Development builds only: Headless servers can accept Lua script instructions over standard input, which allows you to access and manipulate game state without access to a GM screen or opening the HTTP API. For details, see Lua console.

Connect players (clients)

Your players should connect to your server as clients. They must:

1. Launch EmptyEpsilon.

2. Click "Start Client". This opens the server selection screen.

   If your network's port forwarding and server firewall are correctly configured, and if the master server is operational, your server should appear on this screen after a few seconds.

3. If your server is listed, players can select it by clicking on it.

   If your server is correctly configured but not listed, players can connect by entering the server's public IP address in the text field above the "Connect" button.

   If you customized the server's port from the default 35666, the player must also add a colon (:) followed by the port number to the IP address. For example, if the server at 203.0.113.0 was configured to use port 12345, the player must enter 203.0.113.0:12345.

4. Click "Connect" to join the game.

5. Click a ship to select which player screens to use, or select an available additional view. If no player ships are available, the GM might need to unpause the scenario or create a ship on the server.

   If you're joining a player ship, select the screens you want to join, then click "Ready" to join them.

Troubleshooting

While there are no hard limits to the number of players that can connect, large numbers of players, complex scenarios, or low network bandwidth or high latency on the hosting server can cause performance issues on the server. The server updates clients at a 20Hz rate regardless of its own frame rate, and if server performance drops below that 20Hz update rate, all clients experience lag.

All players must run a copy of EmptyEpsilon that has the same version number as the server. If the version number differs, errors should appear in both the client's and server's log output or EmptyEpsilon.log files.

While players don't need to have local copies of the scenario being run on the server, players must locally install any mods or additional assets; the server doesn't transfer any mods or assets to players.

It isn't recommended to enable the HTTP Server on internet-connected servers. HTTP API and server access is experimental and potentially dangerous! If enabled over the internet, it might allow attackers to take down or control your server!

Find the server's public IP address

If you choose not to list your server, you must share your public IP address with your players for them to directly connect.

The server configuration screen also lists detected IP addresses for your server. On home networks, however, the addresses in this list are typically relevant only for LAN play.

To find your public IP address, use a website such as https://whatismyipaddress.com/. Your IP address is typically four sets of numbers separated by periods, such as 203.0.113.0.

If the server has a domain name associated with its IP address, players can optionally enter that instead of the IP address.

Hosting your own master server (advanced)

In addition to the official master server, you can run your own. This is an advanced task that requires you to set up and run a web server and database.

See the SeriousProton documentation for detailed instructions on setting up the server, and the Preferences File document for the required registry_list_url and registry_registration_url settings that players must set to use that master server.