Spawner Plugin | Solarnaut Studios

Plugin Overview

v 1.0

The Solarnaut Spawner plugin offers developers a robust, reliable implementation for spawning gameplay relevant objects at runtime.

At the core is the Subsystem, which manages all of the Spawners. Spawners are defined by their Definition Table, Conditions, Triggers, LocationProviders, and Contexts. There is also built-in handling for Telegraphing spawns.

Please note that comments found in the source code contain more detail and should be considered correct anywhere it may conflict with this documentation.

Subsystem

The Spawner Subsystem (USolSpawnerSubsystem) knows about all spawners and all spawned actors in the world. The Subsystem has a queue for spawners waiting to spawn actors, maintains maps of all relevant information, sends actor death notifications, and broadcasts gameplay requests for spawning to all relevant spawners (via BroadcastTriggerPayload).

The simplest payload to broadcast is just a GameplayTag, and the simplest thing for a spawner to do is see if it wants to respond to that Tag or not (using its triggers). However, the system is open-ended, using USolCustomPayload as a way to pass any arbitrary data around.

Spawners

ASolSpawnerBase is the concrete base class for all spawners, which can be Blueprinted. It has a set of features that should be useful in many situations, but new native classes can also extend or override core functionality when necessary.

Basic Features

MinSpawnCount, MaxSpawnCount: GetNumToSpawn uses FMath::RandRange to pick a number with these values to decide how many actors to spawn.
MaxConcurrentSpawns: optional maximum number of living spawned actors allowed.
MinCooldownSeconds, MaxCooldownSeconds: after firing, the spawner will cooldown for a random amount as determined by GetCooldownSeconds.
SpawnDefinitionTable is a DataTable reference that describes all possible actors the spawner might try to spawn. This defines WHAT gets spawn.
SpawnConditions act as a filter on the SpawnDefinitionTable, meaning multiple spawners can share the same table but effectively use different parts of it.
SpawnTriggers are components added to the spawner that determine if it will be activated. These describe WHY or WHEN to spawn.
SpawnLocationProviders are components added to the spawner to determine WHERE actors will spawn.
SpawnContexts describe HOW to modify or configure the spawned actors. These can also be defined on triggers, and at runtime they can be sent in payloads.
TelegraphActorClass optionally specifies an actor to spawn as the telegraph. When a telegraph is used, the real actor won't spawn until it is over.
bSpawnerArmed starts as true by default (can be changed per spawner). BlueprintCallable ArmSpawner and DisarmSpawner toggle this state. Triggers typically ignore everything while the spawner is disarmed. Spawner cooldowns work by temporarily disarming it.

Spawn Telegraphs

Any Actor class or Blueprint can implement SolSpawnTelegraphInterface, which consists of one function: SetTelegraphDuration(float InSeconds). The spawner can set its own class and duration, but Spawn Definitions can provide their own. The TelegraphOverride field specifies how to choose the correct telegraph actor and time. The bOneTelegraph field enforces only a single telegraph's appearance (at the location of the first spawned actor), but its delay will apply to the entire group of actors spawned.

Spawn Triggers

USolSpawnTrigger is the abstract base class for all triggers, which can be Blueprinted. Initialized in their spawner’s BeginPlay, they have two main ways of activating. The first is DoesPayloadMatch, called from the Subsystem’s BroadcastTriggerPayload. This is the most flexible way to send events to triggers, and each trigger can determine if they care to respond to it or not. If they want to respond, they activate using FireTrigger. The other main activation method is calling FireTrigger directly, but it is recommended to broadcast through the Subsystem whenever possible.

Triggers are components, so must be added via the spawner’s component list.

Included Triggers

Begin Play — Fires once on the tick after BeginPlay.
Timer — Starts a looping timer with the specified RepeatInterval and StartDelay and fires each time.
Simple Tag — Has a RequiredTag (a GameplayTag that uses MatchesTagExact) and a TagQuery. These must be unset or match against a payload’s TriggerTag to fire.
Accumulated Tags — Accumulates matching tags seen in DoesPayloadMatch until it reaches its FireNum. If FireNum is set to 0, the tags will instead need to match a FireTriggerQuery.
OverlapSphere & OverlapBox — Use a SphereComponent or BoxComponent to define a collision area that can trigger when another actor overlaps it. There is an Actor class filter to match only specific types, as well as the BlueprintNativeEvent RespondToActor for more advanced custom filtering.

