**NOTE: This function is slated to appear in 1.07.**

Discuss this page on this page's [[plyGetKeyEventStat Talk Page|Talk Page]]

=== plyGetKeyEventStat ===

^ Syntax | (plyGetKeyEventStat player stat nodeID typeCriteria) -> value |
^ Arguments | player: The player. (See [[Globals#DockScreens|gPlayer]]) |
^ | stat: An identifier naming the stat to obtain (see below). |
^ | nodeID: The nodeID for which stats are desired. If Nil, stats for all nodes will be returned. |
^ | typeCriteria: An a design type criteria specifying the types for which to return the stat. See: [[typFind]]. |
^ Returns | value: The value of the stat. |
^ Category | [[player functions|player]] |
^ Description | Returns the value of a key event stat. |

This function is designed to retrieve statistics about major events related to stations and objects in a system. Note that only ships with the attribute //majorShip// and stations with the attribute //majorStation// are tracked by this function.

=== Stats ===
The following item stat identifiers are defined:

  * **enemyObjsDestroyed** : Returns an array of lists. Each list represents an event in which a major enemy object was destroyed by the player in the systems of interest. See below for the format of the list.
  * **friendlyObjsDestroyed** : Returns an array of lists. Each list represents an event in which a major friendly object was destroyed by the player in the system of interest.
  * **objsDestroyed** : Returns an array of lists. Each list represents an event in which a major object was destroyed in the systems of interest.

An event is represented as a list with five elements. Each element is described below:

  * (0th element) : The type of event. This can be one of the following identifiers:
    * //destroyed// : A major object was destroyed by someone other than the player.
    * //enemyDestroyed// : A major enemy object was destroyed by the player.
    * //friendDestroyed// : A major friendly object was destroyed by the player.
  * (1st element) : The nodeID in which the event happened.
  * (2nd element) : The tick on which the event happened.
  * (3rd element) : The UNID of the object involved (e.g., this is the ShipClass or the StationType of the object that was destroyed).
  * (4th element) : The UNID of the sovereign that caused the event (e.g., the sovereign that destroyed the object).
  * (5th element) : The name of the object involved. Note that this value may be blank if the name is the same as the name of the type.
  * (6th element) : The name flags of the object involved. Ignore this value if the name is blank.

=== Notes ===
  * If the name of the object (5th element) is blank then you can obtain the name from the type.
  * If the name is not blank, use the [[fmtNoun]] function to convert the name and name flags into a proper noun phrase.

=== Example ===

<code lisp>(plyGetKeyEventStat gplayer 'objsDestroyed "SE" "* +commonwealth")</code>

Returns all instances in which a major object with the //commonwealth// attribute was destroyed in the Eridani system (SE).

Return to [[:Functions]] list