Refactor first footfall and organic value/bonus logic

Renamed Body.alreadyfootfalled to alreadyfirstfootfalled for clarity and updated its documentation. Revised footfalled timestamp logic to always record the first footfall by the current commander. Enhanced Organic with value and bonus properties, using actual event or definition data, and added firstFootfallRegistered logic for bonus calculation. Updated organic species definitions with real credit values. Improved [PublicAPI] annotations for better documentation and integration. Updated event handling and LocationMonitor to use new properties and logic.
Resolves #2788.

Author: Tkael

ChangeLog.md

@@ -5,6 +5,12 @@ Full details of the variables available for each noted event, and VoiceAttack in
 ## 5.0.0
   * Core
     * Target framework updated to .Net 8.
+    * The `Body` object boolean property `alreadyfootfalled` has been renamed to `alreadyfirstfootfalled` for clarity.
+    * The `Body` object unix timestamp property `footfalled` has been revised to record your first footfall regardless of whether another commander had already set foot on the body.
+    * The `Organic` object has been revised to include a credit `value` property (set whenever the species is identified and when organic data is sold). 
+    * The `Organic` object has been revised to include a credit `bonus` property (set when you have registered a first footfall on the body and when organic data is sold). 
+  * Events
+    * 
   * VoiceAttack Responder 
     * (**BREAKING CHANGE**) Updated to target VoiceAttack 2.0.0+. VoiceAttack 1.X is no longer supported. 
     * Under the hood, EDDI now runs as a separate process from VoiceAttack. Only the plugin component of EDDI runs within the VoiceAttack process. This should improve stability and performance for both EDDI and VoiceAttack.

DataDefinitions/Body.cs

@@ -6,10 +6,10 @@ namespace EddiDataDefinitions
 {
     public class Organic
     {
-        [ Utilities.PublicAPI ]
+        [ Utilities.PublicAPI ("Genus details" ) ]
         public OrganicGenus genus { get; set; }
 
-        [Utilities.PublicAPI ]
+        [Utilities.PublicAPI ("Species details" ) ]
         public OrganicSpecies species
         {
             get => _species;
@@ -21,7 +21,7 @@ public OrganicSpecies species
         }
         private OrganicSpecies _species;
 
-        [ Utilities.PublicAPI ]
+        [ Utilities.PublicAPI ("Variant details" ) ]
         public OrganicVariant variant
         {
             get => _variant;
@@ -34,39 +34,35 @@ public OrganicVariant variant
         }
         private OrganicVariant _variant;
 
-        [ Utilities.PublicAPI] 
+        [ Utilities.PublicAPI("The invariant name of the organic")] 
         public string invariantName => ConsolidatedName( _variant?.invariantName, _species?.invariantName, genus?.invariantName );
 
-        [Utilities.PublicAPI]
+        [Utilities.PublicAPI("The localized name of the organic")]
         public string localizedName => ConsolidatedName( _variant?.localizedName, _species?.localizedName, genus?.localizedName );
 
-        [JsonIgnore, Utilities.PublicAPI( "The minimum value from all predictions of this genus." )]
-        public long predictedMinimumValue => valueOverride ?? genusPredictedMinimumValue ?? 0;
-
-        [JsonIgnore, Utilities.PublicAPI( "The maximum value from all predictions of this genus." )]
-        public long predictedMaximumValue => valueOverride ?? genusPredictedMaximumValue ?? 0;
-
-        [JsonProperty]
-        internal long? genusPredictedMinimumValue = null;
+        [Utilities.PublicAPI( "The minimum distance that you must travel before you can collect a fresh sample of this genus (if known)" ), JsonIgnore]
+        public int? minimumDistanceMeters => genus?.minimumDistanceMeters;
 
-        [JsonProperty]
-        internal long? genusPredictedMaximumValue = null;
+        [Utilities.PublicAPI( "The base credit value, as awarded when selling organic data" )]
+        public long? value => valueOverride ?? species?.value;
 
-        [JsonIgnore, Utilities.PublicAPI( "The minimum distance that you must travel before you can collect a fresh sample of this genus (if known)" )]
-        public int? minimumDistanceMeters => genus?.minimumDistanceMeters;
+        /// <summary>
+        /// If true, apply a predicted bonus to the value of this organic (as presumably no other commander has sold this organic before).
+        /// </summary>
+        public bool firstFootfallRegistered { get; set; }
 
         /// <summary>
         /// Overrides the credit values from definitions when an actual value is indicated (as by the `OrganicDataSold` event)
         /// </summary>
         public long? valueOverride { get; set; } = null;
 
+        [Utilities.PublicAPI( "The bonus credit value, as awarded when selling organic data. The bonus value is assumed to apply when a first footfall has been registered." )]
+        public long? bonus => bonusOverride ?? (firstFootfallRegistered ? value * 4 : 0); 
+
         /// <summary>
-        /// Sets the value from predictions, this could be the minimum value from several predicted species of the same genus.
+        /// Overrides the bonus credit values from definitions when an actual value is indicated (as by the `OrganicDataSold` event)
         /// </summary>
-        //public long? valuePredicted { get; set; }
-
-        [Utilities.PublicAPI( "The bonus credit value, as awarded when selling organic data" )]
-        public decimal bonus { get; set; }
+        public long? bonusOverride { get; set; } = null;
 
         /// <summary>
         /// Populate the organic from variant data. Most preferred.
@@ -106,16 +102,6 @@ private string ConsolidatedName ( string variantName, string speciesName, string
                     .Where( n => n != null ) );
         }
 
-        public void SetPredictedMinimumValue ( long? minimum )
-        {
-            genusPredictedMinimumValue = minimum;
-        }
-
-        public void SetPredictedMaximumValue ( long? maximum )
-        {
-            genusPredictedMaximumValue = maximum;
-        }
-
         /// <summary> Get all the biological data, this should be done at the first sample </summary>
         [Utilities.PublicAPI]
         public static Organic Lookup ( long entryid, string variant )