MenuHandler

A crosswalk client module to handle UI menus using tagged instances (built with the tag-effect library).

Installation

Add @crosswalk-game/menu-handler in your dependencies:

yarn add @crosswalk-game/menu-handler

Or if you are using npm:

npm install @crosswalk-game/menu-handler

Content

• open

• push

• back

• close

• toggle

• whileOpened

• Tag effects

  • MenuInstance of MenuExtension
  • Menu Navigation

open(menuId: string)

• Description: Opens the menu with the specified ID. Closes any menu that are not explicitly marked as compatible with the ID.

• Parameters:

  • menuId: The unique identifier of the menu to open.

push(menuId: string)

• Description: Similar to the open function: it opens the menu with the specified ID and closes any menu that are not explicitly marked as compatible with the ID.

Additionally, it saves the current menu state into the history stack before opening the new one. Calling back will return to that state.

• Parameters:
  • menuId: The unique identifier of the menu to open.

back()

• Description: Go back to the previous menu state from the history stack. State is added in the history stack when calling push.

close(menuId: string)

• Description: Closes the menu with the specified ID.

• Parameters:

  • menuId: The unique identifier of the menu to close.

toggle(menuId: string)

• Description: Toggles the state (open/close) of the menu with the specified ID.

• Parameters:

  • menuId: The unique identifier of the menu to toggle.

whileOpened(menuId: string, effect: () -> Teardown): () -> ()

• Description: Executes the specified effect while the menu with the specified ID is open. The effect will automatically be cleaned up when the menu is closed.

• Parameters:

  • menuId: The unique identifier of the menu to target.
  • effect: The effect to execute while the menu is open. This function return any kind of teardown object (for example: nil, a cleanup function or event connections) that will automatically get cleaned up when the menu is closed.

• Returns: A function to remove the effect.

Tag Effects

This module defines a series of tag-effects to define menus (that can be opened or closed) or buttons to open, close or toggle those menus.

MenuInstance or MenuExtension

Allowed instance class: GuiObject, LayerCollector, ProximityPrompt, BoolValue

Those two tag-effects are used to define a new menu with the given id. The difference between a MenuInstance and a MenuExtension is how they influence other menus:

• when a MenuInstance is opened, all other MenuInstance will be closed (except other MenuInstance objects explicitly marked as compatible with the opened menu id)
• when a MenuExtension is opened, it does not change other MenuInstance or MenuExtension objects

Both tag-effects have the same base configuration:

Configuration:

• id (string): identifier for the menu

Optional:

• defaultState (boolean): define if the menu is visible (or not) by default

Optionally, the MenuInstance tag effect can also be configured to mark other menus as compatible with itself, by adding string attributes set to other compatible menu id. For example, one could add an attribute compatibleWithStore = "Store", where Store would be another MenuInstance id.

Menu Navigation

There are various tags to navigate through menus: OpenMenu, PushMenu, BackMenu, CloseMenu and ToggleMenu.

These tag-effects can be used bind a signal to open, close or toggle a menu. They can be applied to any kind of instances:

• GuiButton: which will trigger on the Activated event
• ClickDetector: which will trigger on the MouseClick event
• ProximityPrompt: which will trigger on the Triggered event
• Any other instance, if the eventName attribute is set to an appropriate event name

Configuration:

• id (string): identifier of the menu that needs to be opened/pushed/closed/toggled. (excepted for BackMenu, this field is required)

Optional:

• eventName (string): specify which signal to use to bind the behavior

License

This project is available under the MIT license. See LICENSE.txt for details.