Module Scoring

Single-Player:Yes / Multi-Player:Yes / Core:Yes -- Administer the scoring of player achievements, and create a CSV file logging the scoring events for use at team or squadron websites.

Banner Image

1) Scoring#SCORING class, extends Base#BASE

The #SCORING class administers the scoring of player achievements, and creates a CSV file logging the scoring events for use at team or squadron websites.

The scores are calculated by scoring the hits and destroys of objects that players make, which are Unit and Statics** can be defined for which scores are also granted when objects in that Zone are destroyed. This is specifically useful to designate scenery targets on the map that will generate points when destroyed.

With a small change in MissionScripting.lua, the scoring can also be logged in a CSV file.
The CSV files can be used to:

  • Upload scoring to a database or a BI tool to publish the scoring results to the player community.
  • Upload scoring in an (online) Excel like tool, using pivot tables and pivot charts to show mission results.
  • Share scoring amoung players after the mission to discuss mission results.

Scores can be reported. Menu options are automatically added to each group when a player joins a client slot or a CA unit. Use the radio menu F10 to consult the scores while running the mission. Scores can be reported for your user, or an overall score can be reported of all players currently active in the mission.

1.1) Set the destroy score or penalty multiplier

Score multipliers can be set for scores granted when enemies or friendlies are destroyed. Use the method SCORING.SetMultiplierDestroyScore() to set the multiplier of enemy destroys (positive destroys). Use the method SCORING.SetMultiplierDestroyPenalty() to set the multiplier of friendly destroys (negative destroys).

 local Scoring = SCORING:New( "Scoring File" )
 Scoring:SetMultiplierDestroyScore( 10 )
 Scoring:SetMultiplierDestroyPenalty( 40 )

The above sets the multiplier for valid scores to 10. So scores will be given in a scale from 0 to 10. The penalties will be given in a scale from 0 to 40.

1.2) Define special targets that will give extra scores.

Special targets can be set that will give extra scores to the players when these are destroyed. Use the methods SCORING.AddUnitScore() and SCORING.RemoveUnitScore() to specify a special additional score for a specific Units.
Use the methods SCORING.AddStaticScore() and SCORING.RemoveStaticScore() to specify a special additional score for a specific Statics.
Use the method SCORING.SetGroupGroup() to specify a special additional score for a specific Groups. 

 local Scoring = SCORING:New( "Scoring File" )
 Scoring:AddUnitScore( UNIT:FindByName( "Unit #001" ), 200 )
 Scoring:AddStaticScore( STATIC:FindByName( "Static #1" ), 100 )

The above grants an additional score of 200 points for Unit #001 and an additional 100 points of Static #1 if these are destroyed. Note that later in the mission, one can remove these scores set, for example, when the a goal achievement time limit is over. For example, this can be done as follows:

 Scoring:RemoveUnitScore( UNIT:FindByName( "Unit #001" ) )

1.3) Define destruction zones that will give extra scores.

Define zones of destruction. Any object destroyed within the zone of the given category will give extra points. Use the method SCORING.AddZoneScore() to add a Zone for additional scoring.
Use the method SCORING.RemoveZoneScore() to remove a Zone for additional scoring.
There are interesting variations that can be achieved with this functionality. For example, if the Zone is a Zone#ZONE_UNIT, then the zone is a moving zone, and anything destroyed within that Zone will generate points. The other implementation could be to designate a scenery target (a building) in the mission editor surrounded by a Zone, just large enough around that building.

1.4) Configure fratricide level.

When a player commits too much damage to friendlies, his penalty score will reach a certain level. Use the method SCORING.SetFratricide() to define the level when a player gets kicked.
By default, the fratricide level is the default penalty mutiplier * 2 for the penalty score.

1.5) Penalty score when a player changes the coalition.

When a player changes the coalition, he can receive a penalty score. Use the method SCORING.SetCoalitionChangePenalty() to define the penalty when a player changes coalition. By default, the penalty for changing coalition is the default penalty multiplier.

1.8) Define output CSV files.

