Persistent References

Persistent References are a special kind of GameObjects in the RCK that are always loaded and present while the game is running.

Generally, a GameObject such as an AI, a chest or an item in world exists in a scene, such as an Interior cell, and is accessible only if that Interior cell is loaded. This can be the intended behavior for many situations, but there are others where you may want to access or modify GameObjects that are not in a loaded cell.

This is where Persistent References take place, they are GameObject present in the _PersistentReferences_ scene - which is always loaded, therefore every object inside the _PersistentReferences_ scene will always be present while the game is running.

You can easily access the _PersistentReferences_ scene by loading the _WorldLoader_ in the Cell View via the button.

Types of Persistent References

_PersistentReferences_ scene content.

There are several types of Persistent References defined for the purposes of the RPG Creation Kit, but it is important to notice that you can at anytime add new objects and they will effetely be Persistent References, although you may have to define a way of quickly accessing them.

• AI: Defines a special kind of AI which is a Persistent Referenced AI.
• AIPaths: Contains AI Paths mainly used by Persistent Referenced AI.
• LootingPoint: Contains LootingPoints that for a need have to be Persistent Referenced.
• Door: Contains special kinds of Doors that needs to be accessible anytime, for example even when the AI that wants to use it is far away from the Door's transform.
• Other: You can insert your own kind of PRefs in here.
• Unregistered: If for a reason a Persistent Reference happens to be unregistered, it will be a child of this game object.
• Quest Markers: contains the persistent positions of the locations that the compass have to point to while doing a quest.
• QUEST_RELATED: Contains persistent references to Quest Related objects, such as the fire particles that is used in the City during the quest "They Shall Fall".

Creating a New Persistent Reference - Looting Point

In this section, we are going to create a new Persistent Reference to see how they are composed and why you may want to use them.

Here we are going to create a persistent Looting Point, the process is pretty much the same for any other references except for the AI, for creating an AI Persistent Reference, refer to this tutorial: Creating a New Persistent Reference AI

If you don't know how Looting Points work, read this first.

Let's load up the _WorldLoader_ in the Cell View via the button and let's focus on the _PersistentReferences_ scene.

Drag and drop a Looting Point prefab such as "ClosedChestLootingPoint_Prefab" from the Project Window to the LootingPoint GameObject in the Persistent References scene. Next, in the "Looting Point" component, let's set a unique ID and Name, I'll set mine to:

ID: MyPersistentChest001

Name: Persistent Chest

Next up, you may want to place it somewhere. I'm going to place it in the exterior worldspace, near the shack in the cell "Virrihael (0, -2)". Doing it from the _WorldLoader_ scene alone may be a bit complex, because there is nothing in there. What you can do is to quickly load the said cell additively in the Cell View.

Just with that you have a working Looting Point that always exists while the game is running, but currently we do not have a way to quickly access it, for example from a script.

Registering the Persistent Reference

To complete the creation of the Persistent Reference we need to do two things:

1) Add a "Persistent Reference" component to the Looting Point and set it up:

• Show Handle always shows the cyan RefID in the Editor, so that you can quickly see it.
• Ref ID: is the UNIQUE ID that we will use to access this reference. I've used "PREF_MyPersistentChest001".
• Is Loaded: is a flag that states whether this Persistent Reference is loaded or not, for Looting Points it should always be true.
• Type: the Type of the Persistent Reference.

2) Register the Persistent Reference - in the _PersistentReferences_ scene the root GameObject "PersistentReferences" contains a component called "PersistentReferenceManager": We need to register our new Persistent Reference there.

To do so, click on the + button in the "Refs" dictionary, type the same RefID of the Persistent Reference you've set earlier (mine is PREF_MyPersistentChest001) and drag and drop the Looting Point object to the Persistent Reference field.

GIF, click on the image to view it.

Make sure to save the scene, you now have successfully created a new Persistent Reference.

Accessing the Persistent Reference

Now that we have a Persistent Referenced Looting Point, we might as well use it for something. What I will do is the following:

The looting point will start empty by default, when a new character is created, if it is a male, the chest will contain a sword, if it is a female, the chest will contain 100 golds.

This is a pretty good use of the Persistent References, because when the Player creates a new character the chest will always be unloaded (it is too far away), so how could we add new items to the chest if it is not loaded? Now that the chest is a Persistent Reference, we can.

We know that when the game starts for the first time the QuestStage script "JustAnotherDeliverStage10QuestScript" runs, so it is the perfect candidate to our edit.

After setting the Equipment, we can access our persistent reference by its RefID (PREF_MyPersistentChest001), check our gender and call the AddItem() method to add an item to the LootingPoint:

You can download the edited script here.

This should put in perspective the power of the Persistent References, once a reference has been created, you can have complete access over it and do whatever you want with it.