Eventos de botones de UI

Gestiona eventos de botón en Entities de UI.

Para crear un botón en tu UI, crea un Button elemento de UI con las siguientes propiedades:

• value: Una cadena con el texto que se mostrará en el botón.

• onMouseDown: Una función de callback que se ejecuta cada vez que el usuario presiona el botón del puntero sobre la entidad.

• uiTransform: Propiedades de posicionamiento del elemento de UI.

El siguiente ejemplo muestra cómo crear un botón de UI clicable.

archivo ui.tsx:

import { Button } from '@dcl/sdk/react-ecs'

export const uiMenu = () => (
	<Button
		value="Haz clic en mí"
		uiTransform={{ width: 100, height: 100 }}
		onMouseDown={() => {
			console.log('Se hizo clic en la UI')
		}}
	/>
)

archivo index.ts:

import { ReactEcsRenderer } from '@dcl/sdk/react-ecs'
import { uiMenu } from './ui'

export function main() {
    ReactEcsRenderer.setUiRenderer(uiMenu)
}

📔 Nota: Todos los siguientes fragmentos de esta página asumen que tienes un .ts similar al anterior, ejecutando la ReactEcsRenderer.setUiRenderer() función.

También puedes escribir la función que se ejecuta al hacer clic fuera de la definición de la UI, y referenciarla por nombre. Esto ayuda a que el código de la UI sea más legible, y también es útil si varias entidades de UI clicables necesitan llamar a la misma función.

import { Button } from '@dcl/sdk/react-ecs'

function handleClick() {
	// Haz algo en onClick
	console.log('Se hizo clic en la UI')
}
export const uiMenu = () => (
	<Button
		value="Haz clic en mí"
		uiTransform={{ width: 100 }}
		onMouseDown={handleClick}
	/>
)

Los siguientes campos se pueden añadir a un Button elemento de UI:

• onMouseDown: Una función de callback que se ejecuta cada vez que el usuario presiona el botón del puntero sobre la entidad.

• onMouseUp: Una función de callback que se ejecuta cada vez que se suelta el botón del puntero mientras se apunta a la entidad.

• onMouseEnter: Una función de callback que se ejecuta cada vez que el puntero empieza a pasar sobre el botón.

• onMouseLeave: Una función de callback que se ejecuta cada vez que el puntero deja de pasar sobre el botón.

• color: Color del texto del botón.

• font: Fuente del texto del botón.

• textAlign: Alineación del texto dentro del botón

• uiTransform: Propiedades de posicionamiento del elemento de UI.

• uiBackground: Establece el color o la textura del elemento de UI.

• variant: Usa esta propiedad para establecer el estilo del botón como una de las opciones predeterminadas. primary y secondary están disponibles.

• disabled: Booleano para deshabilitar un botón. Cuando disabled se establece en true, las onMouseDown y onMouseUp acciones ya no se llaman. Además, el alpha valor del color tanto del texto como del fondo se reduce a la mitad, por lo que el botón queda "atenuado" y destaca menos.

Estilo del botón

Establece el variant en primary o secondary para aprovechar las opciones de estilo predeterminadas de los botones. primary hace que tu botón sea rojo con texto blanco, secondary hace que tu botón sea blanco con texto rojo.

import { UiEntity, Button, ReactEcs } from '@dcl/sdk/react-ecs'
import { Color4 } from '@dcl/sdk/math'

export const uiMenu = () => (
	<UiEntity
		uiTransform={{
			width: 500,
			height: 230,
			margin: '16px 0 8px 270px',
			padding: 4,
			alignSelf: 'center',
		}}
		uiBackground={{ color: Color4.Gray() }}
	>
		<Button
			value="Haz clic en mí"
			variant="primary"
			uiTransform={{ width: 80, height: 20, margin: 4 }}
			onMouseDown={() => {
				console.log('Se hizo clic en la UI')
			}}
		/>
		<Button
			value="Haz clic en mí"
			variant="secondary"
			uiTransform={{ width: 80, height: 20, margin: 4 }}
			onMouseDown={() => {
				console.log('Se hizo clic en la UI')
			}}
		/>
	</UiEntity>
)

