5. Walls

Herein, we describe how to set up walls and wall-related assets in BFME: Reforged. Later on, we will describe the state of development of the wall system, its architecture, some limitations/areas for improvement, and known issues.

Setting up wall assets

Before diving into specific instructions for setting up wall assets in particular, please review the instructions for setting up buildings in general, here.

Creating the entity configuration

When creating the entity configuration data asset, set the Data Asset Class to either RTSWallHubConfig or RTSWallSegmentConfig. You should be able to find both by typing "wall" into the search box. If you want to set up a wall hub asset, choose the former. Likewise, if you want to set up a wall segment asset, choose the latter. Please see the instructions below for details on setting up each of these configuration data assets.

RTSWallHubConfig

https://cdn.discordapp.com/attachments/534719711137497090/861361197885292554/Capture2.png

In addition to the configuration options available to all buildings, the following should be set for wall hubs as well:

Material Flicker Time

When a wall is being planned by the user, the building cursors used to plan construction (the transparent meshes) are designed to change color if a player attempts to build a wall in an invalid manner. This can be caused by invalid terrain, lack of resources, or attempting to build a wall too far from one of the player's fortresses. These are just examples, and other restrictions on gameplay may be developed later. In any case, when changing materials from the valid material to another material, the planned wall pieces will flicker between two different materials, to make it easier for the player to identify why the wall cannot be built.

This configuration variable dictates the duration of the flicker, in seconds. For instance, if the value is set to 0.25, the material on the walls would be Material A for 0.25 seconds, and then switch to Material B. After another 0.25 seconds, they would switch back to Material A.

As of the writing of this documentation, the default value is 0.25. The value must be greater than or equal to 0 (zero).

Construction Delay

As walls are being constructed, the segments in the wall start their construction at different times, whereas all hubs start construction immediately. Segments begin their construction sequentially, starting with the segment closest to the origin hub of a wall, and ending with the segment farthest from the origin hub. The delay between the start of construction of each segment is equal to the time it takes for a given percentage of the previous segment be built.

For example, if the value of Construction Delay is set to 0.2, then whenever a segment is 20% complete with its own construction, the next segment in the wall will begin its construction process.

As of the writing of this documentation, the default value is 0.2. The value must be greater than or equal to 0 (zero), and less than or equal to 1 (one).

Max Wall Segments Between Hubs

As a player is planning a wall, segments are placed in-between hubs. This configuration variable indicates the maximum number of consecutive segments that may be built between two hubs.

For example, if the value is 5, then it would be possible to build a wall consisting of 5 segments bookended by a hub, but it would be impossible to build a wall with 6 or more consecutive segments (without some serious finicking by the player).

As of the writing of this documentation, the default value is 5 (five). The value must be greater than or equal to 1 (one).

Max Build Inclination

Sometimes a player may attempt to build a wall that intersects with impassible terrain. As of the writing of this documentation, there isn't any data layer for terrain which indicates passability. As such, we instead calculate the angle of incline between the origin points of consecutive wall pieces to determine if the terrain is passable or not. If the angle exceeds the Max Build Incline, the wall will be considered invalid after that point, and will be replaced by a hub, followed by double-length segment. As of the writing of this documentation this feature has not yet been implemented.

For example, if two consecutive wall pieces were being built on sloped terrain that ascended or descended at a 45 degree angle, and the value of this variable was set to 50, then the wall would consider its placement valid. If the value was instead 15, the placement would be considered invalid.

As of the writing of this documentation, the default value is 90.0 (ninety). The value must be greater than or equal to 0.0 (zero), and less than or equal to 90.0 (ninety).

Radius

This variable should be the radius of the static/skeletal mesh for the hub. If the mesh is not perfectly cylindrical (realistically, this will never happen), it should be the radius of the largest cylinder that will fit within the hub's mesh. This is used to determine how hubs are positioned when building a wall.

For example, suppose the mesh is roughly cylindrical, and when viewed from above is a regular hexagon. In this case, the radius would be the distance from the center of the hexagon to the center of one of the edges of the hexagon (The line between these two points should be perpendicular to the edge).

