Anchors and Pinned Shapes

'Anchor' refers to PathEngine's content-side position representation, designed to uniquely identify a position on the surface of a mesh, whilst remaining valid across changes to that mesh as far as possible.
(See Representing Positions on the Ground, in the overview.)

'Pinned shape' refers to the content-side representation for shapes placed on the ground.
These are essentially two dimensional shapes attached to the surface of a ground mesh, but which can effectively be thought of defining cylindrical bounding shapes for more complex obstacles. (See Obstacles, in the overview.)

Anchors are used by content applications to identify which part of a ground mesh each pinned shape is attached to, and to place named positions on a ground mesh such as a player start position, or other scripted position information.

Anchors define both position and orientation.
For anchors which are used just to pin shapes, the orientation is ignored, but for something like a player start position, the orientation can be important.

Anchor representations

The general form of anchor representation within content applications is as a kind of inverted 'L'.
A vertical line identifies both the horizontal position of an anchor, and also a vertical range for intersection with the ground.
For standard anchors, the intersection of this vertical line with the ground mesh defines the position represented by the anchor.
The (optional) horizontal crosspiece then defines the orientation of the anchor.

The exact representation for anchors can vary between content applications.
Anchor naming, and anchor placement within the scene hierarchy can also be important.
Refer to content-platform specific documentation for more details.

Terrain anchors

Content applications will provide a way to mark anchors as being 'terrain anchors'.
The vertical range of these anchors is then ignored, and the anchors instead resolve to a position on the terrain, where terrain is defined as the set of faces marked with a 'sectionID' value of zero.
(Refer to Stripping Height Detail out of Terrain Areas for details about section IDs and terrain.)

The main purpose of terrain anchors is to facilitate anchor resolution against meshes with terrain detail stripped out.
These can also be useful when you know that certain obstacles will only be placed on the terrain, for example in the case of obstacles associated the external geometry of a building that will only ever be placed on the terrain.

Anchor ID, and anonymous anchors

By default, anchors are assigned an ID taken from the name of the object representing the anchor.
After resolution, the anchor position is then stored with the ground mesh associated with this ID, which must therefore be unique.
For anchors whose only purpose is to attach obstacle shapes to a mesh, this is not desirable. To avoid adding unnecesary data to ground meshes, and to avoid the requirement for unique IDs, content applications also support 'anonymous anchors'.
These are anchors which can be used to pin shapes, but are not then stored with the resulting ground mesh.

Pinned shape representations

Pinned shapes are represented within content applications as linear, polygonal shapes.
Only the horizontal components of the shape vertices are relevant.
Refer to content-platform specific documentation for details about the exact representation within each content application.
This platform specific documentation will also detail issues relating to naming pinned shapes, and how pinned shapes are associated with anchors.

Pinned shapes must satisfy PathEngine's constraints on placed shapes. For convenience, however, note that the order of vertices in pinned shapes does not matter. In other words, pinned shape vertices may go either clockwise or anticlockwise around their origin.

The anchor for each pinned shape provides an origin, and the constraint on shape coordinates relates to the coordinates of the shape vertices relative to this origin. For convenience, however, if a shape exceeds the basic range constraint, the content exporters will automatically use the larger, 'large static obstacle', representation internally, meaning that, in most cases, shape range constraints should not be an issue.

Also, starting from release 5.19, PathEngine will try to resolve a suitable root position in cases where the supplied anchor does not fall inside the shape polygon.
This means that, in many cases, (as long as local mesh geometry is straightforward), the constraint that anchors must full inside any pinned shapes can be ignored.

Multiple shapes may be pinned to the mesh by a single anchor (from release 5.19, it should be possible to place clusters of shapes around a single anchor in many situations).

Types of obstacles

Pinned shapes may be marked as either 'base obstacles' or 'named obstacles'.

Base obstacles are immutable scenery obstacles.
These will be burnt in to the mesh and will automatically included in preprocess for the fastest possible pathfinding.

Named obstacles are obstacles that will be stored out with the ground mesh, but will then have no effect unless they are explicitly retrieved by name (or by iteration), by the application run-time.
Named obstacles are assigned an ID taken from object name, and these named obstacle IDs must be unique.

When applied, shapes will obstruct movement as described in The PathEngine Movement Model. It is ok for shapes to overlap the edge of the mesh.

Anchors and pinned shapes in a two-stage content processes

Anchors and pinned shapes can be included in 'content chunk' export, for a two-stage content process.
These will then be resolved when the content chunks are later combined into the run-time ground mesh format, and the resulting positions and obstacle shapes added to the resulting mesh.