# Constellation menu

![](https://developers.google.com/static/vr/images/const-menu.png)

The constellation menu is a gesture-based interaction model that helps users
navigate deep information hierarchies in a simple, responsive way. When a user
triggers the constellation menu, options radiate out from the reticle to
indicate possible paths the user can take down the hierarchy. Upon hovering over
a category option, more options appear, and previously traversed rings of
options recede into the distance to make more room for more items.

This menu gives users the ability to easily explore available options and
ensures that upon triggering the menu, options are only one click away. As the
user pursues a particular path, a line is drawn to connect previously selected
nodes. This creates a unique visual path for each item that helps the user develop
muscle memory for frequently selected items.

Use cases for constellation menus include item inventories, simple file
directories, and enterprise applications. In this example, we use the
constellation menu to present categories of 3D objects that the user can place
in the surrounding environment.

## Getting Started

Constellation Menu is available as part of Daydream Elements.

To Use the Constellation Menu, first add the `ConstellationMenuRoot` prefab to
your scene. The primary script in this prefab is `ConstellationMenuRoot`, which
creates and destroys the menu based on controller input.

## Customization

The `ConstellationMenuRoot` script has the following fields which can be
customized according to your use case.

- **MenuTree** : `ConstellationMenuRoot` uses the same hierarchical menu system Daydream Elements uses in other demos. Create a `ConstellationMenuTreeData` asset and populate it with the menu items you want. See [building a menu section](https://developers.google.com/vr/elements/constellation-menu#Building_a_menu) for more details.
- **Laser Pointer**: Typically, menus need to appear closer to the user than the background elements in the scene. This means that the laser reticle may need to adjust the distance from the controller when a menu is opened. Link the active laser pointer here to allow the reticle to update its distance.
- **Menu Activation Button:** The input event that will allow the menu to open. This is typically a press or release of the app or touchpad buttons.
- **Menu Icon Prefab:** A prefab used to spawn each menu icon.
- **Line Shortening Distance**: A line is drawn between each icon in the path of the hovering icon. Setting Line Shortening Distance will trim the ends of that line by the given distance.
- **Menu Distance:** The distance away from the controller in meters to spawn the Constellation Menu.
- **Close Angle:** The menu will automatically close when you point away from the center by more than this angle.
- **Open FoV Angle:** The menu will only open if the laser is within the field of view by less than this angle. This prevents accidental menu openings.
- **Expandable Icon Decoration (optional)**: This sprite will be used (along with the icon background) for each icon which is in the selected path and can be expanded.
- **Icon Background (optional)**: This background will be used for each icon in the selected path.
- **Hover Delay**: This only applies to icons not in the path of the hovering icon. This is how long in seconds the laser has to point at them before they become the new hover icon. This is to prevent accidentally making icons hover as the user moves the laser pointer around.

## Building a menu

1. Create a ConstellationMenuTree by going to **File \> Assets \> Create \>
   DaydreamElements \> ConstellationMenu \> Tree**.
2. Create a Constellation Menu Item for each menu icon you want to add by going to **File \> Assets \> Create \> DaydreamElements \> ConstellationMenu \>
   Item**.
3. Set the ConstellationMenuItem fields as desired:
   - **ID** : (optional) You may use this field as an identifier. It isn't used by the `ConstellationMenuCode`.
   - **Icon**: This is the foreground image for the button. Avoid text and opt for recognizable icons.
   - **Prefab** : (optional) You may use this to attach a serialized `GameObject` to the Item.
   - **Tool Tip**: (optional) This text is drawn beneath the icon if set and the Tooltip Sprite is not set.
   - **Tooltip Sprite** (optional): This sprite is drawn beneath the icon if set.
4. Each ConstellationMenuItem can then be added to the menu tree by dragging them into the ConstellationMenuTree. Items can be nested as children or as siblings to construct a hierarchy.

## Listening for events

ConstellationMenuRoot provides the following events:

- **OnMenuOpened**
- **OnMenuClosed**
- **OnItemSelected**
- **OnItemHovered**

In order to listen to menu events, either `AddListener` to these events or add
listeners in the editor. **OnItemSelected** is invoked when the user clicks on
an icon. **OnItemHovered** is invoked when a user points the laser pointer at an
icon. Both of these will pass the `ConstellationMenuItem` attached to the icon
to the callback function.

## Backgrounds and lines

Backgrounds for each icon fade in and out depending on the icons state and which
icon was most recently pointed at. The primary background is set via the
**Icon Background** variable on the RootMenu. A secondary decoration can also
be set there via **Expandable Icon Decoration**. This secondary icon can also
be offset to be behind the primary background or in front of it by changing the
transform saved in its prefab, \`ConstellationMenuDecorationLabel.