EDSystemsClassLibrary

.NET 8 library for Elite Dangerous colonization pathfinding: shortest hop chains of at most 15 LY between named systems in the full systems.json.

This is an unofficial fan project. Elite Dangerous is a trademark of Frontier Developments plc.

What it does

• Loads the full systems.json (on the order of 165 million systems with coordinates).
• Builds a structure-of-arrays catalog and a 15 LY spatial grid.
• Persists them as systems.catalog.cache and systems.grid.cache so later runs skip the JSON parse and grid build.
• EDSystemsPathFinder.FindPath(sourceName, destName) returns the hop list as EDSystem records.

First use on a new systems.json is slow and memory-heavy (tens of GB RAM). After the caches exist, load is a binary read of those files.

Requirements

• .NET 8 SDK
• A systems.json file: an array of objects with id64, name, and coords { x, y, z } (for example from Spansh)
• Enough disk and RAM for systems.json plus caches (systems.json alone is tens of GB)

Quick start

using EDSystemsClassLibrary;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;

var builder = Host.CreateApplicationBuilder(args);
builder.Configuration.AddEDSystemsDefaults();
builder.Services.AddEDSystems(builder.Configuration);

var host = builder.Build();
var finder = host.Services.GetRequiredService<EDSystemsPathFinder>();

var path = finder.FindPath("Sol", "Alpha Centauri");
foreach (var system in path)
    Console.WriteLine(system.Name);

Pass a systems.json path into the constructor to override the configured default:

var finder = new EDSystemsPathFinder(logger, options, @"D:\data\systems.json");

FindPath loads (or creates) the catalog and grid on the first call and reuses them afterward. If systems.json is newer than the catalog cache, both caches are deleted and rebuilt.

Configuration

Library defaults live in the embedded appsettings.json. The host should call AddEDSystemsDefaults() first, then overlay its own settings.

Setting	Default	Role
DataDirectory	d:\data	Folder for systems.json and caches
SystemsJsonFilename	systems.json	File name of the full systems.json
SystemsCatalogCacheFilename	systems.catalog.cache	Catalog binary cache
SystemsGridCacheFilename	systems.grid.cache	Spatial grid binary cache
AllowOneCellDetour	false	Allow path search to step one grid cell off the destination axis
Logging:LogLevel:EDSystemsClassLibrary	Information	Library log category

Example host appsettings.json:

{
  "DataDirectory": "D:\\data",
  "AllowOneCellDetour": false,
  "Logging": {
    "LogLevel": {
      "EDSystemsClassLibrary": "Information"
    }
  }
}

Caches

File	When it is created
systems.catalog.cache	First catalog load if the file is missing
systems.grid.cache	First grid load if the file is missing

If a cache file exists but cannot be read, load throws (delete the file to rebuild). Tests that rebuild caches are CatalogCacheCreationTests and GridCacheCreationTests.

Web site

EDSystemsWeb is an ASP.NET Core site plus REST API. The home page takes a source and destination system, calls the API, and shows the hop list with distances.

dotnet run --project EDSystemsWeb

Then open http://localhost:5080. The catalog loads in the background on startup; the form waits until GET /api/status reports ready.

Method	Path	Role
GET	/api/paths?source={name}&destination={name}	Colonization path and hop distances
POST	/api/paths	Same, with JSON { "source", "destination" }
GET	/api/status	Whether the catalog is loaded

Building and testing

dotnet build
dotnet test --filter "FullyQualifiedName~SettingsTests|FullyQualifiedName~BinaryPathFor|FullyQualifiedName~PathResponseMapperTests"

Pathfinding and cache-creation tests need the full systems.json and caches under DataDirectory. systems.json is not in this repository.

License

MIT. See LICENSE.