third-party-mirrors/EDDN
1
0
Fork 0
mirror of https://github.com/EDCD/EDDN.git synced 2025-06-10 04:12:22 +03:00
Code Issues Actions Packages Projects Releases Wiki Activity

schemas/fsssignaldiscovered README: Reworked for changed schema

Browse Source 
* 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
1 changed files with 173 additions and 122 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

113
schemas/fsssignaldiscovered-README.md
View File

@ -8,27 +8,66 @@ 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: Suggested algorithm for 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. 1. You will need to track the current location from `Location`, `FSDJump` and
3. If the next event is any other or there is no other event for more than 10 seconds, send the `CarrierJump` events. This is in order to add the top-level augmentation
temporal list in a single message to EDDN. 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 ### Elisions
You MUST remove the following key/value pairs from the data: You MUST remove the following key/value pairs from the data:
- `TimeRemaining` key/value pair. - `TimeRemaining` key/value pair (will be present on USS). This has a slight
PII nature and is also very ephemeral.
You MUST refuse to send the whole `FSSSignalDiscovered` event if `USSType` key has `$USS_Type_MissionTarget;` value. 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 ### Augmentations
#### horizons flag #### horizons flag
@ -37,42 +76,56 @@ You SHOULD add this key/value pair, using the value from the `LoadGame` event.
#### odyssey flag #### odyssey flag
You SHOULD add this key/value pair, using the value from the `LoadGame` event. You SHOULD add this key/value pair, using the value from the `LoadGame` event.
#### systemName #### StarSystem
You SHOULD add a `systemName` string containing the system name from the last `FSDJump`, `CarrierJump`, or `Location` You **MUST** add a `StarSystem` string containing the system name from the last
event There exists problem when you gets `FSSSignalDiscovered` before tracked location. You **MUST** cross-check each `FSSSignalDiscovered`
`FSDJump`, `CarrierJump`, or `Location` event, so you MUST cross-check it with `SystemAddress` or don't include at all. ->`SystemAddress` value to ensure it matches. If it does not, you **MUST**
drop the event.
#### StarPos #### StarPos
You SHOULD add a `StarPos` array containing the system co-ordinates from the You **MUST** 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 tracked location. You **MUST** cross-check each `FSSSignalDiscovered`
`FSDJump`, `CarrierJump`, or `Location` event, so you MUST cross-check it with `SystemAddress` or don't include at all. ->`SystemAddress` value to ensure it matches. If it does not, you **MUST**
drop the event.
## Receivers ## Receivers
Receivers should remember: `horizons`, `odyssey`, `systemName`, `StarPos` are optional key/value pairs, it means you ### Augmentations are 'SHOULD', not 'MUST'
should not rely on it will appear in every EDDN event. 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 ## Examples
This is a few example of messages that passes current `FSSSignalDiscovered` schema. This is a few example of messages that passes current `FSSSignalDiscovered` schema.
1. A message without `horizons`, `odyssey`, `systemName`, `StarPos` fields. 1. A message without `horizons` or `odyssey` augmentations.
```json ```json
{ {
"$schemaRef":"https://eddn.edcd.io/schemas/fsssignaldiscovered/1", "$schemaRef":"https://eddn.edcd.io/schemas/fsssignaldiscovered/1",
"header":{ "header":{
"gatewayTimestamp":"2021-11-06T22:48:43.483147Z", "gatewayTimestamp":"2021-11-06T22:48:43.483147Z",
"softwareName":"an software", "softwareName":"a software",
"softwareVersion":"a version", "softwareVersion":"a version",
"uploaderID":"an uploader" "uploaderID":"an uploader"
}, },
"message":{ "message":{
"event":"FSSSignalDiscovered", "timestamp":"2021-11-06T22:48:42Z",
"signals":[
{
"timestamp":"2021-07-30T19:03:08Z",
"event":"FSSSignalDiscovered", "event":"FSSSignalDiscovered",
"SystemAddress":1774711381, "SystemAddress":1774711381,
"signals":[
{
"SignalName":"EXPLORER-CLASS X2X-74M", "SignalName":"EXPLORER-CLASS X2X-74M",
"IsStation":true "IsStation":true
} }
],
"StarSystem":"HR 1185",
"StarPos": [
-64.66, -148.94, -330.41
] ]
} }
} }
@ -84,24 +137,22 @@ This is a few example of messages that passes current `FSSSignalDiscovered` sche
"$schemaRef":"https://eddn.edcd.io/schemas/fsssignaldiscovered/1", "$schemaRef":"https://eddn.edcd.io/schemas/fsssignaldiscovered/1",
"header":{ "header":{
"gatewayTimestamp":"2021-11-06T22:48:43.483147Z", "gatewayTimestamp":"2021-11-06T22:48:43.483147Z",
"softwareName":"an software", "softwareName":"a software",
"softwareVersion":"a version", "softwareVersion":"a version",
"uploaderID":"an uploader" "uploaderID":"an uploader"
}, },
"message":{ "message":{
"timestamp":"2021-11-06T22:48:42Z",
"event":"FSSSignalDiscovered", "event":"FSSSignalDiscovered",
"SystemAddress":1350507186531,
"signals":[ "signals":[
{ {
"timestamp":"2021-07-30T19:03:08Z",
"event":"FSSSignalDiscovered", "event":"FSSSignalDiscovered",
"SystemAddress":1774711381,
"SignalName":"EXPLORER-CLASS X2X-74M", "SignalName":"EXPLORER-CLASS X2X-74M",
"IsStation":true "IsStation":true
}, },
{ {
"timestamp":"2020-12-31T14:14:01Z",
"event":"FSSSignalDiscovered", "event":"FSSSignalDiscovered",
"SystemAddress":216054883492,
"SignalName":"$USS_NonHumanSignalSource;", "SignalName":"$USS_NonHumanSignalSource;",
"USSType":"$USS_Type_NonHuman;", "USSType":"$USS_Type_NonHuman;",
"SpawningState":"$FactionState_None;", "SpawningState":"$FactionState_None;",