-
Notifications
You must be signed in to change notification settings - Fork 32
Developer Documentation How to Integrate with or Extend TestFlight
At the core, TestFlight was designed from the ground up to be extensible. All of the work for recording data, determining reliability, and actually failing parts, is handled by modules that plug into the main TestFlight API. This means that the system can be extended to do almost anything you can imagine by making your own custom modules to plug in.
TestFlight has a public interface which can be used to help integrate your own mod with TestFlight. Perhaps you simply want access to the recorded FlightData so that your mod can use it for something, or maybe you want to manipulate the part reliabilities to simulate or more or less advanced space program. Whatever it is you want to do, TestFlight provides a public interface that can be used for many purposes.
TestFlight has essentially two public interfaces or APIs. Although they are very similar -- in fact one is largely calling the other -- two exist because one or the other may be easier to use depending on the situation, and I wanted to make things as easy on other modders as I possibly could.
Although there really is not much of a distinction, if any, between the term Interface and API (in fact the acronym API stands for Application Programming Interface), I use the two terms to separate the two interfaces available.
In general when I say API I am referring to the internal API used by TestFlight modules, which consists of the various PartModule interface definitions such as ITestFlightCore, ITestFlightReliability, IFlightDataRecorder, and ITestFlightFailure. These API interfaces are not, to the best of my knowledge, usable by Reflection. They are what you would be using if you are making a new module to plug in and extend the TestFlight system. They may also be used for other purposes if desired, and I will cover that later.
The other option, which in general I call the Interface was designed specifically to be usable through Reflection. It essentially mirrors and wraps the ITestFlightCore API interface, and makes the majority of its methods available through Reflection calls. This means you can use it without any hard dependency on any of TestFlight's DLL assemblies. There are some limitations of the Reflection system however, so while the majority of ITestFlightCore can be accessed this way, sadly not quite all of it can be.
There are essentially three ways to interact with TestFlight from your own code.
- Standard "Reference"
- Reflection
- Hybrid mechanism
This is the easiest and most basic way to use TestFlight, either to make a new TestFlight module that plugs into the system, or to integrate TestFlight into your own mod. Simply include a reference to TestFlightAPI.dll in your project, and you can directly use the public API, or implement the API Interface into your own modules.
The downside to this system is that you have a hard dependency on TestFlight so anyone using your mod would also need to have TestFlight installed. This is fine if you are making modules to extend TestFlight, but may or may not be desired in other situations. Still it is by far the easiest approach.
Reflection is a whole complex and confusing world of programming that I really wont get into here, and I am no expert on it myself. However in a nutshell what Reflection allows you to do is access TestFlight's Interface without requiring a Reference to the .dll in your project. The advantage here is there is no hard dependency so your mod can still be used even if TestFlight it not installed, as long as you write your code such that you don't call any TestFlight methods unless it is installed.
The downside is it is confusing to most people, the code is ugly, and there are limitations to what parts of the interface I can properly expose to Reflection. Still, I've made as much of it available as possible and it is a viable way to approach it if you want to be sure you have no dependency on TestFlight.
I present a third option which is essentially the best of both worlds, but I want to caveat it as thus: This works for me in my tests, but I have some indication it might not always work.
That said, the hybrid approach is to Reference TestFlightAPI.dll just like you would in the first method, but use Reflection to determine if TestFlight is installed and usable before actually calling any methods using that hard reference. In my tests this allowed the add-on to work properly both with and without TestFlight installed in KSP, and provided the simplicity of direct method calls, without the hard dependency on TestFlight. In my humble opinion, try this first and if it works for you then it really is the best of both worlds.
- TestFlight API Reference Documentation
- Example Failure Module for TestFlight
- Example Reflection Usage
- Example Hybrid Usage