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.
Add an Monkey object, add it to a group (Ctrl-G) and rename the group to player.
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 Datablocks 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
loading and unloading libraries dynamically using Python, but for simpler projects, linked
libraries should do the job.