As of the writing of this documentation, the default value is 0.0 (zero). The value should be given in the default UE unit (probably centimeters). The value must be greater than 0.0 (zero).

Spawnable Wall Hub Config

Instead of assuming that a wall hub builds more versions of itself, we expose to the designers the option to change that with this variable. As such, this variable should be set to reference a wall hub entity configuration data asset to indicate what type of wall hub this hub will be building.

To make a hub spawn more of itself, simply set this variable in the entity configuration to reference the very same entity configuration data asset.

As of the writing of this documentation, the default value is nullptr. The value must be set, or wall-building functionality will not work.

Spawnable Wall Segment Config

Like the spawnable wall hub config, above, this variable specifies what type of wall segments this hub will construct when building walls from it.

When selecting which wall segment you want to use, be sure to specify the normal-length segment for this variable. Double-length segments are specified below.

As of the writing of this documentation, the default value is nullptr. The value must be set, or wall-building functionality will not work.

Spawnable Double Wall Segment Config

Whenever a wall would intersect with impassible terrain, the wall should be cut short, and ended with a hub, followed by a double-length wall segment. This variable allows you to specify the entity configuration data asset that this hub will use to build double-length segments should it need to.

As of the writing of this documentation, the default value is nullptr. The value must be set, or wall-building functionality will not work.

RTSWallSegmentConfig

https://cdn.discordapp.com/attachments/534719711137497090/861361256333180968/Capture.png

In addition to the configuration options available to all buildings, the following should be set for wall segments as well:

Length

This variable should be equal to the length of the longest edge on the wall segment's static/skeletal mesh. This, like the radius variable for hubs, is used to determine how wall segments are positioned when building them.

For example, suppose you model a wall segment that is 1 (one) unit thick, 5 (five) units tall, and 10 (ten) units long. In this case, the value of this variable would be 10 (ten).

As of the writing of this documentation, the default value for this variable is 0.0 (zero). The value must be given in the default UE unit (probably centimeters). The value must be greater than 0.0 (zero).

Spawnable Buildings

This variable is an array of building configurations, indicating what buildings can be built from this wall segment, destroying the segment in the process.

For example, you could add a tower or gate to this array, and it would then be made available to the player to construct from wall segments using this configuration.

As of the writing of this documentation, functionality based on this variable has not been implemented, and the default value for this variable is the empty array. Array elements must be, or have inherited from, URTSBuildingConfig.

Start Construction After Spawn

This variable is not something newly added to the wall segment configuration class; however, it is important to note. For all wall segment configurations, the value of this variable should be set to false (unticked), in order for their construction animations to work properly.

Reason being, most buildings start constructing automatically after they're spawned into the world. However, wall segments need to all spawn simultaneously when constructing a wall, but begin their construction animations in sequence, rather than all at once. When this variable is set to false (unticked), it keeps the segments in a holding state until the animation is allowed to begin from an independent function call. If the value of this variable is left as true, expect to see snapping in the animation, as the building jumps around to different points in its animation as that independent function gets called while the building is already constructing.

this functionality is different from the original functionality of this variable. Before, this variable, if left as false (unticked), would cause the building to be instantly constructed, rather than to be constructed over time if left as true (ticked). Now, the variable, if left as false, leaves the building in an un-constructed state, awaiting the function call that allows it to begin.

State of development

The implementation for the walls system has reached a stable point in its development, but it is not yet complete. It is best to think of it as being in a first-draft state, which we will refer to as a "Tier-0" (tier zero) implementation. Successive updates to the system will be subsequently named "Tier-1", "Tier-2", and so forth. Below, we enumerate the various features of the wall system and the state of each of their developments.

Tier-0

As a player, I must be able to build wall hubs via a builder

  • The player can presently build demo wall hubs. No final art or animations are in yet for any faction.

As a player, I must be able to plan a wall of arbitrary length in an arbitrary direction from a given hub

  • The player can plan a wall of arbitrary length in an arbitrary direction (360 degree rotation around the Z-axis) so long as their mouse cursor does not leave the landscape of the map. Doing so freezes the planning process.

