Module `Client`

This module contains the CLIENT class.

1) Client#CLIENT class, extends Unit#UNIT

Clients are those Units defined within the Mission Editor that have the skillset defined as Client or Player. Note that clients are NOT the same as Units, they are NOT necessarily alive. The Client#CLIENT class is a wrapper class to handle the DCS Unit objects that have the skillset defined as Client or Player:

Wraps the DCS Unit objects with skill level set to Player or Client.
Support all DCS Unit APIs.
Enhance with Unit specific APIs not in the DCS Group API set.
When player joins Unit, execute alive init logic.
Handles messages to players.
Manage the "state" of the DCS Unit.

Clients are being used by the MISSION class to follow players and register their successes.

1.1) CLIENT reference methods

For each DCS Unit having skill level Player or Client, a CLIENT wrapper object (instance) will be created within the _DATABASE object. This is done at the beginning of the mission (when the mission starts).

The CLIENT class does not contain a :New() method, rather it provides :Find() methods to retrieve the object reference using the DCS Unit or the DCS UnitName.

Another thing to know is that CLIENT objects do not "contain" the DCS Unit object. The CLIENT methods will reference the DCS Unit object by name when it is needed during API execution. If the DCS Unit object does not exist or is nil, the CLIENT methods will return nil and log an exception in the DCS.log file.

The CLIENT class provides the following functions to retrieve quickly the relevant CLIENT instance:

CLIENT.Find(): Find a CLIENT instance from the _DATABASE object using a DCS Unit object.
CLIENT.FindByName(): Find a CLIENT instance from the _DATABASE object using a DCS Unit name.

IMPORTANT: ONE SHOULD NEVER SANATIZE these CLIENT OBJECT REFERENCES! (make the CLIENT object references nil).

Global(s)

CLIENT

Type `CLIENT`

CLIENT:AddBriefing(ClientBriefing)	AddBriefing adds a briefing to a CLIENT when a player joins a mission.
CLIENT:Alive(CallBackFunction, ...)	Checks for a client alive event and calls a function on a continuous basis.
CLIENT.ClassName
CLIENT.ClientAlive
CLIENT.ClientAlive2
CLIENT.ClientBriefing
CLIENT.ClientBriefingShown
CLIENT.ClientCallBack
CLIENT.ClientGroupID
CLIENT.ClientGroupName
CLIENT.ClientGroupUnit
CLIENT.ClientName
CLIENT.ClientParameters
CLIENT.ClientTransport
CLIENT:Find(ClientName, ClientBriefing, DCSUnit)	Finds a CLIENT from the _DATABASE using the relevant DCS Unit.
CLIENT:FindByName(ClientName, ClientBriefing, Error)	Finds a CLIENT from the _DATABASE using the relevant Client Unit Name.
CLIENT:GetClientGroupDCSUnit()	Returns the DCSUnit of the CLIENT.
CLIENT:GetClientGroupID()
CLIENT:GetClientGroupName()	Get the name of the group of the client.
CLIENT:GetClientGroupUnit()	Returns the UNIT of the CLIENT.
CLIENT:GetDCSGroup()	Return the DCSGroup of a Client.
CLIENT:IsMultiSeated()	Checks if the CLIENT is a multi-seated UNIT.
CLIENT:IsTransport()	Evaluates if the CLIENT is a transport.
CLIENT:Message(Message, MessageDuration, MessageCategory, MessageInterval, MessageID)	The main message driver for the CLIENT.
CLIENT.Messages
CLIENT.ONBOARDSIDE
CLIENT:Register(ClientName)
CLIENT:Reset(ClientName)	Resets a CLIENT.
CLIENT:ShowBriefing()	Show the briefing of a CLIENT.
CLIENT:ShowCargo()	Shows the AI_Cargo#CARGO contained within the CLIENT to the player as a message.
CLIENT:ShowMissionBriefing(MissionBriefing)	Show the mission briefing of a MISSION to the CLIENT.
CLIENT.SwitchMessages(PrmTable)
CLIENT:Transport()	Transport defines that the Client is a Transport.
CLIENT:_AliveCheckScheduler(SchedulerName)
CLIENT._Menus
CLIENT._Tasks

Global(s)

#CLIENT CLIENT

Type `Client`

Type `CLIENT`

The CLIENT class

Field(s)

CLIENT:AddBriefing(ClientBriefing)

AddBriefing adds a briefing to a CLIENT when a player joins a mission.

Parameter

#string ClientBriefing : is the text defining the Mission briefing.

Return value

#CLIENT: self

CLIENT:Alive(CallBackFunction, ...)

Checks for a client alive event and calls a function on a continuous basis.

Parameters

#function CallBackFunction : Create a function that will be called when a player joins the slot.
... :

Return value

