From b1308e4f28f4cc126b496e199d65a68aef7988ac Mon Sep 17 00:00:00 2001 From: Athanasius Date: Mon, 9 Jan 2023 12:18:13 +0000 Subject: [PATCH] PLUGINS.md: Document addition of Bodt(ID|Type) and the caveats about use --- PLUGINS.md | 33 +++++++++++++++++++++++++++++++-- 1 file changed, 31 insertions(+), 2 deletions(-) diff --git a/PLUGINS.md b/PLUGINS.md index 0378ef96..279f6b5b 100644 --- a/PLUGINS.md +++ b/PLUGINS.md @@ -653,8 +653,9 @@ Content of `state` (updated to the current journal entry): | `SuitLoadouts` | `dict`[2] | CAPI-returned data of all Suit Loadouts. NB: May be `None` if no data. | | `Taxi` | `Optional[bool]` | Whether or not we're currently in a taxi. NB: This is best effort with what the journals provide. | | `Dropship` | `Optional[bool]` | Whether or not the above taxi is a Dropship | -| `Body` | `Optional[str]` | The body we're currently on / in the SOI of | -| `BodyType` | `Optional[str]` | The type of body that `Body` refers to | +| `Body`[3] | `Optional[str]` | Name of the body we're currently on / in the SOI of | +| `BodyID`[3] | `Optional[int]` | ID of the body we're currently on / in the SOI of | +| `BodyType`[3] | `Optional[str]` | The type of body that `Body` refers to | [1] - Contents of `NavRoute` not changed if a `NavRouteClear` event is seen, but plugins will see the `NavRouteClear` event. @@ -676,6 +677,28 @@ least one member is missing, so the indices are not contiguous). We choose to always convert to the integer-keyed `dict` form so that code utilising the data is simpler. +[3] - There are some caveats with the Body data. Firstly the name and ID +can be for the orbital station or fleet carrier the player is docked at. +Check 'BodyType' before using the values. + +Secondly there is an issue with close-orbiting binary bodies. If the player: + +1. Enters Orbital Cruise around a Body an 'ApproachBody' event is emitted + and the tracking will update to reflect this. +2. If the player then flies *in Orbital Cruise without entering Supercruise + proper* to the close-orbiting binary partner of the Body then *there is no + new 'ApproachBody' event to indicate the new Body's details*. **Thus this + tracking will incorrectly indicate the first Body still**. + +So, before making use of any of this Body state a plugin should: + +1. Have a `dashboard_entry()` method and track the Body name present in its + data. +2. Cross-check that Body name with `state['Body']` before making use of any + of `state'`s Body data. + +See `plugins/eddn.py` for an example of this in `export_journal_codexentry()`. + New in version 4.1.6: `CargoJSON` contains the raw data from the last read of `Cargo.json` passed @@ -765,6 +788,12 @@ re-start EDMarketConnector. That will be present when plugins are invoked with the synthetic `StartUp` event. NB: Might just be a `NavRouteClear` event if that's what was in the file. +New in version 5.8.0: +`BodyID` and `BodyType` have been added to the `state` dictionary. These +now track in the same manner as prior core EDDN plugin code. Check the +documentation above for some caveats. Do not just blindly use this data, or +the 'Body' name value. + ___ ##### Synthetic Events