Using Prefab Instances

Tutorial Author:Jeremy Stieglitz
Updated March 12 2005

What is a Prefab Instance?

A Prefab Instance (PI) is a shallow copy of a Prefab loaded by XML from your "Models" directory. Rather than unique Prefabs in your scene, using PI's for multiple duplicates cuts down on memory usage (PI's use essentially no memory beyond the original mesh), improves performance, and allows you to follow a "reference-based" production method where changing the original Model files affects all instances used in any scenes.

PI's behave as regular Prefabs do in all respects, except the following:

• PI's can't be scaled in your final scene (though the original Prefab model can be scaled in its own XML scene).

• PI's can't have uniquely baked PRT (but they can share the original baked PRT or have unique dynamic PRT).

• Because PI's will calculate dynamic PRT uniquely for each instance, they can consume significant CPU if you use non-baked PRT on them. For this reason, if you plan on using many Instances of a given Prefab, it is recommended that you share baked PRT rather than leave it unbaked (and hence dynamic). If you do need unbaked PRT (such as on very large objects), you should consider using unique Prefabs instead.

The "Quick" Way to Convert to Prefab Instances

You can quickly convert any unique Prefabs in your scene into Instances by using the LeftShift+RMB Context Menu. You can then Clone this Instance within your scene, significantly reducing memory overhead.

Beware that Cloning unique Prefabs (before you convert into Instances) will disallow collapsing all the Clones into a single instance, so be sure to convert to Instances early in your scene's construction -- before you've Cloned!

Adding Prefab Instance Via the Asset Browser

PI's can also be added via the Asset Browser's Prefab Library. To get your Prefabs into the Library, they must be located in the Models folder.

If you are working from 3dsmax, you can export your Prefab directly to the "Models" folder for use in the Library. To do this, save your model in the following manner in the Reality Tools export dialog:

If you are working on a scene in RealityBuilder, you can export any Prefab for use in the Library by selecting it, then clicking the "Export Selected to Library Button" in the toolbar:

Inserting a Prefab Instance

Now that you've saved your Prefab into the Library, you're ready to insert it as a Prefab Instance!

In your desired scene, move the camera roughly to where you want to add your Prefab Instance. Open the AssetBrowser and select the Prefabs tab. Select the "Models" folder, and you should see your Prefab's name and icon displayed in the list. Select it, and double-click the "Insert Prefab Instance" button above the list.

The PI will appear in front of you, and you can then transform it, use it with inclusion/exclusion or blocker lists, or do anything else with it except for the limitations noted in the first section. You know that you're looking at a Prefab Instance because its name is prefixed "Prefab_", and the Actor has the "PrefabInstance" Properties category when you select it. You can keep inserting more Prefab Instances or Cloning them to create as many as you want, at no memory cost.

Finally, you can edit the original Prefab file that has been saved into your Models subdirectory. Open that XML in Reality Builder and replace the mesh, scale it, offset its transformation, generate PRT, or perform any other operations and all of its Prefab Instances will be affected. This allows a more effective method of producing large, complex environments composed of many Prefab Instances.

Converting a Prefab Instance back into a Unique Prefab

If you decide that you want to convert a Prefab Instance (in your scene) back into a unique Prefab, you can.

Possible reasons for wanting to convert an Instance back to a unique Prefab include:

• You decided you needed to have unique scaling value for this particular Prefab Instance within the scene
• You decided to have dynamic PRT but can not accept the CPU-expensive calculations used for Prefab Instances' dynamic PRT.
  • This is because unique Prefabs can share dynamic global PRT, which comes at no performance cost. Prefab Instances, as mentioned earlier, run more CPU-expensive calculations when they have unbaked PRT
• You decided to have unique baked PRT -- Prefab Instances only share one set of baked PRT between them.

To convert a Prefab Instance into a unique Prefab, select the Prefab Instance, hold LeftShift and click the RMB to bring up the context menu, select the "Convert To Unique Prefab" menu item, and you will then have a newly unique Prefab there to work with.