mirror of
https://github.com/EDCD/EDDN.git
synced 2025-04-29 06:31:32 +03:00
121 lines
5.1 KiB
Markdown
121 lines
5.1 KiB
Markdown
# EDDN CodexEntry Schema
|
|
|
|
## Introduction
|
|
Here we document how to take data from an ED `CodexEntry` 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.
|
|
|
|
If you find any discrepancies between what this document says and what is
|
|
defined in the relevant Schema file, then you should, in the first instance,
|
|
assume that it is the Schema file that is correct.
|
|
**PLEASE open
|
|
[an issue on GitHub](https://github.com/EDCD/EDDN/issues/new/choose)
|
|
to report any such anomalies you find so that we can check and resolve the
|
|
discrepancy.**
|
|
|
|
## Senders
|
|
The primary data source for this schema is the ED Journal event `CodexEntry`.
|
|
|
|
### Augmentations
|
|
#### horizons and odyssey flags
|
|
Please read [horizons and odyssey flags](../docs/Developers.md#horizons-and-odyssey-flags)
|
|
in the Developers' documentation.
|
|
|
|
#### StarPos
|
|
You MUST add a `StarPos` array containing the system co-ordinates from the
|
|
last `FSDJump`, `CarrierJump`, or `Location` event.
|
|
|
|
**You MUST apply a location cross-check, as per
|
|
[Other data augmentations](../docs/Developers.md#other-data-augmentations).**
|
|
|
|
#### BodyID and BodyName
|
|
You SHOULD attempt to track the BodyName and BodyID where the player is
|
|
and add keys/values for these.
|
|
|
|
You MUST track `BodyName` both from Status.json *and* also from some
|
|
Journal events in order to cross-check it before using the `BodyID` from
|
|
Journal events.
|
|
|
|
The following is correct as of game version 4.0.0.801 (Odyssey initial
|
|
release, Update 7, plus one patch).
|
|
|
|
1. Record `journal_body_name` and `journal_body_id` from the
|
|
`BodyName` and `BodyID` values in `ApproachBody` events.
|
|
|
|
This will occur when the player flies below Orbital Cruise altitude
|
|
around a body.
|
|
2. Also record these from `Location` events to cover logging in already there.
|
|
3. Unset both `journal_body_name` and `journal_body_id` on `LeaveBody` and
|
|
`FSDJump` events.
|
|
Do NOT do so for `SupercruiseEntry`, because a player can enter supercruise
|
|
below max Orbital Cruise altitude and then come back down without a new
|
|
`ApproachBody` event occurring.
|
|
4. If Status.json has `BodyName` present, record that as `status_body_name`.
|
|
|
|
This key and its value will be present whenever the player comes close
|
|
enough to a body for the Orbital Cruise/Glide HUD elements to appear.
|
|
It will disappear again when they fly back above that altitude, or jump
|
|
away.
|
|
5. If Status.json does **not** have `BodyName` then clear `status_body_name`.
|
|
6. For a `CodexEntry` event:
|
|
1. Only if `status_body_name` is set:
|
|
1. Set the EDDN `codexentry` schema message `BodyName` to this value.
|
|
2. Check if it matches the `journal_body_name` value, and
|
|
ONLY if they match, set `BodyID` in the EDDN `codexentry`
|
|
schema message to the value of `journal_body_id`.
|
|
|
|
If `status_body_name` is not set then you MUST NOT include `BodyName` or
|
|
`BodyID` keys/values in the EDDN message.
|
|
|
|
If `status_body_name` is set, but does not match with
|
|
`journal_body_name` then you MUST NOT include a `BodyID` key+value in the
|
|
EDDN message.
|
|
|
|
For emphasis, in both of these cases you MUST NOT include the keys with a
|
|
`null`, `''`, or otherwise 'empty' value. Do not include the key(s) at all.
|
|
|
|
One possible issue is binary bodies where you might get an `ApproachBody` for
|
|
one before descending towards the other, without an additional `ApproachBody`
|
|
to correct things.
|
|
|
|
An example of this is `Baliscii 7 a` and `Baliscii 7 b`. Approaching one
|
|
and going below Orbital Cruise altitude will set `journal_body_name` and
|
|
`journal_body_id` to it, but you can then turn and approach the other
|
|
without a new `ApproachBody` event, but `status_body_name` will change to
|
|
the other when you are close enough.
|
|
|
|
In this case due to `status_body_name` and `journal_body_name` not matching
|
|
the `codexentry` message MUST be sent **without** `BodyID`, but SHOULD be
|
|
sent with the `status_body_name` value on the `BodyName` key.
|
|
|
|
e.g. for `Bestia A 2 a`
|
|
```json
|
|
"BodyName": "Bestia A 2 a",
|
|
"BodyID": 15,
|
|
```
|
|
|
|
If you cannot properly obtain the values for `BodyName` or `BodyID` then
|
|
you MUST NOT include them.
|
|
|
|
## Listeners
|
|
|
|
As per ['BodyID and BodyName'](#bodyid-and-bodyname) above be aware that
|
|
you are not guaranteed to receive these values for any given event. Some
|
|
codex entries will be in space, and thus they aren't even relevant. In
|
|
other cases it may not have been possible to properly determine both of them.
|
|
|
|
So you might receive any of:
|
|
|
|
1. Neither `BodyName` nor `BodyID` present in the message, not even the
|
|
key names. This SHOULD indicate a codex entry object which is not on a
|
|
body surface.
|
|
2. `BodyName` key present with a value, but no `BodyID` key. This SHOULD
|
|
indicate a codex entry object which is on a body surface, but probably
|
|
where there is a close-orbiting binary companion which has confused things.
|
|
3. Both `BodyName` and `BodyID` keys present, with values. This SHOULD
|
|
indicate a codex entry object which is on a body surface.
|
|
|
|
Adjust your local processing accordingly.
|