The CSV file is given the name of the string given in the SCORING.New{} constructor, followed by the .csv extension. The file is incrementally saved in the **\Saved Games\DCS\Logs** folder, and has a time stamp indicating each mission run. See the following example:

local ScoringFirstMission = SCORING:New( "FirstMission" )
local ScoringSecondMission = SCORING:New( "SecondMission" )

The above documents that 2 Scoring objects are created, ScoringFirstMission and ScoringSecondMission.

1.9) Configure messages.

When players hit or destroy targets, messages are sent. Various methods exist to configure:

  • Which messages are sent upon the event.
  • Which audience receives the message.

1.9.1) Configure the messages sent upon the event.

Use the following methods to configure when to send messages. By default, all messages are sent.

1.9.2) Configure the audience of the messages.

Use the following methods to configure the audience of the messages. By default, the messages are sent to all players in the mission.

API CHANGE HISTORY

The underlying change log documents the API changes. Please read this carefully. The following notation is used:

  • Added parts are expressed in bold type face.
  • Removed parts are expressed in italic type face.

Hereby the change log:

2017-02-26: Initial class and API.

AUTHORS and CONTRIBUTIONS

Contributions:

  • Wingthor (TAW): Testing & Advice.
  • Dutch-Baron (TAW): Testing & Advice.
  • **Whisper: Testing and Advice.

Authors:

  • FlightControl: Concept, Design & Programming.

Global(s)

SCORING
nHours
nMins
nSecs

Type SCORING

SCORING:AddScoreGroup(ScoreGroup, Score)

Specify a special additional score for a Group.
SCORING:AddStaticScore(ScoreStatic, Score)

Add a Static for additional scoring when the Static is destroyed.
SCORING:AddUnitScore(ScoreUnit, Score)

Add a Unit for additional scoring when the Unit is destroyed.
SCORING:AddZoneScore(ScoreZone, Score)

Add a Zone to define additional scoring when any object is destroyed in that zone.
SCORING.ClassID
SCORING.ClassName
SCORING:CloseCSV()
SCORING.CoalitionChangePenalty
SCORING.Fratricide
SCORING.GameName
SCORING:IfMessagesDestroy()

If to send messages after a target has been destroyed.
SCORING:IfMessagesHit()

If to send messages after a target has been hit.
SCORING:IfMessagesScore()

If to send messages after a target has been destroyed and receives additional scores.
SCORING:IfMessagesToAll()

If to send messages to all players.
SCORING:IfMessagesToCoalition()

If to send messages to only those players within the same coalition as the player.
SCORING:IfMessagesZone()

If to send messages after a target has been hit in a zone, and additional score is received.
SCORING.MessagesAudience
SCORING.MessagesDestroy
SCORING.MessagesHit
SCORING.MessagesScore
SCORING.MessagesZone
SCORING.MultiplierDestroyPenalty
SCORING.MultiplierDestroyScore
SCORING:New(GameName)

Creates a new SCORING object to administer the scoring achieved by players.
SCORING:OnEventPlayerEnterUnit(Event)

Handles the OnPlayerEnterUnit event for the scoring.
SCORING:OnEventPlayerLeaveUnit(Event)

Handles the OnPlayerLeaveUnit event for the scoring.
SCORING:OpenCSV(ScoringCSV)

Opens a score CSV file to log the scores.
SCORING.Players

A collection of the current players that have joined the game.
SCORING:RemoveStaticScore(ScoreStatic)

Removes a Static for additional scoring when the Static is destroyed.
SCORING:RemoveUnitScore(ScoreUnit)

Removes a Unit for additional scoring when the Unit is destroyed.
SCORING:RemoveZoneScore(ScoreZone)

Remove a Zone for additional scoring.
SCORING:ReportDetailedPlayerCoalitionChanges(PlayerName)

Produce detailed report of player penalty scores because of changing the coalition.
SCORING:ReportDetailedPlayerDestroys(PlayerName)

Produce detailed report of player destroy scores.
SCORING:ReportDetailedPlayerHits(PlayerName)

Produce detailed report of player hit scores.
SCORING:ReportDetailedPlayerMissions(PlayerName)

Produce detailed report of player penalty scores because of changing the coalition.
SCORING:ReportScoreAllSummary(PlayerGroup)

