PositionEventsModule

A module for Blish-HUD which provides functionality to efficiently bundle position checking.

After the module loaded, you register an area for a specific map. When the player enters or leaves this area, a provided callback will be invoked and inform your module of this interaction.

Types of areas (Bounding Objects)

BoundingObjectBox

An axis aligned Bounding Box (Cuboid).

BoundingObjectBox(Vector3 min, Vector3 max);

Caution

Make sure, that min < max for every axis. As a safeguard, you can use BoundingObjectBox(BoundingBox.CreateFromPoints(new Vector3[] { min, max }));

BoundingObjectSphere

A sphere.

BoundingObjectSphere(Vector3 center, float radius);

BoundingObjectPrism

An axis aligned prism. Think of a cylinder, just less round. Aligned with the z-Axis (top) by default.

BoundingObjectPrism(float top, float bottom, IEnumerable<Vector2> polygon, Axis3 alignment = Axis3.Z);

Boolean Operations

The Position Events Package implements capabilities to add (Union), subtract (Difference) and intersect (Intersection) Bounding Objects from/with each other.

There are multiple ways to access these boolean operations.

1. Directly call the constructor of the Bounding Object Groups (not recommended). See PositionEvents.Area for implementation.

BoundingObjectGroupUnion(IEnumerable<IBoundingObject> content);
BoundingObjectGroupDifference(IBoundingObject positive, IEnumerable<IBoundingObject> negatives);
BoundingObjectGroupIntersection(IEnumerable<IBoundingObject> content);

2. Using PositionEvents.IBoundingObjectExtensions

// assumes boundingObject and other to be IBoundingObjects (any of the ones
// mentioned above, including the boolean operations)
boundingObject = boundingObject.Union(other);
boundingObject = boundingObject.Difference(other);
boundingObject = boundingObject.Intersection(other);

3. Using PositionEvents.Area.BoundingObjectBuilder

// assumes oneBoundingObject, anotherBoundingObject, differentBoundingObject and
// anotherDifferentBoundingObject to be IBoundingObjects (any of the ones
// mentioned above, including the boolean operations)
BoundingObjectBuilder builder = new BoundingObjectBuilder()
    .Add(oneBoundingObject) // base
    .Add(anotherBoundingObject) // Union
    .Subtract(differentBoundingObject) // Difference
    .Intersect(anotherDifferentBoundingObject); // Intersection

IBoundingObject boundingObject = builder.Build();

Implement your own

You need a different geometrical shape for your area? Implement the IBoundingObject interface and make your own.

Using the Position Events Module with your Blish-HUD module

Setup

1. Add the PositionEvents Package as a reference to your module. It is available as a NuGet package.
2. Add the Position Events Module .dll as a reference to your module.
3. Add the Position Events Module as a dependency to your module manifest.

dependencies":{
    "bh.blishhud": "^1.0.0",
    "Flyga.PositionEvents": "^1.0.0"
}

Tip

Make sure that the references of the PositionEvents Package and the Position Events Module have Copy Local set to False in the properties of the reference. You don't need to ship them with your module, since they will already be present, because of your modules dependence on the Position Events Module.

Usage inside your module

1. Retrieve a reference to the Position Events Context.

_positionEventsContext = GameService.Contexts.GetContext<PositionEventsContext>();

Warning

Make sure to avoid module load order conflicts. For reference see the Position Events Example.

2. Register your desired areas with the Position Events Module.

// Assumes you retrieved a reference to the Position Events Context before
// calling this
IBoundingObject area = new BoundingObjectBox(new Vector3(0), new Vector3(10, 20, 30));
_positionEventsContext.RegisterArea(this, 15, area, OnAreaJoinedOrLeft);

3. Use the output with a callback action

private void OnAreaJoinedOrLeft(PositionData positionData, bool isInside)
{
    if (isInside)
    {
        Logger.Info("Area joined."); // or do something useful
        return;
    }
    Logger.Info("Area left."); // or do something useful
}

Tip

For an example implementation, take a look at Position Events Example.

Debugging your areas

As a rudimentary way to debug your areas, this module provides the option to display your area as an IEntity in the world.

To make use of this feature, simply set the debug parameter to true, when registering the area.

_positionEventsContext.RegisterArea(this, 15, area, OnAreaJoinedOrLeft, debug: true);

Warning

You should never ship your module with the debug functionality enabled.