Difference between revisions of "Arma 3 Headless Client"

From Bohemia Interactive Community
Jump to navigation Jump to search
(Created page with "=Headless Client Overview= * headless client is used to offload AI calculation from server * headless client is integrated into game client and dedicated server executable (WI...")
 
m (Text replacement - "<br />" to "<br>")
 
(35 intermediate revisions by 12 users not shown)
Line 1: Line 1:
=Headless Client Overview=
+
{{SideTOC}}
* headless client is used to offload AI calculation from server
+
* Headless Client is used to offload AI calculations from the server instance
* headless client is integrated into game client and dedicated server executable (WIndows and Linux, use -client parameter)
+
* Headless Client is integrated into game client and dedicated server executable (WIndows and Linux, use -client parameter)
* server doesn't allow to connect arbitrary headless client because headless clients are not verified on Steam, so server.cfg contains list of allowed headless clients IPs <code>headlessClients[]={"xxx.xxx.xxx.xxx", ...}</code>
+
* The server doesn't allow arbitrary connections from headless clients if you do not define the headless clients IPs in the '''server.cfg''', the below value defines accepted IP Addresses from Headless Clients.
  
* mission needs to be changed a little to support headless clients:
+
Multiple Connections and Addresses are allowed in the case of more than one Headless Client
 +
<syntaxhighlight lang="cpp">headlessClients[] = { "xxx.xxx.xxx.xxx", ... };</syntaxhighlight>
 +
Additionally to define clients with ''unlimited'' bandwidth and ''nearly no latency'' you must include theirs IPs in the '''server.cfg''' too:
 +
<syntaxhighlight lang="cpp">localClient[] = { "127.0.0.1", ... };</syntaxhighlight>
 +
 
 +
* Missions need to be changed a little to support headless clients:
 
** extract AI to separate AI script
 
** extract AI to separate AI script
 
** edit init.sqf to execute an extracted AI on headless client
 
** edit init.sqf to execute an extracted AI on headless client
Line 11: Line 16:
 
* next sections will show you how to use Headless Client
 
* next sections will show you how to use Headless Client
  
=Prerequisites=
 
* read these tutorials (at least the first one):
 
** http://dl.dropbox.com/u/6920345/HC_tutorial/hc_tutorial.pdf
 
** http://www.tacticalgamer.com/arma-mission-development/192601-headless-client-easy.html
 
** http://forums.bistudio.com/showthread.php?146708-A-comprehensive-guide-to-creating-a-headless-client-compatible-mission
 
  
=Prepare mission for Headless Client=
+
== Prerequisites ==
# create ai.sqf script that will spawn AI on headless client (see http://dl.dropbox.com/u/6920345/HC_tutorial/hc_tutorial.pdf)
+
 
# add Headless Client entity to map:
+
Read [https://www.dropbox.com/s/1n5a8entg3hvj5z/A3_hc_tutorial.pdf?dl=0 Headless Client Guide by Monsoon].
## add a regular unit (player, ...)
+
 
## then you can insert Headless Client unit:<code>SIDE: Game Logic, CLASS: Virtual Entities, UNIT: Headless Client, CONTROL: Playable, NAME: somename</code>
+
 
## don't forget to set NAME property, the name will be used to identify headless client in the scripts and it is used to connect headless client to proper headless client slot
+
== Spawning the AI ==
## each Headless Client unit will add one headless client slot, mission may contain multiple Headless Client units
+
 
# update init.sqf to offload AI to Headless Client, to execute AI on Headless Client add these lines to init.sqf: <code>playerName = name player;<br />if(playerName == "hc") then {<br /> // execute extracted AI on headless client named hc<br /> execVM "ai.sqf";<br />};</code>
+
# Add a '''Headless Client''' entity to the mission:
# put packed mission into mpmissions folder
+
## Add a player unit
 +
## Then you can insert a Headless Client unit: <code>SIDE: '''Game Logic''', CLASS: '''Virtual Entities''', UNIT: '''Headless Client''', CONTROL: '''Playable''', NAME: ''somename''</code>
 +
## Don't forget to set NAME property as the name can be used to identify Headless Clients in scripts (by checking it against [[player]])
 +
## Each Headless Client unit will add one Headless Client slot - missions may contain multiple Headless Client units
 +
# Create a script that will spawn AI (in the examples below we will use "init_HC.sqf"). To execute it on the Headless Client you have the two following options.
 +
#;Execute the script at mission start
 +
#*This method will make your mission spawn the AI '''only if''' a Headless Client is present. However it is the most simple to set up.
 +
##Add the following to the beginning of init.sqf:<br><code>[[if]] (![[hasInterface]] && ![[isServer]]) [[then]]<br>{<br> [[execVM]] "init_HC.sqf";<br>};</code>
 +
#;Execute the script via a mission parameter
 +
#*If you intend to share your mission this method is more desirable as it means players do not need a Headless Client to play it.
 +
##First define a [[Functions Library (Arma 3)|function]] to be used to run the headless client script file. Here's what it should look like in [[description.ext]]: <syntaxhighlight lang="cpp">
 +
class cfgFunctions
 +
{
 +
class myTag
 +
{
 +
class myCategory
 +
{
 +
class myFunction {};
 +
};
 +
};
 +
};</syntaxhighlight>The reason we want to define a function is because it can be used within the mission parameter framework to execute the AI spawning script as soon as possible while still allowing the mission to reliably work with or without a headless client.
 +
##Add the following code to your function: <code>[[if]] (([[_this]] [[select]] 0) == 1) [[then]]<br>{ {{codecomment|// Run on the HC only}}<br> [[if]] !([[isServer]] [[or]] [[hasInterface]]) [[then]]<br> {<br> [[execVM]] "init_HC.sqf";<br> };<br>} [[else]] {<br> {{codecomment|// Run on the server only}}<br> [[if]] ([[isServer]]) [[then]]<br> {<br> [[execVM]] "init_HC.sqf";<br> };<br>};</code>This code will be passed the value of the mission parameter defined in the next step, which is where the magic variable _this comes from. It executes the AI spawning script based on the value of the parameter and whether the local machine is the server or a headless client.
 +
##Finally define a [[Arma 3 Mission Parameters|mission parameter]] that players can use to enable/disable use of the headless client. Here's what it should look like in [[description.ext]]: <syntaxhighlight lang="cpp">
 +
class params
 +
{
 +
class headlessClient
 +
{
 +
title = "Headless Client";
 +
texts[] = {"Disabled","Enabled"};
 +
values[] = {0, 1};
 +
default = 0;
 +
function = "myTag_fnc_myFunction";
 +
isGlobal = 1;
 +
};
 +
};
 +
</syntaxhighlight>
 +
The two important values here are "function" and "isGlobal". The function value must correspond to the name of the function defined in step 1. The isGlobal value must be set to 1 so that the function is ran by all machines. This means that the function is executed on any headless clients as well as the server so that it can decide where it is suitable to execute the AI spawning script (based on the value of the parameter).
 +
# Repeat step 1 for the amount of Headless Clients your mission is designed to use. For multiple you must use the NAME property from step 1 to identify them individually within init_HC.sqf
 +
 
 +
 
 +
== Server ==
 +
 
 +
# add headless client IP address into server.cfg (you can use more than one address):<syntaxhighlight lang="cpp">headlessClients[] = { "xxx.xxx.xxx.xxx", "xxx.xxx.xxx.xxx", "xxx.xxx.xxx.xxx" };</syntaxhighlight>
 +
# to run Arma3 Dedicated Server use one of these commands:<code>Windows: arma3server.exe -config=server.cfg<br>Windows: arma3.exe -server -config=server.cfg<br>Linux: arma3server -config=server.cfg</code>
 +
 
  
=Server=
+
== Headless Client ==
# add headless client IP address into server.cfg (you can use more than one address):<code>headlessClients[]={"xxx.xxx.xxx.xxx", "xxx.xxx.xxx.xxx", "xxx.xxx.xxx.xxx"}</code>
 
# to run Arma3 Dedicated Server use one of these commands:<code>Windows: arma3server.exe -config=server.cfg<br />Windows: arma3.exe -server -config=server.cfg<br />Linux: arma3server -config=server.cfg</code>
 
  
=Headless Client=
+
# to run Arma3 Headless Client use one of these commands:<code>Windows: arma3server.exe -client -connect=xxx.xxx.xxx.xxx -password=yourpass<br>Windows: arma3.exe -client -connect=xxx.xxx.xxx.xxx -password=yourpass<br>Linux: arma3server -client -connect=xxx.xxx.xxx.xxx -password=yourpass</code>
# to run Arma3 Headless Client use one of these commands:<code>Windows: arma3server.exe -client -connect=xxx.xxx.xxx.xxx -name=hc -password=yourpass<br />Windows: arma3.exe -client -connect=xxx.xxx.xxx.xxx -name=hc -password=yourpass<br />Linux: arma3server -client -connect=xxx.xxx.xxx.xxx -name=hc -password=yourpass</code>
+
# your client will be automatically connected to a free headless client slot
# your client will be automatically connected to the headless client slot with the same name
 
 
# you can run arbitrary number of headless clients on the same machine
 
# you can run arbitrary number of headless clients on the same machine
  
=Overview of running options=
 
* Main game executable (windows only)<code>arma3.exe<br />arma3.exe -server<br />arma3.exe -client</code>
 
* Windows server executable<code>arma3server.exe<br />arma3server.exe -client</code>
 
* Linux server executable<code>arma3server<br />arma3server -client</code>
 
  
=GUI=
+
== Overview of running options ==
 +
 
 +
* Main game executable (windows only)<code>arma3.exe<br>arma3.exe -server<br>arma3.exe -client</code>
 +
* Windows server executable<code>arma3server.exe<br>arma3server.exe -client</code>
 +
* Linux server executable<code>arma3server<br>arma3server -client</code>
 +
 
 +
 
 +
== Mods ==
 +
 
 +
Headless clients are excluded from signature verification, therefore any mod can be used with the "-mod=" option.
 +
 
 +
"-serverMod=" does not work when used alongside "-client".
 +
 
 +
 
 +
== GUI ==
 +
 
 
* Headless clients can be seen in the Role assignment display when creating a MP game
 
* Headless clients can be seen in the Role assignment display when creating a MP game
 
** If you are admin (host)
 
** If you are admin (host)
Line 53: Line 105:
 
** HCs are listed with other players only if you are admin (map, tasks, kill statistics, ...)
 
** HCs are listed with other players only if you are admin (map, tasks, kill statistics, ...)
  
[[Category:Arma 3]]
+
 
 +
== Feedback ==
 +
 
 +
http://forums.bistudio.com/showthread.php?183918-Dedicated-Client-Headless-Client-feedback-(dev-branch)
 +
 
 +
 
 +
== See Also ==
 +
 
 +
* [[server.cfg]]
 +
 
 +
 
 
[[Category:Arma 3: Tutorials]]
 
[[Category:Arma 3: Tutorials]]
[[Category:Arma 3 Multiplayer]]
+
[[Category:Arma 3: Multiplayer]]

Latest revision as of 10:08, 19 March 2020

  • Headless Client is used to offload AI calculations from the server instance
  • Headless Client is integrated into game client and dedicated server executable (WIndows and Linux, use -client parameter)
  • The server doesn't allow arbitrary connections from headless clients if you do not define the headless clients IPs in the server.cfg, the below value defines accepted IP Addresses from Headless Clients.

Multiple Connections and Addresses are allowed in the case of more than one Headless Client

headlessClients[] = { "xxx.xxx.xxx.xxx", ... };

Additionally to define clients with unlimited bandwidth and nearly no latency you must include theirs IPs in the server.cfg too:

localClient[] = { "127.0.0.1", ... };
  • Missions need to be changed a little to support headless clients:
    • extract AI to separate AI script
    • edit init.sqf to execute an extracted AI on headless client
    • place headless client unit
  • in scripts the headless clients may be identified by its name, multiple headless clients are supported
  • next sections will show you how to use Headless Client


Prerequisites

Read Headless Client Guide by Monsoon.


Spawning the AI

  1. Add a Headless Client entity to the mission:
    1. Add a player unit
    2. Then you can insert a Headless Client unit: SIDE: Game Logic, CLASS: Virtual Entities, UNIT: Headless Client, CONTROL: Playable, NAME: somename
    3. Don't forget to set NAME property as the name can be used to identify Headless Clients in scripts (by checking it against player)
    4. Each Headless Client unit will add one Headless Client slot - missions may contain multiple Headless Client units
  2. Create a script that will spawn AI (in the examples below we will use "init_HC.sqf"). To execute it on the Headless Client you have the two following options.
    Execute the script at mission start
    • This method will make your mission spawn the AI only if a Headless Client is present. However it is the most simple to set up.
    1. Add the following to the beginning of init.sqf:
      if (!hasInterface && !isServer) then
      {
      execVM "init_HC.sqf";
      };
    Execute the script via a mission parameter
    • If you intend to share your mission this method is more desirable as it means players do not need a Headless Client to play it.
    1. First define a function to be used to run the headless client script file. Here's what it should look like in description.ext:
      class cfgFunctions
      {
      	class myTag
      	{
      		class myCategory
      		{
      			class myFunction {};
      		};
      	};
      };
      
      The reason we want to define a function is because it can be used within the mission parameter framework to execute the AI spawning script as soon as possible while still allowing the mission to reliably work with or without a headless client.
    2. Add the following code to your function: if ((_this select 0) == 1) then
      { // Run on the HC only
      if !(isServer or hasInterface) then
      {
      execVM "init_HC.sqf";
      };
      } else {
      // Run on the server only
      if (isServer) then
      {
      execVM "init_HC.sqf";
      };
      };
      This code will be passed the value of the mission parameter defined in the next step, which is where the magic variable _this comes from. It executes the AI spawning script based on the value of the parameter and whether the local machine is the server or a headless client.
    3. Finally define a mission parameter that players can use to enable/disable use of the headless client. Here's what it should look like in description.ext:
      class params
      {
      	class headlessClient
      	{
      		title = "Headless Client";
      		texts[] = {"Disabled","Enabled"};
      		values[] = {0, 1};
      		default = 0;
      		function = "myTag_fnc_myFunction";
      		isGlobal = 1;
      	};
      };
      

The two important values here are "function" and "isGlobal". The function value must correspond to the name of the function defined in step 1. The isGlobal value must be set to 1 so that the function is ran by all machines. This means that the function is executed on any headless clients as well as the server so that it can decide where it is suitable to execute the AI spawning script (based on the value of the parameter).

  1. Repeat step 1 for the amount of Headless Clients your mission is designed to use. For multiple you must use the NAME property from step 1 to identify them individually within init_HC.sqf


Server

  1. add headless client IP address into server.cfg (you can use more than one address):
    headlessClients[] = { "xxx.xxx.xxx.xxx", "xxx.xxx.xxx.xxx", "xxx.xxx.xxx.xxx" };
    
  2. to run Arma3 Dedicated Server use one of these commands:Windows: arma3server.exe -config=server.cfg
    Windows: arma3.exe -server -config=server.cfg
    Linux: arma3server -config=server.cfg


Headless Client

  1. to run Arma3 Headless Client use one of these commands:Windows: arma3server.exe -client -connect=xxx.xxx.xxx.xxx -password=yourpass
    Windows: arma3.exe -client -connect=xxx.xxx.xxx.xxx -password=yourpass
    Linux: arma3server -client -connect=xxx.xxx.xxx.xxx -password=yourpass
  2. your client will be automatically connected to a free headless client slot
  3. you can run arbitrary number of headless clients on the same machine


Overview of running options

  • Main game executable (windows only)arma3.exe
    arma3.exe -server
    arma3.exe -client
  • Windows server executablearma3server.exe
    arma3server.exe -client
  • Linux server executablearma3server
    arma3server -client


Mods

Headless clients are excluded from signature verification, therefore any mod can be used with the "-mod=" option.

"-serverMod=" does not work when used alongside "-client".


GUI

  • Headless clients can be seen in the Role assignment display when creating a MP game
    • If you are admin (host)
      • You will see HCs listed in the Players list on the right
      • You will see a category called Virtual (it can contain both Zeus and HCs) on the left
      • Note: HCs are automatically assigned to their slots
    • If you are normal player
      • You won't see any HCs anywhere
      • You won't see any Virtual category (if the mission contains Zeus then there will be Zeus category)
  • In-game UI
    • HCs are listed with other players only if you are admin (map, tasks, kill statistics, ...)


Feedback

http://forums.bistudio.com/showthread.php?183918-Dedicated-Client-Headless-Client-feedback-(dev-branch)


See Also