1. Introduction

Components TCastleDesign and TCastleTransformDesign allow you to instantiate (reuse) in one design file a component designed in another design file. This is similar to how Unity prefabs are used.

2. Video

If you like to learn by watching, we have a nice video about using these components:

3. Overview

The general idea is simple:

You can reuse a composition of components, that you have designed in CGE editor, multiple times.
You can reuse a UI (TCastleUserInterface). Reuse by TCastleDesign.
You can reuse a transform (TCastleTransform - 3D or 2D stuff that can be placed in a viewport). Reuse by TCastleTransformDesign.

Any design file (.castle-user-interface or .castle-transform) can be loaded (instantiated) by TCastleDesign and TCastleTransformDesign). To create such design file, with any component as a root, you can use:

Menu item "Design → New Xxx (Custom Root) → Xxx"
Or save any component to file using "Save Selected…" command (right-click on the component in hierarchy).

Then you can reuse it:

by manually adding TCastleDesign or TCastleTransformDesign to new designs. Set their URL property to the design that contains the component to be reused.
Or just drag-and-drop a .castle-user-interface or .castle-transform file on your design.

See the context menu (right-click) of the TCastleDesign or TCastleTransformDesign for some helpful commands:

"Edit (Copy Here) Referenced Design" (detach from the referenced design file)
"Revert To Referenced Design" (use after "Edit (Copy Here) Referenced Design"; this removes all the children and reverts back to the original design file)
"Open Referenced Design" (an easy way to open design in the URL of this TCastleDesign or TCastleTransformDesign component).

4. Factory (TCastleComponentFactory)

A related engine feature is TCastleComponentFactory. Use this to instantiate the same .castle-user-interface or .castle-transform multiple times. For example, you could use this to:

spawn creatures
spawn bullets

See examples that use this:

examples/2d_games/space_shooter (spawning bullets, rocks, explosions)
examples/animations/animate_bones_by_code (spawning characters for "Add Crowd" test).

From code, the primary method to use is TCastleComponentFactory.ComponentLoad. It creates another instance of given design, that you can add to the hierarchy.

Note	Hint: if you have scenes inside the designs, that are instantiated many times, usually setting `TCastleSceneCore.Cache` to `true` is beneficial. It will avoid loading the scene from disk multiple times.

To improve this documentation just edit this page and create a pull request to cge-www repository.