DynamicRef Subsystem

Base:

UWorldSubsystem

Type:

UNDynamicRefSubsystem

Header File:

NexusDynamicRefs/Public/NDynamicRefSubsystem.h

A locator system that maintains a map that organizes UObject into predefined categories ENDynamicRef or named buckets (FName).

Getting Actors

Accessing the referenced AActors can be done with minimal overhead.

Blueprint

note

In the above blueprint example, the UNDynamicRefComponent would need to have its Link Phase set to InitializeComponent in order to ensure it is registered prior to a hypothetical BeginPlay() event.

C++

Getting Actors

TArray<AActor*> ReferencedActors = UNDynamicRefSubsystem::Get(GetWorld())->GetActors(ENDynamicRef::NDR_Item_L);
for (AActor* Actor : ReferencedActors)
{
  // Do something with Actor
}

UFunctions

tip

The UNDynamicRefComponent automatically manages the registration lifecycle.

Adding References

Add Object

/**
  * Add a reference by ENDynamicRef to a specified UObject.
  * @remark Be careful with the manual add method. If you add it, you must remove it!
  * @param DynamicRef The desired ENDynamicRef to add to.
  * @param InObject The UObject to be referenced by the provided ENDynamicRef.
  */
void AddObject(ENDynamicRef DynamicRef, UObject* InObject);

Add Object (By Name)

/**
  * Add a reference by FName to a specified UObject.
  * @remark Be careful with the manual add method. If you add it, you must remove it!
  * @param Name The desired FName to add to.
  * @param InObject The UObject to be referenced by the FName.
  */
void AddObjectByName(FName Name, UObject* InObject);

Add Objects

/**
  * Add a reference by ENDynamicRef to a TArray of UObjects.
  * @remark Be careful with the manual add method. If you add it, you must remove it!
  * @param DynamicRef The desired ENDynamicRef to add to.
  * @param InObjects The TArray of UObjects to be referenced by the provided ENDynamicRef.
  */
void AddObjects(ENDynamicRef DynamicRef, TArray<UObject*> InObjects);

Add Objects (By Name)

/**
  * Add a reference by FName to a TArray of UObjects.
  * @remark Be careful with the manual add method. If you add it, you must remove it!
  * @param Name The desired FName to add to.
  * @param InObjects The TArray of UObjects to be referenced by the FName.
  */	
void AddObjectsByName(FName Name, TArray<UObject*> InObjects);

Removing References

Remove Object

/**
  * Remove a reference by ENDynamicRef to a specified UObject.
  * @param DynamicRef The desired ENDynamicRef to remove from.
  * @param InObject The UObject to be having its reference removed by the provided ENDynamicRef.
  */
void RemoveObject(ENDynamicRef DynamicRef, UObject* InObject);

Remove Object (By Name)

/**
  * Remove a reference by FName to a specified UObject.
  * @remark Be careful with the manual remove method, it should be used for things that you have manually added.
  * @param Name The desired FName to remove from.
  * @param InObject The UObject to be having its reference removed by the FName.
  */
void RemoveObjectByName(FName Name, UObject* InObject);

Remove Objects

/**
  * Remove a reference by ENDynamicRef to a TArray of UObjects.
  * @param DynamicRef The desired ENDynamicRef to remove from.
  * @param InObjects The TArray of UObjects to be having their references removed by the provided ENDynamicRef.
  */
void RemoveObjects(ENDynamicRef DynamicRef, TArray<UObject*> InObjects);

Remove Objects (By Name)

/**
  * Remove a reference by FName to a TArray of UObjects.
  * @remark Be careful with the manual remove method, it should be used for things that you have manually added.
  * @param Name The desired FName to remove from.
  * @param InObjects The TArray of UObjects to be having their references removed by the FName.	 
  */
void RemoveObjectsByName(FName Name, TArray<UObject*> InObjects);

Accessing References

Get Actors

/**
  * Gets an array of AActor dynamically associated with the provided ENDynamicRef.
  * @note This method will only return AActor objects, filtering out any non-AActor UObject.
  * @param DynamicRef The desired ENDynamicRef to access.
  * @return An array of UObject. 
  */
TArray<AActor*> GetActors(const ENDynamicRef DynamicRef);

Get Actors (By Name)

/**
  * Gets an array of AActor dynamically associated with the provided FName.
  * @note This method will only return AActor objects, filtering out any non-AActor UObject.
  * @param Name The desired FName to access.
  * @return An array of UObject. 
  */
TArray<AActor*> GetActorsByName(FName Name);

Get Objects

/**
  * Gets an array of UObject dynamically associated with the provided ENDynamicRef.
  * @param DynamicRef The desired ENDynamicRef to access.
  * @return An array of UObject. 
  */
TArray<UObject*> GetObjects(const ENDynamicRef DynamicRef);

Get Objects (By Name)

/**
  * Gets an array of UObject dynamically associated with the provided FName.
  * @param Name The desired FName to access.
  * @return An array of UObject. 
  */
TArray<UObject*> GetObjectsByName(FName Name);

