Using Prefabs

Document Summary: This is a guide to using Prefabs in the Unreal Engine.

Document Changelog: Created by James Golding; Maintained by Richard Nalezynski.

Overview

Prefabs are collections of Actors, with an associated script, that can be stored in a package and instanced into a level.

Quite often when constructing a level you want to create some arrangement of Actors, and then re-use that collection in the same or other levels. An example might be a flaming torch, which consists of a static mesh, a light and a particle system. Prefab's allow you to create this kind of collection once, and then save it in a package as a Prefab. You can then select the Prefab in the Generic Browser, and add it many times through the level.

One feature that makes Prefabs in Unreal Engine 3 very powerful is that you can go back and update the Prefab, and those changes will be propogated to all instances of that Prefab. Because this uses Unreal's property system, only properties that have not been changed in an instance of the Prefab will be updated when the Prefab changes. For example, imagine you have a Prefab that contains a yellow light, and you then change one instance of the Prefab to have a blue light. Then you change the Prefab itself to have a green light. Only instances who's light is still yellow will have the color changed to green. This is very useful, as it allows you modify, or even remove, parts of a Prefab instance to make it fit a particular usage, but also receive updates to the Prefab.

Prefabs also support Kismet sequences. In the example above, you might want to add some Kismet scripting where when you shoot the torch with a particular weapon, the light turns off. This is very time consuming if you have to manually create each copy of the relevant sequence in Kismet and hook all of the Actors up; but is very easy to do with Prefabs.

Creating A Prefab

To create a new Prefab, first assemble the Actors as you wish in the level. Then select them all, right-click and choose Create Prefab from the context menu. You will be prompted for a Package Name, optional Group Name and a name for the new Prefab. It will then ask you if you want to replace the selected Actors with an instance of the new Prefab. The origin that is selected for the new Prefab is the origin of the largest Actor that was selected.

You should now be able to see the new Prefab in the Generic Browser. Prefabs display a thumbnail showing the the Prefab in the level when you created it. This is taken from the position of the camera in the perspective editor viewport when the Prefab was created, so its worth getting a good view on your objects before you create the Prefab.

Placing A Prefab Instance

To place an instance of a Prefab, simply select it in the Generic Browser, right-click in the level and choose Add Prefab: . It should appear in the level. You will also see that all instances of a Prefab have a PrefabInstance Actor associated with them. This looks like a red P icon, and represents the origin of the Prefab.

This is used for keeping track of the Prefab that was used for this instance, and which Actors are part of it.

When you create a Prefab, references between Actors within the Prefab are correctly preserved. So if you have an Actor attached to another Actor in the Prefab, this will be handled correctly each time you place the Prefab. However, any references to Actors outside the Prefab will be cleared.

Editing A Prefab

By default, when you click on any Actor within a Prefab instance it selects the whole instance. This is to make working with prefabs easier, as you can then move them around as one unit. However, you sometimes want to edit a particular Actor within a Prefab. To do this, press the Prefab Lock button on the toolbar, which looks like a letter P.

Updating A Prefab

You change a Prefab after you have created it by modifying an instance of that Prefab, then right clicking on the Prefab Instance and choosing Update Prefab From This Instance. This will then copy the properties from the selected instance to its Prefab. It will then propagate any changes to all instances of that Prefab currently in the level. If you have deleted an Actor from that instance, then that Actor will be removed from the Prefab itself and from all instances of the Prefab. If you wish to add a new Actor to a Prefab, select the PrefabInstance and any Actors you wish to add, and do the update step. These Actors will then be added to the Prefab and all instances. The preview image for the Prefab is also re-captured when you update a Prefab.

As noted above, if you change a property on an instance of a Prefab, that value will not be changed when the base Prefab is updated. Also, when you delete an Actor from an instance of a Prefab, that Actor will not re-appear when the Prefab is updated. BSP brushes and Volumes do not work in this way though, and are always copied from the Prefab.

When you open a map which contains instances of a Prefab that has been updated since the map was saved, it will automatically update any instances of that Prefab in the map and show you this dialog:

Add A Kismet Sequence To A Prefab

Prefabs can contain Kismet scripting as well as collections of Actors. When you create or update a Prefab, it searched the level Sequence to see if there are any references to Actors in the Prefab. If it finds any, it will look for the highest sequence in the hierarchy which contains them all, and then ask you if that is the correct Sequence to use for this Prefab:

If you answer Yes, it performs an extra check that there are no references within this Sequence to Actors that are not in the Prefab. If this is the case, it will display a warning and will not include the Sequence in the Prefab.

When you place a Prefab that contains a Kismet sequence into a level, it will instance the Kismet sequence into a top-level sub-sequence called Prefabs. Each instance of a Prefab in a level has its own copy of the associated Kismet sequence. When the Prefab is updated, the Kismet sequence for each instance is completely replaced from the one in the Prefab, so it not possible to customize the Kismet sequence per-instance. However, it is possible to add input, outputs and variable connectors to the Kismet sequences of the Prefab. In this way you can expose functionality to Level Designers. An example of this might be a door prefab whose sequences exposes inputs for locking and opening the door, and an output which is fired each time the door is opened.

Prefab Tips

• If you select an Actor that is part of a Prefab instance, you can press Shift-P to select all Actors which are part of that instance. You can also do this by choosing the Select All Actors In Prefab(s) option from the context menu.
• If you want to turn an instance of a Prefab back into regular Actors, so changes to the Prefab will not affect them any more, you can choose Convert PrefabInstance To Normal Actors from the context menu.
• If you select a PrefabInstance, you can choose Open Sequence For PrefabInstance In Kismet, to open Kismet and jump straight to the sub-sequence for that instance.
• To completely reset an instance of a Prefab (that is, delete all of the Actors and re-place a new instance), you can right click on the Prefab Instance and select Reset Instance From Prefab .