Referencing Game Objects

Overview

Creating a game involves building the visual and audio parts of your game, using 3D objects and materials, and then controlling their behavior, usually through scripts.

In order to be able to write that behavior, you will need a way to talk about it in code, a reference.

In this lesson, you will learn the many different ways to get references to objects in Core, and which ones to use in different circumstances.

Hierarchy Objects vs. Asset References

When you talk about a Core Object, you could be referring to two different types of things, a specific object present in the hierarchy, called an instance, or a type of object that is used to create those instances, called Asset Reference. An Asset Reference is either in the Core Content or in your Project Content and is just a blueprint, it is not physically present inside your game.

An object in the Hierarchy is an instance of an Asset Reference. It has a position in the world.

Templates

If you have modeled your own object that you want to treat like a prototype, and be able to spawn copies of in game, you will need to make it a template. You can learn more about how to do this in the Core Documentation Template Reference, where you can learn how to make, change, and update templates.

Once a group becomes a template, you can create new copies of it from the Project Content window.

Networking

If you want a script to change an object, that object will need to be networked.

Enable Networking

For an object in the Hierarchy, enable networking by right-clicking and selecting Enable Networking.

For a template:

1. Find the template in Project Content and drag a copy of it into the Hierarchy.
2. Right-click the template instance and select Deinstance This Object.
3. Right-click again and select Enable Networking
4. Right-click one more time and select Update Template From This.

Custom Properties

The easiest way to get a reference to an object is to make it a custom property of the script.

Create a new instance from an Asset Reference

If you drag and drop an Asset Reference in your scene, it will create an object in the Hierarchy: this is an instance of your asset. You can spawn an instance of an object from a script. In order to do that, you need to get the Asset Reference from the Custom Properties.

Drag the Asset Reference from your Core Content to the Custom properties of your script. In this example, we are using the Fantasy Weapon Axe from Core Content and renamed the property to the name Axe. Copy the code at the bottom of the properties to get the reference.

Once you have the reference, you can spawn the asset and rotate it.

local AXE = script:GetCustomProperty("Axe")

local axe = World.SpawnAsset(AXE, { position = Vector3.New(0, 0, 100) })

axe:RotateContinuous(Rotation.New(0, 0, 20))
Code language: PHP (php)

Hierarchy Objects vs. Asset References

One trick to tell if a Custom Property is referring to an object in the Hierarchy or an asset is in the generated variable code. If the object is followed by :WaitForObject(), then it is already part of the Hierarchy, and we are telling Core to wait for it to load before defining the variable.

Other Uses of Custom Properties

Any variable in your code can be made into a custom property. This will allow you to modify inputs to the program by changing them on the properties of an object

MUID’s

Every object in Core has a unique ID string that you can use to find the object with the World.FindObjectByID() function.

This method has the potential to create bugs later down the line. It makes it difficult to tell what type of thing you are dealing with, and will stop working if you try to make a new copy of the object referenced, or save it as part of a template. In general, you should avoid using MUID’s in your code, unless you cannot find an alternative. You can use World.SpawnAsset(MUID) to spawn the object.

local axe = World.SpawnAsset("48954C2AB87CFB76:Fantasy Weapon - Axe 01 (Prop)", { position = Vector3.New(0, 0, 100) })

axe:RotateContinuous(Rotation.New(0, 0, 20))Code language: Lua (lua)

Asset References and Hierarchy Object MUID’s

Assets Core Content and Project Content and instances of objects in the Hierarchy both have ID’s. It can be easy to confuse the two, since they will not have any clear distinguishing characteristics.

Get a reference of an existing instance

If you drag an object from your hierarchy to your custom property, you have a reference to an instance of the object inside the side. If you want to get the template MUID, not the MUID of the instance, you can use object.sourceTemplateId. Using the method just above using the MUID to spawn an object, you can duplicate an object by using World.SpawnAsset(object.sourceTemplateId). Note that it won’t really duplicate your instance if you modify it, it will just take the source template and spawn a new instance.

Parents and Children

The Hierarchy can be arranged so that different objects scripts and folders can be nested under other ones. Those nested objects are children, and the object they are nested under is the parent.

Parents

If you nest a script under an object, that object is the script’s parent. Knowing that, you can easily reference it with

local objectToReference = script.parent Code language: Lua (lua)

You could even get the parent of that object (like if it is part of a template) with script.parent.parent!

Children

Using an object or script’s children is more complicated than getting a parent, because while an object can have only one parent, it can have many children.

There are two useful function for this:

• GetChildren() will give you a table of every child of the object called on it.
• FindChildByName() will allow you to give the name that shows up for the object in the Hierarchy as a string, and get a reference to it in your script.

Descendants and Ancestors

You can also find parents of parents, Ancestors and children of children, Descendants using these CoreObject functions:

• FindAncestorByName()
• FindDescendantByName()

Random Item Spawner

In the following example, we are using what we have seen in this lesson. The goal is to create a template that spawns a random item from a list of templates that are in a data table.

Create Data Table

A data table will contain a list of rows and columns. The rows will be the items that the spawn will be spawning. These items can be your own templates, and should networked.

1. In Project Content, My Tables, right-click and select Create Data Table.
2. Name the data table Items.
3. Click OK to create the Data Table.
4. Open up the Items data table and edit the column.
5. Set the column name to Template and the column type to Asset Reference.
6. Add your items to the data table.

Create Item Container

An item container in the Hierarchy will be the parent for any item spawned in the world.

1. Create a new group in the Hierarchy and name it Item Container.

Create ItemSpawner Script

Create a new script called ItemSpawner and place it in the Hierarchy. This script will be responsible for selecting a random item from the Items data table and spawning it in to the Item Container folder.

The script needs to know about the Item Container and Item data table. So you will need to add these as custom properties to the script.

1. With the ItemSpawner script selected in the Hierarchy, add the Item Container as a custom property.
2. Add the Items data table from Project Content onto the ItemSpawner script as a custom property.

Edit ItemSpawner Script

Open up the ItemSpawner script and add the references to the custom properties that were created. At the same time you will need a variable called lastItem that will store the last item spawned, this is so that it can be destroyed when creating a new one to prevent objects overlapping each other.

local ITEM_CONTAINER = script:GetCustomProperty("ItemContainer"):WaitForObject()
local ITEMS = require(script:GetCustomProperty("Items"))
local lastItem = nilCode language: JavaScript (javascript)

Create RandomizeItem Function

Create a function called RandomizeItem. This function will pick a row from the Items data table at random and spawn the item into the Item Container. When a item has been spawned, a reference to it is stored in the lastItem variable. This is because the item will need to be destroyed each time the function is called. At the top of the function a check is done to see if the lastItem is valid, if it is, then the Destroy function is called to remove the object from the world.

local function RandomizeItem()
	if Object.IsValid(lastItem) then
		lastItem:Destroy()
	end

	local item = ITEMS[math.random(#ITEMS)].Template

	lastItem = World.SpawnAsset(item, { parent = ITEM_CONTAINER })
	lastItem:RotateContinuous(Vector3.New(0, 0, 1))
end

Spawn Repeating Task

A Task can be created that will repeat every 3 seconds that will call the RandomizeItem function to create a new item.

local task = Task.Spawn(RandomizeItem)

task.repeatCount = -1
task.repeatInterval = 3