As a player, I must be shown when my planned wall is unable to be built

  • Players are able to see when a wall cannot be built due to any of three factors, in descending order of severity: invalid placement on terrain, too far from one of the player's fortresses, and not enough resources to fully build wall. However, while the code framework has been set up for the "too far from a fortress" condition, the implementation has not yet been completed for that one yet.

As a player, I must be able to build a valid planned wall

  • Players may build a planned wall like when placing any other building.

As a player, wall pieces that I build must snap to terrain

  • As players plan out a wall, wall pieces automatically adjust their position on the Z-axis to snap to the landscape around them. The implementation of this relies on casting a ray from a point a very long distance above each piece to a point a very far distance below each piece, and finding where that ray intersects with terrain. If there is a better implementation for this functionality, this should be improved.

TODO

As a player, I must not be able to construct walls that intersect with other buildings

  • At present, a player can construct walls through other walls that are still under construction. This may be due to a lack of collisions on wall segments, which was not set to allow for units to pass through under-construction wall segments.

As a player, I must not be able to construct a wall if any piece of it is too far from one of my fortresses

  • At present, this feature is not yet implemented, though the framework for the implementation to be easily integrated into the existing solution is established. See ABFMEPlayerController::ManageWallPieceMaterials.

As a player, the walls I plan to intersect with invalid terrain must be cut short and ended with a hub followed by a double-length wall segment

  • A demo model with a demo construction animation have been created for a double-length wall segment, along with its entity configuration data asset. Furthermore, a pointer to such an asset has been added as a UPROPERTY to all wall hub configs. Implementation of the algorithm to determine when to cut off a wall being planned, and implementation of how to place the pieces of such a wall have not been completed.

As a quality tester, the walls system should provide me relevant information via BFME: Reforged standard logging

  • Logging implementation is limited, presently. Most logging is just an indication of an error (e.g. null pointer) which is used to avoid a crash in the unreal engine. Other logs, such as system warnings for gracefully-handle-able errors are few and far between, and just about zero logs are output for expected program behaviors. However, the implementation does adhere to BFME: Reforged project standards for logging.

As a player, I must not be able to connect my walls to any other players' walls

  • How the walls system behaves in multiplayer situations is wholly untested and unconsidered as of the writing of this documentation.

As a player, I must not be able to see other players planned walls, and vice versa

  • How the walls system behaves in multiplayer situations is wholly untested and unconsidered as of the writing of this documentation.

As an AI, I must be able to plan and construct walls just like any human player

  • AI ability to construct walls should be functional, so long as AIs use BFMEPlayerController. If they don't, then the walls implementation will need to be refactored into a class that both human player controllers and AI player controllers inherit from. Furthermore, no work to develop AI wall building capabilities has been completed as of yet.

As a player, I must be able to build towers, gates, etc. in my walls

  • Wall segments have been set up such that in the future this functionality may be implemented (i.e. the Spawnable Buildings property); however, no specific design or implementation has been finalized as yet for this feature.

Architecture

The implementation of the walls system is built across several interoperating classes & systems. The key classes to take note of are the following:

  • ARTSPlayerController
  • ARTSBuilding
  • ARTSWallHub
  • ARTSWallSegment
  • URTSWallHubConfig
  • URTSWallSegmentConfig
  • ARTSBuildingCursor

The following blueprints are also of note:

  • BP_Building_Cursor

The majority of actual functionality for the walls system resides squarely in ABFMEPlayerController. This is because wall construction requires keeping track of a variety of data, including the positions of multiple ABFMEBuildingCursors, the entity handles that are spawned as the buildings get constructed, and the relationships between each set of constructed wall pieces. This information is not well-suited to being tracked within any of the wall piece classes (i.e. AWallHub & AWallSegment).

