README.md

EliteAPI

An Elite: Dangerous API library for .NET

When playing Elite: Dangerous, many in-game events are outputted to the Journal log files. EliteAPI makes use of these files to provide live information about in-game events in a .NET environment.

Installation

EliteAPI is distributed through the NuGet package manager; the recommended way to install the library. Alternatively, the source can be compiled to retrieve the EliteAPI.dll file.

EliteAPI targets .NET Standard 2.0.

Installation using NuGet

EliteAPI is listed as EliteAPI on NuGet. Installing it can be done as follows:

dotnet add package EliteAPI

Building from source

The library can be built from source using the dotnet CLI.

$ git clone https://github.com/EliteAPI/EliteAPI.git EliteAPI
$ cd EliteAPI
$ dotnet build -c Release

The compiled EliteAPI.dll file can be found in in the bin\Release folder.

Creating an API instance

EliteAPI is designed to be used as a Service with dependency injection. Acquiring an instance of the API can be done in a few ways.

Host

The API can be added to your application's host. A host is used to encapsulate the application's resources, such as logging, configuration, and dependency injection. The API can be added using the AddEliteApi() method.

var host = Host.CreateDefaultBuilder()
    .ConfigureServices(services =>
    {
        services.AddEliteApi();
        services.AddTransient<MyAppService>(); // Example service
    })
    .Build();

var api = host.Services.GetService<IEliteDangerousApi>();

ServiceCollection

You can choose not the use the host and create a ServiceCollection directly, and add the API to it. Note that you lose the ability to configure resources such as logging, configuration, and dependency injection. The library contains an extension method AddEliteApi() that can be used to directly add all required API services to the IServiceCollection.

var serviceCollection = new ServiceCollection();
serviceCollection.AddEliteApi();

var services = serviceCollection.BuildServiceProvider();

var api = services.GetService<IEliteDangerousApi>();

Factory method

Alternatively, the Create() factory method can be used to create an instance of the EliteDangerousApi class.

var api = EliteDangerousApi.Create();

Getting started

EliteAPI constantly scans the Journal log files for new in-game events. Whenever a new event is detected it is invoked in the API.

Subscribing to in-game events

Subscribing to an event is done through the On<T>(), OnJson<T>(), OnAny(), and OnAnyJson() methods in the IEliteDangerousApi.Events property.

Method	Description	Parameter
On<T>()	Subscribes to an event of type T where T : IEvent	The event of type T
OnAny()	Subscribes to all events	The event of type IEvent
OnJson<T>()	Subscribes to an event of type T where T : IEvent	The JSON of the event
OnAnyJson()	Subscribes to all events	The JSON of the event

The EventContext object contains information about the event such as whether the event was raised during session catchup and the source of the event. The EventContext parameter is optional and does not need to be implemented.

The delegates passed to the On<T>() and OnJson<T>() methods are invoked whenever an event of type T is detected in-game. The delegates are invoked with the event and the optional EventContext object.

api.Events.On<DockingRequestedEvent>((e, context) =>
    Console.WriteLine($"Requested docking at {e.StationName}"));

Delegates passed to the OnAny() and OnAnyJson() methods are invoked whenever any event is detected in-game. These delegates are also invoked with the event and the optional EventContext object.

api.Events.OnAny(e =>
    Console.WriteLine($"Received event {e.Event}"));

The delegates can also be implemented through methods, if you prefer.

api.Events.On<GearStatusEvent>(OnGearChange);

void OnGearChange(GearStatusEvent gear, EventContext context)
{
    if (gear.Value)
        Console.WriteLine("Landing gear deployed");
    else
        Console.WriteLine("Landing gear retracted");
}

These delegates also allow for asynchronous implementations.

api.Events.On<FssSignalDiscoveredEvent>(async e =>
    await SomeAsyncMethod(e));

Waiting for in-game events

Waiting for an event is done through the WaitFor<T>() method in the IEliteDangerousApi.Events property.

Keybindings

EliteAPI exposes the in-game keybindings.

License

EliteAPI is distributed under the MIT license.