UI en pantalla

Aprende cómo crear una UI para los jugadores en tu escena. Esto es útil, por ejemplo, para mostrar información relacionada con el juego.

Puedes construir una UI para tu escena, que se mostrará en el espacio 2D fijo de la pantalla, en lugar de en el espacio 3D del mundo.

Los elementos de la UI solo son visibles cuando el jugador está dentro de los parcels de LAND de la escena, ya que las escenas vecinas podrían tener su propia UI para mostrar. Partes de la UI también pueden activarse para abrirse cuando ocurren ciertos eventos en el espacio del mundo, por ejemplo si el jugador hace clic en un lugar específico.

Crea una UI definiendo una estructura de UIEntity objetos anidados en JSX. La sintaxis utilizada para las UIs es muy similar a la de React (una biblioteca basada en javascript muy popular para construir UIs web).

📔 Nota: Solo puedes definir sintaxis de UI en archivos que tengan una .tsx extensión. .tsx los archivos soportan todo lo que los archivos .ts soportan, además de sintaxis de UI. Recomendamos crear un ui.tsx archivo y definir tu UI allí. Recuerda llamar al método render de tu UI desde index.ts con ReactEcsRenderer.setUiRenderer(yourUiMethodName), ver ejemplo a continuación.

Una UI simple con elementos estáticos puede parecerse mucho al HTML, pero cuando agregas elementos dinámicos que responden a un cambio de estado, puedes hacer cosas mucho más poderosas.

La UI por defecto del Explorer de Decentraland incluye un widget de chat, un mapa y otros elementos. Estos elementos de UI siempre se muestran en la capa superior, por encima de cualquier UI específica de la escena. Así que si tu escena tiene elementos de UI que ocupan el mismo espacio de pantalla que estos, serán ocultados.

Ver Guías de UX para consejos sobre cómo diseñar el aspecto y la sensación de tu UI.

Cuando el jugador hace clic en el botón de cerrar UI en la esquina inferior derecha de la pantalla, todos los elementos de la UI se ocultan.

Renderizar una UI

Para mostrar una UI en tu escena, usa la ReactEcsRenderer.setUiRenderer() función, pasándole una estructura válida de entidades, descrita en un .tsx archivo.

Cada entidad se define como un nodo tipo HTML, con propiedades para cada uno de sus componentes.

archivo ui.tsx:

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

export const uiMenu = () => (
  <UiEntity
    uiTransform={{
      width: 700,
      height: 400,
      margin: { top: '35px', left: '500px' },
    }}
    uiBackground={{ color: Color4.Red() }}
  />
)

archivo index.ts:

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

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

También puedes definir una estructura de entidades y renderizarla, todo en un mismo comando en un .tsx archivo.

archivo ui.tsx:

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

export function setupUI() {
  ReactEcsRenderer.setUiRenderer(() => (
    <UiEntity
      uiTransform={{
        width: 700,
        height: 400,
        margin: { top: '35px', left: '500px' },
      }}
      uiBackground={{ color: Color4.Red() }}
    />
  ))
}

archivo index.ts:

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

export function main() {
    setupUI()
}

📔 Nota: Todos tus elementos de UI deben estar anidados en la misma estructura, y tener un único padre en la raíz de la estructura. Solo puedes llamar a ReactEcsRenderer.setUiRenderer() una vez en la escena.

Entidades UI

Cada elemento en la UI debe definirse como una UiEntity, ya sea una imagen, texto, fondo, una caja de alineación invisible, etc. Igual que en el espacio 3D de la escena, cada UiEntity tiene sus propios componentes para darle posición, color, etc.

La sintaxis tipo React te permite especificar cada componente como una propiedad dentro del UiEntity, esto hace que el código sea más corto y más legible.

Los componentes usados en un UiEntity son diferentes de los usados en entidades regulares. No puedes aplicar un componente de UI a una entidad regular, ni un componente regular a una entidad UI.

Los siguientes componentes están disponibles para usar en un UiEntity:

• uiTransform

• uiBackground

• uiText

• onClick

Al igual que con las etiquetas HTML, puedes definir componentes como autocerrados o anidar uno dentro de otro.

archivo ui.tsx:

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

export const uiMenu = () => (
  // entidad padre
  <UiEntity
    uiTransform={{
      width: 200,
      height: 200,
      margin: { top: '250px', left: '500px' },
    }}
    uiBackground={{ color: Color4.Blue() }}
  >
    // entidad hija autocerrada
    <UiEntity
      uiTransform={{
        width: 400,
        height: 400,
        margin: { top: '35px', left: '500px' },
      }}
      uiText={{ value: `Hello world!`, fontSize: 40 }}
    />
    // sentencia de cierre para la entidad padre
  </UiEntity>
)

archivo index.ts:

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

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

Una definición de un módulo de UI solo puede tener una entidad a nivel padre. Puedes definir tantas otras entidades como quieras, pero todas deben caber dentro de una estructura con un único padre en la parte superior.

Múltiples módulos de UI

Tu escena debe tener una sola llamada a la ReactEcsRenderer.setUiRenderer() función. Para definir tu UI mediante una serie de módulos separados en archivos distintos, puedes pasar un arreglo al renderer listando cada módulo. Esto también es útil al combinar módulos de UI de una librería (como la DCL UI toolkit library) con UI personalizada.:

const uiComponent = () => [
  // Función que retorna un módulo de UI,
  // Función que retorna un módulo de UI
  // ...
]

ReactEcsRenderer.setUiRenderer(uiComponent)

A continuación hay un ejemplo más completo:

archivo ui.tsx:

export function UIModule1() {
  return (
    <UiEntity
      uiTransform={{
        flexDirection: 'column',
        alignItems: 'center',
        justifyContent: 'space-between',
        positionType: 'absolute',
        position: { right: '3%', bottom: '3%' },
      }}
    >
      <Label value="Hello World!" fontSize={18} textAlign="middle-center" />
    </UiEntity>
  )
}

export function UIModule2() {
  return (
    <UiEntity
      uiTransform={{
        flexDirection: 'column',
        alignItems: 'center',
        justifyContent: 'space-between',
        positionType: 'absolute',
        position: { right: '3%', top: '3%' },
      }}
    >
      <Label
        value="Here's some more UI!"
        fontSize={18}
        textAlign="middle-center"
      />
    </UiEntity>
  )
}

archivo index.ts:

import { ReactEcsRenderer } from '@dcl/sdk/react-ecs'
import { UIModule1, UIModule2 } from './ui'

export function main() {
    ReactEcsRenderer.setUiRenderer([
      UIModule1(),
      UIModule2(),
      // ...
      // La línea de abajo es para usar la DCL UI Toolkit library
      // https://github.com/decentraland-scenes/dcl-ui-toolkit
      ui.render(),
    ])
}