UI dinâmica

Aprenda a tornar UIs dinâmicas, respondendo a mudanças nos dados.

Você pode definir uma UI que inclua elementos dinâmicos, que são atualizados a cada tick. Você só precisa lidar com a atualização da variável que representa esses dados, e a UI se adaptará em resposta aos novos valores.

Isso é muito útil para incluir elementos como um cronômetro, a pontuação de um jogador, etc. Mas você pode ir ainda mais longe e definir estruturas inteiras de UI com base em state.

Variáveis de referência

Você pode simplesmente referenciar uma variável em qualquer propriedade de um dos components em um uiEntity. À medida que a variável muda de valor, a UI se adaptará de acordo.

O exemplo abaixo define uma variável playerCurrentPosition e a referencia como parte de uma string em um uiText component. Então um system atualiza o valor dessa variável a cada tick, usando a posição atual do jogador. À medida que o valor da variável muda, a UI é atualizada de acordo, sem nunca precisar modificar explicitamente a UI.

arquivo ui.tsx:

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

width: '100%',
export const uiMenu = () => (
  <UiEntity
    uiTransform={{
			height: '100px',
			pointerFilter: `block`,
			justifyContent: 'center',
			alignItems: 'center',
    }}
    uiText={{ value: `Player: `+  playerCurrentPosition, fontSize: 40 }}
    uiBackground={{ color: Color4.create(0.5, 0.8, 0.1, 0.6) }}
  />
)

arquivo index.ts:

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

export function main() {
    ReactEcsRenderer.setUiRenderer(uiMenu, { virtualWidth: 1920, virtualHeight: 1080 })
}

// definir variável
let playerCurrentPosition: string = ""

// system para atualizar variável
engine.addSystem(() => {
  const playerPosition = Transform.getOrNull(engine.PlayerEntity)
  if (!playerPosition) return
  const { x, y, z } = playerPosition.position
  playerCurrentPosition =  `{x: ${x.toFixed(2)}, y: ${y.toFixed(2)}, z: ${z.toFixed(2)} }`
})

No exemplo acima, você também poderia incluir a variável como parte da string, sinalizando a variável com um $.

uiText={{
	value: `Player: $playerCurrentPosition`,
	fontSize: 40
}}

Chame funções de dentro de uma UI

Você também pode chamar uma função de dentro de uma definição JSX, retornando um valor para usar em uma propriedade da UI. Funções chamadas de dentro dessa definição JSX são chamadas recorrentemente, a cada tick do game loop.

No exemplo abaixo, um uiText component chama a getPlayerPosition() função para definir parte da string a ser exibida.

Este exemplo é semelhante ao da seção anterior, mas ao chamar uma função de dentro da definição da UI evitamos declarar uma variável separada e definir um system para alterar essa variável. Observe que getPlayerPosition() é chamado a cada tick do game loop, sem precisar declarar explicitamente um system.

arquivo ui.tsx:

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

export const uiMenu = () => (
  <UiEntity
    uiTransform={{
      height: '100px',
      pointerFilter: `block`,
      justifyContent: 'center',
      alignItems: 'center',
    }}
    uiText={{ value: `Player: `+  getPlayerPosition(), fontSize: 40 }}
    uiBackground={{ color: Color4.create(0.5, 0.8, 0.1, 0.6) }}
  />
)

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

arquivo index.ts:

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

export function main() {
    ReactEcsRenderer.setUiRenderer(uiMenu, { virtualWidth: 1920, virtualHeight: 1080 })
}

Alternar uma UI entre ligado e desligado

A maneira mais fácil de alternar uma UI entre ligado e desligado é usar uma variável para o valor da display property em uma uiTransform. O display property de uma UI entity e de todos os seus children se definido como : O UI element não bloqueia pointer. O elemento não é clicável e qualquer coisa atrás dele pode ser clicada..

O exemplo a seguir usa uma variável para definir o display field de uma parte da UI. O valor dessa variável pode ser alternado ao clicar em outro elemento de UI.

arquivo ui.tsx:

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

// Variável para refletir o estado atual da visibilidade do menu
var isMenuVisible: boolean = false

// Função para alternar o estado do menu
function toggleMenuVisibility() {
  isMenuVisible = !isMenuVisible
}

export const uiMenu = () => (
   // parent
   <UiEntity>
      // Menu
      <UiEntity
       uiTransform={{
          width: '80%',
          pointerFilter: `block`,
          alignContent: 'center',
          justifyContent: 'center',
          display: isMenuVisible ? 'flex': 'none'
        }}
         uiText={{
          value: "Menu",
          fontSize: 30
        }}
        uiBackground={{ color: Color4.Green() }}
      />
      // button
      <UiEntity
        uiTransform={{
          width: 100,
          height: 30,
          margin: { top: '35px', left: '500px' }
        }}
        uiText={{
          value: "Toggle Menu",
          fontSize: 40
        }}
        uiBackground={{ color: Color4.Red() }}
        onMouseDown={toggleMenuVisibility}
      />
   </UiEntity>
)

arquivo index.ts:

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

export function main() {
    ReactEcsRenderer.setUiRenderer(uiMenu, { virtualWidth: 1920, virtualHeight: 1080 })
}

UI entities dinâmicas

Os exemplos nas seções acima mostram como alterar dinamicamente uma única propriedade em uma entity, mas você também pode definir estruturas inteiras de entities que podem ser dimensionadas com base em dados que mudam dinamicamente. Esse tipo de padrão é comum no desenvolvimento web ao usar libraries como React, e é extremamente poderoso. Com isso, você pode definir aplicações de UI extremamente flexíveis e escaláveis.

O exemplo a seguir lista os ids de todas as entities na scene que têm um MeshRenderer e Transform. Ele cria um uiText para cada uma. À medida que o conteúdo da scene muda, a lista de UI entities também se adapta a cada tick.

arquivo ui.tsx:

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

export const uiMenu = () => (
  <UiEntity
    uiTransform={{
      height: '100px',
      height: '300px',
      justifyContent: 'center',
      alignItems: 'center',
    }}
    uiBackground={{ color: Color4.create(0.5, 0.8, 0.1, 0.6) }}
  >
    <UiEntity>
      {generateText()}
    </UiEntity>
  </UiEntity>
)


function generateText(){
  return Array.from(engine.getEntitiesWith(
    MeshRenderer,
    Transform
  )).map(([entity]) => <TextComponent value={entity.toString()} key={entity} /> )
}


function TextComponent(props: { value: string; key: string | number }) {
  return <UiEntity
    key={props.key}
    uiTransform={{ width: 80, height: 20 }}
    uiText={{ value: props.value, textAlign: 'middle-center', fontSize: 12 }}
    uiBackground={{ color: { r: 255, g: 45, b: 85, a: 1 } }}
  />
}

arquivo index.ts:

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

export function main() {
    ReactEcsRenderer.setUiRenderer(uiMenu, { virtualWidth: 1920, virtualHeight: 1080 })
}