Mission Editor Tips and Tricks

Tips and Tricks for using the Ground Branch Mission Editor

Introduction

Welcome to my unauthorised guide for using the Ground Branch mission editor. The mission editor generates a mission file (along with a specific lua script) to deal with spawn placements, various objectives etc for both PVE and PVP game modes. The mission editor can be used to modify the existing mission file for a game mode or to make to completely new mission file for the game mode.

At the current time (2024, GB at 1034.5) the ground branch wiki has been made public which will be the main source of information going forward.
Mission Editor Wiki: https://wiki.groundbranch.com/en/modding/mission-editor
Lua API Wiki: https://wiki.groundbranch.com/en/modding/lua-api

If you are interested in using the mission editor or to make new game modes then please also joint the unofficial ground branch modding discord

Unofficial Ground Branch Modding discord server https://discord.gg/CZG8XGMhGT

CURRENT AIM
The current aim of this guide is to supplement the existing ground branch wiki with methods that can be used to expand the functionality of the mission editor and the lua coding.

The current GB road map indicates that Objective-Based Missions (first pass at least) should be coming to 1035. Hopefully there will be further functionality opening up to make the GB mission types that the community really want.

ACKNOWLEDGEMENT
This guide was originally started while I was experimenting on GB1031.1 when there was not that much knowledge around. Attached below are some of the original resources available to show how far the game has come. Thanks to all those involved here.

• Fatmarrow's unofficial lua library references and unofficial guide to the mission editor. Both of these documents are available in the unofficial ground branch modding discord or in the pinned comments of the modding channel in the official GB discord.
  
• AV's introduction vids on using the mission editor and lua coding - playlist can be found here https://www.youtube.com/playlist?list=PLle5osICJhZJwHxGOb1iBXoyu_uk9yXMY
  
• R1ft's Github lua references (old reference) https://github.com/r1ft4469/GB-Server-Mods
  
• Matt Farrow's mission editing walk through's for the mission editor - https://www.youtube.com/watch?v=5Fa10n9AF-c and https://www.youtube.com/watch?v=oMNskQiOvbw .
  
• The work done by Eelskillz and Bob/AT.

AI Appearance and Loadout

AI Appearance Sets

There are currently 4 AI character classes and 1 character class for players. The character class for players can be used by the AI as well.

New opfor character assets are planned (by Pau who did the player assets) with at least cartel, middle east, and russian (and maybe a PMC group). The current 4 AI character classes are from a unreal engine asset and it is not known if they will remain once the new opfor assets are available.

The 4 AI character assets are generally referred to as RuSoldier, RuSpec, Riot, and Rebel based on the naming of their assets.


"Rebel Assets"

"Riot Assets"

"Ru Soldier" assets

"Ru Spec" There can be small gaps between the head and the other assets but a player will not be able to notic these.

Player assets for the ai

The ai appearance is changed by kit files. At the current time there are only a few base models for the Ru_soldier, rebel and riot classes and none for Ru_spec. Kit files for the ai are assigned in the mission editor (under loadout where the kit file is selected). The game will look for the kit files in the main game directories and then in the directory of the mod your are working in.

Making a new kit file for the ai - I generally try to mimic what I want in a loadout as much as possible. The kit file which corresponds to what you as a player is wearing will then be in the documents - ground branch folder and this can be copied and pasted into a modification of an existing ai file. Some of the references in the player kit files and the ai kit files do not cross over - magwell or something like that. I find it best to have the ground branch log screen open and then load in the mission and look for errors which will come up in the log screen. All the errors should be cleared, particularly if the mission is being put on the steam workshop.

If any errors are detected in the kit files then part of the kit, or the full kit (in which case the ai will not spawn in at all) will not show up in the mission editor.

Important points to note about the kit files:-

• Stability
  In extreme circumstances kit files can cause stability issues for your machine or someone else's machine if they load in a mod. I've recently dealt with a SCAR suppressor which did not list as an error in the log file but when someone else loaded in the workshop mod it crashed there game. I've also had kit files crash my game whenever I loaded in a mission and had to make a new mission and load in kit files 1 at a time.
  
• Saving kit files
  My recommendation is not to save the kit files in the main game directory. In the future these folders will be scanned and may be acted on. Having the kit files here will mean that they will not transfer over if you make the mission a mod and put it on the workshop.
  