También puedes usar libremente todas las propiedades del fondo. También puedes establecer un variant y luego sobrescribir algunas de sus propiedades. Este ejemplo usa el primary variant, pero sobrescribe el color para que sea verde:

import { Button } from '@dcl/sdk/react-ecs'
import { Color4 } from '@dcl/sdk/math'

export const uiMenu = () => (
	<Button
		value="¡Mi botón!"
		variant="primary"
		uiTransform={{ width: 100, height: 100 }}
		onMouseDown={() => {
			console.log('¡Se hizo clic en Mi botón!')
		}}
		uiBackground={{
			color: Color4.Green(),
		}}
	/>
)

Botones conmutables

Un caso de uso común es hacer que un botón alterne entre dos estados, como un interruptor. El siguiente ejemplo cambia entre dos colores cada vez que se presiona el botón:

import { Button } from '@dcl/sdk/react-ecs'
import { Color4 } from '@dcl/sdk/math'

let buttonEnabled = false

export const uiMenu = () => (
	<Button
		value="Mi botón"
		variant="primary"
		uiTransform={{ width: 100, height: 100 }}
		onMouseDown={() => {
			console.log('¡Se hizo clic en Mi botón!')
			buttonEnabled = !buttonEnabled
			if (buttonEnabled) {
				// hacer algo
			} else {
				// hacer algo distinto
			}
		}}
		uiBackground={{
			color: buttonEnabled ? Color4.Green() : Color4.Red(),
		}}
	/>
)

Ten en cuenta que en el ejemplo anterior, el color depende de una buttonEnabled variable. Cada vez que el valor de esta variable cambia, afecta inmediatamente al color de fondo.

Retroalimentación al pasar el cursor

Otro caso de uso común es mostrar algún tipo de pista visual al pasar el cursor sobre un botón, para aclarar que es interactivo, o incluso mostrar una pista emergente que explique qué hace este botón. Usa los onMouseEnter y onMouseLeave callbacks para detectar cuándo el cursor del jugador está sobre el botón y reaccionar en consecuencia.

import { Button } from '@dcl/sdk/react-ecs'

let buttonEnabled = false

export const uiMenu = () => (
	<Button
		value="Mi botón"
		uiTransform={{ width: 100, height: 100 }}
		onMouseDown={() => {
			// función del botón
		}}
		onMouseEnter={() => {
			// mostrar pista
		}}
		onMouseLeave={() => {
			// ocultar pista
		}}
	/>
)

Hacer que otros elementos sean clicables

Cualquier elemento de la UI puede hacerse clicable agregando un onMouseDown propiedad, funciona exactamente igual que un botón. El siguiente ejemplo añade onMouseDown propiedades a imágenes de fondo y texto.

import { UiEntity, Label, ReactEcs } from '@dcl/sdk/react-ecs'
import { Color4 } from '@dcl/sdk/math'
import { engine, Transform } from '@dcl/sdk/ecs'

export const uiMenu = () => (
	<UiEntity
		onMouseDown={() => {
			console.log('¡Se hizo clic en el fondo!')
		}}
		uiTransform={{
			width: 400,
			height: 230,
		}}
		uiBackground={{ color: Color4.create(0.5, 0.8, 0.1, 0.6) }}
	>
		<Label
			onMouseDown={() => {
				console.log('¡Se hizo clic en la etiqueta!')
			}}
			value={`Player: ${getPlayerPosition()}`}
			fontSize={18}
			uiTransform={{ width: '100%', height: 30 }}
		/>
	</UiEntity>
)

function getPlayerPosition() {
	const playerPosition = Transform.getOrNull(engine.PlayerEntity)
	if (!playerPosition) return 'desconocido'
	const { x, y, z } = playerPosition.position
	return `{x: ${x.toFixed(2)}, y: ${y.toFixed(2)}, z: ${z.toFixed(2)} }`
}

Bloqueo de puntero

