Set and Get an Actor Reference

Using Actor Reference to move different Actors around in a level.

Choose your operating system:

Windows

macOS

Linux

By establishing reference to an Actor , you can access its Properties , Variables , Events , or Functions (if applicable) during gameplay through Blueprints or C++ and alter them to suit your gameplay needs.

Say for example you want a light to turn on when a player enters a Trigger Box, having reference to the light and the Trigger Box will allow you to do so by tying the light Actor to the OnComponentBeginOverlap Event of the Trigger Box (in which case you could turn on the light).

Getting proper reference to an Actor is also important for communication between Actors, as incorrectly specifying a reference will result in failed communication and undesirable results.

Follow the steps below for an example of Setting and Getting reference to an Actor.

For this example, we are using a new Blueprint Third Person Template with Starter Content enabled.

  1. From the Place Actors panel in the Basic tab, drag a Box Trigger into your level.

    1AddTriggerBox.png

    We are going to use this to trigger movement in another Actor in the level.

  2. In the Details panel for the Box Trigger , select the Convert to Class Blueprint option.

    2ReplaceWithBlueprint.png

    We are going to create a Blueprint out of this Actor and assign a variable within it which will store the reference Actor.

  3. Give the Blueprint a name then select Create Blueprint (the Blueprint Editor will open).

  4. In the Blueprint Editor, under My Blueprint , click the Add Variable button.

    3AddVariable.png

  5. Click on the variable, then in the Details panel, click the Variable Type button and select Actor under Object Reference .

    4VariableType.png

    Here we are specifying that the reference is of the Actor type and is an Object in our level.

  6. Name the variable TargetActor and click the Editable checkbox.

    5NameVariable.png

    This indicates that the variable is set to Public which allows it to be accessed and set outside of this Blueprint via the Details panel in the Main Editor window. This is useful in situations where you want to modify the variable without having to go into the Blueprint to modify it.

  7. You can also enter in text to appear as the Tooltip for what the variable does or is intended for.

    7ToolTip.png

    Here we have entered in the text "The Actor to Target".

  8. Click the Compile button in the upper left portion of the Blueprint Editor window.

    20Compile.png

    It will change to a green check mark after compiling.

    21Complete.png

  9. Minimize the Blueprint and return to the Main Editor window then select the Box Trigger Blueprint in your level.

  10. In the Details panel for the window, you should see under Default the Target Actor variable and tooltip.

    8DetailsPanel.png

  11. From the Content Browser , under Content/StarterContent/Shapes add three Shape_Cubes to the level.

    9AddingAnActor.png

    If you are using your own project, you can add any Actor, Static Mesh, or Blueprint to the level instead.

  12. Whatever you add to the level, in the Details panel for each Actor, set their mobility to Moveable .

    22Moveable.png

    This will allow us to move them via Blueprint script.

  13. Click on the Box Trigger Blueprint in the level.

  14. In the Details panel, click the None box under Target Actor and search for Shape (or the name of the Actor(s) added).

    10DropDownSelection.png

    When clicking None all Actors currently in the level are displayed, however we are going to target one of the cubes we added.

  15. Click the eye dropper icon next to the magnifying glass icon.

    11PickActor.png

    This will allow you to select an Actor from your level as the Target Actor by clicking on it in the viewport.

  16. Move the eye dropper icon over one of the cubes (or other asset you have added) and click it to make it the Target Actor.

    11ActorSelected.png

  17. When you select an Actor, the Target Actor variable will update with the selected Actor in the Details panel.

    13ActorSelected.png

    Here we have Set reference to an Actor which will be our Target Actor.

  18. Open the Box Trigger Blueprint, then in the MyBlueprint window, click the eye icon and enable Show Inherited Variables .

    showVariables.png

    This will allow us to add events on the Components that were inherited when we first converted the Trigger Box to a Class Blueprint.

  19. Under Trigger Base , Right-click on CollisionComponent and choose Add Event then Add OnComponentBeginOverlap .

    14AddOverlap.png

    This will create a new Event node on the graph.

  20. Hold Control and drag the TargetActor variable into the graph.

    15GetActorReference.png

    This creates a Get node which will get whatever is assigned to the variable which we have set to an Actor in our level.

  21. Drag off the TargetActor node, search for and add an Add Actor Local Offset node.

    16AddOffSet.png

    This will allow us to add to the current target's transform (allowing us to move it from its current position).

  22. Connect the nodes as shown below and set the Z value on the Add Actor Local Offset node to 500.0 .

    17AddZValue.png

    This will get the target's current location and move it up by 500 along the Z axis whenever the trigger box is overlapped.

  23. In the Components window, click TriggerBox_Blueprint so it is selected.

    selectTriggerBox.png

    If you do not see the Components window, you can enable it from the Window menu option.

    enableComponentWindow.png

  24. In the Details panel for the Trigger Box, under Rendering , un-check the Actor Hidden In Game option.

    19ActorHiddenInGame.png

    This will make the trigger box visible in-game so that you can see where it is to enter it with your player.

  25. Click Compile and Save , then close the Blueprint.

  26. From the Main Editor Window, click the Play icon to play in the editor.

When you enter the Trigger Box, your selected Actor should move up by 500 units. Each time you enter the Trigger Box, the box will move up by another 500 units. By establishing a reference, the variable knows which Actor to affect in the Trigger Box script. Try affecting a different Actor in the level using this script.

  1. From the Main Editor window, inside the Level Viewport click the Box Trigger Blueprint.

  2. In the Details panel for the Box Trigger , click the eye dropper icon next to Target Actor .

    11PickActor.png

  3. In the level viewport, click a different Actor than the one you used before.

  4. Play in the editor again.

This time the new Actor selected should move up along the Z axis by 500 units each time you enter the Trigger Box. By using the Target Actor variable in our Box Trigger script, we are not locked into a specific Actor associated with the script and can modify it and change the Actor it affects without having to modify the Blueprint itself.

While this example illustrates how to move different objects around, instead of moving an object you could use this method to open doors when the player presses a button, turn on/off different lights, spawn items for the player to pick up or destroy or any number of other possibilities.

This is also one of multiple ways you can get reference to an Actor, for example if you wanted to get Reference to the Player Character which cannot be explicitly set via the Main Editor window, you would take a different approach (see the Related Links section below).

Help shape the future of Unreal Engine documentation! Tell us how we're doing so we can serve you better.
Take our survey
Dismiss