Blueprint API

Some functions of the plugin are be exposed through blueprint but the blueprint API is fairly limited. This is due to blueprint support in the Mass Entity framework. The blueprint API is curently limited to spawning and despawning and can be accessed through the spawner actor.

Spawner API

Spawner Blueprint API Preview

Spawning Groups

The following functions will create a new boid group and spawn all configured boid subsets (spawn configurations).

Function	Details
Spawn Group	Schedules a spawn request of the group for which the spawner is configured.
Spawn Group with Completion	Schedules a spawn request of the group for which the spawner is configured, with completion callback. Parameters Completion Callback: Event called upon spawn completion. The event returns the Id of the spawned group as well as the handles of all created boids.
Spawn Group Immediate	Spawns the group for which the spawner is configured immediately. Boids are created upon function return but are not fully initialized yet. Users should preferably use the non-immediate version. Return value Group ID: ID of the group that was spawned or -1 if it failed. Spawned Boids: List of boid handles that were spawned
Respawn Group	Schedules a respawn request for a the contents of a group associated with this spawner. This function does not despawn the group, it adds an extra batch of boids to it.
Respawn Group Immediate	Respawn all the contents of the spawner in a group it is associated with immediately. This function does not despawn the group, it adds an extra batch of boids to it. Boids are created upon function return but are not fully initialized yet. Users should preferably use the non-immediate version. Return value Spawned Boids: List of boid handles that were spawned.
Respawn Group with Completion	Schedules a respawn request for a the contents of a group associated with this spawner, with completion callback. This function does not despawn the group, it adds an extra batch of boids to it. Parameters Completion Callback: Event called upon spawn completion. The event returns the Id of the reused group as well as the handles of all created boids.

Spawning Subsets

A subset is a subgroup as defined in the ‘Spawn configurations’ on the spawner. Using the following Blueprint functions, you can spawn subsets individually within a previously created group.

Function	Details
Spawn Subset	Schedules a spawn request for a subset of the group as configured in the spawner. Parameters Group ID: Id of the group in which to spawn, as returned by the ‘Spawn Group’ function variants. Subset Index: Index of the subset configuration to spawn. This index matches the ‘Spawn configs’ list order.
Spawn Subset Immediate	Spawns a subset of the group as configured in the spawner immediately. Boids are created upon function return but are not fully initialized yet. Users should preferably use the non-immediate version. Parameters Group ID: Id of the group in which to spawn, as returned by the ‘Spawn Group’ function variants. Subset Index: Index of the subset configuration to spawn. This index matches the ‘Spawn configs’ list order. Return value Spawned Boids: List of boid handles that were spawned.
Spawn Subset with Completion	Schedules a spawn request for a subset of the group as configured in the spawner. Parameters Group ID: Id of the group in which to spawn, as returned by the ‘Spawn Group’ function variants. Subset Index: Index of the subset configuration to spawn. This index matches the ‘Spawn configs’ list order. Completion Callback: Event called upon spawn completion. The event returns the entity handles of all created boids.
Spawn Subset with Count	Schedules a spawn request for a subset of the group as configured in the spawner, but with the provided number of entities. Parameters Group ID: Id of the group in which to spawn, as returned by the ‘Spawn Group’ function variants. Subset Index: Index of the subset configuration to spawn. This index matches the ‘Spawn configs’ list order. Count: Number of boids to spawn.
Spawn Subset with Count Immediate	Spawns a subset of the group as configured in the spawner immediately. Boids are created upon function return but are not fully initialized yet. Users should preferably use the non-immediate version. Parameters Group ID: Id of the group in which to spawn, as returned by the ‘Spawn Group’ function variants. Subset Index: Index of the subset configuration to spawn. This index matches the ‘Spawn configs’ list order. Count: Number of boids to spawn. Return value Spawned Boids: List of boid handles that were spawned.
Spawn Subset with Count and Completion	Schedules a spawn request for a subset of the group as configured in the spawner. Parameters Group ID: Id of the group in which to spawn, as returned by the ‘Spawn Group’ function variants. Subset Index: Index of the subset configuration to spawn. This index matches the ‘Spawn configs’ list order. Count: Number of boids to spawn. Completion Callback: Event called upon spawn completion. The event returns the entity handles of all created boids.

Despawning Groups

You can despawn boids previously created by a spawner using one of the following functions.

Function	Details
Despawn Group	Schedules a despawn request for the group with the provided ID. Parameters Group ID: Id of the group to despawn, as returned by the ‘Spawn Group’ variants.
Despawn Group Immediate	Despawn the group with the provided ID immediately. This is an unsafe call to do on the game thread as there might be background tasks currently running. Users should preferably use the non-immediate version. Parameters Group ID: Id of the group to despawn, as returned by the ‘Spawn Group’ variants.
Despawn All	Schedules a despawn request for the all groups that were instanciated with this spawner.
Despawn All Immediate	Despawn all groups that were instanciated with this spawner immediately. This is an unsafe call to do on the game thread as there might be background tasks currently running. Users should preferably use the non-immediate version.

MegaBoids Subsystem API

The MegaBoids Subsystem API allows finer grained control of boids lifetime management as well as their group. You do not need a spawner to use the following functions but you will be responsible for manually spawning/despawning of created entities whereas Spawners will despawn it’s associated groups when unloaded as regular actors.

More Blueprint functions will be provided in the future for finer control over boids. We are currently planning to add spawning and despawning without a spawner reference, optimized collision tracing, etc. in order to support more complex gameplay scenarios.

Function	Details
Get Boid Transform	Get the current transform for the provided boid. Return value Transform: The boid’s transform.
Get Boid Velocity	Get the current velocity for the provided boid. Return value Velocity: The boid’s velocity vector.
Get Boid Transform and Velocity	Get the current transform and velocity for the provided boid. Return value Transform: The boid’s transform. Velocity: The boid’s velocity vector.
Get Boid Hit result	Gets the boid that was hit by a trace hit result. Parameters Trace Hit Result: Hit result from a trace for which we want to determine if a boid was hit. Return value Boid Hit Result: Boid hit result with the handle to the boid found.
Despawn Boid	Schedules a task to despawn the provided boid. Parameters Handle: Handle to the boid to despawn.
Despawn Boids	Schedules a task to despawn the provided list of boids. Parameters Handles: List of handles to the boids to despawn.

Extending the plugin & Mass Entity blueprint support

MegaBoids is a plugin based on the Mass Entity framework. Unfortunately, Mass Entity is currently not compatible with Unreal Blueprints and it seems unlikely it ever will given some core design choices from Epic when developing Mass Entity. There is currently no way to create or access data types from blueprint, since they are built upon a C++ feature called ‘templates’. Therefore, the following plugin extensions must absolutely be added through our C++ API:

Driving subprocessors
Environment subprocessors
Initialization subprocessors
Movement models

This is a good opportunity for you to learn C++. We put a lot of effort into abstracting the concepts of Mass Entity in a digestible manner such that developers can focus on what matters to them; making great games! If all else fails, check out our consulting services.