KC Grimes/Sandbox – User

From Bohemia Interactive Community
Jump to navigation Jump to search
(Prepare to edit ArmA: Introduction to Scripting)
 
m (Preparing to modify Waypoint types)
Line 1: Line 1:
{{Stub}}
[[File:icon map waypoint.jpg|thumb|Waypoints]]
 
During [[ArmA: Mission Editing|mission editing]] and [[ArmA: Addon Editing|addon editing]] you may come across situations where actions or features you would like to have in your mission or addon cannot be accomplished using the basic (or even the more advanced) capabilities of the [[ArmA: Mission Editor|mission editor]] or within config files (in the case of addons). Some examples of this might be really cinematic cutscenes in missions or special animations for an addon.
 
 
The '''solution''' to this is to take advantage of the game-engines ability to call on an even more advanced feature known as [[Scripting|scripting]]. [[Armed Assault|Armed Assault's]] '''scripting language''' gives you more direct control of core game commands. With any combination of these [[:Category:ArmA: Scripting Commands|scripting commands]] you can then create custom processes that meet the specific needs of your mission or addon.
 
== Terms ==
 
Before getting started, you should understand the meaning of these terms.
 
;Script
: When speaking about a [[Script (File)|script]], we usually mean a .sqs or .sqf file. Both file types can be edited as a plain text file using a program like Notepad or [http://www.geany.org/ Geany].
 
;Game Engine
: The core program of the game which reads and executes your scripting commands at run time.
 
;Function
: Piece of code which performs a specific task. A function may return a value. The mission author often writes complicated functions in .sqf files and then executes them in-game. Functions can be considered a kind of script. Usually, however, a "script" means a .sqs or .sqf file that runs over a period of time and directs gameplay, while a "function" is usually meant to run instantaneously and return a value. See [[function]].
 
== When Do I Need Scripting? ==


'''Be careful:''' Scripting isn't a solution to everything.
A [[Eden Editor: Waypoint|waypoint's]] type will define what the group is to do when the [[Eden Editor: Waypoint|waypoint]] becomes active.  


The first thing to ask yourself is, "Am I absolutely sure this cannot be done using just the editor?" The goal with scripting is to create processes that can't be done otherwise. Because scripting does use system resources, poorly written scripts can affect game play or performance. So, it pays to be sure you have learned as much as you can about how the editor works and you understand its capabilities and limitations.
= Waypoint Types =


The second thing to ask before you start scripting away is, "Will players even notice or use the action or feature I would like to implement?". It may seem silly, but just because it can be done does not always mean it should be.
== Move ==
The group will move to this point or object. The move waypoint is considered complete when the leader gets close to the waypoint, the required distance being between 1 and 500 meters depending on the leader's vehicle type (if any) and whether a player is controlling the leader. The movement mode and method will depend on the group's behaviour settings, with movement rarely being made in a straight line between waypoints. AI leaders will generally pause to choose a path before they start moving. Groups will automatically board any transport vehicles they own if the next waypoint is far enough away. If the waypoint is too far away or a valid path cannot be found, the group may never reach the waypoint. If a ''Move'' waypoint is attached to a building object, the "Position In House" menu option will become available.  


The third step (which may be the hardest, especially for people new to scripting) is to determine if what you want to do can be implemented with the scripting language.
== Destroy ==
This waypoint type works best when it is attached to a object. The group will attempt to destroy whatever object the waypoint is placed upon, irrespective of the target object's [[side]]. If the group is unable to destroy the attached object they will move within range of being able to identify the object, then wait until it is destroyed (even if the target is not destroyable!). If the waypoint is placed spatially, the waypoint's behaviour is less predictable. If the waypoint is far away from any mission editor placed objects, the waypoint will generally be instantly considered complete without the group moving towards the waypoint's location. If there is any object near the spatial waypoint, the group may treat that object as a normal destroy target. However, sometimes the group may start to attack the object, then instantly move to the next waypoint without destroying anything. The exact object the group will attack is not easily predicted, and if the group itself is near the spatial Destroy waypoint when it becomes active, the group may even choose to attack, but not necessarily destroy, one of it's own members.


If you aren't sure even after working out the preliminaries, just ask in the [http://forums.bistudio.com/ official forums] or at [http://www.ofpec.com OFPEC]. These would also be good places to ask other players for their feedback on question number two. If they become interested, they may serve as beta testers!
== Get In ==
The exact effect this waypoint type has depends on whether it is placed in empty space, attached to a vehicle or a non-vehicle object. There are many possible combinations of circumstances, each with slightly different effects.
* ''Spatial''
**If the waypoint is spatial, any walking units in the group will board free space in any vehicles with that the group possesses. Note this happens as the waypoint becomes active, rather than when it is reached. The group will not travel to the actual ''Get In'' waypoint's position, but carry out the boarding action and then continue on to the next waypoint.  
**If a spatial ''Get In'' waypoint is [[Mission_Editor#Synchronization|synchronized]] with a waypoint of another friendly group with unused vehicle spaces, but the original group has adequate transport, it will mount it's own vehicles.  
**If the spatial ''Get In'' waypoint is synchronized with a waypoint of another friendly group with unused vehicle spaces, the group will mount any available vehicle spaces of its own before boarding the other group's transport.
**If the spatial ''Get In'' waypoint is synchronized with a waypoint of another friendly group with some unused vehicle spaces but not enough to allow the entire group to board, the leader will order as many units as possible to board the other group's vehicles.  
**If the spatial ''Get In'' waypoint is synchronized with a waypoint of another friendly group with no free vehicle spaces, the group will move to the ''Get In'' waypoint's position, then move on to the next waypoint.
* ''Vehicle''
**If the waypoint is placed on an empty vehicle, as many of the group as possible will board it. If the waypoint is placed upon an empty vehicle and the group already has enough vehicle spaces to fit the entire group, the group leader only will board and drive the new vehicle, while any foot units will board the group's original vehicle(s).
**If the ''Get In'' waypoint is placed upon a vehicle driven by a friendly unit that has room enough to hold the entire group, the group will abandon any vehicles it has and board the new vehicle.
**If the waypoint is placed upon a vehicle driven by a friendly unit that is not capable of carrying the entire group and the group has no vehicles of its own, the leader will order as many of his troops as possible to board the vehicle.  
**If the waypoint is placed upon a vehicle driven by a friendly unit that is not capable of carrying the entire group, and the group already has vehicles capable of carrying the entire group, as many units as possible will board the waypoint vehicle and the remainder board the original transport.
**If the waypoint is placed upon a vehicle driven by a friendly unit that is not capable of carrying the entire group and the group has some vehicles but all vehicles will still not enough to fit the entire group, the leader will order as many troops as possible into both the group's vehicles and the waypoint vehicle.
**Finally, if the waypoint is attached to a non-vehicle class of object, the group will move to that object before boarding any available vehicle space it already has.


=== Checklist ===
== Seek & Destroy ==
It does not matter if this waypoint type is placed spatially or on an object. If attached to an object, the waypoint will remain fixed at the objects initial position as displayed in the mission editor (even if that object actually starts the mission in the cargo of another vehicle or has it's position changed by it's initialization string). Behaviour is the same for both situations - the group will move to the waypoint, then the leader will move about to search the immediate area with his group trying to keep up. The exact size of the area searched is limited to the leader's expected travel time. A leader on foot will rarely search more than 50m from the waypoint, while a leader in a helicopter will search up to 300m from the waypoint. The search will attempt to visually check all locations within the search range, so a search inside a city will take far longer than a search in an empty field. Unfortunately the Seek & Destroy waypoint does not appear to make the group deliberately search inside buildings although their pathfinding may lead them to enter some. Whether or not the group finds any enemy units appears to have no impact on the search duration or range.


In summary:
To make AI hunt down a known target, you need to [[setCombatMode]] to "RED". The Seek & Destroy waypoint only makes the AI search the vicinity of the waypoint itself, not affect their behavior on their way to the waypoint.


# Can I do it with the ([[ArmA: Mission Editor|mission editor]], [[ArmA: Addon Configuration|addon]], config files etc.)?
== Join ==
# Will players notice and/or use it?
When this waypoint type is attached to a unit, the group will move to the position of that unit, then join and follow that unit's group, irrespective of side or ranks. Note that the attached unit may have moved on, but the Join waypoint remains at the unit's location when the waypoint became active. When the Join waypoint is spatial, the group will treat it as a ''Move'' type waypoint. If the ''Join'' waypoint is [[Mission_Editor#Synchronization|synchronized]] with another group's waypoint, when both groups are at their waypoint positions, the group that is "synchronized from" will join the group that is "synchronized to", irrespective of which group has the join waypoint itself. When synchronizing, click and hold on the waypoint of the group that is to join the other, then drag to the other group's waypoint. Note only two groups can join at single Join waypoint.
# Is it possible?


If the first point is answered "No", but the second and third are answered "Yes", go on and script it! But be warned: It won't always be easy. ;-)
== Join & Lead ==
This type is exactly the same as the ''Join'' waypoint type, except the group that leads the merged group will be opposite in each situation.


== The Concept ==
== Get Out ==
The group will move to the waypoint, then disembark from any vehicles it's members are in. Helicopters will land on the closest "H pad" object within 500m of the waypoint. If any group members other than the leader are in a vehicle of another group, that vehicle will stop to let them out. If the leader is riding in another group's vehicle, the ''Get Out'' waypoint will not be considered reached until the leader arrives at it under his own control (ie, never). In this case a ''Transport Unload'' waypoint should be used. If the ''Get Out'' waypoint is placed on an object, the group will move to the location of that object at the instant the Get Out waypoint becomes it's current waypoint, then disembark as normal.


Scripts are an essential part of making missions. They allow you to create amazing cutscenes, create effects and customize almost every aspect of your mission. Some diverse examples of what could be scripted are: a simulation of artillery fire, a poisonous gas cloud, or a money system for purchasing equipment.      
== Cycle ==
This waypoint type will change the group's active waypoint to the nearest waypoint other than the group's previous waypoint. Note that the automatically created first waypoint (the leader's initial position as seen in the map editor) is considered as a Move type waypoint and can be used by the Cycle waypoint. A Cycle type waypoint can be used to make the group move in an infinite loop, a great and easy way to create a patrol. Either a ''Switch'' trigger or script can be used to "break" a group out of a cycle loop.


===Algorithm===
== Load ==
The group will move to the waypoint (spatial or object), then any soldiers on foot will board any vehicles the group possesses. They will get into the vehicles as cargo where possible, then as the crew of the vehicle.


Your first task in writing scripts is to decide what sequence of steps is needed to solve a particular problem. This sequence is what would be called an ''algorithm''.  
== Unload ==
The group will move to the waypoint (spatial or object), then any of it's units that are in cargo space of any vehicle will disembark. Units in crew positions will not disembark. One note, on a dedicated server when using this with AI controlled Helicopters. This command only works if there is an AI team commander present in the cargo of the vehicle. If there are only human players, the helicopter will not land. It will hover too high in the air to safely disembark.


For example, if you wanted to transport weapons from Petrovice to Lipany, you would (as commander) give these orders:
== Transport Unload ==
The group will move to the waypoint (spatial or object), where any units from other groups who are in cargo spaces of the original group's vehicles will disembark. On a dedicated server, this waypoint does not work if the commander of the group being transported in the back of the vehicle is human. It will only work with AI One note, on a dedicated server when using this with AI controlled Helicopters. This command only works if there is an AI team commander present in the cargo of the vehicle. If there are only human players, the helicopter will not land. It will hover too high in the air to safely disembark.


*'''Commander:''' Private Honka, private Kouba, come here!
Specifically for landing an AI helicopter on the ground and unloading AI passengers, the waypoint destination for Transport Unload must be a helipad object and be assigned to the pilots, and the separate group as passengers must have the Get Out waypoint at the same location. Both the Transport Unload waypoint and Get Out waypoint have to be synchronized with eachother. Note: createVehicleCrew breaks this functionality.
*'''Commander:''' Private Kouba, get in Ural as driver!
*'''Commander:''' Private Honka, get in Ural!
*'''Commander:''' Private Kouba, drive to Petrovice and load Ural!


*'''Private Kouba''': I don't know where Petrovice is, sir.
== Lift Cargo ==
In Arma 3, this waypoint lets AI helicopters pick up vehicles that their helicopter is capable of lifting. The behaviour seems to be very inconsistant, and the AI pilots seem almost completely incapable of picking up the cargo or dropping it off (They have a tendancy to circle if other entities are nearby).


Now we have a problem. Kouba only knows how to get to Lipany and Honka only knows how to get to Petrovice. Our soldiers are new recruits and are really quite stupid. They can only take simple orders, one order at a time.  They can get in and out of vehicles, drive, and load and unload weapons and ammo. The commander must plan this sequence of orders and make provisions for obstacles that may arise.
== Drop Cargo ==
In Arma 3, this waypoint lets AI helicopters drop off vehicles that their helicopter has already sling loaded. The behaviour seems to be very inconsistant, and the AI pilots seem almost completely incapable of picking up the cargo or dropping it off (They have a tendancy to circle around a few times before dropping the object they are carrying).


1. Destination is Petrovice
== Hold ==
2. Get in vehicle
This waypoint type will cause the group will move to and stay at this position indefinitely. Only a ''Switch'' type trigger or script command will move the group from the waypoint. While waiting, any unknown targets are checked (group moves in the direction of the target) and any recognized enemies are engaged.
3. If driver does not know the way to Destination, swap driver and passenger
4. Drive to Destination
5. Get out of vehicle
6. Load vehicle
7. Destination is Lipany
8. Get in vehicle
9. If driver does not know the way to Destination, swap driver and passenger
10. Drive to Destination
11. Get out of vehicle
12. Unload vehicle


===Interpreter===
== Sentry ==
The group will move to the waypoint and hold position until the group [[knowsAbout|knows]] enough about an enemy unit to identify which side that belongs to, and that they are capable of attacking. At that point, the group will proceed to their next waypoint. They will normally also attack the spotted enemy on the way.


If you have an algorithm, you need something that can execute it. We have a computer game, Armed Assault, which is able to do this; commanders have soldiers.
== Guard ==
This waypoint works in conjunction with the 'Guarded by' trigger type, see that topic above for more details. The group will move to the waypoint's location, then wait for a point to require guarding. A guard point or object is only considered guarded if a group has been set to guard it through a ''Guard'' waypoint (any other friendly forces in the area are not considered). If there are several guard triggers, the group will move to the first placed (highest priority), unguarded trigger (or it's linked object). Once at a guard point, the group will continue to check if any higher priority guard point requires guarding, or for any enemies to engage. A group can be made to stop guarding using the [[setCurrentWaypoint]] command or a ''Switch'' trigger. Besides guarding areas marked by "Guarded by" triggers, guarding groups are also ordered to destroy any enemy units which are known to any group of the same side. See the ''Guarded by <side>'' trigger description for more details. See also: [[Waypoint:Guard]], [[createGuardedPoint]].


===Programming language===
== Talk ==
Is used in combination with the ''Effects'' button at the bottom of the Waypoints menu. The group's leader will speak the given ''Voice'' phrase, complete with lip movements. The group does not move to the waypoint's location, instead skipping immediately to the next waypoint.


It's the way how to write our algorithm for Armed Assault. ArmA scripts are a sequence of 'orders' describing how to do it.
== Scripted ==
This waypoint type will execute the [[Script_%28File%29|script file]] that is in the “Script” box on the bottom of the waypoints screen. Enter the file name directly, without any [[exec]] type command or quotation marks, then up to 4 arguments in an array. The group will not move to the waypoint location. The group will wait until the external script exits before moving on to the next waypoint. An argument array is passed to the script in the form [<group leader>,<waypoint position array>,<object waypoint is attached to>,<user array element 0>,<user array element 1>,<user array element 3>,<user array element 4>]. Note the '''On Activation''' script code block can be used to execute any script at any waypoint, making this waypoint type somewhat redundant.


===Source code===
== Support ==
 
A group with a current waypoint of this type will move to the waypoint's position, then wait until it can provide support for another group that requests relevant support using ''"Call Support"'' command menu. At this time, the waiting group will proceed to the location where support was called for, disembark from any vehicles is possesses and wait for the supported group to declare ''"Support Done"'' before continuing to wait to respond to any further calls for support from their new location. Only groups with a medic, ambulance, fuel, ammo or repair vehicles can respond to support requests. In the case of multiple support groups, the first placed available group will always respond first, irrespective of distance. While this is a powerful waypoint type it requires diligence on the part of any human leaders, as they must announce "Support Done" to allow the AI support group to continue being able to provide support. AI leaders also tend to request that every single appropriate support group attends them. AI will not take a support group's vulnerability into consideration when requesting support.
Source code is algorithm written in any programming language.
 
===Syntax===
 
'''Syntax''' is made up of commands and parameters, sometimes just the command is required as in [[exit]], other times the '''syntax''' is made up of one or more parameters. Each command has it's own reference in the [[Scripting]] section of the wiki. In each case the command + its parameters are listed with examples on how that particular command works.
 
'''[[if]]'''(PrivateHonka == TheMostCleverSoldierInTheWorld) [[then]] {
    IAmChineseGodOfHumour = true;
};
 
You should however be aware that there are two similar scripting grammars in Armed Assault, namely [[SQF]] and [[SQS]]. While the functions are almost the same, there are still minor differences in statement notations, program flow and control structures.
 
===Interpreting works===
 
The '''Armed Assault''' engine reads your code from script files and translates those instructions for you to achieve your desired outcome/effect in the game.
 
===Let's start===
 
Every script consist of commands (see category [[:Category:Scripting Commands|Scripting Commands]]) and [[Control Structures|program flow]] statements (they are implemented as commands in Armed Assault, but it isn't relevant for now). The most useful command in your first script is [[titleText]]. It can write any text you want to the player's screen.
 
[[titleText]]["Good morning, captain", "PLAIN DOWN"]
 
It's a typical way to run commands. Behind the name of the command the parameters follow (but it depends on the command (see [[:Category:Scripting Commands]]). Every command can only have one parameter before it's name and/or one after (more arguments can be given with arrays which count as one parameter). Parameters can be of various [[:Category:Types|Data types]]. In this case it's an [[Array]] - a list of other data types. It can contain 0 - 4096? values. The first value is a [[String]] representing the text to be displayed and the second, in this case, says in what position on the screen the text will be displayed. There can be a third value: a [[Number]] which says how long the text needs to fade in. If this value is not entered, its default value (1) is used.
 
[[titleText]]["Good morning, captain", "PLAIN DOWN", 5]
 
Scripts which are called [[function]]s) are stored in .SQF files the mission folder, or in .SQSs files and then called only scripts.
 
If you want to try our 'script', create a mission in the mission editor, save it as ''testingmission'', open your favorite text edtior (eg. Notepad), write <code>[[titleText]]["Good morning, captain", "PLAIN DOWN"];</code>and save it as ''hello.sqf'' to gamefolder/user/yourname/missions/testingmission. Then add a soldier in the mission editor and type <code>nul = [] [[execVM]] "hello.sqf"</code> to his initialization line. When you run this mission, you should see output of your first script. Well done, soldier! (If you are confused from this quantum of informations, don't panic, more continuously explanation follows.)
 
=== Variables ===
 
See [[Variables]]
 
===Operators===
 
See [[Operators]]
 
== Scripting Code ==
 
The core of scripting is '''scripting code'''. The code consists of [[:Category:ArmA: Scripting Commands|scripting commands]] that tell the game engine what to do. These commands are executed one after another.
 
The code is written into special fields of the [[ArmA: Mission Editor|mission editor]] (see below) or into separate files that are executed at some defined point (i.e. through [[Triggers|triggers]]) during the running mission.
 
=== Syntax ===
 
Every code has to follow a '''syntax'''. The syntax is the "grammar" of the scripting language. It makes sure that the game engine can read and understand the code.
 
The primary syntax used in [[Armed Assault]] and [[ArmA 2]] is [[SQF syntax]]. Read the corresponding article to inform yourself about the exact details. There are some crucial points which you must know about:
 
* Every statement of SQF code ''except for the last one'' should end with a semicolon. Otherwise, the engine doesn't know when one statement ends and the next begins. In SQF (unlike SQS), line breaks made with the ENTER key are only visible to the script writer. Spaces between lines are completely ignored by the engine.
 
:There is an exception to this rule. When using commands such as [[if||if () then {}]], the final statement of code inside the parentheses and {} brackets can go without a semicolon. If this confuses you, just put a semicolon after all statements except for the last one.
 
* The final statement of SQF code should not have a semicolon after it. (As of the current version of ArmA2:OA, this is not a problem, but it was in previous games).
 
At some point you may also find scripts written in the deprecated [[SQS syntax]]. This syntax was the primary syntax in [[Operation Flashpoint]], but is considered deprecated since Armed Assault.
 
All scripting pages about Armed Assault will focus on SQF syntax.
 
=== Layout ===
 
Code should be written in a specific '''layout'''. Complementary to the syntax, the layout assures that ''you and other coders'' can easily read the code. This is especially important when you haven't looked at your code for a long time and want to improve or change this code.
 
* There should be '''only one [[Statement|statement]] per line''' in [[Script (File)|scripts]]. This rule doesn't apply to script lines in the mission editor, since there all the code has to be written within a single line.
* Use '''spaces or tabs''' to indent code in [[Block|blocks]]. This way you can easily tell to which block some code belongs.
 
Example:
 
Statement 1;
   
   
Block
As of '''Arma 3 v1.36''' this waypoint type seems to be semi-functional. If you request support through the status menu (5 key by default) for a "medic", Ai groups assigned this waypoint will move to your location. However once there it would seem there is no way to announce "Support Done". The game also replies to your request for support with "Negative" in the system chat if that type of support is not availiable (e.g. supply or fuel truck).
{
    Statement 2;
    Nested block
    {
        Statement 3;
        Statement 4;
    };
};


=== Comments ===
== Get In Nearest ==
The group will only move to the waypoint if there are any empty vehicles, or vehicles on the group's side with empty seat spaces, that are within about 50m of the waypoint's location. Note the appraisal of a vehicle's side and number of available seats seems to be made before the mission initializes! If there is an empty vehicle in the mission editor within about 50m of the waypoint, the group think that the vehicle will still be available even if it has been completely occupied by enemy forces! Once at the waypoint, the group will fill any available seats in the nearest vehicle (and only this vehicle). If there is no suitable vehicle near the waypoint, the waypoint will complete almost immediately after becoming active, and the group will continue on to their next waypoint. On a dedicated server, an AI unit will only get in vehicles that are empty.


You can and should write comments into your [[Script (File)|scripts]] that describe the purpose of your code. These comments are written in free text and completely ignored by the game engine.
== Dismissed ==
This waypoint type can be used to simulate casual off-duty behaviour. The group will move to the waypoint, then be dismissed. The group will automatically split itself into small teams of one to four units, who will move to random locations, sit down, etc. Given enough time some of the group may wander kilometers from the waypoint. Note that the dismissed waypoint does not inherently alter behaviour mode, nor make units disembark, land aircraft, or turn vehicle engines off. A dismissed waypoint is completes if the group comes into contact with any enemy units. See also: [[expectedDestination]].


Check out [[SQF syntax]] for information about the notation of comments.
== Loiter ==
Introduced in [[Arma 3]], makes group loiter around a position. If group is on foot or inside a ground vehicle, then group will just stand around and the LOITER waypoint will act as a MOVE waypoint. If group is inside an aircraft, the aircraft will orbit the waypoint's position with given height and loiter radius. See also: [[waypointLoiterRadius]], [[waypointLoiterType]], [[setWaypointLoiterRadius]], [[setWaypointLoiterType]].


'''Important:''' Don't write down what the code does, but rather what ''you'' want to do with the code. This is not as easy, but maybe the following example explains it a bit better:
Note: If another waypoint was added soon after the LOITER waypoint, the LOITER waypoint will act as a MOVE waypoint.


Bad comment:
== Follow ==
 
{{Stub}}
// the variable i gets the value 1
See also: [[doFollow]], [[commandFollow]].
i = 1;
 
Good comment:
 
// reset the counter to start with 1 again
i = 1;
 
== Code Execution ==
 
how can I execute code? (external files vs. mission editor)
 
=== Mission Editor ===
 
how to execute code in the editor, listing of mission editor fields to start scripts
 
=== External Files ===
 
how to execute code in external files, scripts & functions
 
== Developing a Script ==
 
script in this case: code in external files (scripts/functions). how to develop a script?
 
* Requirements
* Concept
* Implementation
* Test
 
usually in your head, for complex scripts on paper and drafts
 
=== Requirements ===
 
what shall the script do?
 
=== Concept ===
 
How shall the script do it?
 
=== Implementation ===
 
Writing the code
 
=== Test ===
 
Testing the code
 
== Further Reading ==
 
If you want to learn more about [[Scripting]], read the following articles:


* [[Variables]]
== AND ==
* [[Data Types]]
Only available for groups on the Game Logic side. This waypoint will not complete until all waypoints it is synchronized with have been completed.<br>
* [[Operators]]
'''Not available in [[Eden Editor]]'''.
* [[Control Structures]]
* [[Exception handling]]


== See also ==
== OR ==  
Only available for groups on the Game Logic side. This waypoint will complete when any one of the waypoints it may be synchronized with has been completed.<br>
'''Not available in [[Eden Editor]]'''.


* [[Script (File)]]
= See Also =
* [[Function]]
*[[:Category:Command_Group:_Waypoints|Command Group: Waypoints]]
* [[SQF syntax]]
*[[2D Editor: Waypoints]]
* [[SQS to SQF conversion]]
*[[Eden Editor: Waypoint]]


[[Category:Arma Scripting Tutorials|Introduction to Scripting]]
[[Category:Mission Editor|Waypoints]]
[[Category:Command Group: Waypoints]]

Revision as of 04:36, 15 June 2018

Waypoints

A waypoint's type will define what the group is to do when the waypoint becomes active.

Waypoint Types

Move

The group will move to this point or object. The move waypoint is considered complete when the leader gets close to the waypoint, the required distance being between 1 and 500 meters depending on the leader's vehicle type (if any) and whether a player is controlling the leader. The movement mode and method will depend on the group's behaviour settings, with movement rarely being made in a straight line between waypoints. AI leaders will generally pause to choose a path before they start moving. Groups will automatically board any transport vehicles they own if the next waypoint is far enough away. If the waypoint is too far away or a valid path cannot be found, the group may never reach the waypoint. If a Move waypoint is attached to a building object, the "Position In House" menu option will become available.

Destroy

This waypoint type works best when it is attached to a object. The group will attempt to destroy whatever object the waypoint is placed upon, irrespective of the target object's side. If the group is unable to destroy the attached object they will move within range of being able to identify the object, then wait until it is destroyed (even if the target is not destroyable!). If the waypoint is placed spatially, the waypoint's behaviour is less predictable. If the waypoint is far away from any mission editor placed objects, the waypoint will generally be instantly considered complete without the group moving towards the waypoint's location. If there is any object near the spatial waypoint, the group may treat that object as a normal destroy target. However, sometimes the group may start to attack the object, then instantly move to the next waypoint without destroying anything. The exact object the group will attack is not easily predicted, and if the group itself is near the spatial Destroy waypoint when it becomes active, the group may even choose to attack, but not necessarily destroy, one of it's own members.

Get In

The exact effect this waypoint type has depends on whether it is placed in empty space, attached to a vehicle or a non-vehicle object. There are many possible combinations of circumstances, each with slightly different effects.

  • Spatial
    • If the waypoint is spatial, any walking units in the group will board free space in any vehicles with that the group possesses. Note this happens as the waypoint becomes active, rather than when it is reached. The group will not travel to the actual Get In waypoint's position, but carry out the boarding action and then continue on to the next waypoint.
    • If a spatial Get In waypoint is synchronized with a waypoint of another friendly group with unused vehicle spaces, but the original group has adequate transport, it will mount it's own vehicles.
    • If the spatial Get In waypoint is synchronized with a waypoint of another friendly group with unused vehicle spaces, the group will mount any available vehicle spaces of its own before boarding the other group's transport.
    • If the spatial Get In waypoint is synchronized with a waypoint of another friendly group with some unused vehicle spaces but not enough to allow the entire group to board, the leader will order as many units as possible to board the other group's vehicles.
    • If the spatial Get In waypoint is synchronized with a waypoint of another friendly group with no free vehicle spaces, the group will move to the Get In waypoint's position, then move on to the next waypoint.
  • Vehicle
    • If the waypoint is placed on an empty vehicle, as many of the group as possible will board it. If the waypoint is placed upon an empty vehicle and the group already has enough vehicle spaces to fit the entire group, the group leader only will board and drive the new vehicle, while any foot units will board the group's original vehicle(s).
    • If the Get In waypoint is placed upon a vehicle driven by a friendly unit that has room enough to hold the entire group, the group will abandon any vehicles it has and board the new vehicle.
    • If the waypoint is placed upon a vehicle driven by a friendly unit that is not capable of carrying the entire group and the group has no vehicles of its own, the leader will order as many of his troops as possible to board the vehicle.
    • If the waypoint is placed upon a vehicle driven by a friendly unit that is not capable of carrying the entire group, and the group already has vehicles capable of carrying the entire group, as many units as possible will board the waypoint vehicle and the remainder board the original transport.
    • If the waypoint is placed upon a vehicle driven by a friendly unit that is not capable of carrying the entire group and the group has some vehicles but all vehicles will still not enough to fit the entire group, the leader will order as many troops as possible into both the group's vehicles and the waypoint vehicle.
    • Finally, if the waypoint is attached to a non-vehicle class of object, the group will move to that object before boarding any available vehicle space it already has.

Seek & Destroy

It does not matter if this waypoint type is placed spatially or on an object. If attached to an object, the waypoint will remain fixed at the objects initial position as displayed in the mission editor (even if that object actually starts the mission in the cargo of another vehicle or has it's position changed by it's initialization string). Behaviour is the same for both situations - the group will move to the waypoint, then the leader will move about to search the immediate area with his group trying to keep up. The exact size of the area searched is limited to the leader's expected travel time. A leader on foot will rarely search more than 50m from the waypoint, while a leader in a helicopter will search up to 300m from the waypoint. The search will attempt to visually check all locations within the search range, so a search inside a city will take far longer than a search in an empty field. Unfortunately the Seek & Destroy waypoint does not appear to make the group deliberately search inside buildings although their pathfinding may lead them to enter some. Whether or not the group finds any enemy units appears to have no impact on the search duration or range.

To make AI hunt down a known target, you need to setCombatMode to "RED". The Seek & Destroy waypoint only makes the AI search the vicinity of the waypoint itself, not affect their behavior on their way to the waypoint.

Join

When this waypoint type is attached to a unit, the group will move to the position of that unit, then join and follow that unit's group, irrespective of side or ranks. Note that the attached unit may have moved on, but the Join waypoint remains at the unit's location when the waypoint became active. When the Join waypoint is spatial, the group will treat it as a Move type waypoint. If the Join waypoint is synchronized with another group's waypoint, when both groups are at their waypoint positions, the group that is "synchronized from" will join the group that is "synchronized to", irrespective of which group has the join waypoint itself. When synchronizing, click and hold on the waypoint of the group that is to join the other, then drag to the other group's waypoint. Note only two groups can join at single Join waypoint.

Join & Lead

This type is exactly the same as the Join waypoint type, except the group that leads the merged group will be opposite in each situation.

Get Out

The group will move to the waypoint, then disembark from any vehicles it's members are in. Helicopters will land on the closest "H pad" object within 500m of the waypoint. If any group members other than the leader are in a vehicle of another group, that vehicle will stop to let them out. If the leader is riding in another group's vehicle, the Get Out waypoint will not be considered reached until the leader arrives at it under his own control (ie, never). In this case a Transport Unload waypoint should be used. If the Get Out waypoint is placed on an object, the group will move to the location of that object at the instant the Get Out waypoint becomes it's current waypoint, then disembark as normal.

Cycle

This waypoint type will change the group's active waypoint to the nearest waypoint other than the group's previous waypoint. Note that the automatically created first waypoint (the leader's initial position as seen in the map editor) is considered as a Move type waypoint and can be used by the Cycle waypoint. A Cycle type waypoint can be used to make the group move in an infinite loop, a great and easy way to create a patrol. Either a Switch trigger or script can be used to "break" a group out of a cycle loop.

Load

The group will move to the waypoint (spatial or object), then any soldiers on foot will board any vehicles the group possesses. They will get into the vehicles as cargo where possible, then as the crew of the vehicle.

Unload

The group will move to the waypoint (spatial or object), then any of it's units that are in cargo space of any vehicle will disembark. Units in crew positions will not disembark. One note, on a dedicated server when using this with AI controlled Helicopters. This command only works if there is an AI team commander present in the cargo of the vehicle. If there are only human players, the helicopter will not land. It will hover too high in the air to safely disembark.

Transport Unload

The group will move to the waypoint (spatial or object), where any units from other groups who are in cargo spaces of the original group's vehicles will disembark. On a dedicated server, this waypoint does not work if the commander of the group being transported in the back of the vehicle is human. It will only work with AI One note, on a dedicated server when using this with AI controlled Helicopters. This command only works if there is an AI team commander present in the cargo of the vehicle. If there are only human players, the helicopter will not land. It will hover too high in the air to safely disembark.

Specifically for landing an AI helicopter on the ground and unloading AI passengers, the waypoint destination for Transport Unload must be a helipad object and be assigned to the pilots, and the separate group as passengers must have the Get Out waypoint at the same location. Both the Transport Unload waypoint and Get Out waypoint have to be synchronized with eachother. Note: createVehicleCrew breaks this functionality.

Lift Cargo

In Arma 3, this waypoint lets AI helicopters pick up vehicles that their helicopter is capable of lifting. The behaviour seems to be very inconsistant, and the AI pilots seem almost completely incapable of picking up the cargo or dropping it off (They have a tendancy to circle if other entities are nearby).

Drop Cargo

In Arma 3, this waypoint lets AI helicopters drop off vehicles that their helicopter has already sling loaded. The behaviour seems to be very inconsistant, and the AI pilots seem almost completely incapable of picking up the cargo or dropping it off (They have a tendancy to circle around a few times before dropping the object they are carrying).

Hold

This waypoint type will cause the group will move to and stay at this position indefinitely. Only a Switch type trigger or script command will move the group from the waypoint. While waiting, any unknown targets are checked (group moves in the direction of the target) and any recognized enemies are engaged.

Sentry

The group will move to the waypoint and hold position until the group knows enough about an enemy unit to identify which side that belongs to, and that they are capable of attacking. At that point, the group will proceed to their next waypoint. They will normally also attack the spotted enemy on the way.

Guard

This waypoint works in conjunction with the 'Guarded by' trigger type, see that topic above for more details. The group will move to the waypoint's location, then wait for a point to require guarding. A guard point or object is only considered guarded if a group has been set to guard it through a Guard waypoint (any other friendly forces in the area are not considered). If there are several guard triggers, the group will move to the first placed (highest priority), unguarded trigger (or it's linked object). Once at a guard point, the group will continue to check if any higher priority guard point requires guarding, or for any enemies to engage. A group can be made to stop guarding using the setCurrentWaypoint command or a Switch trigger. Besides guarding areas marked by "Guarded by" triggers, guarding groups are also ordered to destroy any enemy units which are known to any group of the same side. See the Guarded by <side> trigger description for more details. See also: Waypoint:Guard, createGuardedPoint.

Talk

Is used in combination with the Effects button at the bottom of the Waypoints menu. The group's leader will speak the given Voice phrase, complete with lip movements. The group does not move to the waypoint's location, instead skipping immediately to the next waypoint.

Scripted

This waypoint type will execute the script file that is in the “Script” box on the bottom of the waypoints screen. Enter the file name directly, without any exec type command or quotation marks, then up to 4 arguments in an array. The group will not move to the waypoint location. The group will wait until the external script exits before moving on to the next waypoint. An argument array is passed to the script in the form [<group leader>,<waypoint position array>,<object waypoint is attached to>,<user array element 0>,<user array element 1>,<user array element 3>,<user array element 4>]. Note the On Activation script code block can be used to execute any script at any waypoint, making this waypoint type somewhat redundant.

Support

A group with a current waypoint of this type will move to the waypoint's position, then wait until it can provide support for another group that requests relevant support using "Call Support" command menu. At this time, the waiting group will proceed to the location where support was called for, disembark from any vehicles is possesses and wait for the supported group to declare "Support Done" before continuing to wait to respond to any further calls for support from their new location. Only groups with a medic, ambulance, fuel, ammo or repair vehicles can respond to support requests. In the case of multiple support groups, the first placed available group will always respond first, irrespective of distance. While this is a powerful waypoint type it requires diligence on the part of any human leaders, as they must announce "Support Done" to allow the AI support group to continue being able to provide support. AI leaders also tend to request that every single appropriate support group attends them. AI will not take a support group's vulnerability into consideration when requesting support.

As of Arma 3 v1.36 this waypoint type seems to be semi-functional. If you request support through the status menu (5 key by default) for a "medic", Ai groups assigned this waypoint will move to your location. However once there it would seem there is no way to announce "Support Done". The game also replies to your request for support with "Negative" in the system chat if that type of support is not availiable (e.g. supply or fuel truck).

Get In Nearest

The group will only move to the waypoint if there are any empty vehicles, or vehicles on the group's side with empty seat spaces, that are within about 50m of the waypoint's location. Note the appraisal of a vehicle's side and number of available seats seems to be made before the mission initializes! If there is an empty vehicle in the mission editor within about 50m of the waypoint, the group think that the vehicle will still be available even if it has been completely occupied by enemy forces! Once at the waypoint, the group will fill any available seats in the nearest vehicle (and only this vehicle). If there is no suitable vehicle near the waypoint, the waypoint will complete almost immediately after becoming active, and the group will continue on to their next waypoint. On a dedicated server, an AI unit will only get in vehicles that are empty.

Dismissed

This waypoint type can be used to simulate casual off-duty behaviour. The group will move to the waypoint, then be dismissed. The group will automatically split itself into small teams of one to four units, who will move to random locations, sit down, etc. Given enough time some of the group may wander kilometers from the waypoint. Note that the dismissed waypoint does not inherently alter behaviour mode, nor make units disembark, land aircraft, or turn vehicle engines off. A dismissed waypoint is completes if the group comes into contact with any enemy units. See also: expectedDestination.

Loiter

Introduced in Arma 3, makes group loiter around a position. If group is on foot or inside a ground vehicle, then group will just stand around and the LOITER waypoint will act as a MOVE waypoint. If group is inside an aircraft, the aircraft will orbit the waypoint's position with given height and loiter radius. See also: waypointLoiterRadius, waypointLoiterType, setWaypointLoiterRadius, setWaypointLoiterType.

Note: If another waypoint was added soon after the LOITER waypoint, the LOITER waypoint will act as a MOVE waypoint.

Follow

Template:Stub See also: doFollow, commandFollow.

AND

Only available for groups on the Game Logic side. This waypoint will not complete until all waypoints it is synchronized with have been completed.
Not available in Eden Editor.

OR

Only available for groups on the Game Logic side. This waypoint will complete when any one of the waypoints it may be synchronized with has been completed.
Not available in Eden Editor.

See Also

Retrieved from "https://community.bistudio.com/wiki?title=User:KC_Grimes/Sandbox&oldid=108391"