From 86f56eaac2bc5e12574bb857c3300e13be4745e9 Mon Sep 17 00:00:00 2001 From: Athanasius Date: Tue, 14 Jun 2022 14:01:36 +0100 Subject: [PATCH] schemas/fsssignaldiscovered README: Reworked for changed schema * Purely event-based batching, no timer. * Outline Horizons/Odyssey differences. * Point out that USS are manually scanned, so different in time nature. * StarSystem renamed from systemName. * StarSystem and StarPos now mandatory. --- schemas/fsssignaldiscovered-README.md | 295 +++++++++++++++----------- 1 file changed, 173 insertions(+), 122 deletions(-) diff --git a/schemas/fsssignaldiscovered-README.md b/schemas/fsssignaldiscovered-README.md index f07d8ae..6665b22 100644 --- a/schemas/fsssignaldiscovered-README.md +++ b/schemas/fsssignaldiscovered-README.md @@ -1,122 +1,173 @@ -# EDDN FSSSignalDiscovered Schema - -## Introduction -Here we document how to take data from an ED `FSSSignalDiscovered` Journal -Event and properly structure it for sending to EDDN. - -Please consult [EDDN Schemas README](./README-EDDN-schemas.md) for general -documentation for a schema such as this. - -## Senders -The primary data source for this schema is the ED Journal event -`FSSSignalDiscovered`. - -### Batching -You MUST put several `FSSSignalDiscovered` events to an array `signals` which is key of `message`. Minimum size of -`signals` is 1 item. - -Do not make a request for every single event. - -Possible algorithm of batching: -1. If the event is FSSSignalDiscovered, store it to the temporal list and proceed to next event. -2. If the next event is also FSSSignalDiscovered, repeat 1. -3. If the next event is any other or there is no other event for more than 10 seconds, send the - temporal list in a single message to EDDN. - -### Elisions -You MUST remove the following key/value pairs from the data: - - - `TimeRemaining` key/value pair. - -You MUST refuse to send the whole `FSSSignalDiscovered` event if `USSType` key has `$USS_Type_MissionTarget;` value. - -### Augmentations -#### horizons flag -You SHOULD add this key/value pair, using the value from the `LoadGame` event. - -#### odyssey flag -You SHOULD add this key/value pair, using the value from the `LoadGame` event. - -#### systemName -You SHOULD add a `systemName` string containing the system name from the last `FSDJump`, `CarrierJump`, or `Location` -event There exists problem when you gets `FSSSignalDiscovered` before -`FSDJump`, `CarrierJump`, or `Location` event, so you MUST cross-check it with `SystemAddress` or don't include at all. - -#### StarPos -You SHOULD add a `StarPos` array containing the system co-ordinates from the -last `FSDJump`, `CarrierJump`, or `Location` event. There exists problem when you gets `FSSSignalDiscovered` before -`FSDJump`, `CarrierJump`, or `Location` event, so you MUST cross-check it with `SystemAddress` or don't include at all. - -## Receivers -Receivers should remember: `horizons`, `odyssey`, `systemName`, `StarPos` are optional key/value pairs, it means you -should not rely on it will appear in every EDDN event. - -## Examples -This is a few example of messages that passes current `FSSSignalDiscovered` schema. -1. A message without `horizons`, `odyssey`, `systemName`, `StarPos` fields. -```json -{ - "$schemaRef":"https://eddn.edcd.io/schemas/fsssignaldiscovered/1", - "header":{ - "gatewayTimestamp":"2021-11-06T22:48:43.483147Z", - "softwareName":"an software", - "softwareVersion":"a version", - "uploaderID":"an uploader" - }, - "message":{ - "event":"FSSSignalDiscovered", - "signals":[ - { - "timestamp":"2021-07-30T19:03:08Z", - "event":"FSSSignalDiscovered", - "SystemAddress":1774711381, - "SignalName":"EXPLORER-CLASS X2X-74M", - "IsStation":true - } - ] - } -} -``` - -2. A message with `horizons`, `odyssey`, `systemName`, `StarPos` fields which says it sent from Odyssey. -```json -{ - "$schemaRef":"https://eddn.edcd.io/schemas/fsssignaldiscovered/1", - "header":{ - "gatewayTimestamp":"2021-11-06T22:48:43.483147Z", - "softwareName":"an software", - "softwareVersion":"a version", - "uploaderID":"an uploader" - }, - "message":{ - "event":"FSSSignalDiscovered", - "signals":[ - { - "timestamp":"2021-07-30T19:03:08Z", - "event":"FSSSignalDiscovered", - "SystemAddress":1774711381, - "SignalName":"EXPLORER-CLASS X2X-74M", - "IsStation":true - }, - { - "timestamp":"2020-12-31T14:14:01Z", - "event":"FSSSignalDiscovered", - "SystemAddress":216054883492, - "SignalName":"$USS_NonHumanSignalSource;", - "USSType":"$USS_Type_NonHuman;", - "SpawningState":"$FactionState_None;", - "SpawningFaction":"$faction_none;", - "ThreatLevel":5 - } - ], - "StarPos": [ - 8.1875, - 124.21875, - -38.5 - ], - "StarSystem": "HIP 56186", - "horizons": true, - "odyssey": true - } -} -``` +# EDDN FSSSignalDiscovered Schema + +## Introduction +Here we document how to take data from an ED `FSSSignalDiscovered` Journal +Event and properly structure it for sending to EDDN. + +Please consult [EDDN Schemas README](./README-EDDN-schemas.md) for general +documentation for a schema such as this. + +## Senders +The only data source for this schema is the ED Journal event +`FSSSignalDiscovered`. + +### Batching +You MUST coalesce contiguouys runs of `FSSSignalDiscovered` events into a +single `signals` array in the message. Minimum size of `signals` is 1 item. + +Do not make a request for every single event other than where they occur +singly (such as when a player utilises the FSS to zoom into USS individually). + +Suggested algorithm for batching: + +1. You will need to track the current location from `Location`, `FSDJump` and + `CarrierJump` events. This is in order to add the top-level augmentation + of `StarSystem` (system name) and `StarPos`. You will need to record: + 1. `SystemAddress` - for cross-checking. + 2. `StarSystem` - name of the star system. + 3. `StarPos` - the galactic co-ordinates of the system. +2. If the event is `FSSSignalDiscovered`, store it to the temporal list. +3. If the event is any other, then: + 1. check if it is `Location`, `FSDJump` or `CarrierJump` - if so you should + use this new location in the message. + 2. If it is not one of those events then you should use the tracked + location from the prior such event. + + Now construct the full `fsssignaldiscovered` schema message using the + tracked location and the stored list of events. *You **MUST** check that + the `SystemAddress` for each `FSSSignalDiscovered` event matches the + tracked location.* If there is a mis-match then drop that event. +4. Each batch of signals will be contiguous and thus should have the same + timestamp, perhaps +/- 1 second at the ends. As such you only need one + single `timestamp` in the `message` and should use that of the first event + you include. + +Point 3i/ii above are because in the current (3.8.0.406) Horizons client the +`FSSSignalDiscovered` events arrive after `Location`/`FSDJump`/`CarrierJump`, +but in the current (4.0.0.1302) Odyssey client they arrive before such events. + +Thus, in Horizons you use the last-tracked location, but in Odyssey you use +the "just arrived" location. + +Manually FSS-scanned USS type signals will come in one by one, possibly with +other events between them (such as `Music` due to zooming in/out in FSS). +There is no need to attempt batching these together if separated by other +events, even though you'll be using the `timestamp` of the first on the +message, despite the actual time-line being dependent on how quickly the +player scans them. + +This batching is more concerned with not causing an EDDN message per event +upon entry into a system. + +### Elisions +You MUST remove the following key/value pairs from the data: + + - `TimeRemaining` key/value pair (will be present on USS). This has a slight + PII nature and is also very ephemeral. + +You MUST drop the whole `FSSSignalDiscovered` event if `USSType` key +has `$USS_Type_MissionTarget;` value. Only the Cmdr with the mission has any +use of these. There's not even a statistical use. + +### Augmentations +#### horizons flag +You SHOULD add this key/value pair, using the value from the `LoadGame` event. + +#### odyssey flag +You SHOULD add this key/value pair, using the value from the `LoadGame` event. + +#### StarSystem +You **MUST** add a `StarSystem` string containing the system name from the last +tracked location. You **MUST** cross-check each `FSSSignalDiscovered` +->`SystemAddress` value to ensure it matches. If it does not, you **MUST** +drop the event. + +#### StarPos +You **MUST** add a `StarPos` array containing the system co-ordinates from the +tracked location. You **MUST** cross-check each `FSSSignalDiscovered` +->`SystemAddress` value to ensure it matches. If it does not, you **MUST** +drop the event. + +## Receivers +### Augmentations are 'SHOULD', not 'MUST' +Receivers should remember that `horizons`, `odyssey`, `StarSystem`, `StarPos` +are optional key/value pairs. You **SHOULD NOT** rely on them being present +in any given event. + +### Duplicate messages from 'busy' systems +When a system is particularly full of signals, such as when many Fleet Carriers +are present, it has been observed that the game repeats the identical +sequence of `FSSSignalDiscovered` events. So you might receive what looks like +a duplicate message, other than the timestamp (if the timestamp is the same +then the EDDN Relay should drop the duplicate). + +## Examples +This is a few example of messages that passes current `FSSSignalDiscovered` schema. +1. A message without `horizons` or `odyssey` augmentations. +```json +{ + "$schemaRef":"https://eddn.edcd.io/schemas/fsssignaldiscovered/1", + "header":{ + "gatewayTimestamp":"2021-11-06T22:48:43.483147Z", + "softwareName":"a software", + "softwareVersion":"a version", + "uploaderID":"an uploader" + }, + "message":{ + "timestamp":"2021-11-06T22:48:42Z", + "event":"FSSSignalDiscovered", + "SystemAddress":1774711381, + "signals":[ + { + "SignalName":"EXPLORER-CLASS X2X-74M", + "IsStation":true + } + ], + "StarSystem":"HR 1185", + "StarPos": [ + -64.66, -148.94, -330.41 + ] + } +} +``` + +2. A message with `horizons`, `odyssey`, `systemName`, `StarPos` fields which says it sent from Odyssey. +```json +{ + "$schemaRef":"https://eddn.edcd.io/schemas/fsssignaldiscovered/1", + "header":{ + "gatewayTimestamp":"2021-11-06T22:48:43.483147Z", + "softwareName":"a software", + "softwareVersion":"a version", + "uploaderID":"an uploader" + }, + "message":{ + "timestamp":"2021-11-06T22:48:42Z", + "event":"FSSSignalDiscovered", + "SystemAddress":1350507186531, + "signals":[ + { + "event":"FSSSignalDiscovered", + "SignalName":"EXPLORER-CLASS X2X-74M", + "IsStation":true + }, + { + "event":"FSSSignalDiscovered", + "SignalName":"$USS_NonHumanSignalSource;", + "USSType":"$USS_Type_NonHuman;", + "SpawningState":"$FactionState_None;", + "SpawningFaction":"$faction_none;", + "ThreatLevel":5 + } + ], + "StarPos": [ + 8.1875, + 124.21875, + -38.5 + ], + "StarSystem": "HIP 56186", + "horizons": true, + "odyssey": true + } +} +```