Warfare 1 - Editing Guide

From Bohemia Interactive Community
Jump to navigation Jump to search


License

ArmA - Warfare MP Mission
Copyright © 2008 Bohemia Interactive a.s. All rights reserved. Unauthorized use is strictly prohibited.
For more information about the ArmA Warfare mission visit the Warfare forum (dead link).
This archive contains sample models, configs and model configs to be used in BI Editing Tools to create custom models for ArmA.
To distribute or modify or use the ArmA Sample Models in any way, you must agree to the following license:

THE LICENSE
1) Bohemia Interactive grants to you a personal, nonexclusive License to open, modify and distribute the ArmA Warfare MP mission content for the purpose of designing, developing, testing, and producing non-commercial game content for PC game ArmA and its sequels or expansion packs.
2) You acknowledge and agree that you will not commercially exploit any game content you may created using the data without Bohemia Interactive prior written permission.
3) Bohemia Interactive doesn't give you permission to exploit ArmA Warfare MP mission content in any other way, especially not to convert them for use in any other game or engine than ArmA or its sequels and expansion.
4) If you create and distribute a work based on the ArmA Warfare MP mission content you must license it under this License to anyone who will be using it. This License gives no permission to license the work in any other way, but it does not invalidate such permission if you have separately received it.

Intro

Warfare has been designed to be a totally open-ended mission in far more aspects than its gameplay. The core logic of capturing territory and acquiring new equipment can be applied to any location or era in human warfare - or rabbit warfare, if your mod is based on Watership Down rather than Black Hawk Down. This document will provide you with some of the main outlines of how the Warfare mission has been structured on a technical level, allowing you to easily exchange M16s for maces or Sahrani for Sandleford.

Folders and names

When you want to modify the Warfare mission, the first things you require are the mission files. These can be acquired by manually unpacking the Warfare mission files. Locate the WarfareV11.SaraLite.pbo and Warfare32V11.SaraLite.pbo files in you ArmA\MPMissions folder and use a PBO extract application like CPBO to unpack the PBO contents. One new folder will be created for each mission. There's the regular 16 player WarfareV11.SaraLite and the 32 player Warfare32V11.SaraLite. These two mission folders only differ in their mission.sqm files, so changes made to any of the other scripts can directly be copied over to the other mission.

If you want to edit either of these missions in the Mission Editor, it is advised to copy WarfareV11.SaraLite and/or Warfare32V11.SaraLite to your My Documents\ArmA\Profile\Missions folder. When you want to test your changes in multiplayer, simply copy the mission(s) back over to your ArmA\MPMissions folder and give the mission folder a identifiable new name to display it in your server mission list.

Naming will also be important when trying to keep an overview of all community made modifications out there, so here's a short description of what to rename and where.

  • Folder name - Since this also determines the eventual name of the PBO you might want to release, setting up a clear name for your mission folder is quite important.
    • Suggested format: Warfare<player count><Warfare build>_<modification name><modification build>
    • Naming example: Warfare32V11_RabbitWarfareV2.2
  • Mission name - The name under which the mission is listed in the server browser and mission list is defined in the Intel section of the mission.sqm file. You can modify this by clicking on the Intel field in the top right corner of the mission editor, or by locating the entry in the mission file using a text editor. It is recommended that the naming standard follows a similar format to the PBO name.
    • Suggested format: Warfare<player count> <Warfare build> - <modification name> <modification build>
    • Naming example: Warfare32 v1.1 - Rabbit Warfare v2.2

Once your Warfare mission folder is properly set up and renamed, you can again create a PBO out of it at any point using the same PBO application as you used for unpacking. Other people can now play your mission by placing this PBO in their ArmA\MPMissions folder.

Overall mission structure

To ensure a clear overview of who runs which scripts at all times, the mission is split up into four main elements:

  • Mission root – Contains the basic mission files and the start-up scripts for the mission, server and clients.
  • Client folder – Contains all scripts that run exclusively on client-side (the actual players).
  • Common folder – Contains all scripts used by both client and server, including the gear and vehicle config files.
  • Server folder – Contains all scripts used exclusively by the server, such as AI behaviours.

