Building Entrance Connections

When placing a building on a terrain (or other ground surface), there are two things that need to be performed.
Firstly, internal floor surfaces need to be connected to the external ground (so that you can walk in and out of doors, and so on).
Secondly, the outside walls of the building need to obstruct movement on that external ground.
To achieve this the building connections feature is based on defining a building 'external shape' and then marking where 'portals' connect out of an internal floor through the external shape onto the ground outside.
External shape, internal floor and portals are modelled together in a single piece referred to as a 'building internal mesh' that can then be moved around at will with content processing taking care of connection to external floor.

A basic example

Consider the following (very basic) building:

Here a single door enters through some walls into a small internal floor.

The following images show how this would be represented in the source geometry for content processing.
When viewed from above, you can see how the extents of the external shape correspond with the shape of the outsides of the building walls.

The external shape for the building, drawn here in black, must be marked with the PE_FaceAttribute_MarksExternalShape face attribute.

The portal faces, drawn here in blue, must be exactly vertical, and are marked with the PE_FaceAttribute_MarksPortal face attribute.
(Not visible in the above view.)

The remaining geometry, drawn here in white, represents the internal floor of the building.
This internal floor may be complex, and can overlap itself to form multiple floors of a building, overlap back over the external shape extents in the case of something like a balcony, and even cross underneath the terrain to form extensive dungeon complexes.

The portal shares two vertices with the building internal floor, and two other vertices with the external shape.
The horizontal coordinates of all vertices on each side of the portal must be exactly identical. Apart from this the vertical arrangement of the portal faces is flexible. Portal faces may extend both above and below the internal mesh geometry if desired.

The portal faces should intersect the ground on which the building is placed. This is how the content processing determines which part of the external geometry to connect the internal floor.
After resolving external geometry for each portal, the content processing makes a cut in the external geometry, connects the internal floor to that external geometry at this cut and then cuts the external shape out from behind this connection.

The following images show the example building placed against a flat piece of terrain, and the resulting mesh generated by the content processing.

Constraints

Portals must each intersect one single piece of external geometry. (Otherwise an error will be emitted for the portal, and then the portal skipped.)

The cut made by a portal through target geometry must be completely contained by that target geometry.
In other words, portals must not be intersected by external edges of that target geometry.

Invalid portal placement - the portal is intersected by an external edge of the target geometry.

Portals and external shapes must not cut through other portals.

Terrain portals

Release 5.01 adds support for 'terrain portals'.
These are marked by supplying PE_FaceAttribute_MarksTerrainPortal (instead of PE_FaceAttribute_MarksPortal).

The vertical extents of terrain portals are ignored. Instead, these are connected directly to the terrain (defined as the set of faces with section ID set to 0).

This is useful in situations where terrain callbacks are being used, with height detail stripped out for terrain areas, and where it is inconvenient to make anchors intersect the resulting simplified mesh.

'Adjacent portals'

Starting with release 4_64 'adjacent portals' are now permitted.
This enables features such as raised platforms at building entrances to be represented.

A building internal mesh with adjacent portals.

The above mesh placed against a flat terrain.

The result of content processing.

Using 'building internal meshes' to add height detail

Adjacent portals may even connect all the way around the edge of a building internal floor.
This enables 'building internal meshes' to be used for objects that simply serve to add height detail without blocking movement.

A 'building internal mesh' for a pedestal.
Note that an external shape has been modelled underneath the pedestal but is not visible.

The above mesh placed against a flat terrain.

The result of content processing.

Using just portal + external shape for generalised 'cookie cutter' functionality

Starting from release 5.19, it is possible to place portals with external shape geometry but no internal floor, which can be useful in some situations where buildings have no connections to internal ground, but also as a kind of generalised cookie cutter mechanism for cutting arbitrary non-convex obstructed regions out of the base ground mesh.

Reducing the complexity of the resulting mesh

When using automatic connection at building connections, it is a good idea to also turn on the Mesh Optimisation content processing option, to avoid a lot of nearly inline external vertices potentially being created by the boolean subtraction applied for building external shapes.

Example geometry

The source content snapshot 'SDKRoot/resource/content/content_automation_example.sourceContent.tok' can be imported into content applications with appropriate PathEngine exporter plugin to set up a scene that demonstrates the building entrance connection automation functionality.
(See this page, in the content creators guide, for details about this and other example geometry.)