Todas las entidades de UI no bloquean el puntero por defecto, lo que significa que los clics de los jugadores pasarán a través de ellas e interactuarán con objetos en el espacio del mundo 3D detrás de ellas. Si una entidad tiene una onMouseDown callback, entonces se convierte en bloqueadora de puntero, por lo que los clics del jugador no afectan a lo que está detrás de esa entidad de UI.

Puedes cambiar este comportamiento predeterminado cambiando el valor de la pointerFilter propiedad en el uiTransform componente en cualquier entidad de UI. Por ejemplo, para configurar una entidad que no tiene onMouseDown para que bloquee el puntero.

Los valores admitidos para pointerFilter son:

• block: El elemento de UI bloquea el puntero; los jugadores no pueden hacer clic en nada detrás de este elemento de UI.

• none: El elemento de UI no bloquea el puntero. El elemento no es clicable y se puede hacer clic en cualquier cosa detrás de él.

A continuación hay una UI simple que no tiene un onMouseDown, pero que anula el comportamiento predeterminado de no bloquear el puntero estableciendo pointerFilter en block.

import { UiEntity, ReactEcs } from '@dcl/sdk/react-ecs'
import { Color4 } from '@dcl/sdk/math'

// dibujar UI
export const uiMenu = () => (
	<UiEntity
		uiTransform={{
			width: '100%',
			height: '100px',
			pointerFilter: `block`,
		}}
		uiText={{ value: `This element is pointer blocking`, fontSize: 40 }}
		uiBackground={{ color: Color4.create(0.5, 0.8, 0.1, 0.6) }}
	/>
)

Interacciones de arrastre

Los controladores de puntero de UI (onMouseDown, onMouseUp, onMouseEnter, onMouseLeave) no toman parámetros. Se disparan como simples () => void callbacks sin datos de posición o coordenadas. No hay un onMouseDrag o onMouseMove controlador en el sistema de UI.

Para construir UI basada en arrastre (sliders, barras de desplazamiento, asas de arrastre), usa PrimaryPointerInfo.screenDelta de @dcl/sdk/ecs. Esto proporciona el movimiento del ratón en píxeles desde el último frame, actualizado en cada frame independientemente de sobre qué esté el cursor.

El patrón funciona así:

1. onMouseDown sobre el objetivo de arrastre inicia el arrastre y registra el valor inicial.

2. Un sistema lee screenDelta cada frame y lo acumula en el valor mientras el arrastre está activo.

3. Una superposición invisible a pantalla completa con pointerFilter: 'block' captura la liberación del ratón, de modo que soltar fuera del objetivo estrecho también finaliza el arrastre.

import { engine, PrimaryPointerInfo, UiCanvasInformation } from '@dcl/sdk/ecs'

let dragging = false
let sliderValue = 0.5

// Llama a este sistema en cada frame para acumular el movimiento del arrastre
engine.addSystem(() => {
	if (!dragging) return

	const delta = PrimaryPointerInfo.getOrNull(engine.RootEntity)?.screenDelta
	if (!delta || delta.x === 0) return

	// Convierte píxeles de pantalla a un rango de 0–1
	// Divide por el factor de escala de la UI para que la velocidad del arrastre coincida con el cursor
	const canvas = UiCanvasInformation.getOrNull(engine.RootEntity)
	const scale = canvas ? Math.min(canvas.width / 1920, canvas.height / 1080) : 1
	const trackWidth = 200 // ancho virtual en px de la pista del deslizador

	sliderValue = Math.max(0, Math.min(1, sliderValue + delta.x / scale / trackWidth))
})

Nota: En móvil, screenDelta siempre informa 0 (no hay un cursor de libre movimiento). Para deslizadores compatibles con móviles, añade botones incrementadores (- / +) junto a la pista de arrastre. Usa isMobile() de @dcl/sdk/platform para bifurcar tu UI.

Consejo: Divide siempre screenDelta por el factor de escala de la UI, o el arrastre se sobrepasará o quedará corto en pantallas cuya resolución difiera de tu tamaño virtual.