Button

A basic control that can respond to player touch input. Can be styled to have custom artwork for both the background and face image.

Properties

type - "button". Specifies the control type.

action - string. Action(s) to be invoked when a player touches the button.

enabled - boolean, optional. Defaults to true. Sets the visual state of the control to enabled/disabled. A disabled control will still receive input from the player but not change the visual style based on the input.

pullAction - string or object, optional. The Action(s) to be invoked when a player pulls the button during a touch. When defining the pull action as an object, as shown in the below samples, the pull button becomes segmented such that each item in the pull action items array assigns an action to that segment. Segments are spaced evenly around the button with up to 4 segments allowed.

• Segmented Pull Action Properties (Introduced in v4.1)

  • type - "segmented". Specifies the type of the pull action to be a segmented pull action.

  • items - array. An array of up to 4 Action(s), each of which is invoked when a player drags or pulls a touch to the edge of the control in the direction for that segment.

toggle - boolean, optional. Defaults to false.

• If false, input for the button will be sent when pressed and not when not pressed.
• If true, each press of the button will switch if input is being sent for the corresponding action(s) .

visible - boolean, optional. Defaults to true. Determines whether the control is displayed to the player to interact with. To change during game play, see Changing touch layouts using game state.

styles - object, optional. Customization of the visual representation of the control. The styles are represented as an object per state that can be styled.

The button control can have the following states styled.

• default - The base style.
• disabled - The style when the control is disabled. If not specified, when the control is disabled, a transformation will be applied to the default style to make it appear disabled.
• idle - Applied when the player isn't interacting with the control.
• activated - Applied when the player is touching the button.
• pulled - Applied when the player is touching and pulling a button. For segmented pull actions, only the single segment being pulled is styled with this state; other segments retain the activated styling.
• toggled - Applied when the button is in a toggled state and the player isn't touching the button.

Styling properties per state

opacity - number, optional. The opacity to be applied to the control. Default to 1.0 for all states but disabled.

faceImage - object, optional. Can either be an icon or image asset.

background - object, optional. Can either be a color or an image asset. Isn't visible in idle and disabled states.

Asset dimensions

For each of the style objects that accept image assets, a given asset is provided at a base resolution and at 1.5x, 2.0x, 3.0x, and 4.0x scales of that base resolution. The resolution of a given image must be less or equal to the following maximum resolutions.

Remarks

Buttons are commonly used to allow the player to perform actions that would normally be done by one or more physical buttons on their physical controller.

Utilize multiple actions to enable the player to easily replicate combination actions (for example, press the left bumper and the right bumper simultaneously).

Styling remarks

When in the activated state, the faceImage is displayed 25% smaller.

There are labels and default styling for the background color for buttons that don't use custom assets and have a single action of gamepadX, gamepadY, gamepadA, or gamepadB.

Samples

Example 1: Jump button mapped to the A button

{
    "type": "button",
    "action": "gamepadA",
    "styles": {
        "default": {
            "faceImage": {
                "type": "icon",
                "value": "jump"
            }
        }
    }
}

Example 2: Crouch button mapped to pressing the left bumper and the right bumper simultaneously

{
    "type": "button",
    "action": [ "leftBumper", "rightBumper"] ,
    "styles": {
        "default": {
            "faceImage": {
                "type": "icon",
                "value": "crouch"
            }
        }
    }
}

Example 3: Button with custom face image and background image

{
    "type": "button",
    "action": "gamepadA",
    "enabled" : true,
    "styles": {
        "default": {
            "background": {
                "type": "asset",
                "value": "hex_background"
            },
            "faceImage": {
                "type": "asset",
                "value": "one"
            }
        },
        "activated": {
            "background": {
                "type": "asset",
                "value": "hex_background_glow"
            }
        }
    }
}

Example 4: Segmented pull action with custom styling per segment

{
    "type": "button",
    "action": "gamepadA",
    "pullAction": {
       "type": "segmented",
       "items": [
          "gamepadB",
          "gamepadY"
       ]
    },
    "styles": {
        "default": {
           "pullIndicator": [
               {
                 "faceImage": {
                    "type": "icon",
                    "value": "sword"
                 }
               },
               {
                 "faceImage": {
                    "type": "icon",
                    "value": "block"
                 }
               }
            ]
        },
        "idle": {
           "pullIndicator": [
               null,
               {
                 "opacity": 0.5
               }
            ]
        }
    }
}

Requirements

Minimum Layout Version: 1.0+ (Styling support in 2.0+).

See also

Touch Adaptation Kit Reference