Creating a Reference in the Properties of a Symbol



Here’s a clear example of what I’m talking about.

Create a new video player symbol.

Drag that symbol to the Hierarchy, and select it.

Look down at properties, under references.

Note that it has videoURL, autoPlay, showControls, and showSeekBar.

Now, how do I make my own versions of these for my own sub symbol? I want to be able to put in a keyword so that when I make this symbol it knows how to set up it’s textures and how to look. That way I can have one symbol that has multiple looks. So example of my own.

I am making a “button” symbol. In this symbol it can look like a play, stop, or pause button. When I pull this symbol into my parent hierarchy, I’d like in the reference section to have a field for “material,” where I will then say “play,” so when the symbol activates the script within it will know to set the material to play.

I know how to make this button otherwise, but this to me is a cleaner way of doing so. How do I make references under the Properties of a symbol? If there’s a document for this, please point me to it! I haven’t found it yet (or, it’s vague and I didn’t catch it in the symbol documents already.)

Thanks =)


Gosh, of course, as always… I spend 30 minutes trying to figure it out, then make a post about it… I go back and find it 5 minutes after posting.

Now I know where it is. I’ll play with it there. Is there a document on this feature?

For anyone else searching for this. In your symbol, look at the top of your hierarchy where the options are. That drop down menu has “references” in it. You can play with that there.


And now the issue becomes, how do I use the information found in that reference field. So if I have a reference field of type string, and I’ve entered the word play in there. How do I access that in the script inside that symbol? Where is it? How do I call it?

The only reference I can find to what I’m trying to do, is in the video streaming symbol that you can just plug in. I just don’t understand the scripting in there.

var sym : any = symbol;
myvid = Z.Video(sym.export("videoUrl")());

This is what I see. I don’t get how that happens to be working? Or even if I’m looking at the right example to accomplish what I want personally.


Hi there,

You can’t access a referenced property in a script node within the parent symbol, as it’s meant solely for use in the hierarchy.

If you have a property within a subsymbol that you’d like to access within a script in the parent you can use subsymbol communication.

Essentially, you’d export a variable or function from a script in the subsymbol, which you’d then be able to access from a script in the parent symbol.

Hope this helps.

All the best,


Then I suppose I’m confused. I’ve done the above and that’s cool too. Here are the panels I’m asking questions about though? Maybe I’m asking the wrong question? I just want to know how to utilize this feature. Or maybe it’s not really a feature anymore? The first image comes from “Videoplayer” symbol which you guys have already made. It’s under its properties. The second image is from inside the Videoplayer, and you access it from the Hierarchy menu under References.


My question is, from the Subsymbol Videoplayer. How do I write a script inside that subsymbol, that uses the values entered into that reference box? I’m not trying to write a script from my parent symbol to access them. =)


Did you ever get a good answer for this? I’m looking to use the References as well and can’t find any doc on it.



Hi @stevesanerd and @chioxin,

Hope you’re both well!

The references properties is a tool that allows specific properties of objects within a subsymbol to be changed from the parent through the GUI interface.

There are 2 ways in which it can be used -

  1. Reference existing properties of the subsymbol by right clicking on the property and selecting the reference tab. The name given to this property will now appear in the parent symbol and will work much the same as if you were to change/edit it from the subsymbol. I have added a visual example to explain this below -

  2. Or to create custom references for properties that do not exist in the list already. This can be done within the subsymbol by clicking the burger symbol in the hierarchy and selecting references. A modal will open and it will show all the references that have been added previously along with the option to create a new custom reference. As this is custom, the value can be changed and will modify the property option in the parent. For the example I have created a boolean (bool) value as I want a check box in the subsymbol properties in the parent. An example of setting this up is below -

Now a custom referenced property is set up, it can be accessed from within a script using the export change event handler.

//Check to see if the user has updated any values from the UI
symbol.on(“exportchange”, (name, value) => {

switch (name) {
    case "Exact Name From References":
        variable = value;


The string value within the " " must be the exact name set previously in the import modal. This will get the value and set it to a variable (please change the variable name).

In the example above, I had a boolean value and within the parent, it was checked (set to true). This value of true is now saved to this variable allowing it to be accessed to create an if statement making the plane visible or not on start depending on the users choice in the GUI in the parent!

Hope this helps, let me know if you have any questions. :slight_smile:




I am still blocked here, I have an integer variable that I want to change from the parent symbol property but when I copy the last script in my subsymbol script, I get:

"Invalid character.
Expected 2 arguments, but got 3.
Cannot find name “exportchange”.


Hi @MrPropre,

If you want just one reference property to be changed, you can use -


So for instance, if you wanted a variable in the subsymbol to be the value set in the parent properties you would use -

let integer = symbol.references.“Exact_Name_From_References”;

The switch statement above is a nice way of working out and assigning multiple referenced properties from the parent.

Hope this helps.



Thanks @George, I have managed to make the switch cases working, the problem was that copy/pasting the quotes from the forum broke the code… so I needed to write it again in the script editor.

To follow this topic, my next question is: Why I can’t get the path of a video file from a parent property into a subsymbol using an existing reference?

I try to make my own “Alpha video player” subsymbol with an Autoplay property and a “source file selection” property, but it does not display anything now…

Alpha video player test.zpp (7.2 MB)



I am still stuck on this, but close to do what I want…
Can somebody tell me how to get the source of an embedded video file that is imported in the main project library to a subsymbol video node?

Right now I am using the .source() function to call the video, but it only works when my videofile is embended in the subsymbol library, not from the main project library.



Still not working.
If I add a custom reference of type value “Native Video”, then I get my list of videos in the property and I even manage to get the raw name of the database in my subsymbol (for exemple “6811b508-f5f7-48cc-b3f3-59b8af4357ff”).

Then I tried to make a simple concatenation with the .mp4 extension but the video won’t display in the subsymbol. Can you tell me if this feature is possible or not so I don’t spend too much time on it?

Thanks George!


Hi @MrPropre,

I have looked through your question again and I think I understand the issue you are running into.

The parent symbol can get data from subsymbols, however, subsymbols cannot get data from the parent. So in this instance, you have a video file located within the parent and it is trying to be retrieved from the subsymbol, which isn’t possible and will give an error.

All the best,


I posted my video online and then used references to change it. That’s how it got the videos to work in my ancient history competition. It’s the same sub symbol used over and over for each individual item.



Thanks @George for your reply. I understand now. I managed to make it work in a far less elegant way, by using a simple string value (“filename.mp4”) in a reference.

And thanks @stevesanerd, I know that using an url would make it easier, but I would like to have local contents this time.