If you develop with Unreal Engine 4, you have certainly used the Construction Script. Probably without knowing this can ruin your project.

The Construction Script is accessible within the blueprint editor:

You can access the construction script in the blueprint editor

Or if you prefer, in C++, it is represented by the OnConstruction method:

virtual void OnConstruction(const FTransform& Transform) {}

And more details can be found here: https://docs.unrealengine.com/en-us/Resources/ContentExamples/Blueprints/1_4

This convenient tool is really useful to define how an actor must be constructed. A typical use case is when you want to be able to set the properties of an actor and automatically see it being updated according to these parameters in the editor. For instance, we could use it to build a polygon actor with the number of edges as a property, and everytime the number of edges is edited, we can see the polygon being rebuilt and updated in the editor (and not at runtime).

But while it is really useful it also very dangerous if not used carefully, eventually causing crashes of the editor.

To avoid any potential problems, we need to:

  • know when the construction script is called
  • understand how it could cause an editor crash, making your project uneditable
  • learn to use it appropriately (the Construction Script is not always the answer)

How and when the Construction Script is called

It is the most interesting point of the Construction Script: it is called in the editor, and not at runtime.

And in the editor, it can be called several times:

  • When the actor is spawned
  • When the actor is moved (PostEditMove event): in this case it will be called several times while the object is being moved
  • When a property of the actor is changed (PostEditChangeProperty event)

As we can see, it can be called really often. While, it’s really useful (if I change any property, I can directly see the object being rebuilt by the Construction Script), some drawbacks appear.

The main threats of an abusive usage

There are two main threats when using the Construction Script. The first one is obvious, the second one is more tricky.

The first one is the impact on the performance of your project: even though the Construction Script is called only in the editor, if your Construction Scripts are too heavy, you will no longer be able to move the actor in the editor. Let’s say it takes one second to run your ConstructionScript, if you try to move the actor, the Construction Script will be called dozens of time while it being displaced, and so it will freeze during dozens of seconds. You may think that it’s not a big issue, that the actor will need to be spawned only once and not moved after, but for the designer that will be using your actor, it will be a real pain to remember to not move this specific object if he/she doesn’t want to freeze his/her editor.

The second threat, as I said, is more tricky. It concerns circular calls of the Construction Script: if the change of a property causes a circular call of the Construction Script, the editor will crash. The principle is the following: let’s say we have a property A and a property B on an actor, and the Construction Script states that if the A is changed, then B is equal to A+1, if B is changed, then A is equal to B+1. This could theoretically causes a crash with an infinite loop. Fortunately, this specific case is managed by the editor: the Construction Script cannot trigger itself (even if it changes properties of its actors). But when you have an actor with a ChildActorComponent and a circular relation between the actor and the child, the editor won’t save you. It will just crash (and in my experience, not everytime, making it harder to diagnose). Indeed, if the Construction Script of the parent changes a property of the child, and if the Construction Script of the child changes a property of the parent, we will have the circular call (between two different Construction Scripts).

Patterns and anti-patterns

That being said, here are my recommendations with the usage of the Construction Script:

  • Avoid using them if it’s not necessary: it’s an automation tool, use it only if you have a repetitive task to automatize
  • Keep the Construction Scripts simple and fast, it is just here as a convenient tool and not to make a fully procedural game
  • Avoid changing the properties of another actor (even a child actor) in the Construction Script, and if you have to do so, keep in mind that a circular call of the Construction Script may crash the editor