Report all players score
SCORING:ReportScoreGroupDetailed(PlayerGroup)

Report Group Score Detailed
SCORING:ReportScoreGroupSummary(PlayerGroup)

Report Group Score Summary
SCORING.RunTime
SCORING:ScoreCSV(PlayerName, ScoreType, ScoreTimes, ScoreAmount, PlayerUnitName, PlayerUnitCoalition, PlayerUnitCategory, PlayerUnitType, TargetUnitName, TargetUnitCoalition, TargetUnitCategory, TargetUnitType)

Registers a score for a player.
SCORING.ScoringCSV
SCORING.ScoringObjects
SCORING.ScoringZones
SCORING:SecondsToClock(sSeconds)
SCORING:SetCoalitionChangePenalty(CoalitionChangePenalty)

When a player changes the coalition, he can receive a penalty score.
SCORING:SetFratricide(Fratricide)

When a player commits too much damage to friendlies, his penalty score will reach a certain level.
SCORING:SetMessagesDestroy(OnOff)

Configure to send messages after a target has been destroyed.
SCORING:SetMessagesHit(OnOff)

Configure to send messages after a target has been hit.
SCORING:SetMessagesScore(OnOff)

Configure to send messages after a target has been destroyed and receives additional scores.
SCORING:SetMessagesToAll()

Configure to send messages to all players.
SCORING:SetMessagesToCoalition()

Configure to send messages to only those players within the same coalition as the player.
SCORING:SetMessagesZone(OnOff)

Configure to send messages after a target has been hit in a zone, and additional score is received.
SCORING:SetMultiplierDestroyPenalty(Multiplier)

Set the multiplier for scoring penalty destroys (friendly destroys).
SCORING:SetMultiplierDestroyScore(Multiplier)

Set the multiplier for scoring valid destroys (enemy destroys).
SCORING:_AddMissionScore(Mission, PlayerUnit, Text, Score)

Registers Mission Scores for possible multiple players that contributed in the Mission.
SCORING:_AddMissionTaskScore(Mission, PlayerUnit, Text, Score)

Registers Scores the players completing a Mission Task.
SCORING:_AddPlayerFromUnit(UnitData)

Add a new player entering a Unit.
SCORING:_EventOnDeadOrCrash(Event)

Track DEAD or CRASH events for the scoring.
SCORING:_EventOnHit(Event)

Handles the OnHit event for the scoring.

Global(s)

#SCORING SCORING
nHours
nMins
nSecs

Type Scoring

Type SCORING

The Scoring class

Field(s)

SCORING:AddScoreGroup(ScoreGroup, Score)

Specify a special additional score for a Group.

Parameters

Return value

#SCORING:

SCORING:AddStaticScore(ScoreStatic, Score)

Add a Static for additional scoring when the Static is destroyed.

Note that if there was already a Static declared within the scoring with the same name, then the old Static will be replaced with the new Static.

Parameters

Return value

#SCORING:

SCORING:AddUnitScore(ScoreUnit, Score)

Add a Unit for additional scoring when the Unit is destroyed.

Note that if there was already a Unit declared within the scoring with the same name, then the old Unit will be replaced with the new Unit.

Parameters

  • Wrapper.Unit#UNIT ScoreUnit : The Unit for which the Score needs to be given.

  • #number Score : The Score value.

Return value

#SCORING:

SCORING:AddZoneScore(ScoreZone, Score)

Add a Zone to define additional scoring when any object is destroyed in that zone.

Note that if a Zone with the same name is already within the scoring added, the Zone (type) and Score will be replaced! This allows for a dynamic destruction zone evolution within your mission.

Parameters

  • Core.Zone#ZONE_BASE ScoreZone : The Zone which defines the destruction score perimeters. Note that a zone can be a polygon or a moving zone.

  • #number Score : The Score value.

Return value

#SCORING:

#number SCORING.ClassID
#string SCORING.ClassName
SCORING:CloseCSV()
SCORING.CoalitionChangePenalty
SCORING.Fratricide
SCORING.GameName
SCORING:IfMessagesDestroy()

