Screen Symbol
Studio is being deprecated, please head over to the documentation page for Mattercraft, our most advanced 3D tool for the web, where you can find the most recent information and tutorials.
A Screen symbol is a form of symbol designed for building discrete areas or screens within an experience. Screen symbols are great for components like high score tables or instruction boxes that take up the whole screen and encapsulate their own user journey.
By default the root node of a Screen symbol is relative to Z.screen.
Creating a Screen Symbol
Section titled “Creating a Screen Symbol”A Screen symbol can be created by clicking on the plus icon from the Symbol Definitions panel, selecting the ‘Screen symbol’ template, and giving the symbol a name. Selecting ‘Create’ will add the subsymbol to the list of Symbol Definitions.
Setting up a Screen Symbol##
Section titled “Setting up a Screen Symbol##”Double clicking a subsymbol within the Symbol Definitions list will open the subsymbol allowing functionality to be added. Each subsymbol has its own Hierarchy, Media Library, Scene View and Controllers, just like the parent symbol.
To return to the parent symbol click on the gear icon in the top middle of the window, next to the name of the subsymbol.
Using a Screen Symbol
Section titled “Using a Screen Symbol”Once back within the parent symbol, some script will have to be written to construct and display the new Screen symbol.
Displaying a Screen Symbol
Dragging a subsymbol into a script adds code that constructs a new instance of the symbol and assigns it to a variable.
// The symbol variable 'hi_score' assigned to a new instance of the hi_score subsymbolvar hi_score = symbol.symbolDefinitions.hi_score();
This variable can be used to display the subsymbol by calling display( ).
For example a plane can be added to the root symbol with a pointerdown
event handler attached. display()
can then be called within the event handler function to display the Screen symbol when the user presses it.
Example:
// In a script node in the parent symbol
// Construct a new instance of our subsymbolvar hi_score = symbol.symbolDefinitions.hi_score();
// pointerdown event handlerparent.on("pointerdown", parent_pointerdown);function parent_pointerdown() { // Runs when pointerdown occurs on the parent node // Display the subsymbol hi_score.display();}
Closing a Screen Symbol
Once a subsymbol has been displayed, it can be closed by calling symbol.close();
from within the subsymbol.
Example:
// In a script node in the subsymbol
// pointerdown event handlerparent.on("pointerdown", parent_pointerdown);function parent_pointerdown() { // Runs when pointerdown occurs on the parent node // Close the subsymbol symbol.close();}
Hiding the Parent Symbol
Section titled “Hiding the Parent Symbol”It is also possible to hide the parent symbol after calling a subsymbol to display by calling symbol.hide();
from a script node within the parent symbol. The example below shows the subsymbol’s display function being called and then the parent symbol’s hide function.
Example:
// In a script node in the parent symbol
parent.on("pointerdown", parent_pointerdown);function parent_pointerdown() { // Runs when pointerdown occurs on the parent node // Display the subsymbol hi_score.display(); // Hide the parent symbol symbol.hide();}
Once the subsymbol is closed, the parent symbol should be shown again. To do this we need to attach a handler function to the subsymbol instance’s close event and call symbol.show();
.
Example:
// In a script node in the parent symbol
parent.on("pointerdown", parent_pointerdown);function parent_pointerdown() { // Runs when pointerdown occurs on the parent node // Display the subsymbol hi_score.display(); // Hide the parent symbol symbol.hide();}
hi_score.on("close", display_parent_symbol);function display_parent_symbol() { // Runs when the 'hi-score' subsymbol is closed // Show the current symbol, the parent symbol symbol.show();}
For the above example to work the
hi-score
subsymbolsclose
event must be emitted. This is achieved by callingclose()
on it within a script node like in the ‘Closing a Screen symbol’ example.
Next Steps
Section titled “Next Steps”Having covered the two primary templates, the following article will discuss Attachment Points, a way of exposing points within a subsymbol to be used within a parent symbol.