• Version changes
  The kit file system changes every 2 or so main versions of the game and all the kit files need to be revised for it.
  
• Ammo
  The base Opfor character models have ammo storage on them and the ai will not run out of ammo. If a player character model is used then ammo will need to be provided and the ai can run out of ammo. If additional ammo is added to the current opfor kits then there will be a bit of clipping etc.
  
• Adding a pistol
  At the current time (1034) the ai don't use pistols at all even when only a pistol is equipped. The devs have been informed of this but I don't know where fixing this is on the list of priorities. You will also need to provide a holster as well otherwise the pistol will be discarded once the ai spawn in. The base ai character model has a pistol in built (which cannot be used) and the new pistol may clip through it a bit.
  
• Armour
  On some of the character models there is some signs of armour. Armour is not currently implemented in the game so these don't do anything at the current time. How armour will work for ai is not known at the current time.
  
• Adding NVGs
  Adding NVGs on a helmet changes the profile of the AI significantly and makes PID a lot harder. If a IR strobe is on the helmet then it will only be visible if you are on the same team as the AI.
  At night time the NVGs on the AI do not flip down (they did in previous builds).
  
• Potential FPS effects
  Adding in additional elements for the game to render due to additional items on the AI rifles or additional vests / belts with pouches may incur some change in fps.

Conclusion

The mission editor, even in its initial state, enables significant changes to the current Ground Branch game play, all that it takes is some time.

Some of the User Interface for selecting missions etc will need to be thought out, however as these missions may be tied to the steam workshop (let us hope), it will take some time.

Kris has previously bragged that he spent more time limiting the weapon customisation to prevent "artists making masterpieces" than setting up the weapons customisation system in the first place. Then he makes a mission editor...

References for Kythera AI

Attached below are links relating to Kythera AI.

