Game state logging

EmptyEpsilon includes a feature to log snapshots of parts of each object's state in a running scenario to JSON.

This feature is enabled by default (game_logs=1 in the Preferences file) but works only when the working directory from which you run EmptyEpsilon has a subdirectory named logs.

Format

On each interval, the game state logger captures details about all existing SpaceObjects, including missiles and explosion effects. Each object type reports certain types of data; ships, for example, report shield and hull strength, and missiles report their active target (if any).

The output JSON lacks whitespace between objects and properties, but when reformatted, it resembles:

{
  "type": "state",
  "time": 0.0,
  "new_static": [
    {
      "type": "Mine",
      "id": 329,
      "position": [
        -5075.96142578125,
        -24131.759765625
      ],
      "rotation": 0.0
    },
...
  "type": "state",
  "time": 3.032273292541504,
  "new_static": [],
  "del_static": [],
  "objects": [
    {
      "type": "SpaceStation",
      "id": 327,
      "position": [
        0.0,
        -15000.0
      ],
      "rotation": 189.4150848388672,
      "callsign": "DS327",
      "faction": "Independent",
      "station_type": "Large Station",
      "hull": 500.0,
      "shields": [
        1000.0,
        1000.0,
        1000.0
      ],
      "config": {
        "hull": 500.0,
        "shields": [
          1000.0,
          1000.0,
          1000.0
        ]
      }
    },
  ...

Each line in the log is a "type": "state" with a unique, sequential time value in seconds equal to the scenario's mission clock.

Each state entry contains three arrays:

• new_static, reporting newly created objects that EE doesn't expect will change each second
• del_static, reporting objects that have been removed since the last state update
• objects, reporting every object that still exists

objects contains JSON object representations of things in the game at that time, and their properties.

All objects report some basic properties:

• type, representing its object type
• id, containing its unique multiplayer ID
• position, containing its x and y coordinates in the game space
• rotation, containing its rotation in degrees from pointing right ("east") on player views

Many SpaceObjects also report:

• callsign, as shown on player radars
• faction, as its string representation ("Independent", "Human Navy", etc.)

Other properties are specific to the object type. For example, in the station example above we see its current hull and shields segment values, followed by a config object containing its maximum values. We also see the station_type.

Note: Not all of a scenario's state is captured by the game state logger. For example, scenario-defined variables that aren't SpaceObjects aren't recorded.

Interval

The hardcoded logging interval is once per second on the mission clock. Pausing the game also pauses the logger.

For scenarios with many objects, especially ships, this interval means logs can grow to be very large, very quickly. Logs can easily reach hundreds of megabytes in size.

Usage

For an example of how you can use this logging data, see the logs directory of this repository, which contains an HTML document you can load in a web browser, then drag game state logs onto it to view a replay of the scenario. For another example of this, see https://oznogon.github.io/ee-gsl-viewer and its repository.