View source for Terrain Control Tutorial for Mappers

This is based on Wilsons [http://forum.mechlivinglegends.net/index.php/topic,11973.0.html Terrain Control Mapping Guide].

= Terrain Control Community Guide =

== Introduction ==

Welcome to the Mechwarrior: Living Legends Terrain Control game mode community guide. 

This document will explain and provide examples on how the developers of Mechwarrior:  Living Legends setup the official Terrain Control maps. It will also provide a rundown on the various entities that are and can be used on Terrain Control maps.
There is quite a lot of variety in the way that terrain control capture points can be setup, and even after reading through this document, I would strongly urge our community level designers to experiment and try things out, you may just come up with the next great MWLL game mode!
One last quick note before we get into it, this is not a beginner’s guide. It is written with the assumption that the reader will have some knowledge of installing and using Sandbox2 to create multiplayer maps. To explain from a complete beginner’s point of view is beyond the scope of this document, but that being said, every effort will be made to explain things clearly, concisely and as simply as possible. For readers that are new to Sandbox2, there are many great tutorials and documents available online to get started with – some quick links -

* http://www.crymod.com
* http://wiki.crymod.com/index.php/Category:Official:Sandbox2_Manual
* http://wiki.crymod.com/index.php/Map_Creation_Tutorial_Series_-_Chapter_1

== Entity/Object Usage Breakdown ==

The vast majority of these entities should be familiar to anybody using Crytek’s Sandbox2 Editor to design levels. Following will be a brief rundown of the various entities, their important properties and any specifics of their use internally by the MWLL dev team.
One of the best ways to figure all these different entities out for anybody not already familiar with them, would be to run through some of the editor tutorials available at Crymod.com and just plain experiment to see what effect different things have.
MWLL prefabs, such as the Mechhangers and Aero/Vtol pads, can be placed and extracted onto empty maps for tinkering with. This is also a good way to learn how these entities interact with each other.

=== Areashape ===

The Area Shape, Area Box and Area Sphere should be familiar to     anybody working with Sandbox2 as they are used to represent all kinds of things from being     used as trigger zones through to being attached to an ambient volume to enable sound to be created in specific areas.
In the case of capture points, we use area shapes as the trigger volume to start/end capturing when players enter or leave it.
They should be placed so as to not include any repair bays, mechhangers or spawn points in their areas. This prevent players from exploiting game mechanics by sitting in a repair bay and becoming invulnerable while locking the base from capture at the same time, or hiding in a corner of a mechhanger etc.
It is also important to set the height of an area being used for a capture point. In-house development on MWLL used a rule of thumb of 15mtrs off the ground as the highest point on any capture zone. This was done to ensure that VTOL and aerospace assets could not be used to easily capture ground objectives.

=== Buyzone ===

Buyzone entities function in almost every respect identically to a Factory entity. The difference is that where a factory entity can allow asset repair, selling and various other functions, a Buyzone will only allow purchases. It cannot be setup to allow selling or repair, and it may not spawn vehicles correctly. 
Internally these entities are only used in bases that have no purchasable assets. They are used in Battle Armour spawn points and at bases where due to the fact that there are no vehicle facilities or turrets, a factory is not required. A Buyzone entity may not be represented on map with geometry the way a factory can.
===CapturePoint (required) ===
The capture point is, as its name suggests, the most important entity when it comes to setting up working capturable areas on maps. This entity has 3 states, represented by Boolean variables accessible through the entity inside a flowgraph, the states are, Neutral-InnerSphere-Clan, and represent which team holds the capture point if any. While one of the states is true, the others are false. 

The capture point entity is also the central point for linking other objects and entities that are supposed to change teams, like factories or repair bays, turrets etc.
All links from the capture point to another entity such as a factory, repair bay or turret must be named “capture”. You can rename links by right-clicking on the link in the capture point’s “Entity Links” properties, and selecting “Rename”.

A capture point requires that either an Area shape be created and linked to it, or its own bounding box properties be set – “DimX”, “DimY”, and “DimZ”. Internally on MWLL maps, our developers use Areashape objects to represent capture areas. This is done for the single and extremely important reason that using an area shape, complete control is gained over exactly where the capture area is. Non-uniform shapes are possible using the area shape object, which means exclusion of things like spawn points from the capture area is quite easy.

A Capture Point also has 2 properties for setting the “weight” of the point. These are “Clanweight” and “Isweight”. These 2 values represent the amount this capture point contributes to the overall ticket decrement rate, for the team holding it. 

The last property, “Type” is a simple text string denoting the type of the base. The type of base captured or under attack is voiced by “betty” during the game but currently has no actual affect on gameplay or base capture. Valid strings are: 

* Outpost  (default)
* Base
* Factory
* StrategicPoint

Please note that it is recommended to have at least one base per team that is non-capturable. Failing to provide one team with a non-capturable base can result in the opposing team taking everything and half of the players having nowhere to spawn; this situation would be no fun for either side.

=== Factory ===

The factory entity is one of the more important entities on the map. It is responsible for most of the asset (Mech, VTOL and Aero) production, as well as ensuring nearby turrets are owned by the correct side. 
These entities must have a link from a capture point to them, named “capture” as do all entities that need to change teams. 
An initial team can be selected for the factory, either black (for Clan) or tan (for IS), allowing factories to be setup with an initial owner at the start of battles.
The best way to learn how these entities work is to examine how they are setup in the prefab library supplied with MWLL – mwll_assets.xml. The simplest setup for a factory entity can be seen in the “TC_Neutral_Mechbay\Singlebay_nospawn_defFactory” prefab. The factory in that prefab is setup in its “default MWLL” state, allowing purchase of all ground based assets. 
The easiest way to select entities for linking on maps is through the object selection panel (default hotkey ctrl-t) and filtering their names. On that point, it is also a good idea to give any entities placed onto maps a meaningful name.
To setup a factory to allow custom production options, the entity property “FactoryClass” needs to be removed, otherwise the entity will ignore the checkboxes below. Once the FactoryClass has been blanked, the checkboxes below will allow selection of various assets for production, by weight, class and team (IS or Clan). It should not be necessary to alter production of clan/is between factories as this is achieved via a server flag. If a category of asset is selected for one team, it is recommended to select it for the other team as well.
Factories can also be setup like many other entities with an initial team alignment. The settings that are valid are either, black (for clan) or tan (for IS). This allows capturable bases to be setup with an initial owner. 

=== Prefabs ===

Prefabs can be placed on maps, but to have them linking properly to capture points, it is necessary to extract them. This is because of the fact that on export, the editor reads in from the prefab library xml and places into the level.pak file all of the relevant placement/material and linkage info for each prefab directly from the xml. So, when the editor replaces that info at export, any user links or changes will be broken and the prefab will be reverted to its “default” state. This also means that prefab library xml’s are not required for distribution with maps, as they are effectively “embedded” into the level.pak file on export.

=== Repair Bay ===

A repair bay on a TC map consists of 2 separate objects. First, the RepairBay entity and second, the Areashape which is the area that repairs can take place in.  
A link must be made FROM the area shape TO the repairbay entity, and the ID of the Areashape must be set to match the RepairBay’s “repairAreaId” property.  This property will default to -1 when placed on the map at first, but this should be replaced with a specific ID chosen for repair areas on the map. As you can see in the image on the right, ID 990 was used on this repair bay.
The “CheckForTeam” property tells the repair bay that it should check which team a player is on before allowing repair. This ensures that players cannot repair at the bay if it is hostile or neutral to them. The “StartingTeam” property allows a repair bay to be aligned to a specific team, Clan (black) or IS (tan), at the start of a battle.

=== Spawngroup ===

A Spawngroup is the main entity used to setup areas on the map where players can spawn in. They are used in conjunction with Spawnpoint entities (see below) to create these areas allowing players to spawn into the map. The Spawngroup entity is usually placed slightly above, but in line with, the CapturePoint. This is done so that it’s icon on the minimap lines up with the CapturePoint icon.
A Spawngroup needs to be linked to all of the Spawnpoint entities and the link needs to be named “spawnpoint”. A Spawngroup can also be setup to be aligned to a specific team at the start of a battle, by setting the appropriate entity property.
Note: For examples of setting up Spawngroup entities, place and extract the “Mechhanger” or “MechhangerCL” prefab on a blank map.

=== Spawnpoint ===

Spawnpoint entities are used in conjunction with the Spawngroup entity listed above. These entities represent the exact point on the map that a player can spawn at. These are usually placed inside hanger models, or inside bunker models for consistency on official MWLL maps. 
Note: For examples of setting up Spawnpoint entities, place and extract the “Mechhanger” or “MechhangerCL” prefab on a blank map.

=== Turrets ===

All turrets used on maps must be placed on the map as an “Archetype Entity”. They are contained in the mwll_props.xml archetype library, which can be opened like any other through the Database view. They are contained under the “Multiplayer/autoturrets” heading group. Note that archetype libraries and prefab libraries may share the same name, but are stored in different locations and are not interchangeable. 

The turrets that can currently be used for Terrain Control maps reliably are:

* Turret_AMS
* Turret_Calliope
* Turret_EagleEye
* Turret_Hellgiver
* Turret_Sentinel

Other variations of turrets may also function, though they have not been tested and may not function correctly with TC game mode rules.
Turrets that need to swap ownership on maps have a few small quirks at the moment in the way they need to be setup to actually capture and swap teams properly(these will be addressed and ironed out in future releases). First, they need to be linked to a capture point, in the same way that all other entities are, with the link being named “capture” and Second, their alignment will match that of the closest Factory entity. What this means, is that if a base is setup with turrets, but no factory entity, that base’s turrets will align themselves to the next closest factory, which could be at a base being held by the enemy. The workaround for this behaviour is to ensure that if a capture point has turrets, it also has a factory linked to the capture point, to ensure the turrets have the correct alignment.

== Basic Capture Point Setup ==

The above image, as its footnote states, is a completed working capturable base. It is taken from the community map TC_StarLeagueCache, which is nearing completion at the time of writing this document.
The base itself features 2 single bay mechhangers, 2 repair bays, 2 Sentinel(2xMBL) turrets, 1xHellgiver(1xLBL) turret, a spawning location with individual spawn points inside the mechhangers and a capture point to allow it all to change sides when captured.

Following is a short guide on setting up a similar, yet somewhat simpler, working capturable base for a terrain control map.
This image is depicting a very simple capturable base, with all of its entities placed, though not connected as yet. There is a single mechhanger, placed from the prefab “TC_Neutral_Mechbay\Singlebay_nospawn_defFactory” and extracted before being re-grouped for ease of selection. An area shape has been placed down around the base as can be seen, making sure to keep the mechhanger, which will also contain the spawn points, out of being capturable. The other entities include the Capture Point itself, a Spawngroup entity, 3 Spawnpoint entities (which will represent 3 places the player can spawn into) and lastly, a Sentinel Turret archetype entity (Contains 2xMBL).

The first thing that should be done is to set the Capture Point’s properties, link it to all of the other entities and move it to its proper location inside the area to be captured. The capture point entity places an icon on the minimap to allow selection for capturing, and it is more intuitive to have that icon actually be in the capture area rather than off in some arbitrary place. 
As can be seen in the image on the right, this capture point has had its weighting for both teams set to “2”, has had its type changed to “factory” and is linked to the turret, mechhanger factory and the Spawngroup. All of the links are named “capture”.

The next thing that should be done is to ensure the Area shape is linked properly to the capture point. This area is what will be used as the trigger volume to start and end captures, as players enter and leave.
As can be seen in the image to the right, the “Target” of this area shape is the “CapturePoint”. The easiest way to link these entities, is to bring up the object selection panel with ctrl-t, select the area shape so its properties are showing as in the image, click the “pick” button on the area shape’s rollout and then select the capture point in the object selection panel, finally click the “pick” button on that object selection panel (not the area shape’s rollout) to make the link. If the link is made properly, the area shape’s rollout panel should show the link as it does in the image.
The link must not go from the capture point to the area but from the area to the capture point.
This area has had its height set to 25units or metres high and has been lowered into the ground approx. 10 units, leaving 15 above ground and making sure that any dips in the base’s terrain are covered.
Once the area is linked to the capture point, the map could essentially be fired up and tested with that area being capturable. However, there is a little more setup that needs to be done beforehand to ensure everything is working and tidy on the map.

The Spawngroup entity has to be linked to each of the 3 Spawnpoint entities, with each link being named “spawnpoint”.  Those Spawnpoint entities should be placed where the map designer would like the player to spawn in. The best place in the case of this example is inside the mechhanger.
The image to the right shows the entities placed on the map and linked to each other properly. Note the spawn point links going into the mechhanger, and also note the way the capture point, factory and Spawngroup entities are all positioned on the same X, Y co-ords.
They are positioned like this due to the way the current Crysis minimap icons work.  If they are not on top of each other, then at various stages of the battle they will all show icons resulting in a very messy and difficult to see or select from minimap. This icon issue will be resolved in the future, one of the planned features for MWLL involves reworking the minimap icons to be more indicative or what each one contains, to be able to see at a glance what each base has or does not have.
Finally, level designers should keep in mind that they will be required to denote their capturable areas to players somehow other than relying on a minimap icon. This should be something like a familiar object or architecture used between each point, maybe some specific particle effects around capturable areas.
Internally the MWLL developers used a prefab called a “tc_beacon”. The variations on this model that were used by the developers can be found in the mwll_assets.xml prefab library under TC_Beacon group. It contains the many variations used on MWLL’s official maps by the developers. This prefab is used internally to denote the bordering areas of a capture point, visually informing players they are about to enter a capturable area.
The other visual indicator used internally by MWLL’s developers is an entity called a TCFlag. These entities can be placed inside and around capturable areas without having to worry about linking them to anything. The TCFlags will align themselves to the closest Capture Point on the map.

TCFlags require a small amount of explanation to use properly, as they are required to be used in pairs.
The first of the pair’s material should be a Clan material and the second of the pair’s material should be an Inner Sphere material.
The first flag should be set to team 1; the second flag should be set to team 2. Team 1 is Inner Sphere, Team 2 is Clan. As can be seen in the image each team’s flag can be given its own material and model.
When placing TCFlags, it is important to place each of the 2 flags in each pair right on top of each other. This is so that when one flag fades out during capture and the other beings to fade in, they are both in the same location.

== XML Setup ==

Finally, for a map to be played or even tested on a server, it will require, as do all MWLL maps, a TC_<MapName>.xml file in the folder with the level files. For example – TC_Marshes.xml.
This XML file follows the same format as previous versions of the mod, with one simple difference. That is in the <Gamerules /> section. Everything else stays the same, minimap filename and co-ords, loading screen filename, display name, description text etc. For those unsure as to how these files are set out, open one of the official map’s XML files. They can be found in the MWLL\Game\Levels\Multiplayer\TC\ folder
The change in the Gamerules section is quite simple and just involves adding in the Terrain Control game mode string as one of the options. The exact string is “TerrainControl” – all one word, camel case. This is also the string used in levelrotation xml files in their Gamerules section.

== Capture Point Flownode Basics ==

The following is a short explanation of the usage of a capture point’s flowgraph node. This node can be used to achieve many scripting oriented tasks within levels, such as controlling effects, moving entities, weather, lighting, physics and other things that are based around capture point ownership. 
The basic point of using the control point in the flowgraph is to enable events to be manipulated based on the state of the capture point, i.e. Which team has control, is the point neutral, has the point just changed teams etc. The functionality of the node may be added to in the future as the development needs of MWLL dictate.
The image to the right shows a flowgraph with the Capture Point Flownode added to it, it is linked in this case to a pair of logic OR nodes, which in turn are ultimately linked to the enable/disable nodes of a set of particle effect entities. The Capture Point flowgraph entity can be added to any flowgraph in the same way as any other entity, by selecting the entity on the map, then “Add Selected Entity” from the right-click context menu in the flowgraph panel. If the flowgraph is being attached to the actual Capture Point itself, the entity should be added as the “Graph Default Entity” (highlighted in above image). 
The capture point flowgraph node has 3 output nodes, as stated in the entity breakdown above. These 3 output nodes are named “Clan”, “InnerSphere” and “Neutral”. The outputs will fire upon a new client joining the game and upon change of state of the Capture Point. Each of the outputs is represented as a Boolean variable, with its state being set to either true or false.
The image to the right shows a completed and working flowgraph from the community map TC_StarLeagueCache. This flowgraph is responsible for turning on and off a set of effects that mark who owns one of the capture points. In this case it’s a “hyper pulse” beam particle effect, along with the hazard entities that go with it. The effects are turned on and off based on which team holds the capture point or if the point is neutral. This is just one very simple way of implementing a capture point based flowgraph for effects in levels. 
Flowgraphs can be as simple or as complex as required, though care must be taken to ensure that any flowgraphs made that could have some form of gameplay impact, such as affecting visibility or movement of players, is synced properly between the server and clients. The capture point Flownode will sync itself properly between clients and the server in almost all cases. At the present time, MWLL developers recommend that Capture Points not be used to control gameplay impacting effects as latency issues and unforseen bugs may cause the node to sync incorrectly, resulting in some clients having their node’s not firing at the same time as others.

== Conclusion ==

Reading through this document should give a fairly solid understanding of what is required to get a Terrain Control map into the game and running. One piece of advice the developers will give to their community level designers is to not give up at the first attempt. There may be problems that cannot be solved, or parts of the process that are not clear enough. All of these things can be addressed to the MWLL Community Created Content forums board at the following internet address:

http://forum.mechlivinglegends.net/index.php/board,87.0.html

These forums can be used as a contact point between community level designers and MWLL’s developers, to have questions answered and problems hopefully solved. 
Finally, this document should be thought of as fluid and ever changing during MWLL’s development. It will be updated and changed as required during the development of the Mechwarrior: Living Legends Mod.
This document has been compiled and written by the Mechwarrior: Living Legends Level Design Team.

= References = 
* [http://forum.mechlivinglegends.net/index.php/topic,11973.0.html MechWarrior: Living Legends - Terrain Control Tutorial for Mappers]

Map example Link: http://clanjadewolf.net/mwll/maps/TC/TC_Reference.zip

[[Category:Sandbox 2]]
[[Category:Guides]]