Each of the three main folders contain Init and a Functions folders, handling initialisation of the local gameplay scripts and their function processes respectively. If you are relatively new to scripting or have no desire to radically change any core game play mechanics, it is best to leave the Functions folder untouched for now. Certain files in the Init folder provide you with a lot of control over these function scripts by simply adjusting some very basic values.

Similarly, the scripts in the Config folders (located in \Common and \Server) contain definitions for all weapons and vehicles used in the game, again allowing you to quickly edit such content with minimal knowledge of ArmA scripting.

Common script structures

While you may not want to write them yourself, you could come across some seemingly complex lines of code in the scripts you want to edit. The following explanation should give you a basic overview of how this code is often composed, making it easier to interpret or even adjust them.

Config file arrays – Scripts that define the troops, vehicles, weapons and buildings used in the game generally do so using arrays like this one:

  • _v = ["WSOLDIER"]  ;> Reference name
  • _u = ["USMCD_Soldier_R"]  ;> Unit class
  • _d = [Localize "STR_DN_RIFLEMAN"]  ;> Display name
  • _c = [100]  ;> Cost
  • _t = [5]  ;> Build time
  • _p = [5]  ;> Point value
  • _i = ["\Ca\characters\data\Ico\i_null_CA.paa"]  ;> Unit icon

Each of these lines is turned into a separate array entry, with subsequent classes being added to it. For example, the local variable _u contains the class name of this soldier. Generally this is the only entry you have to change to replace a soldier with a different variant. The next soldier to be defined in the script is an AT soldier, but this time the class name is listed as:

  • _u = _u + ["USMCD_Soldier_AT"]

This means the local variable _u has now become ["USMCD_Soldier_R","USMCD_Soldier_AT"], an array. This is done for all the variables in each entry, resulting in an array for class names, one for unit prices, etc. You can now easily get all data for a specific unit type by refering to, for instance, position 2 in every one of these arrays.

Dynamic variables – To prevent a lot of duplicate variable names for values that have slightly different variants, we can change part of the variable name like this:

  • Call Compile Format["%1RabbitCount == 8",_color]

This setup basically adds the value of _color in front of RabbitCount, allowing you to change the value of RedRabbitCount, BlueRabbitCount or GreenRabbitCount using just this one line of code.

Editing default parameters

The first and easiest method of “modding” Warfare is the aforementioned use of init script files. To be more precise, the file Init_CommonConstants.sqs located in the Common\Init\ folder. In this file you will find a big list of variables, influencing things ranging from respawn times to AI team sizes. Each parameter is accompanied by a clear comment indicating its purpose, making it a rather safe environment in which to experiment with value changes.

Modifying units

The second way of changing the face of the mission with rather little effort is by replacing default weapons, characters, vehicles and buildings with your own selection of add-ons. This can be done by replacing some of the default class names with the class names of the content you want to use in the mission instead.

For example, exchanging Warfare's USMC infantry for the default ArmA US Army troops can be done as follows:

  • Locate the soldier class names in the mission and script files: “USMCD_Soldier_R”, etc.
  • Overwrite these entries with your new replacement classes: “SoldierWB”, etc.

And you're done. It's really that simple, the only effort really being to locate all class names. So to make life even easier for you, here is a complete overview of the files where all the different soldier, weapon, vehicle and building properties are located. In these files you can adjust class names, unit costs, construction times and more.

The following files contain soldier class properties that can be adjusted:

  • \
    • mission.sqm – Contains all playable soldiers
  • \Common\Config\
    • Config_Barracks.sqs – Contains all US / SLA / Resistance soldier classes

