mirror of
https://github.com/EDCD/EDDN.git
synced 2025-06-11 21:02:12 +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
|
# 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
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|||||||
Loading…
x
Reference in New Issue
Block a user