Posicionamiento de entities

Cómo establecer la posición, rotación y escala de una entity en una escena

Puedes establecer la position, rotation y scale de cualquier entidad usando el Transform componente. Esto puede usarse en cualquier entidad en el espacio 3D, afectando dónde se renderiza la entidad. Esto incluye formas primitivas (cubo, esfera, plano, etc.), formas de texto 3D, formas NFT y modelos 3D (GltfContainer).

Usa el Scene Editor en Creator Hub

Al agregar un elemento a tu escena mediante el Scene Editor, implícitamente incluye un Transform componente. Entonces cambias los valores en el componente Transform de la entidad implícitamente cambiando la posición, rotación o escala de una entidad. También puedes usar la UI del Scene Editor para proporcionar valores numéricos con mayor precisión.

Conceptos básicos de código

// Crear una nueva entidad
const ball = engine.addEntity()

// Dar a esta entidad una forma, para hacerla visible
MeshRenderer.setSphere(ball)

// Dar a esta entidad un componente Transform
Transform.create(ball, {
	position: Vector3.create(5, 1, 5),
	scale: Vector3.create(1, 1, 1),
	rotation: Quaternion.Zero(),
})

Para mover, rotar o redimensionar una entidad en tu escena durante un periodo de tiempo, cambia los valores en este componente incrementalmente, cuadro por cuadro. Ver Mover entidades para más detalles y buenas prácticas.

📔 Nota: Vector3 y Quaternion deben importarse vía

import { Vector3, Quaternion } from "@dcl/sdk/math"

Ver Imports para ver cómo manejarlos fácilmente.

Position

position es un vector 3D, establece la posición del centro de la entidad en los tres ejes, x, y, y z. Ver Tipos de geometría para más detalles.

// Crear una nueva entidad
const ball = engine.addEntity()

