Scripting

Building Game Elements with Custom UIs

By Meta

Hands-On Challenge: Building Game Elements with Custom UIs

Create custom UI panels
Build an interactive custom UI
Player-specific custom UI
Video Presentation on how to build performant CUIs

Hands-On Challenge Overview

Want to learn how to build a dynamic Custom UI panel that responds to player input? This challenge will help you understand the basics of UI panels and interactivity.

You’ll learn how to:

Set up a Custom UI gizmo and attach a script.

Create a panel using the Custom UI API.

Add interactive elements like buttons.

Use bindings to update UI content in real time.

Estimated Time: 1 hour

What You'll Need:

Access to the Meta Worlds Desktop Editor.

An existing world project or a new one to work in.

Basic familiarity with Worlds TypeScript and scripting APIs

Challenge Steps:

1. Add a Custom UI Gizmo

In the Worlds Desktop Editor, open your world project.

From the Build menu, select Gizmos and drag a Custom UI Gizmo into your scene.

Position the gizmo where players can easily see it. Adjust its scale and rotation as needed.

2. Attach the Script

In the properties panel of the Custom UI Gizmo, press the Attach Script button. Then, press the New UI Script button at the bottom of the list. Give your script a name.

Click the 3 dots on the right side of the script that you created, and click edit script.

This should open your code editor with a default UI template.

3. Add a Button

In your script, locate the initializeUI() method. This is where you define the UI layout and elements.

To add a button, use the Pressable component from 'horizon/ui'. Place it inside the children array of a View.

Example:

Pressable({
  children: [
    Text({
      text: 'Press me',
      style: { fontSize: 12 }
    }),
  ],
  // ...event handlers and style...
})

You can add multiple buttons by adding more Pressable elements to the children array. Each button can have its own text, style, and event handlers.

Customize the button’s appearance and behavior using the style property and event handlers like onClick, onPress, onRelease, onEnter, and onExit.

Example:

// OnClick Event Handler
onClick: () => {
  console.log('Hello from the button!');
},
//Button Style
style: {
  width: 120,
  height: 50,
  backgroundColor: 'green'
}

4. Use Bindings

Bindings allow your UI to update in real time when values change. Create a Binding instance to hold a value (e.g., button color or label).

Example:

private buttonColorBinding = new Binding('gray');

Use the binding in your UI element’s properties.

For example, set the button’s background color:

style: {
  backgroundColor: this.buttonColorBinding,
}

Update the binding in response to events.

For example, change the color when the button is pressed or hovered:

onPress: () => { this.buttonColorBinding.set('yellow'); },
onRelease: () => { this.buttonColorBinding.set('gray'); },
onEnter: () => { this.buttonColorBinding.set('white'); },
onExit: () => { this.buttonColorBinding.set('gray'); },

To update a binding for a specific player (for per-player UI), use the set(value, [player]) method.

5. Test the Interaction

Enter Preview mode in the editor.

Press E to focus on the Custom UI panel, Then, click on your Pressable.

Observe the color change and any logic you added to the onClick handler.