Andys Screens And Buttons

This package enables creators to add a menu system to their game. The menu system is accessible by controller, keyboard and mouse or touch input.

Use the Andys Screens And Buttons Blueprint to see a working example of this package.

To install the package into your game:

  1. Install “Andys Scripts And Buttons”
  2. Add the UserScreens Script Folder Template to the User Template
  3. Add the example button into the world

If you test the game you will now see it start with a Title Screen. You can play the game and then interacting with the free standing button will take you to the Game Over screen.

It is recommended that you set your control scheme to use the “Custom” Touch Input Method.

Adding a new screen
  1. Add the UserScreens Script Folder to your User Template, or create a new Script Folder (for the purposes of this tutorial we will refer to the Script Folder you use to organise your screens as UserScreens).
  2. Create a new Script Folder within UserScreens in the User Template.
  3. Add the userScreenScript to the Script Folder.
  4. Configure the userScreenScript as per your requirements (see configuring userScreenScript).
  5. (Optional) If you don’t want to write your own widget, create a duplicate of the titleScreenWidget in the Library and rename it (e.g. playerStatsScreenWidget).
  6. (Optional) Configure the widget to display the title and buttons of your choice.
  7. (Optional) Add the widget to the userScreenScript:screenWidgets array.
Configuring userScreenScript

userScreenScript is the logic for what happens on this screen. This includes what widgets are shown, what player inputs will do on this screen and handles the spawning logic for the player. This script can work independently of widgets in order to navigate between different game states, or even to just show custom onscreen buttons.

** Functions **

The state of the screens is set internally in the script with self.active. This is inaccessible outside of the Script to ensure that script clashes and race conditions are avoided.

Show() / Hide()
It is best practice to use the button events on the userScreenScript to show and hide the different screens. Order them in the bindings so that hiding the current screen is first, and showing the next screen is second. Avoid showing more than one screen at once (this wasn’t built for that!).

ShowScreenWithName(screenName (string))
If you need to change the screen from outside of the User template be sure to use user:SendToScripts(“ShowScreenWithName”, [screen name]). You can use showScreenScript to call this function without code.

Properties

Name (string)
Useful if you need to inject some Print statements to follow the code. This is also used for the UserScreenScript:ShowScreenWithName(screenName) function to show/hide the screen based on the name.

Show On Init (boolean)
Make this the default screen and show o the user when they login.

Visuals

Configuration properties for in-game visuals whilst screen is active.

Use Spawn Camera (boolean)
This is only selectable if respawnPlayer is true and there is at least one spawn point (entity | locator). You can add a camera as a child of the spawn point locator and checking this box will automatically use the camera that is the child of that spawn point locator (seen on GameOverScreen in the demo).

Camera (entity | camera)
Select a camera entity in the game world to use that camera’s view as the backdrop for the menu. This will only be available if Use Spawn Camera is false (or despawnPlayer is true).

Screen Widgets (widgetasset array)
Set which widgets should be shown when this screen is active. The API can only find one widget of each widgetasset so you cannot use copies of the same widget on different screens. Make duplicate widgetasset’s and name them differently if you want to re-use similar widgets.

Controls

Properties for the controls on this screen.

Control Scheme (string)
The name of the control scheme to use on this screen (from the Game tab). This is useful to clear the screen of input buttons on mobile (set the Touch Input Mode to custom), or if this screen relates to gameplay and you want to offer a different control scheme for the help screen. If blank the default control scheme will be used. NOTE: There is currently a known bug that doesn’t allow switching of Touch Input Modes.

Lock Player Input (boolean)
If true then input will be disabled for controlling the player character.

onPrimary / onSecondary / onJump / onExtra1 / onExtra2 / onExtra3 / onExtra4 (event)
These events can be used to map inputs to functionality. For example On Jump could hide the titleScreen, show the gameplayerScreen and start the game.

Spawn

Properties for controlling if / how the player is spawned when this screen is active.

Despawn Player (boolean)
If true then the player will be despawned from the game. This will disable the options to “Use Spawn Camera” and “Respawn Player” as there will be no player visible when this screen is active.

