Tutorial:Context Menu
More actions
This tutorial attempt to be as generic as possible, providing fundamentals rather than specific examples, though with a focus on use on creation of custom menus for avatars. There are a number of ways to get the same end results result of them with either less components or with more features. Notes are included to help provide some ideas. This is not an exhaustive guide.
It also assumes being comfortable with the Dev Tool and Scene Inspector, including adding components and editing Slot Properties as making Context Menus is a more advanced subject.
At the end of this tutorial is a collection of videos that provide visual guides to the context provided in this tutorial. Or if you learn better that way. :)
Overview
Like everything else in Resonite, Context menu(Also called the 'Radial Menu') are made from a combination of slots and components with the occasional sprinkling of ProtoFlux.
Slots provide the menu layout/structure. Components provide the functionality. Basic parts can be found under: "Radiant UI > Context Menu" in the Component Browser.
The core component of the Context menu is the ContextMenuItemSource each menu item in a slot that contains this component. It allows setting the menu's name, colour, icon as well as change behaviors. For example, CloseMenuOnPress makes the context menu close when selected and AllowDrag allows users to press the buttons by dragging the cursor from the center circle to the item instead of clicking.
The ContextMenuItemSource sends an IButton event, triggering one of a number of of possible components in the same slot. For example, ButtonToggle or ButtonValueCycle. For the full list, see: Category:Components:Common UI:Button Interactions.
The other most commonly used component is the ValueOptionDescriptionDriver, this allows the values in ContextMenuItemSource to be changed controlled by a value elsewhere. For example, the two most common is changing the menu title between 'On' to 'Off' or the colour from Red to Green, depending if a setting is on or off. Or more complicated behaviors when cycling.
Root and sub menus
While a context menu can grow to any depth, for custom menus typically you would want to start with a new menu in the Context Menu. Try to limit the number of menus that use this as it can cause a lot of clutter. For an avatar, it's best to have a single 'Avatar' menu with resulting sub menus.
The RootContextMenuItem puts the resulting menu item directly in the users main context menu.
ContextMenuSubmenu is the component that provides the references to the next level up in the menu.
Required components:
- RootContextMenuItem: With the
Itemsfield populated with a reference to the component below. - ContextMenuItemSource: Title and visual details of the menu item.
- ContextMenuSubmenu: Unless you want a single item,
ItemsRootshould be the slot to the next part of the menu.
Back button
Back buttons are simply a ContextMenuSubmenu but instead of going up one slot, it goes down.
Create it as you would a sub menu, but place the previous menu's slot in ItemsRoot instead of a higher one.
Toggles
Normally this takes advantage of the ButtonToggle component. It requires a field to toggle, this can either be used toggle the Active field of a slot or component, the state of a ValueField<bool> or using BooleanValueDriver to control blendshapes.
Required components:
- ContextMenuItemSource: Title and visual details of the menu item. Often controlled by a ValueOptionDescriptionDriver.
- ButtonToggle: This is the actual part that toggles the
TargetValuebetween True and False.
One of:
- A Value to drive directly: This can be any bool on the avatar or item. For example, the
Activefield of a clothing slot. - ValueField<bool>: If the value is going to be used elsewhere or via a component that requires a Target field.
- BooleanValueDriver<float>: Connecting ButtonToggle to this component's State field allow driving of BlendShapes directly. See component for examples.
- ValueMultiDriver: Used if you need to drive a number of fields(For example several clothing items), not just a single one.
Other parts:
- ValueOptionDescriptionDriver<bool>: Changes the title, colour and other details. Set Value to the same field that ButtonToggle toggles.
Notes: MultiBoolConditionDriver is a handy way to control things if a number of blendshapes or toggles interact. See component for details.
Cycling
This uses one of a number of cyclic button components, the example below uses ButtonValueCycle as it easily allows each option to be customized.
Required:
- ContextMenuItemSource: The actual Title and visual details of the menu item.
- ButtonValueCycle: This is the part that provides the actual cycling, pressing the Add button allows for any number of discrete items that will be cycled through. Set it's
TargetValueto the option chosen bellow.
One of:
- A Value to drive directly: This could be something like a BlendShape of a SkinnedMeshRenderer
- ValueField: This is where the value is stored for use by another component or flux.
- ValueMultiDriver: Used if you need to drive a number of fields from the same value, not just a single one.
Other parts:
- ValueOptionDescriptionDriver: Changes the title, colour and other details. Set Value to the same field that ButtonToggle toggles.
Other methods
If you want to cycle through just a series of ints, ButtonValueShift with ValueTextFormatDriver to change the Text field of the ContextMenuItemSource. Combined with BooleanSwitcher it allows an easy way to toggle between many bools, for example a series of clothing item that need to be shown one at a time. BooleanAssetDriver also ties in well with this as a way to swap between two materials or textures on the clothing/model.
You can use ButtonReferenceCycle and ValueOptionDescriptionDriver<Reference> to for example change between a collection of textures. Or one of the int cycles and MaterialSet to for more advanced material switching.
You can also use triggers as below to do the counting in ProtoFlux using Increment, a compare, an if and a write node.
Triggers
The Context Menu doesn't only need to drive components such as ButtonToggle, it can also be used to trigger impulses using the ButtonEvents ProtoFlux node. Simply drag the ContextMenuItemSource component into the 'Button' field at the bottom of the node to set the reference. Then every time the context menu item is clicked, it sends an impulse to do whatever you want.
Sliders
Resonite doesn't yet support context menu naively(GH#718), however a number of community examples exist.
Simple slider based on colour visuals
resrec:///U-IHaveAName2653/R-69266D1AFE8909A324A804DD8C288C9478DF6CECED2AB42055A072C0DD17B4FA IHaveAName's public -> Prefabs -> Conext Menu Prefab V1.5
Examples: Also includes slider, toggle and Button.
More complicated example with more traditional UI design
resrec:///U-art0007i/R-8DD3F38F960FFA10E71D909CC7F09587D1EA9FD14F4E44F96EE5E357F78F6BE4
Arti's Public > Examples > VRChat Radial Puppet
Icons
There is a field for an icon or Sprite in ContextMenuItemSource and ValueOptionDescriptionDriver.
The component SpriteProvider allows conversion of a texture into a sprite. Add the component, drag an image into the Texture field, then drag the whole component into the Sprite field of either ContextMenuItemSource or ValueOptionDescriptionDriver.
A good place to start looking for icons is either: https://fonts.google.com/icons
Or for the ones used on the UI: Resonite Essentials -> Assets -> Resonite Assets -> Resonite Presskit -> Icons
Resources
Example menu will be in Electra's public folder at the end of this:
resrec:///U-1cLc1qmP4CG/R-6C7EF13BF825579A8E5A82098E53563106C41994C4679BCDAF1A88FE186C53E4
Resonite Icons: resrec:///G-Resonite/R-21E2CE17AE95C45864C138508205683FFC603A488D63088D31B06582445A7F88
World for making your own menus in game: Context menu creation tool(M.C)
Videos
Youtube tutorial that goes over setting up simple toggles with several examples. Shows creating a toggle for your tool shelf, clothing toggles, and cycling multiple options on one button from scratch.
Video by Flux: Covering mostly just toggles, however showing clever uses of ValueTextFormatDriver to change the menu's text fields.
Examples
Should these be on another page?
- Toggling clothing
- Toggling blendshape
- Using a slider to change a size/colour.