The following files contain vehicle class properties that can be adjusted:

  • \
    • mission.sqm – Contains the US / SLA Mobile Headquarters vehicles
  • \Common\Config\
    • Config_AircraftFactory.sqs – Contains all helicopters purchasable at helipads
    • Config_Airport.sqs – Contains all fixed wing aircraft purchasable at the airfield
    • Config_AITeams.sqs – Contains all vehicles used by US / SLA AI teams
    • Config_Artillery.sqf – Contains all artillery cannons
    • Config_Depot.sqs – Contains all vehicles purchasable at town camps
    • Config_HeavyFactory.sqs – Contains all purchasable heavy vehicles
    • Config_LightFactory.sqs – Contains all purchasable light vehicles
  • \Server\Config\
    • Config_Resistance.sqs – Contains all vehicles used by Resistance AI teams
  • \Server\Init\
    • Init_Server.sqs – Contains all default vehicles spawned at the start of the game

The following files contain weapon class properties that can be adjusted:

  • \Common\Config\
    • Config_Loadouts.sqs – Contains all purchasable weapons

The following files contain building class properties that can be adjusted:

  • \Common\Config\
    • Config_Structures.sqs - Contains all structures that can be purchased at the main base and at the town camps

Modifying teams

There are three types of teams to be found in Warfare. For the US and SLA there are the (player or AI controlled) regular combat teams and the (AI controlled) defense teams. The third type are the Resistance teams occupying neutral towns. The following list gives you an overview of where and how each of these teams can be modified:
  • Regular combat teams
    • Mission.sqm – The US and SLA infantry units placed in the mission comprise the selectable player slots and the commanding officers for the regular combat teams on each side. Adding more troops to each side is possible, as long as you properly incrementally name them up from the existing units (WestSlot9, WestSlot10, etc.)
    • InitMission.sqf – Any playable units added in the Mission.sqm have to be added to the eastTeam/westTeams and eastSlots/westSlots arrays in this script. These can be found under the //Advanced squads comments.
    • \Common\Init\Init_CommonConstants.sqs – The MAXPLAYERTEAMSIZE value allows you to set the number of subordinates in a regular combat team.
    • \Common\Config\Config_AITeams.sqs – The different AI team types defined here are composed as arrays of unit class names from the Barracks/Light/Heavy config scripts. Each array has a team class name (_n) by which the team is referenced in other scripts, and a display name (_d) by which it is displayed during the mission. The first unit is defined as _u = [..], with all subsequent units in the team being added as _u = _u + [..]. When adding or removing team types, be sure to also list them under “;AI commander preferences for AI teams.” to ensure the AI commanders will properly deploy them during a mission.
  • Defense teams
    • \Common\Config\Config_AITeams.sqs – The aforementioned unit class arrays are also used to define the base defense teams in the same file. The types named “ATAA” and “BaseDefense” are spawned at the base, with the former used to patrol to area, while the latter mans any fixed defenses placed in the vicinity of the base.
  • Resistance teams
    • \Server\Config\Config_ResistanceTeams.sqs – Structured similarly to the Config_AITeams script, this file lists all the teams spawned by the Resistance to defend the neutral towns they occupy.

Modifying the island

Obviously you'd much rather be fighting for strategic control over your own back yard than sunny Sahrani, so replacing Somato with the bicycle shed and Paraiso with your mom's flowerbed is a high priority modification. Assuming you've already recreated a fully functional map of your back yard, or just downloaded a nice alternative instead, converting Warfare to make use of it is again fairly easy.