Kythera AI is named after the Antikythera mechanism (https://en.wikipedia.org/wiki/Antikythera_mechanism) which is described as one of the oldest known example of an analogue computer.

Kythera AI is also known as Moon Collider.

Kythera AI website: https://kythera.ai/news/blackfoot-studios-adopts-kythera-ai/
YouTube: https://www.youtube.com/@kytheraai3330
Vimeo: https://vimeo.com/kytheraai


GDC Vault
2011 - Smarter AI Through Influence Maps - https://www.gdcvault.com/play/1014498/Lay-of-the-Land-Smarter

2012 - Believable Tactics for Squad AI - https://www.gdcvault.com/play/1015665/Believable-Tactics-for-Squad

2013 - Spaces in the Sandbox: Tactical Awareness in Open World Games - https://www.gdcvault.com/play/1018038/Spaces-in-the-Sandbox-Tactical

2021 - Steering Formations and a Trail of Blood: AI in Wolcen - https://www.gdcvault.com/play/1026979/AI-Summit-Steering-Formations-and

Other Presentations, etc
https://www.youtube.com/watch?v=zUo-PI30wBQ&t=2s

https://www.youtube.com/watch?v=pmAn1NNjtjU

https://www.youtube.com/watch?v=05x81r9vORA

https://www.scottishai.com/news/ai-in-the-scottish-gaming-industry

https://80.lv/articles/exploring-kythera-ai-s-toolset-for-unity-game-development/

https://www.gameaipro.com/GameAIPro/GameAIPro_Chapter26_Tactical_Position_Selection.pdf

https://www.gameaipro.com/GameAIPro2/GameAIPro2_Chapter30_Modular_Tactical_Influence_Maps.pdf

https://www.gameaipro.com/GameAIPro2/GameAIPro2_Chapter31_Spatial_Reasoning_for_Strategic_Decision_Making.pdf

superseeded - Getting Into the Mission Editor

The mission editor currently only works in the "Lone Wolf" type gameplay. It does not work on any of the servers or on the listen server, even with settings such as "enablecheats" on.

Method 1: Lone Wolf - From the ready room
From the ready room type `editmission
The mission editor will start from the players position in the ready room, the current mission file will load if applicable and show the start position for the various items in the mission file.

Method 1b: Open Map from main menu then use console command
A similar setup can be done from opening a map from the main menu (say 'open Smalltown and then from that ready room typing 'editmission
In this case as no mission type was selected the mission editor will open with no mission.
This is particularly useful for PVP mission types.

Method 2: Lone Wolf - In round
Once the round has started (and you have been transported from the ready room to the round and the pre-start timer has closed), type `editmission
The mission editor will start in game from the player's position and show the current AI positions along with the other mission items in their initial state in the current mission file.

• The edit screen can be a lot more cluttered as it shows the initial position of the items in the mission file along with all the AI moving.
  
• New AI spawn points / defend points / patrol routes can be added but the AI will ignore them as they were not placed at the start of the round.
  
• Enemy AI will kill the player if they find him. It is best to make the player invisible to the AI during these edits by typing `notarget as well as making the player impervious to damage by typing `god
  
• It does enable the editor to see what behaviours the AI will exhibit with there patrol / defend points as placed in the file.
  
• The position of the defend points and the position of the node points for the patrol route can be changed in real time to see the AI behaviour or guide the AI to a particular location etc. This has potential cinematic implications discussed towards the end of this guide.

I don't know if this method is intended to be in the game. Hopefully it will not be taken out.

Known Issues for Starting

• Typing `editmission from Spectator will crash the game after loading in the editor
  
• Typing `editmission whilst slomo=0 will also crash the game. Note that the items in the top right hand pane do not appear also.

Superseeded - Mission Editor Basic Instructions and Issues

You will generally start from where the 'editmission command was raised which is generally the ready room and will then need to fly out of the mission area.

Navigation
To move around use the WASD and the mouse to change direction. Q and E can be used to move vertically.

Alternatively select an actor (/ item placed in the mission file) and hit f to be transferred to the location of that item.

General Screen
From left to right.
Mission file name / file name menu
At the top is the mission file name. Clicking the left button will reveal the mission file name menu which allows for other actions to be undertaken such as adding a new file, loading a file, validating the file (used in conjunction with the validate for the particular lua script), save, save as and exiting the mission editor.
Note that using the save as command saves a new copy of the mission file but does not make this mission file the one you just saved as (like windows). You will then need to load the new mission file.
Lua gamemode
Next is the lua gamemode file associated with the mission file. The lua gamemode file essentially tells the mission file how to set up the game mode etc. Without a lua gamemode file the mission file cannot be used.
The button gives the following choices:
I've only used the select so I'm not sure what the others ones do.



Go to AV's introduction on using the lua code and a much better introduction to basic editor functions than the one below.

• To move around use the right mouse button along with [w] [a] [s] or [d] with the mouse movement to change direction.
  
• Clicking on an item in the top right hand corner and hitting [f] will teleport the editor close to the object.
  
• The name of the items in the top right hand corner can be changed by hitting [F2]
  
• The position of an item can be changed by using the arrow commands, the rotation by using the rotation key, and the scale by using the scale key. This could also be done by using the number pad in the middle right hand pane.
  
• Items on the left hand pane can be dragged and dropped into the mission area.
  
• Items can be copied by clicking on the item in the top right hand pane, clicking Cntrl C to copy then Cntrl V to paste. The item will be at the same location and orientation as the original item even if you move / re-orientate away.
  
• The AI do not recognise the bombs for their pathing etc and can get stuck on them.
  
• NEW 1032 CTE - new items for blocking such as barrels etc available.
  
• NEW 1032 CTE - for the laptops can now have items such as boxes, chairs, toolboxes underneath the laptop. Once the laptop is picked up these items will remain.

Known Issues

• The console command to freeze the AI, debuggamecommand freezeai can be problematic. For AI on the defend mode it may not freeze the AI while they are walking between defend points, however once they do reach the next defend point they generally freeze. Similarly for the patrol the AI may not freeze until they reach the next patrol point.
  
• The "camera" for the mission editor has a collision volume, which may cause issues when viewing the AI walking around in game - the ai can walk into the collision volume and be stopped, and similarly the collision volume will change the weapon stance of the ai and the player model.
  

SuperSeeded - Actors / Items to be placed

Underneath the top two buttons are all the actors (items) that can be placed in the mission file.

• Insertion Point - used for a group of player starts. It is advisable to NOT COPY insertion points, place down new ones. The insertion point will need to have individual names so the name on the ready room board is specific. If you copy an insertion point and change the name then it is highly likely that any player starts associated with the insertion point change to the new insertion point.
  
• Player Starts - used as a start position for the player. The insertion point associated with the player start will need to be specified. It is recommended to not place down player starts in this way. It is recommended to go to the insertion point and add in the new player starts through the add player starts button.
  
• AI Spawn Point, AI Guard Point, AI Patrol Route - these are associated with AI and are discussed in more detail further down. The spawn point is where the AI will spawn. There are several order types (Idle, guard - requires guard points, and patrol - requires patrol points) and the kit for the ai will need to be specified.
  
• Spawn protection volume is used for several of the PVP modes. The activation / de-activation is generally implemented through the lua gamemode file along with the team id that it selected (but not always). Players of other teams inside this area will have a blurred screen. Depending on the settings the players of the team may also not received damage.
  
• Game triggers are used in conjunction with the gamemode lua script to trigger certain events. eg in some of my custom modes it is used to trigger the extraction zone to be activated - so the smoke grenade gets triggered only when the player is in close proximity and not in the main zone.
  
• Extraction zone is used in conjunction with the gamemode lua. It is similar to the game trigger but once activated a smoke grenade will spawn in and activate green smoke. The activation of the extraction zone is generally handled through the gamemode lua code along (generally) with the team id. An example is for the intel retrieval mode where the extraction zone will be triggered in the player with the laptop enters the zone.
  
• Laptop usable - this is a laptop which can be placed down.
  There is also a drop down box for meshes which the laptop will be on, such as a chair etc.
  A lua script will need to be specified for the laptop (this is a different script to the gamemode script) which may trigger various actions.
  Generally the laptop will be activated (spawn in) through the lua gamemode script.
  As an example, the intel retrieval game mode script selects a random laptop to be spawned in. At this time it also attaches a tag to the laptop. Once in game the player will walk up to the laptop - the message on the laptop if governed by the script nominated in the lua file associated on the laptop.
  Similarly when the players starts or finished interacting with the laptop there are possibilities for the functions in the main gamemode lua script to be activated - such as the bumrush feature in intel retrieval.
  In general the AI will be able to avoid the laptop / associated support meshes.
  
• Bomb - spawns a basic bomb mesh into the area (if activated). This was introduced a while back for a mode similar to the defend the laptop mode but as it was very similar it was not adopted. The AI (currently) do not recognize the bomb which seriously affects their navigation.
  The bomb needs to be spawned in through the gamemode lua file which also need specific functions to handle the detonation.
  A specific lua file needs to be listed for the bomb for the player interaction etc.
  
• Mesh
  A number of meshes can be added into the map. The original aim of these was to close off various areas of a larger map, The AI will recognize these and avoid them. However as there is no navmesh on them the ai will not climb or navigate on any structure composed of these meshes. If an ai is spawned on these items they may rotate around and crouch but will never walk on them.
  
• Blocking
  blockers are used to prevent players from reaching certain parts of the map. They can be turned on or off through the gamemode lu file.
  
• Navblock
  Nav blockers block the navmesh and can be used to prevent the ai from travelling in certain areas / block off certain parts of the map. The navmesh inside the navblockers will be removed. They can be activated / de-activated through the gamemode lua file and will apply for all ai, not just certain team ids.
  
• AI Hotspot
  used in the 1033 terrorist hunt mode where all ai inside the zone are given a higher priority of spawning in.
  
• Hostage Spawn
  used in the 1033 hostage rescue game mode and defines the spawn locations for the player hostages.

Superseeded - AI Structure and Behaviours

AI Teams
The available teams (or factions) for Ground Branch is 1 to 255.

• The current lua coding for PVE game modes sets the players as Blufor as team 1 and Opfor ai as team 100.
  
• It is possible to set the AI to other teams / factions so that the AI will be fighting each other
  
• Each team / faction will try to wipe all other factions out (by default). Currently there is no way to assign ROE between the different teams. (For example in Arma none of the factions would fire upon the civilian faction and the independent faction could be set to be friend or foe or neutral to NATO or CSAT.) Different factions can be assigned by assigning different team numbers. The relationship between the teams can be defined using the gamemode.SetTeamAttitude(team, other team, attitude). The attitudes here are "Hostile", "Neutral" and "Friendly".
  • Testing (1031.3) indicates that the attitude set at the beginning of the round lasts throughout the entire round. Additional calls of the command to change the attitude in the middle of the round are currently ignored most of the time however about 5% of the time they will be obeyed.
    
  • The command will need to be given twice to cover each team attitude to each other.
    
  • When under fire by the other team the attitude can change to hostile, even if set at neutral at the beginning of the round.
    
  • Any IR strobes on the helmets of the other teams helmets do not show up on the nods, even if the sides are nominally friendly towards each other.
• Team 255 is its own team. It does not try to balance the teams like for the bots. (For the bots, using the addbots command, 255 would assign the bots to a particular team to try and balance numbers.)

AI Squad
AI can be assigned to a particular squad in the box at the right hand pane. Currently that list does not re-organise itself to align the squads into one particular area (like Arma).
The game assigns a "squad leader" for the squad who takes the lead on patrols or who will determine what set of defend points to head to (more on that later on). The game mechanism for determining this is not clear at this point.


AI Squad Orders
The game currently has 3 basic orders which can be assigned to the AI - idle, patrol and guard. These are described later in the document in more detail.
Currently it is possible for different members of a particular squad to be assigned different behaviours. In general the entire squad will do one particular behaviour which I believe to be that of the "squad leader".
1032 CTE UPDATE - there is now a "Test AI" button available which can be used on individual AI or all the AI. This is a very welcome debugging command, although I have found it "sticky" in some situations where the AI don't do anything.


Bot interactions - 1032 CTE update - bot commands no longer function
Using the "addbots" command it is possible to add bots at the player spawn positions. Note the following behaviour:-

• On a server or a listen server the bots appear to be assigned to their various teams, which may result in them fighting the player when they are aligned with the AI team.
  
• On the lone wolf mode the bots tend to be aligned with the player, regardless of the team they were assigned to. The AI tend to hunt them down and kill them regardless of the team the bots were assigned to.

Spawn Priority
The spawn priority is the class assigned to each spawn point. The current LUA coding using this to create a table to decide which AI to spawn in depending on the number of AI to spawn in. A lower number means a higher chance the AI will spawn in.

Superseeded - AI Behaviour - Idle

"Idle" AI are a semi QRF who initially stand with weapons slung. Once a member of another team come within a given range (even if behind the AI) then the AI "sense" the opposing team, shoulder weapons and start to manoeuvre on the "spotted" team members.

Testing appears to show that the AI don't communicate the players position even if they are in the same squad. Refer to the v YT vid below - the AI placed in the basement appear to react more to the gunfire and have to search based on the sounds then the AI on the roof giving the position - even though they are all in the same squad.

Superseeded - AI Behaviour - Patrol

To set up a patrol route:-

• On the left hand pane drag and drop a patrol icon onto the map
  
• Click on that node and on the right hand pane click on the add additional patrol point.
  
• Repeat until finished. It is possible to close the loop using the close loop button which will close the loop to the nearest node.
  
• The patrol route needs at least 2 nodes. A single node will not work.

Issues for note regarding patrol behaviour:-

• Initially the AI will have their weapons slung. However if the AI detect a dead fellow team member then they will shoulder their weapons. If the AI come under fire then they will shoulder their weapons and react to the fire. They may or may not resume the patrol after they deal with / no longer can detect the threat to them.
  
• The AI will randomly select a direction for the route (particularly those in loops).
  
• Where multiple squads are on the same patrol route each squad will independently randomly select the patrol direction - it is possible for 3 squads to be patrolling in the same direction for a loop patrol route.
  
• After the initial spawning the AI will move the patrol route closest to the squad leader. The squad leader leads the squad with the remaining members following is 2 lines.
  
• The squad leader will move from each node on the patrol route. The other squad members will move towards the squad leader, so if they get hung up on the terrain it is possible to see them slice the corner of the patrol route.
  
• The nodes generally only need to be on the navmesh for the patrol to move between them. Although not specifically required additional nodes can be placed so that the patrol moves along a certain route say along a road or in cover behind a hill etc.
  
• The navmesh is not perfect. There can be a lot of items on the ground (fallen logs particularly in depot, fallen cabinets in rundown) which the AI do not detect. Currently it seems that the AI will not try to vault over these items and the squad leader (and hence the entire patrol) will get stuck. Note that it is possible for the AI to get stuck going in one direction but be fine in the other direction.
  
• At the moment it does not appear possible to add additional node points into a patrol route.
  
• All nodes need to be in an area on the nav mesh, and need to be between ground level and roughly 2m above ground level. If the node is not on the nav mesh (for instance is in a wall or a non enterable structure (like a small process tank) then the AI will stop and hold indefinitely at the previous node.

Particular Issues when using the mission editor in an open mission:-

• The AI will not follow any new patrol routes as they select the patrol route to follow at the start of the mission.
  
• The position of the nodes for the patrol routes can be changed. But note that once the squad leader gets to a node he calculates the route to the next patrol point instantaneously. Changing the node after this does not do anything. If the node position is move than 2m above ground or below ground, or in an area with no nav mesh, when the squad leader hits the previous point then the patrol will stop as it cannot calculate a path to the next node.

Superseeded - AI Behaviour - Guard

To set a series of Guard points:-

• On the left hand plane drag and drop guard point onto the map and adjust to the desired location.
  
• Enter in the name of the group of guard points that this belongs to
  
• The orientation that the AI will face can also be adjusted using the rotate function
  
• The pitch of the viewpoint can also be altered in the box on the right
  
• Other parameters can also be tweaked here:-
  
  • The magnitude does not currently work. Note that UE4 works in centimetres but even throwing that out to a really large number will not change the AI from trying to go to exactly the defend point on the mission editor.
    
  • The sweep angle, the angle in the plan view, for the guard point can be varied.
    
  • The pitch angle, the angle to the horizontal plane, can also be varied.
    
  • The nominal time that the AI will stay at the guard point is defined by the base time (enterable) and a variation time along with a hold time and a variation. This appears to introduced to aid some randomness of how long the AI stays at the guard points.

Issues to note about defend points:-

• The AI squad will randomly go to the guard points belonging to the group of guard points closest to the squad leader.
  
• Guard points must be on the nav mesh and generally at ground level to within 2m of the ground / structure level to be recognized by the AI. Above this and the AI just seem to ignore the point. If the AI is slightly of the nav mesh (say it is in a parked car) then they will go as close as possible to the point.
  
• AI currently try to go to the exact centre of the guard point. This makes them somewhat predictable after a while as they end up exactly at the same point.
  
• The AI will use the nav mesh to navigate between sometimes far away points. If the AI encounters an obstacle (or another AI at a choke point or the like) then after 20 seconds or so the AI will try a different route to the destination.
  
• If there are no guard points, or the last guard point has been moved so it is more than 2m above the ground / structure level, then the AI seem to move randomly in the area to various cover points in the area.

Particular Issues when using the Mission Editor in an Open Mission

• As per above, it is possible to move the guard point below ground or sufficiently above the ground / structure level so that the guard point no longer works.

Other Opportunities

• Using the guard point it is possible to semi-command AI in game to behave a particular way for cinematics etc, particularly if the AI appearance is changed (refer below).
  
• As a single AI can be placed into its own squad, it may be possible to continuously update the guard marker position and orientation to that of a player. For this the hold times should be set to 0, the scan time to something low like 0.5 sec and the deviation to 0. This may be useful in creating a primitive hostage (the hostage etc is coming but appears to be in a long, long time).

Superseeded - "Primitive" Hostage Rescue Scenario

Attached below is a YT video showing a "primitive" hostage rescue scenario worked in during the 1032 CTE to give an overview of what is capable at the current time.

The zip file for the lua, kit, mission files etc can be found on the Ground Branch Modding discord.

[tjl]

This is just the mission editor.
The SDK for a map editor and the like is planned but not available at this time (early 2023). My understanding is that there are some legal hurdles to get over for this.

[FIN]

Any map editor ?)

[๖ۣۜTheforeigner]

For PvP the RED (OPFOR) is Team ID 2

[Jeza]

Nice work mate.

[Nerf.Man]

wow, thats good.
but I will have to wait for the translation of this guide to do something like this ""xddd