Fondo de UI

Establece un fondo y un borde de una Entity de UI.

Las siguientes propiedades se usan para establecer un fondo y un borde en una UI entity.

Fondo

Un uiBackground Un component da color o una texture al área de una entity. Usa el tamaño y la posición definidos por la uiTransform.

Se pueden configurar los siguientes campos; todos son opcionales:

• color: El color que se usará en la entity, como un Color4 valor.

💡 Consejo: Haz que una entity sea semitransparente estableciendo el 4.º valor de la Color4 a menos de 1.

• texture: La texture que se mostrará en la entity; esto toma un objeto con varios parámetros sobre la texture. Las mismas propiedades están disponibles que en textures en materials en 3D entities.

  • src: La ruta al archivo de imagen que se usará como texture. (string)

  • filterMode: (opcional) Determina cómo se estiran o comprimen los píxeles en la texture cuando se renderiza. . Ver Texture Scaling. (FilterMode = 'point' | 'bi-linear' | 'tri-linear')

  • wrapMode: (opcional) Determina cómo se tesela una texture sobre una entity. Esto toma un valor de la TextureWrapMode enum. Ver [Texture Wrapping]((Ver documentación). (WrapMode = 'repeat' | 'clamp' | 'mirror')

  Consejo: Puedes combinar ambos texture y color properties en un solo uiBackground component para producir una texture teñida.

• textureMode: Selecciona cómo quieres que la texture se adapte al tamaño de la entity a la que se aplica. (TextureMode = 'nine-slices' | 'center' | 'stretch')enum, que admite los siguientes valores:

  • center: La texture no se estira; se coloca centrada en la entity y partes de ella pueden recortarse según el tamaño de la entity.

  • stretch: La texture se estira para coincidir con toda la superficie de la entity.

  • nine-slices: Partes de la texture se estiran para coincidir con toda la superficie de la entity, dejando los márgenes sin estirar. Ver textures de nueve cortes.

• avatarTexture: Muestra una miniatura del perfil de un avatar, basada en un avatar ID. Ver [Avatar Portraits]((Ver documentación).

• textureSlices: Determina los márgenes que se usarán al utilizar el modo de texture de nueve cortes, ver textures de nueve cortes. Establece un número menor que 1, como fracción del ancho total o la altura total de la imagen.

Color simple:

archivo ui.tsx:

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

export const uiMenu = () => (
  <UiEntity
    uiTransform={{
      width: 700,
      height: 400
    }}
    uiBackground={{
		color: Color4.create(0.5, 0.8, 0.1, 0.6)
	}}
  />
)

archivo index.ts:

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

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

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

Patrón de texture repetido:

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

export const uiMenu = () => (
  <UiEntity
    uiTransform={{
      width: 700,
      height: 400
    }}
    uiBackground={{
		textureMode: 'center',
		texture: {
			src: "images/brick-wall-texture.png",
			wrapMode: 'repeat'
		}
	}}
  />
)

Bordes

Se usan algunas propiedades para establecer un borde alrededor de una UI entity. Estas propiedades existen en la uiTransform component. Cada una te permite establecer un único valor para todos los lados del border, o valores distintos para cada lado.

• borderColor: El color que se usará en la entity, como un Color4 valor.

• borderWidth: El ancho del border, como un número en píxeles. También admite valores en porcentajes; por ejemplo borderWidth: '2%' establecerá el ancho del border en el 2% del ancho de la entity.

• borderRadius: Usa esta property para dar a las esquinas de la entity un border redondeado. Establece el radio de las esquinas en píxeles.

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

export const uiMenu = () => (
  <UiEntity
    uiTransform={{
      width: 700,
      height: 400,
      borderColor: Color4.Red(),
      borderWidth: 4,
      borderRadius: 10
    }}
  />
)

borderWidth, borderColor y borderRadius también se puede establecer con valores diferentes para cada lado de la entity.

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

export const uiMenu = () => (
  <UiEntity
    uiTransform={{
      width: 700,
      height: 400,
      borderColor: { top: Color4.White(), left: Color4.Red(), right: Color4.Blue(), bottom: Color4.Gray() },
      borderRadius: { topLeft: 20, topRight: 20, bottomLeft: 20, bottomRight:0 },
      borderWidth: { top: 3, left: 2, right: 3, bottom: 4 }
    }}
  />
)

Opacidad

Usa la opacity property en la uiTransform de una UiEntity para añadir transparencia a la entity y a todos sus children. La property opacity es un valor de 0 a 1, donde 0 es completamente transparente y 1 completamente opaco.

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

export const uiMenu = () => (
  <UiEntity
    uiTransform={{
      width: 700,
      height: 400,
      opacity: 0.7
    }}
    uiBackground={{ color: Color4.Green() }}
  >
    <UiEntity
        uiTransform={{
          width: 100,
          height: 30,
        }}
        uiText={{
          value: "Este texto también es transparente",
          fontSize: 40
        }}
      />
   </UiEntity>
)

El valor de opacity afecta a todos los children de una UiEntity, aplicando transparencia a los colores de background, a los colores del texto y a las imágenes de background. Cuando tanto el padre como un child tienen valores de opacity, la opacity final del child es el producto de su propio valor y el del padre.

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

export const uiMenu = () => (
  <UiEntity
    uiTransform={{
      width: 700,
      height: 400,
      opacity: 0.7
    }}
    uiBackground={{ color: Color4.Green() }}
  >
    <UiEntity
      uiTransform={{
        width: 100,
        height: 30,
        opacity: 0.7
      }}
      uiText={{
        value: "Este texto es aún más transparente",
        fontSize: 40
      }}
    />
  </UiEntity>
)

Textures de nueve cortes

Puedes usar escalado de 9 cortes con tus textures para asegurarte de que las esquinas y los márgenes no se estiren de forma desigual.

Con esta técnica popular, divides una imagen en 9 segmentos, que se estirarán de distintas maneras para preservar las proporciones de los márgenes y las esquinas. Por ejemplo, úsala para definir fondos con esquinas redondeadas que se adapten fácilmente a cualquier tamaño. Considera la siguiente imagen (tomada de Wikipedia):

En esta imagen vemos la texture original (arriba a la izquierda) y el resultado de escalarla de forma tradicional (arriba a la derecha); observa cómo se deforman las esquinas. Debajo, vemos la texture segmentada en 9 slices (abajo a la izquierda) y luego el resultado de estirar la imagen según el método de 9 slices (abajo a la derecha).

Así es como se ve afectado cada segmento, usando la imagen anterior como referencia.

• El segmento 5 es la única parte de la imagen que se estira por completo tanto en el eje x como en el eje y.

• Los segmentos 1, 3, 7 y 9 (las esquinas) no se estiran en absoluto.

• Los segmentos 2 y 8 solo se estiran horizontalmente

• Los segmentos 4 y 6 solo se estiran verticalmente.

Para usar el estiramiento de nine-slice en una entity, establece el textureMode en 'nine-slices'. Opcionalmente, también puedes establecer un ancho para el margen en cada lado en textureSlices.

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

export const uiMenu = () => (
  <UiEntity
    uiTransform={{ width: 700, height: 400 }}
    uiBackground={{
      textureMode: 'nine-slices',
      texture: {
        src: 'images/rounded_alpha_square.png'
      },
      textureSlices: {
        top: 0.2,
        bottom: 0.2,
        left: 0.2,
        right: 0.2
      }
	}}
  />
)

Texture UVs

Usa la uvs property en un uiBackground component para mostrar una región específica de una texture. Esto es útil para elegir sprites individuales de una sprite sheet o para rotar una imagen.

El uvs El field toma un array de 8 numbers, que representan 4 pares de coordenadas UV para las cuatro esquinas de la región de la texture. El orden es: abajo a la izquierda, arriba a la izquierda, arriba a la derecha, abajo a la derecha. Cada valor va de 0 a 1, donde (0, 0) es la esquina inferior izquierda de la imagen y (1, 1) es la esquina superior derecha.

💡 Consejo: Cuando uses custom uvs, establece textureMode en 'stretch' para que la región seleccionada llene el área de la entity.

Sprites de una hoja de sprites

Para mostrar una parte de una imagen más grande (por ejemplo, una card de una sprite sheet que contiene varias), establece el uvs en las coordenadas de esa región.

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

// Mostrar la mitad izquierda de una texture (p. ej., la primera tarjeta en una hoja de 2 columnas)
export const uiMenu = () => (
  <UiEntity
    uiTransform={{ width: 200, height: 300 }}
    uiBackground={{
      textureMode: 'stretch',
      texture: { src: 'images/card-atlas.png' }
      uvs: [
        // abajo a la izquierda, arriba a la izquierda, arriba a la derecha, abajo a la derecha
        0, 0,
        0, 1,
        0.5, 1,
        0.5, 0
      ]
    }}
  />
)

Para una sprite sheet con una cuadrícula de frames (por ejemplo, una hoja de 4 columnas por 2 filas), calcula los UVs según la columna y la fila del frame que quieras:

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

// Elige un único frame de una sprite sheet en cuadrícula
function getFrameUVs(col: number, row: number, totalCols: number, totalRows: number): number[] {
  const stepU = 1 / totalCols
  const stepV = 1 / totalRows
  const left = col * stepU
  const right = (col + 1) * stepU
  const top = 1 - row * stepV
  const bottom = 1 - (row + 1) * stepV
  return [
    left, bottom,
    left, top,
    right, top,
    right, bottom
  ]
}

// Muestra la columna 2, fila 0 de una sprite sheet de 4x2
export const uiMenu = () => (
  <UiEntity
    uiTransform={{ width: 128, height: 128 }}
    uiBackground={{
      textureMode: 'stretch',
      texture: { src: 'images/spritesheet.png' }
      uvs: getFrameUVs(2, 0, 4, 2)
    }}
  />
)

Rotar una imagen con UVs

Puedes rotar una texture aplicando una rotación 2D a las coordenadas UV. Esto es útil para spinner o indicadores de carga sin necesidad de una rotación basada en Transform.

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

// Rota un punto 2D alrededor de un centro
function rotate2D(angle: number, x: number, y: number, cx: number, cy: number): number[] {
  const cos = Math.cos(angle)
  const sin = Math.sin(angle)
  return [
    cos * (x - cx) - sin * (y - cy) + cx,
    sin * (x - cx) + cos * (y - cy) + cy
  ]
}

// Construye coordenadas UV rotadas
function rotateUVs(angle: number): number[] {
  const uv00 = rotate2D(angle, 0, 0, 0.5, 0.5)
  const uv01 = rotate2D(angle, 0, 1, 0.5, 0.5)
  const uv11 = rotate2D(angle, 1, 1, 0.5, 0.5)
  const uv10 = rotate2D(angle, 1, 0, 0.5, 0.5)
  return [uv00[0], uv00[1], uv01[0], uv01[1], uv11[0], uv11[1], uv10[0], uv10[1]]
}

let spinnerAngle = 0

// System que actualiza el ángulo en cada frame
engine.addSystem((dt: number) => {
  spinnerAngle += dt * 5
})

export const uiMenu = () => (
  <UiEntity
    uiTransform={{ width: 128, height: 128 }}
    uiBackground={{
      textureMode: 'stretch',
      texture: { src: 'images/spinner.png' },
      uvs: rotateUVs(spinnerAngle)
    }}
  />
)

El rotateUVs function rota las cuatro esquinas UV alrededor del punto central (0.5, 0.5) por el ángulo dado en radianes. Como esto se llama en cada frame por el renderer similar a React, el spinner se actualiza con suavidad.

💡 Consejo: Ver un ejemplo completo y funcional con sprites, sprite sheets animadas, spinners y más en la UI Animations escena de ejemplo.