Elite.SpanshTools 1.0.0

Elite.SpanshTools

Tools for working with Spansh data dumps for Elite Dangerous. An expanded version of this readme with additional information is on the GitHub page.

What is this?

This is a set of tools and models for working programmatically in .NET with Spansh data dumps for Elite Dangerous. Specifically, it's for parsing files into an object model that can then be used in your tools, or just dumped to some format you feel like using to examine it. The sky's the limit.

What's in this?

This package contains two major items:

1. An object model representing the JSON format of the data dumps. The top-level object is StarSystem. Where possible, the model provides empty collections when a property doesn't exist for the system (e.g., a body has no stations) rather than null values, though there are plenty of nullable strings around.

2. A class called GalaxyParser (along with IGalaxyParser for dependency injection purposes) that parses a data dump as a stream. That is, it parses one line, does a yield return, and goes to the next line. See below for the method signatures.

You can also find some benchmarks in a separate project if you want to look at the code. To run the benchmark, you can just build it and run it at the command line (I recommend running it outside of the Visual Studio debugger). Use these commands, beginning at the source code root:

$ cd benchmarks
$ dotnet build -C Release
$ bin/Release/net8.0
$ ./Elite.SpanshTools.Benchmark.exe

Usage

Parsing a dump into a model is really easy:

string fileName = "galaxy.json";    // Downloaded from Spansh
await foreach (var system in parser.ParseFileAsync(fileName))
{
	// Do something with the system here
}

That's it! In most cases, the library will take care of opening and disposing the file stream for you. (With one exception; see Caveats, below.)

Performance

But how does it perform? Well, in addition to your machine, performance is dependent on the length of the individual records. A system like Sol (that has a JSON record 1,760,997 characters long) or Achenar (869,049 characters) will take longer to parse than Hypi Flee AA-A h0 (157 characters). Likewise, the galaxy files that contain details about systems, bodies, stations, markets, and commodities will take longer than the system files that contain top-level system information only.

That said, here are some numbers I found during my testing.

Caveats

There a few things to be aware of here:

1. Of the three methods available on GalaxyParser, only ParseFromStream() will not dispose the stream for you. The caller is responsible for handling that. The other two will create and tear down streams based on their input.

2. The format of the dumps is an array of objects (see below), comma-separated. Therefore, it is assumed that the format of any input is the same.

[
    { "id64":1234567890987, "name":"system1", ... },
    { "id64":8675309521474, "name":"system2", ... },
    { "id64":2516514354896, "name":"system3", ... }
]

Thanks and Final Notes

Thanks to Spansh for all the work he does both in providing these dumps to the Elite community and creating phenomenally useful tools for CMDRs. I've used them for most of my exploration missions, and they're invaluable.

If you have any questions, comments, or whatever, feel free to contact Merovech on GitHub.