Skip to content

Custom Objects ("prefabs")

Custom objects are containers, composed of one or more other objects and having custom logic (made with events, like in a traditional scene) inside them.

Tip

"Custom objects" are also called "Prefabs" or "Templates" in some game engines.

They allow to speed-up development and make games more modular by having an object that can be reused in different scenes.

For example, you can build:

  • A dialog, composed of a background, some text, some buttons. This allows to do all the logic related to this dialog inside the custom object events, without cluttering the scene events.
  • A character or some other game objects that is composed of multiple parts. For example, a player with a moving arm.

Note

The multitouch joysticks, buttons, sliders and other user interface objects that you can find in the list of objects are “custom objects” built with other objects.

The objects contained inside a custom object are called "children" or "child objects".

Create a new custom object

Custom objects are grouped into "extensions". Extensions are composed of functions, behaviors or custom objects powered by events. You can see the list of all the extensions the game has in the Project Manager.

To create a new custom object, the easiest way is to add a few objects on the scene, then put an instance of each on the scene editor. Select then these instances, right click/long touch the selection and choose "Extract" > "Extract as a custom object".

Two objects extracted into a single custom object

Choose an extension name, custom object name and validate. This will open a new editor containing the objects you've selected along with the instances from the scene. In the scene, the instances you've selected are replaced by a unique custom object, that acts as a container for all of them.

A custom object that was just created

Note

At the moment, you can't mix 2D and 3D objects in a custom object.

If you started creating events using these objects, you must rework them. Indeed, the objects are now hidden inside the new custom object (they are called "children"). In most cases, you want to add 2 type of "functions" to your custom object:

  • A doStepPostEvents function that are events launched at every frame - much like scene events. They can do logic on the child objects. For example, it could rotate them, animate them or something else.
  • One or more action or condition. If your scene wants to manipulate a child, or use a condition on it, it's a good sign that you need to "expose" this through a custom action or condition.

This is an example of a condition made inside a custom object:

A custom condition in a custom object

Of course, this example is pretty simple and just check if the button is clicked. But similar conditions and actions could be added to manipulate the custom object, and any logic you add here will work across all the scenes using the custom object.

The condition can be then used in the scene:

By doing this for more complex needs, you can break down game menus or even gameplay objects (like a player character, complex obstacles, enemies, etc...) into custom object that can be edited independently. Your scene stays simple and only focused on the high level details of your game.

Change the default size of a custom object

The grey rectangle on the scene is the custom object default size. Your can change this size by clicking on the button on the top right corner.

Custom object variants: create various styles or configurations

Variants allow you to create different visual styles or configurations of the same custom object. Each variant can have its own child object configurations (like different images, fonts, or colors) and initial instance placements, while sharing the same events and logic.

For example, you can create a "Button" custom object with multiple variants:

  • A "Primary" variant with a blue background
  • A "Secondary" variant with a grey background
  • A "Danger" variant with a red background

All these variants will share the same button logic (hover effects, click handling, etc.), but each can have different visual appearances.

To create a new variant:

  1. Open the properties editor of an object (which is based on a custom object)
  2. Click on the Duplicate button next to the Variant title to duplicate the current variant, or create a new variant with the Plus button
  3. Give your variant a name
  4. Click on the Edit button to open the variant editor in a new tab
  5. Customize the child objects and their instances as needed

When you use the custom object in a scene, you can select which variant to use from the object properties.

Making variants using different objects inside

An important thing to understand is that all variants of a custom object share the same set of child objects. This is because all variants use the same events: if a child object exists in one variant, it must exist in all variants.

In practice, this means:

  • You cannot add new child objects to a specific variant only
  • You cannot remove child objects from a specific variant
  • The main (default) variant of your custom object should contain all the possible child objects that any variant might need

However, variants can differ in how they use these child objects:

  • A variant can choose to not place any instances of a child object if it doesn't need it
  • Each variant can configure child objects differently (different images, sizes, colors, etc.)
  • Each variant can position the instances of child objects differently

For instance, if you have a dialog custom object with an optional "icon" child object, you should add the icon object in the main variant. Then, variants that need an icon can include an instance of it, while variants that don't need an icon simply don't place any instance of it.

The game over dialog is a good example for this. It has several optional child-objects:

  • Its Decoration child-object has a tween into view behavior that allows fade in and out animations.
  • A Medal child-object where users can choose the animation with an action.
  • Several optional buttons, for instance a button to submit a score to a leaderboard.
  • For text, users can choose between bitmap text objects for pixel-art variants or text objects for variants with smooth art (for instance BitmapScoreLabel and ScoreLabel).

Add custom logic to variants

You can't directly add logic to a variant, but you can create a new custom object that contains the existing custom object.

The steps to create this custom object are the same as the ones detailed in the following section. The only difference is that you will use only 1 kind of custom object as child object and you may add other objects for your custom logic.

Use several custom objects as the same

Sometimes objects which fill the same purpose are too much different to be the same object type because they require different logic and properties.

This is the case for Resource bar (continuous) and resource bar (separated units) objects. In the following project example, an intermediate custom object is implemented to use the 2 kinds of bar.

Creating a intermediate custom object allows to:

  • Use the 2 kind of bars in groups as if they were the same object type.
  • Switch between the 2 kinds of bars by choosing a different variant for the object.
  • Add new kinds of bar without having to change the main events.

Indirection custom object

Open example in GDevelop

You can do the same with your own custom objects by following these steps:

  • Add a new custom object

  • Add the custom objects you want to use as child-objects

  • If one of the custom objects has the expands inner area with parent box checked
  • Check it for the new custom object
  • Add an anchor behavior set on following the size on all children them even the ones that has it unchecked

  • Generate functions from one of the custom object

  • Modify the generated functions to use all the child-objects

  • Remove the functions that are not shared by all the child-objects
  • Copy-paste all properties from one of the child-object

  • Remove properties that are not shared by all the child-objects
  • Add an hidden function to refresh the custom object properties

  • Call this function from onCreated and onHotReloading
  • Create variants with an instance of the child-object
  • Make the area fit the object dimension