As described previously, moving the missions to your My Documents\ArmA\Profile\Missions folder allows you to open them in the ArmA mission editor. Once the mission has been loaded, you will find the following elements on the map:

  • Team objects:
    • Playable characters (red and green infantry icons) – These soldiers are the selectable player slots available at the start of the game.
      • Name: Incrementally named WestSlot1 or EastSlot1 and onwards
    • Mobile headquarters (yellow M113/BMP2 vehicle icons) – The two empty vehicles are the main objectives in the game and allow commanders to build bases once deployed.
      • Name: WestMHQ and EastMHQ
    • Resistance reference unit (single red infantry icon) – Found on the island of San Tomas in the far South, this lone soldier is used as a basic Resistance group in which all other RACS units will initially spawn.
    • Starting locations (blue game logic flags) – Scattered all over the island, these game logic objects mark all the locations where the two playable factions can be placed at random at the start of the game. Positioning them on flat and clear surfaces is recommended.
      • Name: Incrementally named StartingLocation0 and onwards
      • Executes script: [this] Exec "Common\Init\Init_StartingLocation.sqs"
  • Town objects:
    • Town depots (yellow object icons) – These buildings are located near the center of each town, acting as the capture point that determines who controls the town.
      • Name: Same name as the town in which the depot is located
      • Executes script: [this,"<town name>",[<bordering town 1>,<bordering town 2>, ... ],["<Resistance defense team 1>","<Resistance defense team 2>", ...],<optional town size value>] Exec "Server\Config\Config_Town.sqs"
    • Town camps (yellow object icons) – Placed on the outskirts of towns, these bunkers act as an infantry respawn and resupply point. They are usually accompanied by walls, MASH tents and some empty defensive emplacements for use by the Resistance teams.
      • Name: Incrementally named <town name>Camp1 and onwards (e.g. “CayoCamp1”)
      • Executes script: [this,<town name>] Exec "Common\Init\Init_Camp.sqs"
    • Airfield hangar (yellow object icon) – This is a hangar objects where players can purchase fixed wing aircraft. It should be placed next to a runway or airstrip of some sorts.
      • Name: NorthAirport
      • Executes script: nullReturn = [this,Localize "STRWFNORTHAIRPORT"] ExecVM "Server\Server_UpdateAirport.sqf"
  • Markers:
    • Respawn markers (red target markers) – These markers define the location where respawning units are temporarily placed until their respawn count down has finished. Try not to place it anywhere players can normally reach, or above water or something.
      • Name: WestTempRespawnMarker and EastTempRespawnMarker
    • Town center markers (red target markers) – Marking the center of a town, allowing scripts to accurately detect a unit's distance from the town and generate defensive troops.
      • Name: <town name>CenterMarker (e.g. “CayoCenterMarker”)
    • Town depot markers (blue square markers) – This marker is placed on top of the Depot building in each town, clearly indicating its position on the map.
      • Name: <town name>Depot (e.g. “CayoDepot”)
    • Airport marker (blue square marker) – This marker is placed on top of the aifield hangar object, indicating its location on the map.
      • Name: NorthAirportLocationMarker
    • Town arrival zone markers (red upwards arrow markers) – These big markers indicate the location where Fast Traveling units will be spawned upon arrival. To ensure no units flip over or get stuck in buildings, this should be a relatively large area clear of obstacles.
      • Name: <town name>ArrivalZoneMarker (e.g. “CayoArrivalZoneMarker”)

To convert the Warfare mission over to a different island, you will first have to rename the mission folder to use the suffix of your new map. So for the Cold War Reloaded map Everon, the folder would change from WarfareV11.SaraLite into WarfareV11.Eden. After opening the renamed mission in the editor, you will only have to move the objects listed above to suitable locations, and replace the references to the old town names with the ones of the new island. Any other objects you find on the map are triggers and game logic objects that will function regardless of their placement.

New playable characters, towns, camps and starting positions can all be added (or removed), as long as you ensure they are still named properly and where required call the correct scripts. The aforementioned list of map elements describes all required entries, but be sure to double-check your additions by comparing them to existing towns.

Capture logic

Capturing town in Warfare is triggered by ground units standing within a certain range of an neutral or enemy town's depot building. If no enemy units are within the same range, the Supply Value of this town will start to deplete, declaring the town “captured” upon reaching zero. A higher number of friendly units around the depot and the number of camps occupied in that town, both act as multipliers of the capture speed.

