Module Client

Wrapper -- CLIENT wraps DCS Unit objects acting as a Client or Player within a mission.


Author: FlightControl

Contributions:


Global(s)

CLIENT

CLIENT class, extends Unit#UNIT

Clients are those Units defined within the Mission Editor that have the skillset defined as Client or Player.

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.ClientAlive2
CLIENT.ClientBriefing
CLIENT.ClientBriefingShown
CLIENT.ClientCallBack
CLIENT.ClientGroupID
CLIENT.ClientGroupName
CLIENT.ClientGroupUnit
CLIENT.ClientParameters
CLIENT.ClientTransport
CLIENT:Find(ClientName, ClientBriefing, DCSUnit, Error)

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: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

Global(s)

#CLIENT 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 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.

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).

Type Client

Type CLIENT

Extends Wrapper.Unit#UNIT

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:

#boolean CLIENT.ClientAlive2
CLIENT.ClientBriefing
#boolean CLIENT.ClientBriefingShown
CLIENT.ClientCallBack
CLIENT.ClientGroupID
CLIENT.ClientGroupName
CLIENT.ClientGroupUnit
CLIENT.ClientParameters
#boolean CLIENT.ClientTransport
CLIENT:Find(ClientName, ClientBriefing, DCSUnit, Error)

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 :

  • Error :

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.

CLIENT:Register(ClientName)

Parameter

  • ClientName :

CLIENT:Reset(ClientName)

Resets a CLIENT.

Parameter

  • #string ClientName : Name of the Group as defined within the Mission Editor. The Group must have a Unit with the type Client.

CLIENT:ShowBriefing()

Show the briefing of a CLIENT.

Return value

#CLIENT: self

CLIENT:ShowCargo()

Shows the AI_Cargo#CARGO contained within the CLIENT to the player as a message.

The AI_Cargo#CARGO is shown using the Message#MESSAGE distribution system.

CLIENT:ShowMissionBriefing(MissionBriefing)

Show the mission briefing of a MISSION to the CLIENT.

Parameter

  • #string MissionBriefing :

Return value

#CLIENT: self

CLIENT.SwitchMessages(PrmTable)

TODO (1) I urgently need to revise this. - A local function called by the DCS World Menu system to switch off messages.

Parameter

  • PrmTable :

CLIENT:Transport()

Transport defines that the Client is a Transport.

Transports show cargo.

Return value

#CLIENT:

CLIENT:_AliveCheckScheduler(SchedulerName)

Parameter

  • SchedulerName :

#table CLIENT._Menus