Component references

A component reference names a component of an actor, and optionally a socket on it, without holding the component itself. The plugin looks the component up on the actor when it needs it. Settings such as Angle Detection Component and Trigger Components use references, and so do the move handlers and actions of a guide. You fill a reference in the Details panel of the object, the character or the action that holds it. A reference has no panel of its own.

What it does

• It names a component of an actor. The types are FCISSceneComponentsOnActor, for a scene component, and FCISPrimitiveComponentsOnActor, for a primitive component such as a mesh or a collision box.
• Each reference has a Component field and a Socket Name field. The Component field offers a picker, which lists the components of the actor of the matching kind.
• Blueprints can resolve a reference at run time with GetSceneComponentWithName and GetPrimitiveComponentWithName. Both return the component, and the socket’s location.

How it works

Resolution. The plugin finds the component in this order:

1. An empty reference names no component, and the lookup returns nothing without a warning.
2. The value of the picked property is used when it is a component of the requested kind and, unless the reference names another actor, the actor owns it.
3. Otherwise the lookup takes the component whose object name equals the picked property name, on the actor or on the other actor the reference names.
4. Otherwise the lookup returns nothing and writes one warning per actor class and name.

Socket. When a component is found, GetSceneComponentWithName and GetPrimitiveComponentWithName set the output socket location to the location of Socket Name on that component. The location is not set when nothing is found. The character’s Trigger Components ignore Socket Name. For an object’s Angle Detection Component, the socket’s location is the point the character must face. With an empty Component, that socket is looked up on the actor’s root component.

An empty reference. An unset reference means no component. It never means the root of the actor. The one exception is Angle Detection Component: when it is empty, the object’s angle is measured to the root of its actor.

Warning. The warning Component '<name>' (<class>) not found on <actor> (class <class>). Select the component again in the settings. is written when a reference names no component of that name and kind on the actor. It is written once for each actor class and name, and the set of written names is kept for the life of the process.

Where the plugin uses references. The character’s Trigger Components are resolved this way, one by one. The object’s Angle Detection Component is resolved and cached, and the lookup runs again until it finds the component or the reference is empty.

Names from 1.x. A reference saved by 1.x holds its name in a field that is cleared when the data loads. The name moves into Component. This is for old data only.

Set it up

The steps are in the guide, so this page gives only the outline. Pick the components in the Details panel of the object, as Two-sided door does in its step 3. There the move handler takes Move To This Component and Looking Point, and the action takes Mesh Component On Object. The character’s Trigger Components are set in Your own character, steps 1 and 2.

Use it

• In a Blueprint, call GetSceneComponentWithName or GetPrimitiveComponentWithName with the actor and the reference. Use the returned component, and the socket location, for example to place an effect.
• The lookups return null when nothing is found. Check the result before you use it, because the component may not exist on that actor.
• The Component field is writable in Blueprints, and Socket Name is read-only there.

Key settings

This page has no Details panel of its own. The two fields below appear in the Details panel of every object or action that holds a reference.

Setting	What it does	Default
Component	The component the reference names, chosen in the picker. The picker lists the components of the matching kind.	Empty: no component
Socket Name	The socket on that component. When the component is found, its location is the socket’s location. When the name is empty, the location is the component’s own location. The character’s Trigger Components ignore it. For an object’s Angle Detection Component, the socket’s location is the point the character must face; with an empty Component, the socket is looked up on the actor’s root component.	None

Check that it works

• Play the level of the guide, and walk to the door. The character walks to the point of the side it stands on, as Two-sided door describes in its check section. That walk depends on its references.
• Read the Output Log at its default level, Warning, while you play. It shows no Component '<name>' warning when every named component exists.

Troubleshooting

• The warning Component '<name>' (<class>) not found on <actor> (class <class>). Select the component again in the settings. appears. The reference names no component of that name and kind on the actor. It was renamed, removed or changed to another kind, or the reference points at another actor. Select the component again in the reference’s field. The warning appears once for each actor class and name until the editor restarts.
• A field is empty and nothing warns. An empty reference writes no warning. Check that each field the guide sets is filled in, as Two-sided door says in its “If something is off” section.
• The angle of an object is measured to its root. The Angle Detection Component is empty, or it names no component. The root of the object’s actor is then the point the character faces.
• The reference finds a component that is not the one you expect. The lookup takes a component that a property holds only when the actor owns it. Otherwise it matches the name, on the actor itself, or on the other actor that the reference names when that is set.