// Crear transform con una posición predefinida
Transform.create(ball, {
	  position: Vector3.create(5, 1, 5)
}

// Obtener una versión mutable del transform
const mutableTransform = Transform.getMutable(ball)

// Establecer la posición con un objeto
mutableTransform.position = { x: 5, y: 1, z: 5 }

// Establecer la posición con un objeto (sintaxis alternativa)
mutableTransform.position = Vector3.create(2, 1, 4)

// Establecer cada eje individualmente
mutableTransform.position.x = 3
mutableTransform.position.y = 1
mutableTransform.position.z = 3

Al establecer una posición, ten en cuenta las siguientes consideraciones:

• Los números en un vector de posición representan metros (a menos que la entidad sea hija de una entidad escalada).

• Una escena compuesta por un único parcel mide 16m x 16m. El centro de la escena (a nivel del suelo) está en x:8, y:0, z:8. Si la escena está compuesta por varios parcels, entonces el centro variará dependiendo de su disposición.

• x:0, y:0, z:0 se refiere a la esquina suroeste de la parcela base de la escena, a nivel del suelo.

  Consejo: Al ver una vista previa de la escena, aparece una brújula en el punto (0,0,0) de la escena con etiquetas para cada eje como referencia.

  Nota: Puedes cambiar la parcela base de una escena editando el atributo base de scene.json.

• Para orientarte mejor, usa tu left mano:

  • tu dedo índice (apuntando hacia adelante) es el z eje

  • tu dedo medio (apuntando hacia los lados) es el x eje

  • tu pulgar (apuntando hacia arriba) es el y eje.

• Si una entidad es hija de otra, entonces x:0, y:0, z:0 se refiere al centro de su entidad padre, dondequiera que esté en la escena.

• Cada entidad en tu escena debe estar posicionada dentro de los límites de los parcels que ocupa en todo momento. Si una entidad sale de estos límites, generará un error.

  Consejo: Al ver una escena en modo de vista previa, las entidades que están fuera de los límites se resaltan en red.

• Tu escena también está limitada en altura. Cuantos más parcels conformen la escena, más alto se te permite construir. Ver limitaciones de la escena para más detalles.

Rotación

rotation se almacena como un quaternion, un sistema de cuatro números, x, y, z y w. Cada uno de estos números va de 0 a 1. Ver Tipos de geometría para más detalles.

// Crear una nueva entidad
const cube = engine.addEntity()

// Crear transform con una rotación predefinida de 0
Transform.create(cube, {
	  rotation: Quaternion.Zero()
}

// Obtener una versión mutable del transform
const mutableTransform = Transform.getMutable(cube)

// Establecer la rotación con un objeto, desde ángulos euler
mutableTransform.rotation = Quaternion.fromEulerDegrees(0, 90, 0)

// Establecer la rotación con un objeto
mutableTransform.rotation = { x: 0.1, y: 0.5, z: 0.5, w: 0 }

// Establecer cada eje individualmente
mutableTransform.rotation.x = 0
mutableTransform.rotation.y = 1
mutableTransform.rotation.z = 0.3
mutableTransform.rotation.w = 0

También puedes establecer el campo de rotación con Euler ángulos, la notación más común x, y y z con números que van de 0 a 360 con la que la mayoría de la gente está familiarizada. Para usar ángulos Euler, utiliza una de las siguientes notaciones:

// Crear transform con una rotación predefinida en ángulos Euler
Transform.create(cube, {
	  rotation: Quaternion.fromEulerDegrees(0, 90, 0)
}

// Obtener una versión mutable del transform
const mutableTransform = Transform.getMutable(cube)

// Establecer la rotación con un objeto, desde ángulos euler
mutableTransform.rotation = Quaternion.fromEulerDegrees(0, 90, 0)

Al usar un vector 3D para representar ángulos Euler, x, y y z representan la rotación en ese eje, medida en grados. Una vuelta completa requiere 360 grados.

Cuando recuperas la rotación de una entidad, devuelve un quaternion por defecto. Para obtener la rotación expresada en ángulos Euler, usa .toEuler():

// Obtener una versión de solo lectura del transform
const transform = Transform.getMutable(cube)

// Establecer la rotación con un objeto, desde ángulos euler
const eulerAngle = Quaternion.toEuler(transform.rotation)

Obtener la posición y rotación global de una entidad

El getWorldPosition y getWorldRotation las funciones retornan la posición y rotación global de una entidad. Eso significa que devuelve la posición o rotación percibida que el jugador verá el elemento, ignorando cualquier jerarquía de padres.

• getWorldPosition(engine, entity: Entity): Vector3Type: Esta función devuelve la posición World de una entidad, teniendo en consideración todas las posiciones de las entidades padres, si la entidad misma tiene alguna, devolviendo {x: 0, y: 0, z: 0} si la entidad no tiene Transform.

const worldPos = getWorldPosition(engine, childEntity)
console.log(`World position: ${worldPos.x}, ${worldPos.y}, ${worldPos.z}`)

• getWorldRotation(engine, entity: Entity): QuaternionType: Esta función devuelve la rotación World de una entidad, teniendo en consideración todas las rotaciones de las entidades padres, si la entidad misma tiene alguna. Devuelve un Quaternion tipo, devolviendo el quaternion identidad {x: 0, y: 0, z: 0, w: 1} si la entidad no tiene Transform.

const worldRot = getWorldRotation(engine, childEntity)
console.log(`World rotation: ${worldRot.x}, ${worldRot.y}, ${worldRot.z}, ${worldRot.w}`)

Nota: La posición global y la rotación global son relativas a las coordenadas dentro de la escena y no a Genesis City.

Mirar al jugador

Añadir un Billboard componente a una entidad para que siempre rote para mirar al jugador.

Los billboards eran una técnica común usada en los juegos 3D de los 90, donde la mayoría de las entidades eran planos 2D que siempre miraban al jugador. La misma idea también puede usarse para rotar un modelo 3D.

// Crear una nueva entidad
const cube = engine.addEntity()

// Dar a la entidad una forma visible
MeshRenderer.setBox(cube)

// Crear transform con una posición predefinida
Transform.create(cube, {
	  position: Vector3.create(5, 1, 5)
}

// Dar a la entidad un componente Billboard
Billboard.create(cube, {})

Puedes configurar cómo se comporta el billboard con los siguientes parámetros:

• billboardMode: Usa un valor del BillboardMode para establecer su comportamiento:

  • BillboardMode.BM_ALL: La entidad rota para mirar al jugador en todos sus ejes de rotación. Si el jugador está muy por encima de la entidad, la entidad mirará hacia arriba.

  • BillboardMode.BM_NONE: La entidad no rotará en absoluto.

  • BillboardMode.BM_X: La entidad tiene su x eje de rotación fijado.

  • BillboardMode.BM_Y: La entidad tiene su y eje de rotación fijado. Solo rota a la izquierda y a la derecha, no hacia arriba y hacia abajo. Permanece perpendicular al suelo si el jugador está por encima o por debajo de la entidad.

  • BillboardMode.BM_Z: La entidad tiene su z eje de rotación fijado.

// billboard plano
const perpendicularPlane = engine.addEntity()

Transform.create(perpendicularPlane, {
	position: Vector3.create(8, 1, 8),
})

PlaneShape.create(perpendicularPlane)

Billboard.create(perpendicularPlane, {
	billboardMode: BillboardMode.BM_Y,
})

// etiqueta de texto
const textLabel = engine.addEntity()

Transform.create(textLabel, {
	position: Vector3.create(6, 1, 6),
})

TextShape.create(textLabel, {
	text: 'This text is always readable',
})

Billboard.create(textLabel)

💡 Tip: Los billboards son muy útiles para añadir a campo text entidades, ya que las hace siempre legibles.

El rotation el valor del Transform componente de la entidad no cambia a medida que el billboard sigue a los jugadores.

Si una entidad tiene tanto un Billboard componente y Transform componente con rotation valores, los jugadores verán la entidad rotando como un billboard. Si el billboard no afecta todos los ejes, los ejes restantes se rotarán según el Transform component.

📔 Nota: Si hay varios jugadores presentes al mismo tiempo, cada uno verá las entidades con el modo billboard orientadas hacia ellos. Las rotaciones de billboard se calculan localmente para cada jugador y no afectan lo que ven los demás.

Mirar a un conjunto de coordenadas

Para que la entidad A mire a la entidad B:

1) Resta la posición de la entidad A de la de la entidad B para obtener un vector que describa la distancia entre ellas.
2) Normaliza ese vector, para que tenga una longitud de 1, manteniendo su dirección.
3) Usa `Quaternion.lookRotation` para obtener una rotación Quaternion que describa rotar en esa dirección.
4) Establece ese Quaternion como la rotación de la entidad A