FireTrigger always calls CanFireTrigger first to ensure the trigger hasn’t hit its MaxTriggerCount and that its Spawner is Armed. The provided trigger classes also gate DoesPayloadMatch with CanFireTrigger so that they only count while “active”.

Triggers may continue tracking while the spawner is disarmed, then fire immediately once it is re-armed (if it wants to).

Spawn Location Providers

USolSpawnLocationProvider is the abstract base class for all location providers, which can be Blueprinted. Each provider implements GetSpawnTransforms (in C++ or Blueprint). Points returned by the provider can be adjusted to find a suitable ground location automatically (with configurable options for raycasting and/or navmesh projection).

Location providers are components, so must be added to a spawner’s component list.

Included Location Providers

NavMesh — Has a SphereComponent to define the origin and radius for calling GetRandomPointInNavigableRadius.
Box — Has a BoxComponent it uses to return points from RandPointInBox.
Spline — Has a SplineComponent and uses its points as the locations.
Cluster — Has a list of transforms that can be explicitly defined in the editor.

Spawn Definitions

FSolSpawnDefinition specifies what will be spawned: an AActor derived class, GameplayTags to identify the definition, a Weight to use when picking multiple definitions, and an optional Telegraph Actor class. This struct is used to create DataTable assets. There can be one table per spawner, or a table can be shared across as many spawners as desired.

Spawn Conditions

USolSpawnCondition is a simple object that can filter a Spawn Definition’s Actor class or GameplayTags. Spawners have their own list of conditions. Triggers can also define their own list of conditions, so that a spawner with multiple triggers might only be able to spawn a particular actor from one of those triggers. All conditions must pass for a definition to be eligible.

Spawn Contexts

USolSpawnContext is the abstract base class for contexts. A spawn context typically modifies a spawned actor in some way, though it isn’t required to. Contexts can be configured on Spawners and Triggers, and sent in payloads.

Included Contexts

SetLifeSpan — Calls SetLifeSpan with a random value between a set Min and Max.
SetScale3D — Calls SetActorScale3D with a random value between a set Min and Max.
PlaySound — Calls PlaySoundAtLocation to play the sound at the spawned actor’s location.
ApplyMaterial — Finds all SkeletalMesh and StaticMesh components on the actor and calls SetMaterial on them.
BroadcastPayload — Calls the Subsystem’s broadcast with a new payload, trigger tag, and contexts.

First Implementation Steps

Create a new DataTable using SolSpawnDefinition.
Configure it with at least one row, e.g. set the ActorClass to a character BP.
Place a Solarnaut Spawner in the level.
Set its SpawnDefinitionTable to the one created in step 1.
Add a Begin Play Trigger to the spawner.
Press Play!
One of the actors in the DataTable will spawn at the spawner’s location.

Console Commands

Sol.Spawner.List — displays the names of all registered spawners in the log.
Sol.Spawner.ShowSpawner <name> — displays the information (implemented in GetDebugString) of any spawner whose name matches in the log.
Sol.Spawner.BroadcastTag <tag> — broadcasts the specified tag through the Subsystem.
Sol.Spawner.DestroyActors <name> — destroys all actors currently spawned by the specified spawner and reports the count.

Play-in-Editor Testing

While running in PIE, the Details panel for a Spawner will include a “Force Spawn (Bypass Triggers)” button as well as a “Notify Triggered by [name]” button for each trigger on it.
“Force Spawn” calls PerformSpawnFromPayload with an empty payload. No triggers are used, and the spawner's Armed state is ignored. However, spawning still adheres to the normal rules (like not spawning beyond MaxConcurrentSpawns).
“Notify Triggered by” tells the spawner that trigger has activated it with an otherwise empty payload, and the spawner's Armed state is ignored. This ignores any of the trigger's usual checks (like calling CanFireTrigger).