Wall planning and construction themselves follow a multi-step process:

  1. Player clicks on the "build a wall" button after selecting an existing wall hub, the origin hub.
  2. System calculates distance between origin hub, and where the player's cursor intersects with the terrain. See ABFMEPlayerController::PlanWall
  3. Using this distance, the system calculates how many segments and how many hubs are needed to span the distance, taking into account spacing rules specified in the hub configuration files. See ABFMEPlayerController::GetWallPiecesNeededToSpanDistance
  4. System then manages the lifecycle of spawned ABFMEBuildingCursors, creating new ones and destroying extraneous ones to match the calculated demand for hubs and segments. See ABFMEPlayerController::ManageWallPieceLifeCycles
  5. System then positions each hub and segment into place along the line between the center of the origin hub and where the player's cursor intersects with the terrain. See ABFMEPlayerController::RelocateWallPieces
  6. System then colors each hub and segment according to the coloring rules defined for all wall pieces. See ABFMEPlayerController::ManageWallPieceMaterials
  7. The coloring process also indicates whether the wall can be built as a whole, and that information is stored in ABFMEPlayerController::m_ValidWallPieces for later
  8. As the player moves the cursor around the terrain, these steps are repeated every tick to correctly position, color, etc. each wall piece while the player remains engaged with wall planning.
  9. The player, after finding a valid set of locations for building all pieces of the wall they are planning, confirms their intent to construct the wall (as of the writing of this documentation, by clicking the left mouse button).
  10. The system begins wall construction, moving any units out of the way of constructing buildings. All ABFMEBuildingCursors are also destroyed at this time. See ABFMEPlayerController::BeginWallConstruction
  11. The system spawns in all wall pieces simultaneously. Construction of wall hubs begins "instantly" (after a 0.01 second delay). Construction of each wall segment is set to begin after a calculated delay, based on how far that segment is from the origin hub. Segments further away start construction later than closer segments. See ABFMEPlayerController::BeginWallConstruction and ABFMEPlayerController::ServerBeginWallConstruction
  12. Wall piece construction completes.

Some further considerations:

  • BP_Building_Cursor and ARTSBuildingCursor were updated to add in colors and controls for more building cursor states than just "valid" and "invalid". It now has the capability to handle the "other nearby buildings are invalid", "you don't have enough resources", and "I'm too far away from a fortress" states, along with a new color for each. As of the writing of this documentation, the colors are yellow, green, and blue, respectively. Recall that valid buildings are grey, and invalid buildings are red.
  • ARTSBuilding and several adjacent classes (e.g. URTSConstructionSiteComponent) have been updated to accommodate several necessary changes for the wall system/implementation, or have been updated merely to better conform to coding syntax standards (sometimes both).

Limitations

The limitations of the current implementation are listed in the State of development section, at least as far as functional limitations go. If a further examination of limitations is required, please notify someone in the Who's worked on it section, below, to update this section and specify what you would like details on.

  1. Building cursor spawning and positioning are currently separate steps, as you will note in the Architecture section, above. As such, wall pieces are, at present, spawned inside the origin hub, and then near-instantaneously teleported to their proper positions. As such, if the spawned wall pieces' meshes are larger than the origin hub's mesh, the player may see odd behavior, as meshes flicker into and out of existence while they briefly reside inside the origin hub. This may be especially concerning for double-length wall segments, and on machines with low performance that cannot maintain high tick rates.
  2. When spawned, all wall hubs are built with a 0.01 second delay between when construction desire is confirmed by the player, and when the hubs are actually spawned. As such, something could happen in the space where a wall hub will be built in that short time before it is built which would normally not be permissible. This could be especially concerning if a player uses macros or external programs to automate certain game functions, potentially permitting them to overlap multiple buildings into the same space in the game. The implementation is like this right now because it keeps the implementation of spawning for wall segments and wall hubs the same (wall segments must be built with a delay).

Known issues

Known issues with the current implementation are listed in the State of development section. If a further enumeration of known issues is required, please feel free to perform a QA pass on the system, testing out the user stories listed above and examining edge cases. A record of them can be kept here, as well as in the issue tracker (preference goes toward the issue tracker).

  1. When you first boot up Unreal Engine, and try to build a wall, it may fail. It won't crash the editor, but it'll simply seem like you didn't click on anything at all. If you check the logs, you should see that a bunch of errors about "missing segment config" are spamming the log. As a workaround, you can stop the game and open the wall hub's entity configuration file. Inside, reset the value of Spawnable Wall Segment Config to be empty, and then set it back to the same value it was just at. Save the asset and then play the game again. From here onward, that error shouldn't appear anymore until you close and reopen the UE editor. Ultimate resolution/root cause of this issue is presently unknown.