Posicionamiento de entidades

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

Puedes establecer la propiedad 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, NftShape y modelos 3D (GltfContainer).

Usa el Scene Editor en Creator Hub

Al añadir un elemento a tu escena mediante el Scene Editor, implícitamente incluye un Transform componente. Luego cambias los valores en el componente Transform de la entidad implícitamente al cambiar 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 esenciales de código

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

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

// Darle 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 de este componente de forma incremental, 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"

Vea Imports para ver cómo manejar estos fácilmente.

Posición

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 múltiples parcels, entonces el centro variará según 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 un lado) 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 las parcels que ocupa en todo momento. Si una entidad sale de esos límites, generará un error.

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

• Tu escena también tiene un límite de altura. Cuantas más parcels componen la escena, más alto puedes construir. Ver limitaciones de la escena para más detalles.

Rotación

rotation se guarda 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, a partir de á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 rotation 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 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, a partir de á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, a partir de ángulos Euler
const eulerAngle = Quaternion.toEuler(transform.rotation)

Mirar al jugador

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

Los billboards fueron una técnica común usada en 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 de la 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á 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 arriba y 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)

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

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

Si una entidad tiene tanto un Billboard componente como un 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 la Transform componente.

📔 Nota: Si hay múltiples 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 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 B para obtener un vector que describa la distancia entre ellas.
2) Normaliza ese vector, de modo 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 una primitiva o un modelo 3D.

La escala por defecto es 1, así que asigna un valor mayor a 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 sobrescriben los de los padres; en su lugar, se componen.

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

Transform de la entidad hija.

Si una entidad padre está escalada, todos los valores de posición de sus hijos también se escalan.
const parentEntity = engine.addEntity()
const childEntity = engine.addEntity()

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

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

position: Vector3.create(0, 1, 0), En este ejemplo, la entidad hija se reducirá 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, 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 } rotation. Si el padre tuviera una

, esto también afectaría la posición final del hijo, ya que cambia el eje en el que el hijo se desplaza. position Si una entidad hija no tiene 0,0,0en su Transform, el valor por defecto es

, 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 envolver un conjunto de otras entidades. Esta entidad no será visible en la escena renderizada, pero puede usarse para agrupar sus hijos y aplicarles un transform a todos.

Adjuntar una entidad a un avatar

• Hay tres métodos para adjuntar una entidad al jugador: Hacerla hija del

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

• Usa la Camera Entity

componente AvatarAttach La forma más simple de adjuntar una entidad al avatar es establecer el parent como la engine.PlayerEntityentidad reservada

. La entidad entonces se moverá junto con la posición del jugador.

let childEntity = engine.addEntity()

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

parent: engine.PlayerEntity, La forma más simple de adjuntar una entidad al avatar es establecer el parent como la También puedes asignar una entidad a laengine.CameraEntity

. La entidad entonces se moverá junto con la posición del jugador.

let childEntity = engine.addEntity()

Transform.create(childEntity, {
	MeshRenderer.setCylinder(childEntity)
	scale: Vector3.create(0.2, 0.2, 0.2),
	. 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 del arma siempre visible, incluso cuando la cámara apunta hacia arriba.
})

parent: engine.CameraEntity, AvatarAttach Para adjuntar un objeto a uno de los huesos del avatar y que se mueva junto con las animaciones del avatar, añade un

componente al 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 mientras corre, como si el jugador estuviera sosteniendo la entidad en su mano.
// Adjuntar al jugador principal; si avatarId no está establecido, por defecto se usa engine.PlayerEntity
	AvatarAttach.create(myEntity, {
})

anchorPointId: AvatarAnchorPointType.AAPT_NAME_TAG,
// Adjuntar al jugador principal; si avatarId no está establecido, por defecto se usa engine.PlayerEntity
	// Adjuntar a un jugador por ID
	AvatarAttach.create(myEntity, {
})

Al crear un AvatarAttach avatarId: '0xAAAAAAAAAAAAAAAAA',

• componente, pasa un objeto con los siguientes datos:: avatarId Opcional

• El ID del jugador al que adjuntar. Esto es lo 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.

📔 NotaAvatarAnchorPointType componente, pasa un objeto con los siguientes datos:: 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 sostiene en la mano izquierda, entonces debes proporcionar un valor a

. Si no se especifica, todos los jugadores verán el objeto adjunto a sus propios avatares.

import { getPlayer } from '@dcl/sdk/src/players'
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 { AvatarAnchorPointType, AvatarAttach, engine, Entity } from '@dcl/sdk/ecs'

