HTTP Server

WORK IN PROGRESS! The web server is experimental and potentially unsafe. If security is a high priority, don't enable it, especially on internet-accessible servers!

The HTTPServer provides access to certain functions of the game through web clients, such as web browsers and apps.

Enabling HTTPServer

With options.ini

Edit the Preferences file (options.ini) with your favorite text editor, and change this line:

httpserver=

to

httpserver=8080

Save the file, then launch EmptyEpsilon.

On the command line

Like other options.ini settings, you can also set httpserver when launching EmptyEpsilon from the command line:

EmptyEpsilon httpserver=8080

Accessing the server

By default, there are no pages to view. The HTTPServer is primarily designed for accessing the API. See Serving webpages for help publishing web pages from the HTTPServer.

API

Script function reference

See the scripting reference for the current version of EmptyEpsilon for functions to use with these API endpoints, or for the scripting_reference.html file included with EmptyEpsilon (location depends on operating system).

get.lua

Calls Lua-exposed script functions and returns their result in a dictionary. Each function can be passed to the endpoint as a separate parameter of a GET request.

Use _OBJECT_=someObjectGetter() to select an object of which to call functions. The default object is getPlayerShip(-1).

Example:

Get the hull value and number of nukes of the newest player ship on the EmptyEpsilon server at serverip:

http://serverip:8080/get.lua?hull=getHull()&nukes=getWeaponStorage("nuke")

Returns:

{"nukes": 4.000, "hull": 100.000}

set.lua

Calls Lua-exposed script functions and returns their result in a dictionary. Each function can be passed to the endpoint as a separate parameter of a GET request.

Use _OBJECT_=someObjectGetter() to select an object of which to call functions. The default object is getPlayerShip(-1).

Example:

On the newest player ship on the EmptyEpsilon server at serverip, raise its shields and plot a course to heading 200 at three-quarters impulse:

http://serverip:8080/set.lua?setShieldsActive(true)&commandTargetRotation(200)&commandImpulse(0.75)

Returns nothing if successful, or an error (such as {"ERROR": "Script error"}) on failure.

exec.lua

Executes Lua script code and returns the result (if any) in a dictionary. Code can be passed to the endpoint as the data in a POST request. Note: The total request is limited to a size of 2kb.

Example:

Use the curl command to create a new Human Navy player ship, located at the default origin coordinates and using the Atlantis ship template, in the active scenario running on the EmptyEpsilon server at serverip.

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

Regardless of whether the script is successful, the request returns HTTP code 200. Any output from the script is returned in the response body. For instance, a script typo returns:

{"ERROR": "Script error: [string 'FlayerSpaceship():setFaction('Human Navy'):se...']:1: attempt to call a nil value (global 'FlayerSpaceship')"}

Other script failures can crash the game server, so be careful when enabling it!

To return data from the API, remember to use the return command. For example, in a scenario where the first player ship has the callsign "PL4", running:

curl \
    --data "return getPlayerShip(-1):getCallSign()" \
    http://localhost:8080/exec.lua

Returns:

"PL4"

Serving webpages

Create a directory called www in the EmptyEpsilon directory (Windows) or its resources directory (Linux, macOS; location depends on the operating system) and place files you want served (such as HTML, CSS, images, and JavaScript) there.

If you add an index.html file, opening http://<server's IP address>:8080 will load it automatically. This allows you to create a web interface that can trigger API endpoint commands, distribute EmptyEpsilon clients to players, or provide information about your game, event, or game server. The www directory in this repository includes an example that allows you to issue API requests using your web browser.

The web server is experimental and potentially unsafe. If security is a high priority, don't enable it, especially on internet-accessible servers!