#CLIENT:

#string CLIENT.ClassName

#boolean CLIENT.ClientAlive

#boolean CLIENT.ClientAlive2

CLIENT.ClientBriefing

#boolean CLIENT.ClientBriefingShown

CLIENT.ClientCallBack

CLIENT.ClientGroupID

CLIENT.ClientGroupName

CLIENT.ClientGroupUnit

CLIENT.ClientName

CLIENT.ClientParameters

#boolean CLIENT.ClientTransport

CLIENT:Find(ClientName, ClientBriefing, DCSUnit)

Finds a CLIENT from the _DATABASE using the relevant DCS Unit.

Parameters

#string ClientName : Name of the DCS Unit as defined within the Mission Editor.
#string ClientBriefing : Text that describes the briefing of the mission when a Player logs into the Client.
DCSUnit :

Return value

#CLIENT:

Usage:

-- Create new Clients.
 local Mission = MISSIONSCHEDULER.AddMission( 'Russia Transport Troops SA-6', 'Operational', 'Transport troops from the control center to one of the SA-6 SAM sites to activate their operation.', 'Russia' )
 Mission:AddGoal( DeploySA6TroopsGoal )

 Mission:AddClient( CLIENT:FindByName( 'RU MI-8MTV2*HOT-Deploy Troops 1' ):Transport() )
 Mission:AddClient( CLIENT:FindByName( 'RU MI-8MTV2*RAMP-Deploy Troops 3' ):Transport() )
 Mission:AddClient( CLIENT:FindByName( 'RU MI-8MTV2*HOT-Deploy Troops 2' ):Transport() )
 Mission:AddClient( CLIENT:FindByName( 'RU MI-8MTV2*RAMP-Deploy Troops 4' ):Transport() )

CLIENT:FindByName(ClientName, ClientBriefing, Error)

Finds a CLIENT from the _DATABASE using the relevant Client Unit Name.

As an optional parameter, a briefing text can be given also.

Parameters

#string ClientName : Name of the DCS Unit as defined within the Mission Editor.
#string ClientBriefing : Text that describes the briefing of the mission when a Player logs into the Client.
#boolean Error : A flag that indicates whether an error should be raised if the CLIENT cannot be found. By default an error will be raised.

Return value

#CLIENT:

Usage:

-- Create new Clients.
	local Mission = MISSIONSCHEDULER.AddMission( 'Russia Transport Troops SA-6', 'Operational', 'Transport troops from the control center to one of the SA-6 SAM sites to activate their operation.', 'Russia' )
	Mission:AddGoal( DeploySA6TroopsGoal )

	Mission:AddClient( CLIENT:FindByName( 'RU MI-8MTV2*HOT-Deploy Troops 1' ):Transport() )
	Mission:AddClient( CLIENT:FindByName( 'RU MI-8MTV2*RAMP-Deploy Troops 3' ):Transport() )
	Mission:AddClient( CLIENT:FindByName( 'RU MI-8MTV2*HOT-Deploy Troops 2' ):Transport() )
	Mission:AddClient( CLIENT:FindByName( 'RU MI-8MTV2*RAMP-Deploy Troops 4' ):Transport() )

CLIENT:GetClientGroupDCSUnit()

Returns the DCSUnit of the CLIENT.

Return value

Dcs.DCSTypes#Unit:

CLIENT:GetClientGroupID(): TODO: Check Dcs.DCSTypes#Group.ID - Get the group ID of the client. @param #CLIENT self @return Dcs.DCSTypes#Group.ID

CLIENT:GetClientGroupName()

Get the name of the group of the client.

Return value

#string:

CLIENT:GetClientGroupUnit()

Returns the UNIT of the CLIENT.

Return value

Wrapper.Unit#UNIT:

CLIENT:GetDCSGroup()

Return the DCSGroup of a Client.

This function is modified to deal with a couple of bugs in DCS 1.5.3

Return value

Dcs.DCSWrapper.Group#Group:

CLIENT:IsMultiSeated()

Checks if the CLIENT is a multi-seated UNIT.

Return value

#boolean: true if multi-seated.

CLIENT:IsTransport()

Evaluates if the CLIENT is a transport.

Return value

#boolean: true is a transport.

CLIENT:Message(Message, MessageDuration, MessageCategory, MessageInterval, MessageID)

The main message driver for the CLIENT.

This function displays various messages to the Player logged into the CLIENT through the DCS World Messaging system.

Parameters

#string Message : is the text describing the message.
#number MessageDuration : is the duration in seconds that the Message should be displayed.
#string MessageCategory : is the category of the message (the title).
#number MessageInterval : is the interval in seconds between the display of the Message#MESSAGE when the CLIENT is in the air.
#string MessageID : is the identifier of the message when displayed with intervals.