mirror of
https://github.com/EDCD/EDDN.git
synced 2025-06-09 20:02:21 +03:00
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
parent
329d59831f
commit
86f56eaac2
@ -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
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user