Headless server

A headless server launches directly into a scenario from the commandline without displaying a graphic user interface. This lets you run the server component of EmptyEpsilon on a dedicated piece of hardware without a display, whether for better server performance or to offload server tasks onto lower-spec hardware.

As with any EmptyEpsilon server, you must open port 35666 (TCP) on your firewall to allow people to connect to your server.

NOTE: The GM screen is inaccessible on a headless server.

Quickstart guide

1. Build EmptyEpsilon for your operating system.
2. Generate a default preferences file by launching EmptyEpsilon, then quitting.
3. Open the preferences file in a text editor. See Preferences file for the location on your operating system.
4. Add headless=scenario_00_basic.lua to configure EmptyEpsilon to run the Basic scenario, or replace scenario_00_basic.lua with the filename of any scenario in EmptyEpsilon's scripts directory.
5. Launch EmptyEpsilon.

EmptyEpsilon clients who can reach your system over the network should now be able to connect to your server.

For a more detailed guide on setting up a headless host on a virtual private server, see Setting up a VPS host.

headless option

To run a scenario as a headless server, use the headless option and set its value to one of the Lua scenario scripts in EmptyEpsilon's scripts directory.

For example, to launch a headless server with the Basic scenario, add this to the Preferences file (options.ini) before launching EmptyEpsilon:

headless=scenario_00_basic.lua

scenario_settings option

To run a specific variation of the scenario, use the scenario_settings option:

headless=scenario_00_basic.lua
scenario_settings=variation=Hard

startpaused option

Optionally start the scenario in a paused state by adding the startpaused option and setting it to 1:

startpaused=1

If you do so, you'll need to use the unpauseGame() scripting function using the HTTP server or Lua console to start the scenario because only the server can pause or unpause a running game.

headless_name option

Set an optional server name by adding the headless_name option:

headless_name=Federation

If you want spaces in the name, use double quotes:

headless_name="My Server"

headless_password option

Set an optional password for the server by using the headless_password option:

headless_password=supersecretpassword

You might have to escape certain symbols, such as $ or %, depending on your OS.

headless_internet option

To optionally register your headless server with the internet master server for online play, add the headless_internet option. This is the equivalent of starting an "Internet" server in the GUI (as opposed to a "LAN" server).

headless_internet=1

Launching a headless server from the command line

You can configure the headless server's name, password, and internet availability by setting the above options in the Preferences file (options.ini). As with other such settings, you can also launch EmptyEpsilon from the command line with these settings by adding them to the launch command:

EmptyEpsilon headless=scenario_00_basic.lua headless_name=Federation headless_password=supersecretpassword headless_internet=1

Adding player ships

There isn't a way to access the GM screen or server creation interface to spawn a player ship on servers launched with the headless option. If the selected scenario doesn't spawn a player ship, players can connect but won't have a ship to join.

The easiest solution is to include at least one player ship in the scenario before launching the headless server. However, if all player ships in the scenario are destroyed, players won't be able to spawn another ship to continue.

If you enable the [[httpserver option|HTTP-server]] (using httpserver=8080 in options.ini or on the command line), you can use an exec.lua API command to spawn a player ship.

For example, if you have curl installed and httpserver enabled on port 8080, you can spawn an Atlantis into the active scenario by running from the server:

curl --data "PlayerSpaceship():setFaction('Human Navy'):setTemplate('Atlantis')" http://localhost:8080/exec.lua

If you set the startpaused option to 1 (the equivalent of true), run this to unpause the game:

curl --data "unpauseGame()" http://localhost:8080/exec.lua

Note: Exposing the HTTP API port to the public internet is not recommended and potentially dangerous.