Procedural Buildings Tool

Note

This is a project from my personal portfolio. Check it out here

---

Procedural buildings generator is an UE editor tool for generation of panel-type buildings. It utilizes cpp, blueprints, and PCG to give designers a highly configurable building constructor. I took up the project to explore Unreal’s PCG (it’s honestly what UE was missing badly, and it is already for sure a must-know tool for any UE dev) and programming editor utilities like custom asset types and custom component visualizers (it turned out to be more convoluted than I would have liked but fun nevertheless). The tool is organized roughly in three layers:

1. the c++ layer

   This one contains lower-level logic that would be tedious to implement in blueprints or PCG: the custom building grammar parser and the panel-fitting algo. It also defines some base actor classes. Custom component visualizers and custom asset types also belong in this layer

2. the blueprint layer

   Mainly contains the UPCGBlueprint implementations that serve as custom nodes in PCG graphs, for example a PCG blueprint that generates the grid of building panel points or a blueprint that calculates satellite dish occlusion per panel

3. the PCG layer

   This is where designers make use of the first two layers provided by the tool to create the actual buildings

Custom grammar and its parser

The grammar

The grammar is best explained with an example:

{0 2 1 2 0}+ | 5 5 | {3}+ [0: 1 > 4 0 > 3]

What this grammar implies is as follows:

• {0 2 1 2 0}+ means “The wall on the front (the first rule is always for the front side) of the building is made from panels with indices 0, 2, 1, 2, and 0, in this order, and the whole group is repeated as many times as needed to match the building width specified by the level designer”
• the pipe separator | starts a rule for the next building side. Logically you are allowed to have only three of those (four sides in a typical building). The order of sides is front -> left -> back -> right
• 5 5 means “The left-side wall of the building consists of two panels, both with index 5”
• the next | separator means we are defining the rule for the back side of the building now
• as you might have guessed, {3}+ means “The back wall consists only of panels of type 3, repeated as many times as necessary to match the requested building width”
• [0: 1 > 4 0 > 3] is an optional override rule. 0: means the rule must be applied to the ground floor (you can define the rule for any floor you want). 1 > 4 implies that panel with index 1 will be replaced by panel with index 4 in the first floor. The same goes for 0 > 3. Why? Because you might want to prevent balconies and such from spawning on the ground floor and replace them with normal windows or special panels instead. Also you can create custom looks for certain floors

You probably noticed that we defined the panel composition for the front, left, and back, but not the right side of the building. That’s correct: you can omit building sides - and in this case the rules for the missing sides will be extended using the existing defined rules. Let’s say you define your grammar as 5 5 - in this case the algo will read 5 5 | 5 5 | 5 5 | 5 5. You can also define only the front and the left of the building as 1 2 | 3 3, and in this case the algo will be smart enough to understand it as 1 2 | 3 3 | 1 2 | 3 3

Panel definitions

At this point, you’re probably asking yourself: we defined the panel grammar using numeric indices, but how does the algo know the actual panel dimensions, appearance etc.? For that purpose, you define panel layout assets which store information about the panel dimensions, whether it has a window and where exactly, and you store them in an array on your panel building actor. The panel building actor will then link the indices in the grammar to the indices of the panel layout assets in the array. This information is then passed to PCG points as attributes. As for the looks, they are defined by the meshes you spawn in your PCG graph.

In the screenshot below, you can see what attributes are defined for a panel layout:

• the panel’s id can later be used in the PCG graph to spawn meshes or set materials
• panel dimensions define offsets between the points and floors
• panel dimensions and window dimensions information can be used to spawn objects on the panel surface

---

The parser

I decided to not use any existing grammar parsing libraries or tools and write my own tiny parser instead. My grammar DSL is a tiny one, and I decided to go with my own thing to keep it lightweight and maintainable. The parser code is fairly straightforward and you’re welcome to inspect it in the PBGrammar.h

Panel-fitting algo

