From 30048ded885938acdd9c4527360b4bdc40e71e76 Mon Sep 17 00:00:00 2001
From: norohind <60548839+norohind@users.noreply.github.com>
Date: Wed, 11 Aug 2021 17:47:06 +0300
Subject: [PATCH] PLUGINS.md: initial update for `journal_entry_cqc`
---
PLUGINS.md | 92 ++++++++++++++++++++++++++++++++++++++++++++++++++++--
1 file changed, 90 insertions(+), 2 deletions(-)
diff --git a/PLUGINS.md b/PLUGINS.md
index 5a7388b7..cf13d176 100644
--- a/PLUGINS.md
+++ b/PLUGINS.md
@@ -519,9 +519,9 @@ See [Avoiding potential pitfalls](#avoiding-potential-pitfalls).
### Events
-Once you have created your plugin and EDMC has loaded it there are three other
+Once you have created your plugin and EDMC has loaded it there are four other
functions you can define to be notified by EDMC when something happens:
-`journal_entry()`, `dashboard_entry()` and `cmdr_data()`.
+`journal_entry()`, `journal_entry_cqc()`, `dashboard_entry()` and `cmdr_data()`.
Your events all get called on the main Tkinter loop so be sure not to block for
very long or the app will appear to freeze. If you have a long running
@@ -697,6 +697,9 @@ react to either in your plugin code then either compare in a case insensitive
manner or check for both. The difference in case allows you to differentiate
between the two scenarios.
+**NB: Any of these events are passing to `journal_entry_cqc` rather than to
+`journal_entry` if player has loaded into Arena (CQC).**
+
This event is not sent when EDMC is running on a different
machine so you should not *rely* on receiving this event.
@@ -737,6 +740,91 @@ Examples of this are:
---
+---
+
+### Journal entry CQC
+New in version 5.1.3+
+```python
+def journal_entry_cqc(cmdr: str, is_beta: bool, entry: Dict[str, Any], state: Dict[str, Any]) -> None:
+ if entry['event'] == 'Location':
+ # We loaded to CQC match, lets detect map!
+ cqc_maps = { # dict to map systems names to CQC maps
+ 'Bleae Aewsy GA-Y d1-14': 'Asteria Point',
+ 'Eta Cephei': 'Cluster Compound',
+ 'Theta Ursae Majoris': 'Elevate',
+ 'Boepp SU-E d12-818': 'Ice Field',
+ }
+ cqc_map = cqc_maps.get(entry['StarSystem'])
+ logger.info(f'Loaded to CQC map {cqc_map}')
+```
+
+This gets called when EDMC sees a new entry in the game's journal and we are currently in CQC.
+
+| Parameter | Type | Description |
+| :-------- | :--------------: | :--------------------------------------------------------------------- |
+| `cmdr` | `str` | Current commander name |
+| `is_beta` | `bool` | Is the game currently in beta |
+| `entry` | `Dict[str, Any]` | The journal event |
+| `state` | `Dict[str, Any]` | More info about the commander, their ship, and their cargo (see below) |
+
+Content of `state` (updated to the current journal entry):
+
+| Field | Type | Description |
+| :------------------- | :------------------------------------ | :-------------------------------------------------------------------------------------------------------------- |
+| `GameLanguage` | `Optional[str]` | `language` value from `Fileheader` event. |
+| `GameVersion` | `Optional[str]` | `version` value from `Fileheader` event. |
+| `GameBuild` | `Optional[str]` | `build` value from `Fileheader` event. |
+| `Captain` | `Optional[str]` | Name of the commander who's crew you're on, if any |
+| `Cargo` | `Optional[dict]` | Current cargo. Note that this will be totals, and any mission specific duplicates will be counted together |
+| `CargoJSON` | `Optional[dict]` | content of cargo.json as of last read. |
+| `Credits` | `int` | Current credits balance |
+| `FID` | `str` | Frontier commander ID |
+| `Horizons` | `bool` | From `LoadGame` event. |
+| `Odyssey` | `bool` | From `LoadGame` event. `False` if not present, else the event value. |
+| `Loan` | `Optional[int]` | Current loan amount, if any |
+| `Raw` | `Optional[dict]` | Current raw engineering materials |
+| `Manufactured` | `Optional[dict]` | Current manufactured engineering materials |
+| `Encoded` | `Optional[dict]` | Current encoded engineering materials |
+| `Component` | `Optional[dict]` | Current component materials |
+| `Engineers` | `Optional[dict]` | Current Raw engineering materials |
+| `Rank` | `Optional[Dict[str, Tuple[int, int]]` | Current ranks, each entry is a tuple of the current rank, and age |
+| `Statistics` | `Optional[dict]` | Contents of a Journal Statistics event, ie, data shown in the stats panel. See the Journal manual for more info |
+| `Role` | `Optional[str]` | Current role if in multi-crew, one of `Idle`, `FireCon`, `FighterCon` |
+| `Friends` | `set` | Currently online friends |
+| `ShipID` | `Optional[int]` | Frontier ID of current ship |
+| `ShipIdent` | `Optional[str]` | Current user-set ship ID |
+| `ShipName` | `Optional[str]` | Current user-set ship name |
+| `ShipType` | `Optional[str]` | Internal name for the current ship type |
+| `HullValue` | `Optional[int]` | Current ship value, excluding modules |
+| `ModulesValue` | `Optional[int]` | Value of the current ship's modules |
+| `Rebuy` | `Optional[int]` | Current ship's rebuy cost |
+| `Modules` | `Optional[dict]` | Currently fitted modules |
+| `NavRoute` | `Optional[dict]` | Last plotted multi-hop route |
+| `ModuleInfo` | `Optional[dict]` | Last loaded ModulesInfo.json data |
+| `OnFoot` | `Optional[bool]` | Whether the Cmdr is on foot |
+| `Component` | `Optional[dict]` | 'Component' MicroResources in Odyssey, `int` count each. |
+| `Item` | `Optional[dict]` | 'Item' MicroResources in Odyssey, `int` count each. |
+| `Consumable` | `Optional[dict]` | 'Consumable' MicroResources in Odyssey, `int` count each. |
+| `Data` | `Optional[dict]` | 'Data' MicroResources in Odyssey, `int` count each. |
+| `BackPack` | `Optional[dict]` | `dict` of Odyssey MicroResources in backpack. |
+| `BackpackJSON` | `Optional[dict]` | Content of Backpack.json as of last read. |
+| `ShipLockerJSON` | `Optional[dict]` | Content of ShipLocker.json as of last read. |
+| `SuitCurrent` | `Optional[dict]` | CAPI-returned data of currently worn suit. NB: May be `None` if no data. |
+| `Suits` | `Optional[dict]`[1] | CAPI-returned data of owned suits. NB: May be `None` if no data. |
+| `SuitLoadoutCurrent` | `Optional[dict]` | CAPI-returned data of current Suit Loadout. NB: May be `None` if no data. |
+| `SuitLoadouts` | `Optional[dict]`[1] | 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 |
+
+[1] - Some data from the CAPI is sometimes returned as a `list` (when all
+members are present) and other times as an integer-keyed `dict` (when at
+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.
+___
+
### Shutdown
This gets called when the user closes the program: