The Parts and Whole: Prefab Import

By Geep 2022, with content from Greebo and others

Introduction to "Import Prefab..."

In a hurry? For a quick take on importing and exporting prefabs, see the [https://www.darkradiant.net/userguide/#WorkingWithPrefabs "Working with prefabs" in the Dark Radiant User Guide].

A prefab offers a curated set of Dark Radiant map objects (brushes/patches and entities) in a file, so that it can be re-used again. TDM provides an organized collection of stock prefabs to choose from. Or import custom prefabs that you or colleagues have created. Once imported, the concept of a prefab goes away; you just have objects, although they can be in a DR Group.

Importing and Using a Prefab

Either

• File > Import Prefab...
• In a DR orthogonal view, RMB > Insert Prefab...

A "Choose Prefab" window is brought up. At the top, radio buttons allow you to select a source.

Specifying a Prefab Source

• For stock prefabs, select the default radio button "Browse mod resources". The left pane then gives a tree view into TDM's prefabs folder.
• For custom prefabs, stored on your disk in a location you know, choose a different radio button (and associated control):
  • "Browse custom path", or, if cached...
  • "Select recently used path"

In either case, with a particular prefab selected in the left pane, the right pane shows what it looks like.

Viewing a Prefab's Description

Occasionally, a prefab author will provided a description about a prefab and/or how to use it in the text box above the rightside preview pane. If none, you'll see:<no description>

Check also if the author has added information elsewhere:

• to the Wiki's Prefab Comments article.
• to a forum thread maintained by the author.

Specifying Import Options

Before clicking OK to import, note two important checkboxes at the bottom left edge:

• Create Group out of Prefab parts
• Recalculate Prefab Origin

For a new FM, these are on by default, and are generally recommended. IMPORTANT: Any changes you make will be remembered across imports and DR sessions.

"Create Group Out of Prefab Parts" Checkbox

If this is checked, upon import, the resulting map objects are automatically in an overall DR Group, which makes them easy to position as a whole. This is generally desirable unless you're interested in immediately placing components individually. Or putting the parts in a Layer instead.

If the prefab is in a .pfbx file (which conveys Group and Layer information) rather than .pfb, the author may have:

• already put everything in a Group before prefab creation. If so, the checkbox state will be in effect ignored.
• defined possibly-helpful sub-set Groups.
• defined probably-unhelpful Layers.

In any event, it's simple to ungroup the prefab after import; see Groups for general methods. Unneeded Layers can also be deleted.

= "Recalculate Prefab Origin" Checkbox

This has the tooltip: "Check to move uncentered prefab back to the prefab's 0,0,0 coordinate before insertion."

The XYZ locations of component origins in a prefab will be as given in the author's map. These dimensions are then used as offsets from the insertion point during import.

So ideally, the author, before prefab creation, would move the components to optimal places near the map 0,0,0 origin, so the prefab doesn't end up far away from the insertion point when imported. This prep step is more likely to have occurred with stock prefabs than custom.

In any event, checking "Recalculate Prefab Origin" overcomes any neglect here.

Completing the Import

Hit "OK" to import.

When importing, it is best-practice to temporarily disable all filters, to avoid overlooking ungrouped items as you position them or adapt them.

Component Renaming

During import, it is not unusual for components to be renamed (i.e., get a different number suffix) to avoid duplications. This can affect targets, scripts, etc.

Prefab Dependencies & Missing Components

Prefabs often rely on components (textures, sounds, scripts) beyond what can be included the pfb/pfbx file. Ideally, for stock prefabs, these components are included in the TDM distribution. In other cases, you'll have to track them down from source FMs or elsewhere.

Rotating Prefabs

After inserting a prefab, if you need to rotate its objects collectively on a single axis, either:

• leave the objects grouped together and use the basic Rotate tool ( R ).
• with ungrouped objects, toggle on "Rotate func_* Entities about origin" ( CTRL+R ). Make sure "Rotate Objects independently" is toggled off.

Once an imported prefab has been rotated, you might find that things like brush doors no longer operate correctly. You'll have to change spawnargs appropriately.

See Also

• The Prefab section of The Parts_and_Whole:_Overview
• The Parts and Whole: Prefab Export, particularly for more about prefab file formats.
• Some material here is adapted from the pre-DR-2.8 treatment in Prefabs by Fical, Destined, and Greebo.
• "Working with prefabs" in the Dark Radiant User Guide.