If to send messages after a target has been destroyed.

Return value

#boolean:

SCORING:IfMessagesHit()

If to send messages after a target has been hit.

Return value

#boolean:

SCORING:IfMessagesScore()

If to send messages after a target has been destroyed and receives additional scores.

Return value

#boolean:

SCORING:IfMessagesToAll()

If to send messages to all players.

Return value

#boolean:

SCORING:IfMessagesToCoalition()

If to send messages to only those players within the same coalition as the player.

Return value

#boolean:

SCORING:IfMessagesZone()

If to send messages after a target has been hit in a zone, and additional score is received.

Return value

#boolean:

#number SCORING.MessagesAudience
SCORING.MessagesDestroy
SCORING.MessagesHit
SCORING.MessagesScore
SCORING.MessagesZone
#number SCORING.MultiplierDestroyPenalty
#number SCORING.MultiplierDestroyScore

Multipliers

SCORING:New(GameName)

Creates a new SCORING object to administer the scoring achieved by players.

Parameter

  • #string GameName : The name of the game. This name is also logged in the CSV score file.

Return value

#SCORING: self

Usage:

-- Define a new scoring object for the mission Gori Valley.
ScoringObject = SCORING:New( "Gori Valley" )
SCORING:OnEventPlayerEnterUnit(Event)

Handles the OnPlayerEnterUnit event for the scoring.

Parameter

SCORING:OnEventPlayerLeaveUnit(Event)

Handles the OnPlayerLeaveUnit event for the scoring.

Parameter

SCORING:OpenCSV(ScoringCSV)

Opens a score CSV file to log the scores.

Parameter

  • #string ScoringCSV :

Return value

#SCORING: self

Usage:

-- Open a new CSV file to log the scores of the game Gori Valley. Let the name of the CSV file begin with "Player Scores".
ScoringObject = SCORING:New( "Gori Valley" )
ScoringObject:OpenCSV( "Player Scores" )
SCORING.Players

A collection of the current players that have joined the game.

SCORING:RemoveStaticScore(ScoreStatic)

Removes a Static for additional scoring when the Static is destroyed.

Parameter

Return value

#SCORING:

SCORING:RemoveUnitScore(ScoreUnit)

Removes a Unit for additional scoring when the Unit is destroyed.

Parameter

Return value

#SCORING:

SCORING:RemoveZoneScore(ScoreZone)

Remove a Zone for additional scoring.

The scoring will search if any Zone is added with the given name, and will remove that zone from the scoring. This allows for a dynamic destruction zone evolution within your mission.

Parameter

  • Core.Zone#ZONE_BASE ScoreZone : The Zone which defines the destruction score perimeters. Note that a zone can be a polygon or a moving zone.

Return value

#SCORING:

SCORING:ReportDetailedPlayerCoalitionChanges(PlayerName)

Produce detailed report of player penalty scores because of changing the coalition.

Parameter

  • #string PlayerName : The name of the player.

Return value

#string: The report.

SCORING:ReportDetailedPlayerDestroys(PlayerName)

Produce detailed report of player destroy scores.

Parameter

  • #string PlayerName : The name of the player.

Return value

#string: The report.

SCORING:ReportDetailedPlayerHits(PlayerName)

Produce detailed report of player hit scores.

Parameter

  • #string PlayerName : The name of the player.

Return value

#string: The report.

SCORING:ReportDetailedPlayerMissions(PlayerName)

Produce detailed report of player penalty scores because of changing the coalition.

Parameter

  • #string PlayerName : The name of the player.

Return value

#string: The report.

SCORING:ReportScoreAllSummary(PlayerGroup)

Report all players score

Parameter

SCORING:ReportScoreGroupDetailed(PlayerGroup)

Report Group Score Detailed

Parameter

SCORING:ReportScoreGroupSummary(PlayerGroup)

Report Group Score Summary

Parameter

SCORING.RunTime
SCORING:ScoreCSV(PlayerName, ScoreType, ScoreTimes, ScoreAmount, PlayerUnitName, PlayerUnitCoalition, PlayerUnitCategory, PlayerUnitType, TargetUnitName, TargetUnitCoalition, TargetUnitCategory, TargetUnitType)

