Using Linked Libraries In Game

Linked Library is a Blender feature that allows referencing a datablock from another blend file into the current one, allowing easier manipulation of common assets and better project management, as you only need to edit the original file to update all the references. UPBGE supports this Blender feature, specially group instances, which ones are fairly well integrated through Python. This tutorial aims to show how to use linked libraries, group instances and manage the links.

Before We Start

To proceed with this tutorial, we need some base files first. On a directory, save three empty blend files: game.blend (which will contain the references from the libraries), lib_character.blend (which will contain the actual model of our character) and lib_scenery.blend (which will contain the actual model of our ground). We’ll edit the file game.blend later, first we must create the contents of our libraries.

lib_character.blend

Add an Monkey object, add it to a group (Ctrl-G) and rename the group to player.

lib_scenery.blend

Add an Plane, scale it by 5 (so it have the size of 10x10), add it to a group (Ctrl-G) and rename the group to ground.

Both files should be set up somewhat like this:

Split view of the two files.

Linking The Groups

Now, we’ll create a blend file named game.blend on the same directory as our previous files. In this file, we’ll do the following procedures:

• Go to the File menu, click the option Link.

• Select the either lib_character.blend or lib_scenery.blend.

• Select the option Group.

• Select the corresponding group and double click it / click Link from Library.

Linking procedures diagram.

If everything went right, you should see in the 3D Viewport the group instances added. They are not editable as they are only Empty objects referencing groups from the original files.

Groups instanced on game.blend scene.

With the instances added, all you have to do is place them with the desired transformations, and if you need to edit all the placed instances, just edit the original file to update all the references. Pretty handy, isn’t it?

Managing the Links

If you rename or move any of your libraries to another folder, you will face a common problem: broken links. There are several ways to deal with this problem, and this section will present you the use of the Outliner to manage links (and Datablocks).

I have renamed the library files to LibCharacter and LibScenery, which are different names from the previous ones (with underlines and only lower case characters). When opening game.blend, the editor will complain about the non existing libraries, and our instances will be shown only as Empty objects.

Main file after libraries be renamed.

To fix this, we must go to the Outliner and select the Blend File mode. On this mode we’ll see all :ref:`datablock-index`s on our blend file.

Blend File mode on the Outliner.

The important elements here are the references to our libraries at the bottom: they are being shown as cracked icons and their previous names. We have two choices to fix this issue:

Renaming the references

You only need to double click the references and provide the new names. If they are in another folder, you must provide the relative path.

Relocating the references

You only need to right click the references, select Relocate and select the corresponding file.

Broken references fix modes on the Outliner.

After fixing the broken references, their icons will change back to normal and the objects will be automatically updated in the 3D Viewport.

Fixed references and objects updated on the 3D Viewport.

Understanding how to use and manage linked libraries is important to maintain a complex and healthy project environment. Much more can be achieved through the use of bge.logic.LibLoad, loading and unloading libraries dynamically using Python, but for simpler projects, linked libraries should do the job.