// XRC Students wi2024-ws02-cwp57
Overview
This package is an implementation of a customizable radial marking menu. Users can create menu items with icons or labels that hook up to and trigger public functions in the scene, as well as create nested submenus to organize them. These functions can be triggered intuitively through quick movements, encouraging muscle memory development and making tool use feel seamless.
Watch a demonstration video here.
Components
Marking Menu
This component contains the main logic for the Marking Menu interaction technique. The Marking Menu technique allows for simple invocation of functions in the scene through quick and intuitive hand movements, while also allowing for a wide variety of options through nested submenus.
This script holds a reference to the user's viewpoint and controller to orient the menu, along with information about the menu's structure and the functions it calls.
| Property | Description |
|---|---|
| XR Camera | The transform of the user's viewpoint. |
| XR Controller | The transform of the XR controller used for operating the menu. |
| Outer Radius | The radius of the outer ring of the marking menu. |
| Inner Radius | The radius of the inner ring of the marking menu. |
| Menus | A list of marking menus operated by this controller. See Menu Structure for more information. |
| Submenu Move Time | The time it takes the menu to move when going into or out of a submenu. |
| Submenu Hover Time | The amount of time a submenu must be hovered over before it is selected. |
Marking Menu Input
This component handles the user input, and calls the corresponding methods in the Marking Menu component.
| Property | Description |
|---|---|
| Menu Action | The input action property associated with opening and closing the menu. |
Marking Menu Feedback
This component renders a menu based on the properties of the Marking Menu component, such as the number of menu items and their labels. It mirrors the current state of the menu, and provides visual & haptic feedback to indicate actions such as opening & closing the menu or selecting an item.
The menu has an optional time delay, where the menu will first open in a minimized view before expanding to the full menu. See Expert Mode for more information.
| Property | Description |
|---|---|
| Placeholder Prefab | The placeholder used if a menu element does not have an associated GameObject. |
| Backwards Prefab | The GameObject used to represent the backwards element (optional). |
| Ring Prefab | The prefab used to create the menu ring. |
| Ring Color | The color of the ring's background. |
| Line Color | The color of the segment outlines. |
| Hover Color | The selection color for the segment outlines. |
| Time Delay | The amount of time that the minimized menu will be shown. See Expert Mode for more information. |
| Expand Time | The amount of time it takes for the menu to expand from its minimized version. |
| Shrink Time | The amount of time it takes for the menu to shrink down after closing. |
Installation instructions
To install this package, follow these steps:
- In the Unity Editor, click on Window > Package Manager
- Click the + button and choose Add package from git URL option
- Paste the URL to the package repository: https://github.com/xrc-students/xrc-students-wi2024-ws02-cwp57.git in the prompt and click on Add (make sure your URL ends with ".git")
- If the repository is private, you will be asked to authenticate via your GitHub account. If you haven't been granted access to the repository you will not be able to install the package.
- The package should be installed into your project
- You can download the package samples from under the Samples tab in the Package Manager
Note: Even though the package documentation is public, several XRC packages are private and accessible only to XRC staff and students.
Requirements
This package was developed and tested using the following Unity Editor version:
2022.3.7f1 LTS
Dependencies: Input System, Text Mesh Pro, XR Interaction Toolkit.
Limitations
- The radial ring in the marking menu usually renders behind other transparent objects (such as text), which may result in confusing perspective if text is used commonly elsewhere in your scene.
- The fields contained in the inspector are only modifiable in the inspector and not editable at runtime - the menu structure cannot change during use.
- The menu is limited to invoking Unity Events.
- The menu is not responsive to external factors, e.g. there is no ability to grey out or hide an option in the menu if it is currently disabled. Feedback that a function is not available needs to be integrated into the function the menu calls.
- While the menu structure can be copied/saved by Copy Component or saving as a prefab, the direct connection to GameObjects in the scene means it has to be re-populated with function references for each new scene.
- There is a cap of ~20 items in a single menu past which the scripts will begin to throw errors.
Workflows
To add the marking menu to your scene:
- In the Hierarchy window, right click to create an asset at the root level, then navigate to XR Collaboratory > XRC Marking Menu to create a GameObject with the necessary components. Alternatively, you can make it manually by creating an empty GameObject and adding the Marking Menu, Marking Menu Input and Marking Menu Feedback components.
- Customize the Menu field in Marking Menu, choosing functions to call, setting names/icons, and creating submenus if needed. See Menu Structure for more information.
- Ensure that the input action field in Marking Menu Input is properly mapped to your desired input.
- Adjust other settings (including color & size) as needed.
Advanced Topics
Expert Mode
The Marking Menu Feedback component contains an important setting, Time Delay, whose ideal value changes significantly depending on the target application. It indicates the amount of time that the menu spends in a minimized "expert mode" when first opened. The menu still provides feedback and directional information in this minimized state, but is much smaller and does not display icons. This is intended to help encourage development of muscle memory, and to reduce distractions for expert users.
In applications where users are expected to build up mastery of the program or tool over time, it is recommended to keep Time Delay at the default level of 0.4 seconds or higher; however, in situations where users are not expected to have or build mastery of the tool, it is recommended to either lower or outright remove Time Delay.
Menu Structure
The data structure used to define the menu hierarchy in the Marking Menu component can be slightly unintuitive, so this section explains it in detail.
The menu is stored as a list of menus, without a strictly defined hierarchy. The first menu in the list is the "main menu" that will appear when the user opens the marking menu; all others are "submenus" that must be opened via a submenu element. Their order does not matter beyond the first element; however, all menus must have unique names.
Each menu contains a name and a list of items, each with their own properties. An item can either be a normal item or a submenu; the visible fields in the inspector will change accordingly.
| Property | Description |
|---|---|
| Name | The name of this menu item; will be used as a label if GameObject is empty. |
| GameObject | Optional prefab to be used as an icon in the Marking Menu Feedback component. |
| Is Submenu? | If true, this menu item connects to a submenu rather than triggering an event. |
| Unity Event | The Unity Event that will be triggered when this item is selected. Only used if Is Submenu? is false. |
| Submenu Name | The name of the submenu this item is linked to. Only used if Is Submenu? is true. |
The order of items in a menu matters; starting with the first item, they are placed in a clockwise order.
In a submenu, there will be a backward element pointing in the direction the submenu came from; menu items will be placed in a clockwise order starting after said backwards element.
Samples
Example Scene
An example scene demonstrating the marking menu implementation.