Registers a score for a player.

Parameters

  • #string PlayerName : The name of the player.

  • #string ScoreType : The type of the score.

  • #string ScoreTimes : The amount of scores achieved.

  • #string ScoreAmount : The score given.

  • #string PlayerUnitName : The unit name of the player.

  • #string PlayerUnitCoalition : The coalition of the player unit.

  • #string PlayerUnitCategory : The category of the player unit.

  • #string PlayerUnitType : The type of the player unit.

  • #string TargetUnitName : The name of the target unit.

  • #string TargetUnitCoalition : The coalition of the target unit.

  • #string TargetUnitCategory : The category of the target unit.

  • #string TargetUnitType : The type of the target unit.

Return value

#SCORING: self

SCORING.ScoringCSV
SCORING.ScoringObjects

Additional Object scores

SCORING.ScoringZones

Additional Zone scores.

SCORING:SecondsToClock(sSeconds)

Parameter

  • sSeconds :

SCORING:SetCoalitionChangePenalty(CoalitionChangePenalty)

When a player changes the coalition, he can receive a penalty score.

Use the method SCORING.SetCoalitionChangePenalty() to define the penalty when a player changes coalition. By default, the penalty for changing coalition is the default penalty multiplier.

Parameter

  • #number CoalitionChangePenalty : The amount of penalty that is given.

Return value

#SCORING:

SCORING:SetFratricide(Fratricide)

When a player commits too much damage to friendlies, his penalty score will reach a certain level.

Use this method to define the level when a player gets kicked.
By default, the fratricide level is the default penalty mutiplier * 2 for the penalty score.

Parameter

  • #number Fratricide : The amount of maximum penalty that may be inflicted by a friendly player before he gets kicked.

Return value

#SCORING:

SCORING:SetMessagesDestroy(OnOff)

Configure to send messages after a target has been destroyed.

Parameter

  • #boolean OnOff : If true is given, the messages are sent.

Return value

#SCORING:

SCORING:SetMessagesHit(OnOff)

Configure to send messages after a target has been hit.

Parameter

  • #boolean OnOff : If true is given, the messages are sent.

Return value

#SCORING:

SCORING:SetMessagesScore(OnOff)

Configure to send messages after a target has been destroyed and receives additional scores.

Parameter

  • #boolean OnOff : If true is given, the messages are sent.

Return value

#SCORING:

SCORING:SetMessagesToAll()

Configure to send messages to all players.

Return value

#SCORING:

SCORING:SetMessagesToCoalition()

Configure to send messages to only those players within the same coalition as the player.

Return value

#SCORING:

SCORING:SetMessagesZone(OnOff)

Configure to send messages after a target has been hit in a zone, and additional score is received.

Parameter

  • #boolean OnOff : If true is given, the messages are sent.

Return value

#SCORING:

SCORING:SetMultiplierDestroyPenalty(Multiplier)

Set the multiplier for scoring penalty destroys (friendly destroys).

A calculated score is a value between 0.1 and 10. The multiplier magnifies the scores given to the players.

Parameter

  • #number Multiplier : The multiplier of the score given.

Return value

#SCORING:

SCORING:SetMultiplierDestroyScore(Multiplier)

Set the multiplier for scoring valid destroys (enemy destroys).

A calculated score is a value between 0.1 and 10. The multiplier magnifies the scores given to the players.

Parameter

  • #number Multiplier : The multiplier of the score given.

SCORING:_AddMissionScore(Mission, PlayerUnit, Text, Score)

Registers Mission Scores for possible multiple players that contributed in the Mission.

Parameters

SCORING:_AddMissionTaskScore(Mission, PlayerUnit, Text, Score)

Registers Scores the players completing a Mission Task.

Parameters

SCORING:_AddPlayerFromUnit(UnitData)

Add a new player entering a Unit.

Parameter

SCORING:_EventOnDeadOrCrash(Event)

Track DEAD or CRASH events for the scoring.

Parameter

SCORING:_EventOnHit(Event)

Handles the OnHit event for the scoring.

Parameter