export function turn(entity: Entity, target: ReadOnlyVector3) {
	const transform = Transform.getMutable(entity)
	const difference = Vector3.subtract(target, transform.position)
	const normalizedDifference = Vector3.normalize(difference)
	transform.rotation = Quaternion.lookRotation(normalizedDifference)
}

Escala

scale es también un vector 3D, almacenado como un Vector3 objeto, incluyendo el factor de escala en el x, y y z eje. La forma de la entidad se escala en consecuencia, ya sea que sea una primitiva o un modelo 3D.

La escala por defecto es 1, así que asigna un valor mayor que 1 para estirar una entidad o menor que 1 para reducirla.

// Crear una nueva entidad
const ball = engine.addEntity()

// Crear transform con una posición predefinida
Transform.create(ball, {
	  scale: Vector3.create(5, 5, 5)
}

// Obtener una versión mutable del transform
const mutableTransform = Transform.getMutable(ball)

// Establecer la escala con un Vector3

mutableTransform.scale = Vector3.create(2, 2, 2)

// Establecer la posición con un objeto
mutableTransform.scale = { x: 5, y: 1, z: 5 }

// Establecer cada eje individualmente
mutableTransform.scale.x = 3
mutableTransform.scale.y = 3
mutableTransform.scale.z = 2

Heredar transformaciones del padre

Cuando una entidad está anidada dentro de otra, las entidades hijas heredan componentes de los padres. Esto significa que si una entidad padre está posicionada, escalada o rotada, sus hijos también se ven afectados. Los valores de posición, rotación y escala de las entidades hijas no reemplazan los de los padres, sino que se combinan.

Asignas una entidad como padre de otra estableciendo el parent campo en el Transform component.

de la entidad hija.

// Crear entidades
const parentEntity = engine.addEntity()
const childEntity = engine.addEntity()

// Crear un transform para el padre
Transform.create(parentEntity, {
	position: Vector3.create(3, 1, 1),
	scale: Vector3.create(0.5, 0.5, 0.5),
})

// Crear un transform para el hijo y asignarlo como hijo
Transform.create(childEntity, {
	position: Vector3.create(0, 1, 0),
	parent: parentEntity,
})

En este ejemplo, la entidad hija se escalará a 0.5, ya que su padre tiene esa escala. La posición de la entidad hija también será relativa a su padre. Tenemos que sumar la posición del padre más la del hijo. En este caso, dado que el padre está escalado a la mitad de su tamaño, la transformación del hijo también se reduce proporcionalmente. En términos absolutos, el hijo está posicionado en { x: 3, y: 1.5, z: 1 }. Si el padre tuviera un rotation, esto también afectaría la posición final del hijo, ya que cambia el eje en el que el hijo se desplaza.

Si una entidad hija no tiene position en su Transform, el valor por defecto es 0,0,0, lo que la dejará posicionada en la misma posición que su padre.

Puedes usar una entidad invisible sin componente de forma como padre, para agrupar un conjunto de otras entidades. Esta entidad no será visible en la escena renderizada, pero puede usarse para agrupar a sus hijos y aplicarles un transform a todos.

Adjuntar una entidad a un avatar

Hay tres métodos para adjuntar una entidad al jugador:

• Hazla hija de la a la Avatar Entity

• Hazla hija de la a la Camera Entity

• Usa la componente AvatarAttach

La forma más simple de adjuntar una entidad al avatar es establecer el padre como el reserved entity engine.PlayerEntity. La entidad entonces se moverá junto con la posición del jugador.

let childEntity = engine.addEntity()

MeshRenderer.setCylinder(childEntity)

Transform.create(childEntity, {
	scale: Vector3.create(0.2, 0.2, 0.2),
	position: Vector3.create(0, 0.4, 0),
	parent: engine.PlayerEntity,
})

También puedes configurar una entidad al reserved entity engine.CameraEntity. Al usar la camera entity en primera persona, la entidad adjunta seguirá los movimientos de la cámara. Esto es ideal para mantener algo siempre a la vista, por ejemplo para mantener el modelo 3D de un arma siempre visible, incluso cuando la cámara apunte hacia arriba.

let childEntity = engine.addEntity()

MeshRenderer.setCylinder(childEntity)

Transform.create(childEntity, {
	scale: Vector3.create(0.2, 0.2, 0.2),
	position: Vector3.create(0, 0.4, 0),
	parent: engine.CameraEntity,
})

Para adjuntar un objeto a uno de los huesos del avatar, y hacer que se mueva junto con las animaciones del avatar, añade un AvatarAttach component a la entidad.

Puedes elegir diferentes puntos de anclaje en el avatar; la mayoría de estos puntos están vinculados al armature del jugador y siguen las animaciones del jugador. Por ejemplo, al usar el punto de anclaje de la mano derecha, la entidad adjunta se moverá cuando el avatar salude o balancee los brazos al correr, tal como si el jugador estuviera sosteniendo la entidad en su mano.

// Attach to main player, if avatarId is not set, engine.PlayerEntity is used by default
AvatarAttach.create(myEntity, {
	anchorPointId: AvatarAnchorPointType.AAPT_NAME_TAG,
})

// Attach to a player by ID
AvatarAttach.create(myEntity, {
	avatarId: '0xAAAAAAAAAAAAAAAAA',
	anchorPointId: AvatarAnchorPointType.AAPT_NAME_TAG,
})

Al crear un AvatarAttach component, pasa un objeto con los siguientes datos:

• avatarId: Opcional El ID del jugador al que adjuntarlo. Esto es el mismo que la dirección Ethereum del jugador, para aquellos jugadores conectados con una wallet de Ethereum. Si no se especifica, adjunta la entidad al avatar del jugador local.

• anchorPointId: Qué punto de anclaje en el esqueleto del avatar usar para adjuntar la entidad, usando un valor del enum AvatarAnchorPointType.

📔 Nota: Si quieres que todos los jugadores en la escena vean un objeto adjunto al mismo jugador, por ejemplo para que todos vean que el Jugador A recogió un objeto y lo tiene en la mano izquierda, entonces debes proporcionar un valor a avatarId. Si no se especifica, entonces todos los jugadores verán el objeto adjunto a sus propios avatares.

El siguiente ejemplo coloca una entidad adjunta a un avatar en particular, para que todos los demás jugadores la vean adjunta a ese mismo avatar.

import { getPlayer } from '@dcl/sdk/src/players'
import { AvatarAnchorPointType, AvatarAttach, engine, Entity } from '@dcl/sdk/ecs'
import { syncEntity } from '@dcl/sdk/src/network'

async function attachToPlayer(){

 let userData = await getPlayer()
 console.log(userData)

 if (!userData || !userData.wearables) return

  let entity = engine.addEntity()

  AvatarAttach.create(entity, {
    avatarId: userData.userId,
    anchorPointId: AvatarAnchorPointType.AAPT_RIGHT_HAND,
  })

  // Other components

  syncEntity(entity, [AvatarAttach.componentId])

}

Los siguientes puntos de anclaje están disponibles en el AvatarAnchorPointType enum:

• AAPT_RIGHT_HAND: Fijado en la mano derecha del jugador

• AAPT_LEFT_HAND: Fijado en la mano izquierda del jugador

• AAPT_HEAD: Fijado al centro de la cabeza del jugador.

• AAPT_NECK: Fijado en la base del cuello del jugador.

• AAPT_SPINE: Fijado en la sección superior de la columna vertebral.

• AAPT_SPINE1: Fijado en la sección media de la columna vertebral.

• AAPT_SPINE2: Fijado en la sección baja de la columna vertebral.

• AAPT_HIP: Fijado al hueso de la cadera.

• AAPT_LEFT_SHOULDER: Fijado al hombro izquierdo.

• AAPT_LEFT_ARM: Fijado al primer hueso del brazo izquierdo, a la altura del hombro.

• AAPT_LEFT_FOREARM: Fijado al hueso del antebrazo izquierdo.

• AAPT_LEFT_HAND_INDEX: Fijado en la punta del dedo índice izquierdo.

• AAPT_RIGHT_SHOULDER: Fijado al hombro derecho.

• AAPT_RIGHT_ARM: Fijado al primer hueso del brazo derecho, a la altura del hombro.

• AAPT_RIGHT_FOREARM: Fijado al hueso del antebrazo derecho.

• AAPT_RIGHT_HAND_INDEX: Fijado en la punta del dedo índice derecho.

• AAPT_LEFT_UP_LEG: Fijado al hueso superior de la pierna izquierda.

• AAPT_LEFT_LEG: Fijado al hueso inferior de la pierna izquierda.

• AAPT_LEFT_FOOT: Fijado al tobillo de la pierna izquierda.

• AAPT_LEFT_TOE_BASE: Fijado en la punta del dedo del pie de la pierna izquierda.

• AAPT_RIGHT_UP_LEG: Fijado al hueso superior de la pierna derecha.

• AAPT_RIGHT_LEG: Fijado al hueso inferior de la pierna derecha.

• AAPT_RIGHT_FOOT: Fijado al tobillo de la pierna derecha.

• AAPT_RIGHT_TOE_BASE: Fijado en la punta del dedo del pie de la pierna derecha.

• .AAPT_NAME_TAG: Flota justo encima del name tag del jugador, no se ve afectado por las animaciones del jugador.

  Nota: La altura del name tag se ajusta dinámicamente según la altura de los wearables que tenga un jugador. Por lo tanto, un jugador que lleve un sombrero alto tendrá su name tag un poco más alto que otros.

• AAPT_POSITION DEPRECATED: La posición general del jugador. Esto aparece a una altura de 0.8 por encima de los pies del jugador.

> **📔 Nota**: El `AAPT_POSITION` está deprecated. Para seguir la posición general del jugador, es mejor hacer la entidad hija del Avatar Entity. Ve el inicio de esta sección para un ejemplo. >

💡 Tip: Para usar estos valores, escribe AvatarAnchorPointType. y VS Code mostrará la lista completa de opciones en un desplegable.

El renderizado de entidades se determina localmente en cada instancia de la escena. Adjuntar una entidad a un jugador no hace que sea visible para otros jugadores que estén viendo a ese jugador. Si una entidad está adjunta al jugador local por defecto, cada jugador experimentará la entidad como adjunta a su propio avatar.

📔 Nota: Las entidades adjuntas a un avatar deben permanecer dentro de los límites de la escena para ser renderizadas. Si un jugador sale de tu escena, cualquier entidad adjunta deja de renderizarse hasta que el jugador vuelva a entrar. Los smart wearables no tienen esta limitación.

El AvatarAttach component sobrescribe los valores en el Transform component. Cualquier valor que pongas en el Transform component es reemplazado por la posición relativa de la entidad respecto a la del Transform del jugador; estos valores se actualizan cuadro por cuadro a medida que el jugador se mueve y anima.

Si necesitas posicionar una entidad con un offset desde el punto de anclaje en el avatar, o una rotación o escala diferente, hazlo mediante una entidad padre.

1. Crea una entidad invisible con solo un Transform y un AvatarAttach component. Sus Transform valores serán sobrescritos a medida que el jugador se mueva

2. Establece la entidad que quieres adjuntar como hija de este padre. Sus Transform valores pueden describir el offset desde el punto de anclaje.

// Create parent entity
const parentEntity = engine.addEntity()

// Attach parent entity to player
AvatarAttach.create(parentEntity, {
	anchorPointId: AvatarAnchorPointType.AAPT_NAME_TAG,
})

// Create child entity
let childEntity = engine.addEntity()

MeshRenderer.setCylinder(childEntity)

Transform.create(childEntity, {
	scale: Vector3.create(0.2, 0.2, 0.2),
	position: Vector3.create(0, 0.4, 0),
	parent: parentEntity,
})

📔 Nota: Si la entidad adjunta tiene colliders, estos colliders podrían bloquear el movimiento del jugador o causar efectos de temblor. Puede que quieras deshabilitar la physics layer de los colliders de la entidad adjunta. Ver Collision layers

📔 Nota: Si tienes una entidad hija y quieres conocer la Position y/o Rotation global de la misma, puedes usar las getWorldPosition y getWorldRotation functions. Puedes consultarlas en el Getting Global Position and Rotation sección.

Adjuntar a otros jugadores

Puedes usar el AvatarAttach component para adjuntar una entidad a otro jugador. Para hacer esto, debes conocer el id del jugador.

Para adjuntar una entidad al avatar de otro jugador, debes proporcionar el ID del usuario en el campo avatarId. Hay varias maneras de obtener estos datos.

📔 Nota: Para aquellos jugadores conectados con una wallet de Ethereum, su userId es la misma que su dirección Ethereum.

Obtén el userId para todos los demás jugadores cercanos vía getPlayer()

executeTask(async () => {
	for (const [entity, data] of engine.getEntitiesWith(PlayerIdentityData)) {
		console.log('Player id: ', data.address)
	}
})

Usándolo junto con AvatarAttach, podrías usar el siguiente código para añadir un cubo flotando sobre la cabeza de cada otro jugador en la escena:

executeTask(async () => {
        for (const [entity, data] of engine.getEntitiesWith(PlayerIdentityData)) {
            const myEntity = engine.addEntity()
            MeshRenderer.setBox(myEntity)
            AvatarAttach.create(myEntity, {
                anchorPointId: AvatarAnchorPointType.AAPT_LEFT_HAND,
                avatarId: data.address,
            })
        }
    })

Ve otras formas de obtener los IDs de otros usuarios en Get Player Data.

Límites de la escena

Todas las entidades en tu escena deben caber dentro de los límites de la escena, ya que lo que esté fuera de esos límites son parcelas de tierra propiedad de otros jugadores.

Si alguna parte de tus modelos se extiende más allá de estos límites al ejecutar una preview, esas partes que se extiendan serán recortadas y no se renderizarán, tanto al ejecutar una preview como en la escena publicada.

La posición de las entidades en tu escena se comprueba constantemente mientras se mueven; si una entidad sale de la escena y luego vuelve, será eliminada y luego renderizada normalmente otra vez.

Una cuadrícula en el suelo de la escena muestra los límites de la escena, que por defecto van de 0 a 16 en el eje x y z y hasta 20 en el eje y . Puedes colocar entidades bajo tierra, por debajo de 0 en el y eje.

💡 Tip: Si tu escena necesita más parcelas, puedes añadirlas en el archivo del proyecto scene.json . Ver Scene metadata para las instrucciones. Una vez añadidas, deberías ver la cuadrícula extenderse para cubrir las parcelas adicionales.