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.
This commit is contained in:
Athanasius 2022-06-14 14:01:36 +01:00
parent 329d59831f
commit 86f56eaac2
No known key found for this signature in database
GPG Key ID: AE3E527847057C7D

View File

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