import { syncEntity } from '@dcl/sdk/src/network'

 async function attachToPlayer(){
 console.log(userData)

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

  let userData = await getPlayer()

  let entity = engine.addEntity()
    AvatarAttach.create(entity, {
    avatarId: userData.userId,
  })

  anchorPointId: AvatarAnchorPointType.AAPT_RIGHT_HAND,

  // Otros componentes

}

syncEntity(entity, [AvatarAttach.componentId]) : Qué punto de anclaje en el esqueleto del avatar usar para adjuntar la entidad, usando un valor del enum Los siguientes puntos de anclaje están disponibles en el

• enum:AAPT_RIGHT_HAND

• : Fijado en la mano derecha del jugadorAAPT_LEFT_HAND

• : Fijado en la mano izquierda del jugadorAAPT_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 inferior 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 en función de la altura de los wearables que tenga un jugador. Así que un jugador que lleve un sombrero alto tendrá su name tag un poco más alto que otros. AAPT_POSITIONDEPRECATED

: La posición general del jugador. Aparece a una altura de 0.8 por encima de los pies del jugador.

💡 Consejo> **📔 Nota**: `AAPT_POSITION` está deprecated. Para seguir la posición general del jugador, es mejor hacer la entidad hija de la Avatar Entity. Ver el inicio de esta sección para un ejemplo. > : Para usar estos valores, escribe AvatarAnchorPointType.

y VS Code mostrará la lista completa de opciones en un desplegable.

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

El AvatarAttach : 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, las entidades adjuntas dejan de renderizarse hasta que el jugador vuelva a entrar. Los smart wearables no tienen esta limitación. Transform El componente sobrescribe al AvatarAttach componente. Una sola entidad puede tener tanto un Transform como un Transform componente al mismo tiempo, pero los valores en el

componente se ignoran.

Si necesitas posicionar una entidad con un offset respecto al punto de anclaje en el avatar, o con una rotación o escala diferente, adjunta una entidad padre al punto de anclaje. Luego puedes establecer el modelo visible en una entidad hija de ese padre y darle a esta hija su propio componente Transform para describir sus desplazamientos desde el punto de anclaje.
const parentEntity = engine.addEntity()

// Crear entidad padre
// Adjuntar entidad padre al jugador
	AvatarAttach.create(myEntity, {
})

AvatarAttach.create(parentEntity, {
. La entidad entonces se moverá junto con la posición del jugador.

let childEntity = engine.addEntity()

Transform.create(childEntity, {
	MeshRenderer.setCylinder(childEntity)
	scale: Vector3.create(0.2, 0.2, 0.2),
	parent: parentEntity,
})

📔 Nota// Crear entidad hija : Si la entidad adjunta tiene colliders, estos colliders podrían bloquear el movimiento del jugador. Considera deshabilitar la capa de física de los colliders de la entidad. Ver

Collision layers

Puedes usar la AvatarAttach Adjuntar a otros jugadores

componente para adjuntar una entidad a otro jugador. Para hacer esto, debes conocer el id del jugador. componente, pasa un objeto con los siguientes datos:Para adjuntar una entidad al avatar de otro jugador, debes proporcionar el ID del usuario en el campo . Hay varias formas

📔 Notade obtener estos datos. userId : Para aquellos jugadores conectados con una wallet de Ethereum, su

es lo mismo que su dirección Ethereum. userId Obtén el getPlayer()

executeTask(async () => {
	para todos los demás jugadores cercanos vía
		for (const [entity, data] of engine.getEntitiesWith(PlayerIdentityData)) {
	}
})

console.log('Player id: ', data.address) AvatarAttachUsándolo junto con

executeTask(async () => {
        para todos los demás jugadores cercanos vía
            const myEntity = engine.addEntity()
            MeshRenderer.setBox(myEntity)
            // Adjuntar al jugador principal; si avatarId no está establecido, por defecto se usa engine.PlayerEntity
                , podrías usar el siguiente código para añadir un cubo flotando sobre la cabeza de cada otro jugador en la escena:
                anchorPointId: AvatarAnchorPointType.AAPT_LEFT_HAND,
            })
        }
    })

avatarId: data.address, Ver otras formas de obtener los IDs de otros usuarios en.

Límites de la escena

Obtener datos del jugador

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 parcels de tierra que pertenecen a otros jugadores.

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

La posición de las entidades en tu escena se verifica constantemente a medida que se mueven; si una entidad sale de la escena y luego vuelve, será eliminada y luego renderizada normalmente otra vez. x y z 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 y , y hasta 20 en el eje y eje.

💡 Consejo. Eres libre de colocar entidades bajo tierra, por debajo de 0 en el scene.json : Si tu escena necesita más parcels, puedes añadirlas en el archivo del proyecto file. Ver Scene metadata