# API Reference

AfterPrime Systems | AP Event Bus | Version 1.0.0 Module: APEventBusRuntime

# Contents


EAP_EventScope	Delivery scope enum
FAP_EventPayload	Event data struct
UAP_EventBusComponent	Core pub/sub component
UAP_EventBusBlueprintLibrary	Static convenience helpers
AAP_EventBusDemoCharacter	C++ reference implementation
Log Category	Debug output

# EAP_EventScope

Controls how an event is delivered across the network.

Value	Description
`All`	Server fires locally + NetMulticast to all connected clients.
`OwnerOnly`	Server fires locally + Client RPC to the owning connection only. Best for player-specific events when the bus is on a player-owned actor.
`ServerOnly`	Server fires locally only. No replication. Zero client cost.
`LocalOnly`	Fires on the calling machine only. No authority check, no RPC. Zero network cost. Use for UI-only events.

# FAP_EventPayload

Self-contained event data. All fields are optional except EventTag. Passed by value through all publish and RPC paths.

Property	Type	Description
`EventTag`	`FGameplayTag`	Required. Gameplay Tag identifying the event. Must be a registered tag — `PublishEvent` validates and discards if invalid.
`Instigator`	`AActor*`	The actor that triggered the event. May be null.
`Target`	`AActor*`	The target actor of the event. May be null.
`Magnitude`	`float`	General-purpose numeric value. Default: `0.0`.
`ContextTags`	`FGameplayTagContainer`	Additional tags for filtering or metadata.

Multiplayer Actor References

Instigator and Target serialize correctly across RPCs for replicated actors. If the referenced actor is not replicated, the pointer arrives as null on the remote end — this is expected UE5 behavior.

# UAP_EventBusComponent

Type: UActorComponent Display Name: AP_EventBus Category: AP|EventBus

Core pub/sub component. Place on your GameState for a project-wide global bus, or on any individual Actor for a scoped per-actor bus. Each component instance is an independent bus.

Replication Model

All replication is RPC-based — there are no replicated UPROPERTYs on this component. Events are delivered via ServerPublishEvent, MulticastPublishEvent, ClientDeliverEvent, ServerRequestCachedEvents, and ClientReceiveCachedEvent RPCs internally. Do not call these RPCs directly.

# Delegates

# OnEventReceived

Fires for every event dispatched on this bus, regardless of tag. Use for catch-all listening.

Signature: (FGameplayTag EventTag, FAP_EventPayload Payload)

Fires on:

Server — via direct dispatch (ServerOnly, OwnerOnly) or NetMulticast (All)
Client — via NetMulticast (All), Client RPC (OwnerOnly), or late-join cache delivery

# OnListenedEventReceived

Fires only for events whose EventTag matches a tag registered via ListenForEvent.

Signature: (FGameplayTag EventTag, FAP_EventPayload Payload)

Fires on the same paths as OnEventReceived, gated by the local tag filter set. Use alongside OnEventReceived when an actor only cares about a specific subset of bus traffic.

# Publishing

# `PublishEvent`

Any Machine

The only publish function you should call. Handles all routing automatically.

void PublishEvent(FAP_EventPayload Payload, EAP_EventScope Scope = EAP_EventScope::All)

Condition	Action
`Scope == LocalOnly`	Dispatches immediately on calling machine. No authority check.
Called on client, any other scope	Routes to `ServerPublishEvent` RPC — arrives on server, re-enters `PublishEvent` with authority
Server, `Scope == All`	Updates cache if persistent → `MulticastPublishEvent` (server + all clients)
Server, `Scope == OwnerOnly`	Updates cache if persistent → dispatch on server + `ClientDeliverEvent` to owning client
Server, `Scope == ServerOnly`	Updates cache if persistent → dispatch on server only

Validation

If Payload.EventTag is not a valid registered Gameplay Tag, PublishEvent logs a warning and returns without firing.

# Listeners

# `ListenForEvent`

Any Machine

void ListenForEvent(FGameplayTag Tag)

Register a tag filter so OnListenedEventReceived fires when events with this tag are dispatched. Idempotent — calling twice with the same tag is safe. Has no effect on OnEventReceived.

# `StopListeningForEvent`

Any Machine

void StopListeningForEvent(FGameplayTag Tag)

Remove a single tag from the filter set. No-op if the tag was not registered.

# `StopAllListening`

Any Machine

void StopAllListening()

Clear all tag filters. Called automatically in EndPlay — you do not need to call this manually on actor destruction.

# `IsListeningForEvent`

Any Machine BlueprintPure

bool IsListeningForEvent(FGameplayTag Tag) const

Returns true if the specified tag is currently in the filter set.

# Cache

# `RegisterPersistentEvent`

Server Only

void RegisterPersistentEvent(FGameplayTag Tag)

Mark a tag as persistent. After registration, every PublishEvent for this tag stores the payload in the server-side cache. Late-joining clients automatically receive the last cached payload for all persistent tags when their component's BeginPlay fires.

Call in GameState BeginPlay before any events fire.

# `UnregisterPersistentEvent`

Server Only

void UnregisterPersistentEvent(FGameplayTag Tag)

Remove a tag from the persistent set and clear its cached payload. Future publishes for this tag will no longer be cached. Late joiners will not receive this event.

# Query

Server + Client BlueprintPure

Client Cache

Query functions are meaningful on the server. On clients the cache is empty — use OnEventReceived to react to events on clients.

# `WasEventFired`

bool WasEventFired(FGameplayTag Tag) const

Returns true if the tag is in the persistent cache and at least one PublishEvent has fired for it since registration.

# `GetLastPayload`

