Defense Council of Humanity (DCOH) API support for getting system / station "thargoid war" state

[slippycheeze]

What happens now

Nothing. There is no way to easily determine the "thargoid war" state of a system, or a station, from the events the game fires. None of the existing API exposed to Cottle (or, as far as I can tell, used at all in EDDI) provides this information.

The Defense Council of Humanity (DCOH) provide an API on their website that combines data from participating commanders and human intervention to provide information on the "thargoid war" situation; this is the current gold standard for this data.

See How it can happen for details.

What I want to happen

I have a rescue ship, for landing on "burning" stations and pulling out refugees before they die. This can involve landing on a station that is literally on fire, which taking fire from an active thargoid attack ground on the way in.

I have a docking computer on the rescue ship because, honestly, I can't stand manual landings. A burning station, though, doesn't have auto-dock. It broken. So, I'd like to know where my landing pad is to manually set down on it.

EDDI, smartly, doesn't tell me where the landing pad is if a docking computer is present; I'd like that to be smarter, and skip that unless the station is broken, and so auto-docking won't work.

I'd also like to have EDDI yell at me—quite possibly literally—if I'm about to jump into a system that is thargoid controlled, under active attack, or otherwise carries a high risk of being hyperdicted and summarily shot by Thargoids.

That'd have to happen once I started a jump (or maybe targetted a system for jump?) but during the time I could still cancel charging and change my route or whatever.

How it can happen

The DCOH API is "documented" at https://dcoh.watch/consumer-api – just a bare list of endpoints. I've looked at the data, and my suggestion would be that EDDI fetch the "List systems" endpoint at GET /api/v1/overwatch/systems when missing or outdated.

note: they offer no expiration data or change checking in the headers, so it'd probably be best to define "outdated" as "15 minutes" or something like that.

Using the data returned as a local database of "thargoid war" information would allow EDDI to expose this to the Speech Responder cottle scripts, with no latency or network dependency.

From an API and long-term-support perspective, I'd add a custom function to retrieve the information, and define it to return null when there is no information available. That way if the DCOH API goes away, or the thargoid war vanishes, it can always return null and so provide a transition period where scripts still work (function is present) but never trigger (no data, which is technically correct.)

That'd allow a smooth transition between current and future support for the information.

A "thargoid war" monitor?

The information exported by DCOH could be used to build additional monitoring, such as "announce changes in system / station state", or informing users of updates to the overall situation. Providing UI to focus on what users care about, and events / speech responder scripts, would really tie it together.

I think that'd be something best left for later; there is a lot of gain from the minimal and fast implementation of a UI-free "monitor", and a cottle function, with low maintenance overhead and an easy path to removing it if it stops being relevant.

Determining state from ED Journal JSON, etc

Technically, there is some information available to EDDI that might make it possible to infer the state of a system or station, but: most of it is inference, and unreliable, and the other is only available very late, would need to be stored locally by EDDI, and would become out of date quickly.

In practice, it is best to treat the ED journal and other client-exported data as having zero "thargoid war" information.

EDDI Version

v.4.0.2, though it applies to all versions, at least until the Thargoid war stops being part of the FDev plan, and /that/ looks like a long way off.

[Tkael]

Closed as a duplicate of #2469.