Let’s say you defined your panel layouts, for panels 3 and 5 meters wide, 3 meters tall. You also wrote a grammar describing the composition of the building. The algo is now ready to take this information and generate the panel points for the entire building, given you supply the desired width and depth of the building. This is exactly what FitPanelsToBoundingBox does. You tell the algo about the panel dimensions, the building’s composition, your target building width, depth, and height, and the algo gives you the points with correct transforms and additional attributes which you then can use to spawn the panel meshes and other objects in your PCG graph.

As you can see, the entire panel-fitting algo and parser logic is hidden away from designers and follows the Unreal’s philosophy of implementing game mechanics and algos in C++ and exposing only the actual game-design tools and facilities via blueprint nodes.

Panel building actor

The panel building actor (see this base class) is an actor that hosts the building’s PCG graph. The PCG graph will read several properties from the actor, including the building grammar, basement and attic height, etc. Also, the actor stores several read-only building properties, such as the building’s dimensions, the number of floors, etc which are updated after the PCG graph regenerates in the construction script.

PCG blueprints

This section describes the three custom nodes provided by the tool. They can be executed with the Execute Blueprint node in the PCG graph.

Generate panel building

Provides a single drop-in PCG graph node that generates the building points. As you can see in the illustration below, it creates the points with correct transforms and offsets and adds a number of point attributes, such as panel dimensions, window location and so on. The resulting point data and the attributes can be used to spawn panel meshes etc.

---

Single point on panel surface

This node samples a single point on the panel surface, that is, avoiding the window. This can be used to spawn objects like condenser units, satellite dishes, and virtually anything else on the panel surface. In the image below on the left, you can see a number of points generated on panel surfaces for a random selection of panels.

---

Satellite visibility for points

Calculates whether satellites (at a given position in the sky) are visible from a given point on the panel surface or are occluded by the building. For example, northern building wall will not have any satellite dishes if satellites are geographically in the southern sky. Geographical position of the satellites is governed by a helper actor.

---

Combining the tools in a PCG graph

The PCG nodes provided by the tool and described above are used by level artists in a PCG graph to produce a building with a specific look. For example, in the sample building included with the project, I attempted to reproduce the soviet-type ‘Khrushovka’ panel building. I created some panel and balcony meshes and their materials, as well as condenser boxes and satellite dishes, and used the ‘Generate panel building’ and other nodes to spawn the meshes. I additionally spawned several entrance actors at the ground floor.

As you can see in the screenshot below, it is a relatively simple PCG graph. Most of the nodes spawn meshes and set materials, with somewhat more complexity in the part where satellite dishes and condenser units are generated.

---

Other whatnots

The building’s sizebox

---

I decided to introduce a custom actor component for the building’s bounding box. For one, I wanted to learn Unreal’s code around custom components. Also, I really wanted fancy resize controls on the building instead of the existing box component. As you can see in the screenshot above, the white square controls allow you extend the box dimensions by changing the control’s location in the viewport.

Multiple objects per panel

---

A single panel can host multiple objects. There is no dedicated PCG node to achieve that - I have used `Single point on panel surface’ and then took a difference on the resulting points to exclude overlaps. As you can see in the screenshot above, a satellite dish and a condenser unit box happily coexist on a single panel.

Dynamic roof meshes

---

The building roofs in my example building are procedural meshes generated with PCG’s Geometry Script support. Of course, you can spawn further objects on the roof or generate more complex procedural roofs but I decided against further complication of this project.

Geographic satellite dish orientation

For a satellite dish to work, it must have a clear view of the sky where satellites are positioned. Someone might say it’s an overkill but I believe such details are crucial for realism and immersion. In my example building, all the satellite dishes are rotated towards a fixed position in the sky and are not generated if there’s no clear view of the sky (see Satellite visibility for points node)

---

Afterword

For desigining the grammar and writing its parser, implementing the panel-fitting algo and writing cpp tests, creating the PCG blueprints and the PCG graphs, and producing all the meshes and designing all the materials in UE, I spent a little over three months, working about 5 hours a day, with some days skipped where I had to take a break or deal with my chores. PCG turned out to be a fairly mature and powerful system, and definitely very fun to work with. I am really excited to see how far UE PCG will evolve in the future.