bool GetLastPayload(FGameplayTag Tag, FAP_EventPayload& OutPayload) const

Retrieve the last cached payload for a persistent event tag.

Returns: true if found and OutPayload is populated. false if the tag is not in the cache.

# `GetAllCachedEventTags`

FGameplayTagContainer GetAllCachedEventTags() const

Returns all tags currently in the persistent cache. Returns an empty container if no persistent events have been fired.

# Lifecycle

Standard UActorComponent overrides — you do not call these directly.

Function	Behavior
`BeginPlay`	If not authority (client), automatically calls `ServerRequestCachedEvents` to receive any cached persistent events from the server.
`EndPlay`	Calls `StopAllListening()` to clean up the tag filter set.

# Internal RPCs

Called internally by PublishEvent. Do not call these directly.

RPC	Direction	Purpose
`ServerPublishEvent`	Client → Server	Routes non-local publish calls from clients to the server
`MulticastPublishEvent`	Server → All	Delivers `All` scope events to server and all clients
`ClientDeliverEvent`	Server → Owning Client	Delivers `OwnerOnly` scope events to the owning connection
`ServerRequestCachedEvents`	Client → Server	Called in `BeginPlay` on clients to request cached persistent events
`ClientReceiveCachedEvent`	Server → Client	Delivers one cached event to a late-joining client

# UAP_EventBusBlueprintLibrary

Static convenience functions. Available in Blueprint under AP|EventBus|Utilities.

# `GetEventBusComponent`

static UAP_EventBusComponent* GetEventBusComponent(AActor* Actor)

Find the UAP_EventBusComponent on any Actor. Returns null if the actor is invalid or has no bus component.

# `GetEventBusFromGameState`

static UAP_EventBusComponent* GetEventBusFromGameState(const UObject* WorldContextObject)

Get the UAP_EventBusComponent from the current world's GameState. The most common accessor when using the recommended global bus pattern.

Returns null if the world, GameState, or component is not found.

Timing

In multiplayer, call this after a short Delay (0.1s) in BeginPlay to ensure the GameState has replicated before access.

# `PublishEventOnBus`

static void PublishEventOnBus(
    AActor* BusOwner,
    FAP_EventPayload Payload,
    EAP_EventScope Scope = EAP_EventScope::All)

Convenience wrapper — finds the bus on BusOwner and calls PublishEvent. No-op if no bus component is found on the actor.

# `MakeEventPayload`

static FAP_EventPayload MakeEventPayload(
    FGameplayTag EventTag,
    AActor* Instigator = nullptr,
    AActor* Target = nullptr,
    float Magnitude = 0.0f,
    FGameplayTagContainer ContextTags = FGameplayTagContainer())

Construct and return a FAP_EventPayload. Appears as a pure node in Blueprint — use this instead of splitting struct pins manually.

# AAP_EventBusDemoCharacter

C++ reference implementation demonstrating AP Event Bus usage. Ships as demo content — not required for plugin usage.

On BeginPlay, caches the GameState bus, binds both delegates, and registers three demo tag filters. On SetupPlayerInputComponent, binds four input actions (locally controlled only).

Input Action	Scope	Tag	Magnitude
`DemoPublishDamage`	All	`Event.Demo.Damage`	25
`DemoPublishHeal`	All	`Event.Demo.Heal`	10
`DemoPublishAlert`	ServerOnly	`Event.Demo.Alert`	0
`DemoPublishUINotify`	LocalOnly	`Event.Demo.UINotify`	0

Demo Tags

Demo tags are not shipped in a plugin .ini file. Register them in your project's Gameplay Tags config before use.

# Log Category

All plugin log output uses the LogEventBus category. Filter in the Output Log by typing LogEventBus.

Warning Message	Cause
`PublishEvent — EventTag is invalid. Event discarded.`	`Payload.EventTag` is not a registered Gameplay Tag
`ListenForEvent — Tag is invalid. Ignored.`	Tag passed to `ListenForEvent` is not valid
`RegisterPersistentEvent — must be called on server. Ignored.`	Called on a client
`RegisterPersistentEvent — Tag is invalid. Ignored.`	Tag is not valid
`UnregisterPersistentEvent — must be called on server. Ignored.`	Called on a client
`AAP_EventBusDemoCharacter: No AP_EventBusComponent found on GameState.`	Demo character could not find a bus on the GameState

AfterPrime Systems — Building the Gameplay Foundation

# API Reference

# Contents

# EAP_EventScope

# FAP_EventPayload

Multiplayer Actor References

# UAP_EventBusComponent

Replication Model

# Delegates

# OnEventReceived

# OnListenedEventReceived

# Publishing

# PublishEvent

Validation

# Listeners

# ListenForEvent

# StopListeningForEvent

# StopAllListening

# IsListeningForEvent

# Cache

# RegisterPersistentEvent

# UnregisterPersistentEvent

# Query

Client Cache

# WasEventFired

# GetLastPayload

# GetAllCachedEventTags

# Lifecycle

# Internal RPCs

# UAP_EventBusBlueprintLibrary

# GetEventBusComponent

# GetEventBusFromGameState

Timing

# PublishEventOnBus

# MakeEventPayload

# AAP_EventBusDemoCharacter

Demo Tags

# Log Category

# `PublishEvent`

# `ListenForEvent`

# `StopListeningForEvent`

# `StopAllListening`

# `IsListeningForEvent`

# `RegisterPersistentEvent`

# `UnregisterPersistentEvent`

# `WasEventFired`

# `GetLastPayload`

# `GetAllCachedEventTags`

# `GetEventBusComponent`

# `GetEventBusFromGameState`

# `PublishEventOnBus`

# `MakeEventPayload`