The Parts and Whole: Prefab Export

By Geep 2022, with content from Greebo and others

Introduction to Prefabs

In a hurry? For a quick take on Prefab import and export, see "Working with prefabs" in the Dark Radiant User Guide.

A Prefab is like a map file with a different extension, and a different use case. It is used to pack a collection of DarkRadiant map opjects (brushes/patches and entities) into a file so that it can be re-used again. There is no expectation that a prefab by itself is compilable as a map.

For example, you can set up something like a streetlight mesh, the light entity for it, two particle effects for the electric transmission, and a sound speaker. Save it as one prefab object. Then you can import it multiple times into your current or future projects. Or, if sharing more widely, mappers can just drop it into their maps. This can be useful for things like doors or other entities with a complex Stim/Response setup. Ideally, it saves a bit of work.

Using "Export Selection as Prefab..."

Before exporting, it is best-practice to temporarily disable all filters, to avoid overlooking items to include.

Then, just select your items in DR and choose:

File > Export Selected as Prefab...

Available export formats are:

Portable Prefab (*.pfbx)  The default; also retains DR Group and Layer info
Prefab (*.pfb) Traditional.

Suggestions on Where to Save the File

It depends on what you plan. If the Prefab is...

• Just for Your Current FM. Create a <FM>/prefabs folder, which DarkRadiant will subsequently use by default; otherwise, DR will use your maps folder.
• For Your Current & Future FMs. Store this prefab anywhere you wish, typically in a folder you call "Prefabs". Avoid embedding it with the DR or TDM distributions, where it might get lost on upgrades.

Choice of File Formats

There are two ASCII, human-readable data formats:

• ".pfbx": The more-recent "Portable Prefab" format, built on XML syntax, and available since DR 2.8.0
• ".pfb": The traditional "Doom 3 decl-style" syntax

Other than the syntax difference, both formats will contain equivalent information about the included map objects, except that .pfbx also has info about DR Layer and Groups (In the analogous .map file, that info would be contained in the .darkradiant file. There is no similar such file generated if you select .pfb export.)

In terms of style and content, .pfbx is similar to .mapx, .pfb is similar to .map, though in both cases the prefabs will have slightly less content than equivalent maps. XML uses more disk space than Decl-sytle.

The next section has additional considerations about this choice.

Additional Considerations For Prefabs to be Shared

There are further cleanup steps you might take when prepping a Prefab to be used in other FMs or to become part of the core TDM assets:

• Ensure brush vertices are grid-snapped, ideally not to a fine grid.
• For patches, grid-snap vertices that need to align with those of other patches or brushes.
• Move the prefab's components to a grouping around 0,0,0. A separate map, with a floor at z=0, can help with this. (This lessens the need that "Recalculate Prefab Origin" has to be checked on import.)
• If you don't want to convey either Group and Layer information in the prefab, consider using the "pfb" instead of "pfbx" format.
• If you want to convey Group information, but not Layers, put the Prefab in a separate minimal map with no Layers, and export it from there using the .pfbx format.
• Review naming and dependency issues that follow.

Component Naming Considerations for Prefabs

When creating Prefabs with multiple components of the same name, e.g., a cupboard with two doors, don't name them with numerical suffixes like door1 & door2. Although the Prefab may insert and work correctly, you may find the renumbering confusing, especially if the doors have handles bound to them and targets. The door2 handle may work correctly and be bound to the correct door but it might be named handle1. Instead, name them, say, doorA & doorB. That way, if they then get renumbered on insertion as doorA2 & doorB2 with handleA2 & handleB2, there's no confusion as to what goes where.

Prefab Comments and Dependent Components

Prefabs that you are sharing with others may rely on custom components (textures, sounds, scripts not found in TDM core) that can't be part of a map file. Consider how to convey these assets and information about their use. Ways to alert your Prefab recipients about this include:

• Putting comments within the Prefab. Add the following key/value pair to the worldspawn of the prefab...

editor_description <your description> If the Prefab has no worldspawn, add a tiny brush and texture it nodraw.

(This spawnarg is automatically removed during import of the Prefab.)

• Particularly if the instructions are complex or have diagrams...
  • append to the Wiki's Prefab Comments article; and/or
  • maintain a forum thread dedicated to your Prefabs.

See Also

• Some material here is adapted from the pre-DR-2.8 treatment in Prefabs by Fical, Destined, and Greebo.