Get First Actor

/**
  * Retrieves the first/oldest AActor associated with a specified ENDynamicRef.
  * @param DynamicRef The ENDynamicRef collection to iterate.
  * @return A pointer to the first AActor found for the specified ENDynamicRef, or nullptr if no actors are found.
  */
AActor* GetFirstActor(const ENDynamicRef DynamicRef);

Get First Actor (By Name)

/**
  * Retrieves the first/oldest AActor associated with a specified FName.
  * @param Name The FName collection to iterate.
  * @return A pointer to the first AActor found for the specified ENDynamicRef, or nullptr if no actors are found.
  */
AActor* GetFirstActorByName(FName Name);

Get First Object

/**
	* Gets the first/oldest UObject associated with the provided ENDynamicRef.
	* @param DynamicRef The desired ENDynamicRef collection to access.
	* @return The first UObject in the collection. 
	*/
UObject* GetFirstObject(const ENDynamicRef DynamicRef);

Get First Object (By Name)

/**
  * Gets the first/oldest UObject associated with the provided FName.
  * @param Name The desired FName to access.
  * @return The first UObject in the collection. 
  */
UObject* GetFirstObjectByName(FName Name);

Get Last Actor

/**
  * Retrieves the last/newest AActor associated with a specified ENDynamicRef.
  * @param DynamicRef The ENDynamicRef collection to iterate.
  * @return A pointer to the first AActor found for the specified ENDynamicRef, or nullptr if no actors are found.
  */
AActor* GetLastActor(const ENDynamicRef DynamicRef);

Get Last Actor (By Name)

/**
  * Retrieves the last/newest AActor associated with a specified FName.
  * @param Name The FName collection to iterate.
  * @return A pointer to the first AActor found for the specified ENDynamicRef, or nullptr if no actors are found.
  */
AActor* GetLastActorByName(FName Name);

Get Last Object

/**
  * Gets the last/newest UObject associated with the provided ENDynamicRef.
  * @param DynamicRef The desired ENDynamicRef collection to access.
  * @return The last UObject in the collection. 
  */
UObject* GetLastObject(const ENDynamicRef DynamicRef);

Get Last Object (By Name)

/**
	* Gets the last/newest UObject associated with the provided FName.
	* @param Name The desired FName type to access.
	* @return The last UObject in the collection. 
	*/
UObject* GetLastObjectByName(FName Name);

Utilities

Get Count

/**
  * Retrieves the count of UObjects associated with a specified ENDynamicRef collection.
  * @param DynamicRef The desired ENDynamicRef collection.
  * @return The number of UObjects associated with the specified ENDynamicRef collection.
  */
int32 GetCount(const ENDynamicRef DynamicRef);

Get Count (By Name)

/**
  * Retrieves the count of UObjects associated with a specified FName collection.
  * @param Name The desired FName collection.
  * @return The number of UObjects associated with the specified FName collection.
  */
int32 GetCountByName(FName Name);

Get Dynamic Refs

/** @return All ENDynamicRef slots that currently have at least one registered object. */
TArray<ENDynamicRef> GetDynamicRefs() const;

Returns only the populated slots, which is useful for tooling — for example, the Developer Overlay iterates this list to render one row per active slot.

Get Names

/** @return All FName buckets that currently have at least one registered object. */
TArray<FName> GetNames() const;

Same shape as GetDynamicRefs, but for the free-form FName buckets backed by the named-collection map.

Native-Only Fast Paths

Four *Unsafe accessors mirror the GetFirst* / GetLast* pairs above but skip the bounds and emptiness checks. They are not exposed to Blueprint and exist for tight inner loops where the caller can guarantee the slot/bucket is non-empty.

Method	Equivalent To
GetFirstObjectUnsafe(ENDynamicRef)	GetFirstObject without nullptr/empty checks.
GetFirstObjectByNameUnsafe(FName)	GetFirstObjectByName without nullptr/empty checks.
GetLastObjectUnsafe(ENDynamicRef)	GetLastObject without nullptr/empty checks.
GetLastObjectByNameUnsafe(FName)	GetLastObjectByName without nullptr/empty checks.

warning

The *Unsafe variants will dereference into an empty array if you call them on a slot/bucket with no registered objects — only use them from native code paths that already gated the lookup with GetCount or by subscribing to the registration delegates below.

Delegates

The subsystem fires four native multicast delegates that broadcast every registration change. The shipped Developer Overlay listens on all four to keep its UI in sync without polling — mirror that pattern when you build custom diagnostic UIs.

Delegate	Signature	Fires When
OnAdded	(ENDynamicRef, UObject*)	An object is registered under a slot.
OnRemoved	(ENDynamicRef, UObject*)	An object is unregistered from a slot.
OnAddedByName	(FName, UObject*)	An object is registered under a named bucket.
OnRemovedByName	(FName, UObject*)	An object is unregistered from a named bucket.

The delegates are native (not BlueprintAssignable) — bind from C++ via OnAdded.AddUObject(...) and remove with RemoveAll(this) in your teardown path.