Respawn Player (boolean)
If true then the player will be respawned at one of the Spawn Points. If no Spawn Point is set then the player will be spawned at the default spawn point for the world.

Player Template (template)
The player template to use when spawning the player. If blank then the default player template will be used.

Spawn With Effect (boolean)
Whether to spawn the player with their spawn-in effect. I recommend you use this wherever possible as it gives players an opportunity to express themselves with their spawn animation.

Spawn Point (entity | locator array)
Set one or more spawn points if you are respawning your player. Use multiple spawn points if there are lots of people in your game to avoid them spawning over each other. I would advise creating the same number of spawn points as max players. If you have multiple spawn points then it will select the one without anyone occupying it (similar to how the Auto-Respawn package works).

On Show (event)
Fired when this screen is made active.

On Hide (event)
Fired when this screen is no longer active.

Configuring titleScreenWidget

titleScreenWidget is a basic “main menu” widget that is designed to work with userScreenScript. It features a space for a title and subtitle, as well as buttons which display context-aware input icons (or not if user is on touch device)

Properties

Title (text)
The main title of the page.

Tagline (text)
The subtitle.

Buttons

The Buttons properties are an indexed system that relate to each other. If you have 3x buttons then you should expect 3x elements in titles, inputs and keyBindings respectively. Each element should be at the same position as related elements, e.g. input[1] contains “jump”, so keyBindings[1] should contain “{jump-icon}”.

Laying out the buttons can be partially executed by adjusting the size and anchors of the widget. For example, if you want the buttons in the left half of the screen you can set the size.x of the widget to 50 (50% of screen width) and the anchor.x to 0 (align to left side of screen). Then setting the Alignment property of the widget to “left” will align the buttons to the left side of the screen.

Titles (text array)
The titles to display on the buttons. The number of titles will determine how many buttons there are.

Inputs (string array)
The input that each button should fire when clicked. For example, adding “jump” as an element will ensure that button fires Input.PressInput(“jump”) when pressed and Input.ReleaseInput(“jump”) when released.

Key Bindings (string array)
The context-aware input to display on this button. E.g. “{jump-icon}” will ensure that the users jump button is displayed under the button - for keyboard (space) or controller (A). If the user is using mobile then no key binding will be displayed.

Button Style

These properties refer to the style of the buttons (no way!).

Direction (string)
Whether buttons should be displayed horizontally (“horizontal”) or vertically (“vertical” - default).

Alignment (string)
Mostly for use when buttons are displayed vertically. This determines whether the buttons are aligned “left”, “right” or “center”.

Font Size (number)
Font size for the buttons.

Background Color (color)
Background color of the buttons. All buttons are the same background color. To make different buttons different color will require editing the widget code.

Font Color (color)
Font color of the buttons.

Key Background Color
Background color of the key binding prompt.

Key Font Color
Font color of the key binding prompt. Note that in the case of controller buttons the buttons will be the font color, with the character on the button the Key Background Color.

4 Likes

I think it would be even better if we could also select buttons by pressing up / down on the keyboard / controller. Or even click the buttons with the mouse. Give the user any option they want on how to use the menu :slight_smile:

3 Likes

OK! I 100% agree - navigating the menu with directions on controller should be easy enough, and also improves accessibility. I’ll look into that, thanks for the suggestion.

Notes: possibly add override hotbar navigation too.

Maybe need a “Advanced mode” boolean like the customisable effects to hide all the specific use-case buttons from novice users.

Further ideas:

A confirmation option on buttons so the player gets prompted with “Are you sure?” once they press a button. A property on the example widget “requires confirmation” should do it, but will be useful if someone were to use it on a “save game / delete game” menu.

Change the widget strings for text to enable translation.

Examples of buttons using images.

Examples of leaderboard on Game Over screen with player images.

A cleaner way to organise button details and control hooks - Adam O had a good suggestion on this using multiple “buttonData” scripts as our data models. Gathering them with FindAllScripts and generating a data model that we can feed to the widget (which then populates the buttons). This will create a much cleaner way to make buttons.

3 Likes