The time it takes to capture a town, the distance one has to be from the depot to start this process, and the types of units that are allowed to do so, are all controlled in the \Server\Server_UpdateTown.sqs file. Several external factors are called to modify the capture process that takes place here:

  • StartingSupplyValue – This variable defined in \Common\Init\Init_Location.sqs (default value: 10), determines the initial Supply Value a town receives upon capturing it, and thus the minimal time it takes to capture this town.
  • Range – Defines roughly the “size” of the town, determining the range in which Resistance defenses will be removed once the town has been captured by the US or SLA.
  • TOWNCAPTURERANGE – A constant value determining the minimum distance a unit has to be from the depot in order to capture it. Defined in \Common\Init\Init_CommonConstants.sqs, the default value is set to 38.
  • TOWNCAPTURERATE – A constant value determining the speed at which the Supply Value is drained during the capture process. Again defined in \Common\Init\Init_CommonConstants.sqs, the default value is set to 1.
  • GetTotalCampsOnSide – This function, located in \Common\Functions\, counts the number of camps that is under the control of the side capturing the town. A higher number results in a faster capture.
  • SupplyValue – The accumulated value of supplies delivered to this town by Supply Trucks. Depleting during the capture process, a higher value obviously results in a longer capture time.

Within the UpdateTown script, the #Update section constantly checks for the presence of enemy units within the defined TOWNCAPTURERANGE. If any units have been located and no defending troops are present, the script continues to the #TownOccupied section, determining the number of attacking units present and any possible modifiers to the capture rate, after which the Supply Value will start to drain accordingly. Upon reaching zero, the script will continue to the #Resistance/East/WestCapture section, depending on who now controls the town, broadcasting the change of ownership across the network.

Respawn logic

One of the most influential game mechanics is the speed and location at which players and AI can respawn. The current logic is rather straightforward: you respawn in your team's main base, unless you get killed in a town where you control at least one camp. The latter scenario will bring up the respawn map interface, allowing you to select one of the nearby camps as a respawn location. The following elements are used to create the basic requirements for the default respawn behaviour:
  • \
    • Description.ext – Contains the definitions for respawn type and respawn timeout (respawn = 3; and respawndelay = 1;)
    • Mission.sqm – Contains the WestTempRespawnMarker / EastTempRespawnMarker markers used to designate the “storage space” where respawning units are placed for the duration of the respawn countdown.
  • \Server\Init\
    • Init_Server.sqs – ArmA's respawn behaviour requires default East and West respawn markers, which are created in the #CreateEastRespawn / #CreateWestRespawn section of the script. Respawning units will only appear at this marker for a split second, before being moved to the WestTempRespawnMarker / EastTempRespawnMarker locations.
  • \Server\
    • Server_Update.sqs – Updates the base respawn markers to be positioned anywhere the MHQs are deployed.

While the mission is being played, several scripts track who is being killed and where. As shown above, much of the actual “respawn time” is somewhat faked, with the players looking at an interface while their characters are actually standing somewhere far away. This time is used by the following scripts to select a suitable respawn location:

  • \Server\AI\Advanced\
    • Advanced_UpdateSquadRespawn.sqf – This function is executed on all respawnable AI team leaders. After getting killed, the script moves them to the TempRespawnMarker location the moment they respawn. After a 14 second countdown, the unit is placed back in the base, nearest to the facility they need for the vehicles in their team type.
  • \Client\
    • Client_Killed.sqs – This script functions somewhat differently from the previous AI-oriented one. Instead of waiting for a unit's death, this script is only executed the moment a player is killed. The player is again moved to the TempRespawnMarker location, while a suitable respawn location is being determined. The script also checks if the player was killed near a town where any occupied camps might be available. If this proves to be the case, the default countdown interface is closed and the respawn map interface is shown instead. After a 14 second countdown the interfaces are closed and the player is placed at the selected respawn location.

Once a unit is ready to respawn back onto the battlefield, the following scripts ensure it will make a clean start, resetting all related tracking functions:

  • \Client\Functions\
    • Client_PlayerRespawn.sqf – Called at the end of the Client_Killed script, this function clears and resets all action menu entries, and calls a function to equip the player with the selected weapon kit.
  • \Common\Functions\
    • Common_InitUnit.sqf – This function is called for all units and vehicles that (re)enter the battlefield. EventHandlers can be easily added here, allowing you consistently execute them on all units in the mission.

Evolving the editing guide

The info thus far should allow you to change a substantial portion of the Warfare mission. If you have already worked on specific scripts or functions, feel free to supplement this page with additional info or chapters. New features in upcoming official releases will also be described here, ensuring the documentation stays up to date.