HTTP Server

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 options.ini file 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 configure httpserver when launching EmptyEpsilon:

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

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 Player Cruiser ship template, in the active scenario running on the EmptyEpsilon server at serverip.

curl \
    --data "PlayerSpaceship():setFaction('Human Navy'):setTemplate('Player Cruiser')" \
    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 cause the game server to halt.

Serving Webpages

Create a directory called www in the EmptyEpsilon directory and place your html, css, images, and javascript files there. If you have an index.html file, others can browse to http://serverip:8080 to view the index page. 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 web server is experimental and potentially unsafe. If security is a high priority, don't enable it, especially on internet-accessible servers!