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

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##

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

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 subsymbol
var 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 subsymbol
var hi_score = symbol.symbolDefinitions.hi_score();

// pointerdown event handler
parent.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 handler
parent.on("pointerdown", parent_pointerdown);
function parent_pointerdown() {
    // Runs when pointerdown occurs on the parent node
    // Close the subsymbol
    symbol.close();
}

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 subsymbols close event must be emitted. This is achieved by calling close() on it within a script node like in the ‘Closing a Screen symbol’ example.

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.

Next Article: Attachment Points