Entity Positioning

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

Puedes establecer la posición, rotación y escala de cualquier entity usando el Transform component. Esto se puede usar en cualquier entity en el espacio 3D, afectando dónde se renderiza la entitiy. 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 ítem a tu scene mediante el Scene Editor, este incluye implícitamente un Transform component. Luego cambias los valores del componente Transform de la entity implícitamente al cambiar la posición, rotación o escala de una entity. También puedes usar la UI del Scene Editor para proporcionar valores numéricamente con mayor precisión.

Aspectos esenciales del código

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

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

// Darle a esta entity 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 entity en tu scene durante un período de tiempo, cambia los valores de este componente de forma incremental, cuadro por cuadro. Consulta Mover entities para más detalles y mejores prácticas.

📔 Nota: Vector3 y Quaternion deben importarse mediante

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

Consulta Imports para ver cómo manejar esto fácilmente.

Posición

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

// Crear una nueva entity
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 entity sea hija de una entity escalada).

• Una scene compuesta por una sola parcel mide 16 m x 16 m. El centro de la scene (a nivel del suelo) está en x:8, y:0, z:8. Si la scene 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 South-West de la parcel base de la scene, a nivel del suelo.

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

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

• Para orientarte mejor, usa tu left mano:

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

  • tu dedo medio (apuntando hacia un lado) es el x axis

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

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

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

  Consejo: Al ver una scene en modo Preview, las entities que están fuera de límites se resaltan en rojo.

• Tu scene también está limitada en altura. Cuantas más parcels compongan la scene, más alto podrás construir. Consulta limitaciones de la scene para más detalles.

Rotación

rotación 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. Consulta Tipos de geometría para más detalles.

// Crear una nueva entity
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 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 las personas 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 entity, devuelve un quaternion de forma predeterminada. Para obtener la rotación expresada como á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)

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

El getWorldPosition y getWorldRotation functions devuelven la posición y rotación globales de una entity. Eso significa que devuelve la posición o rotación percibida en la que el jugador verá el ítem, ignorando cualquier jerarquía padre.

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

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

• getWorldRotation(engine, entity: Entity): QuaternionType: Esta function devuelve la rotación World de una entity, teniendo en consideración todas las rotaciones de las entities padre, si la propia antity tiene alguna. Devuelve un Quaternion type, devolviendo el quaternion identidad {x: 0, y: 0, z: 0, w: 1} si la entity no tiene Transform.

const worldRot = getWorldRotation(engine, childEntity)
console.log(`Rotación World: ${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 scene y no a Genesis City.

Mirar hacia el jugador

Agrega un Billboard component a una entity para que siempre gire 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 entities eran planos 2D que siempre miraban al jugador. La misma idea también puede usarse para rotar un modelo 3D.

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

// Darle a la entity una forma visible
MeshRenderer.setBox(cube)

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

// Darle a la entity 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 entity rota para mirar al jugador en todos sus ejes de rotación. Si el jugador está muy por encima de la entity, la entity mirará hacia arriba.

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

  • BillboardMode.BM_X: La entity tiene su x eje de rotación fijo.

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

  • BillboardMode.BM_Z: La entity tiene su z eje de rotación fijo.

// 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: 'Este texto siempre es legible',
})

Billboard.create(textLabel)

💡 Consejo: Los billboards son muy útiles para agregar a text entities, ya que las hace siempre legibles.

El rotación valor del componente Transform de la entity no cambia mientras el billboard sigue a los jugadores.

Si una entity tiene tanto un Billboard componente y Transform component con rotación valores, los jugadores verán la entity rotando como un billboard. Si el billboard no afecta a todos los ejes, los ejes restantes rotarán de acuerdo con el Transform componente.

📔 Nota: Si hay varios jugadores presentes al mismo tiempo, cada uno verá las entities con modo billboard mirándolo a él. Las rotaciones de billboard se calculan localmente para cada jugador y no afectan lo que ven los demás.

Mirar hacia un conjunto de coordenadas

Para que la entity A mire a la entity B:

1) Resta la posición de la entity A de la entity 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 la rotación en esa dirección.
4) Establece ese Quaternion como la rotación de la entity 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

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

La escala predeterminada es 1, así que asigna un valor mayor que 1 para estirar una entity o menor que 1 para encogerla.

// Crear una nueva entity
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 entity está anidada dentro de otra, las entities hijas heredan componentes de los padres. Esto significa que si una entity padre está posicionada, escalada o rotada, sus hijas también se ven afectadas. Los valores de posición, rotación y escala de las entities hijas no sobrescriben los de los padres; en cambio, se componen.

Asignas una entity para que sea padre de otra configurando el parent campo en el Transform componente.

Si una entity padre está escalada, todos los valores de posición de sus hijas también se escalan.

// Crear entities
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 child, y asignarlo como child
Transform.create(childEntity, {
	position: Vector3.create(0, 1, 0),
	parent: parentEntity,
})

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

Si una entidad child no tiene posición en su Transform, el valor predeterminado es 0,0,0, lo que la dejará posicionada en la misma posición que su parent.

Puedes usar una entidad invisible sin componente shape como parent para envolver un conjunto de otras entidades. Esta entidad no será visible en la escena renderizada, pero se puede usar para agrupar a sus children y aplicarles una transformación a todos ellos.

Adjuntar una entidad a un avatar

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

• Hacerla child de la Avatar Entity

• Hacerla child de la Camera Entity

• Usa la componente AvatarAttach

La forma más sencilla de adjuntar una entidad al avatar es establecer el parent como la entidad reservada engine.PlayerEntity. Entonces la entidad se moverá junto con la posición del player.

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 establecer una entidad en la entidad reservada 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 del arma siempre visible, incluso cuando la cámara apunta 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 bones del avatar y que se mueva junto con las animaciones del avatar, añade un AvatarAttach componente a la entidad.

Puedes elegir diferentes anchor points en el avatar; la mayoría de estos puntos están vinculados al armature del player y siguen las animaciones del player. Por ejemplo, al usar el anchor point de la mano derecha, la entidad adjunta se moverá cuando el avatar salude o balancee los brazos mientras corre, como si el player sostuviera la entidad en su mano.

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

// Adjuntar a un player por ID
AvatarAttach.create(myEntity, {
	avatarId: '0xAAAAAAAAAAAAAAAAA',
	anchorPointId: AvatarAnchorPointType.AAPT_NAME_TAG,
})

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

• avatarId: Opcional El ID del player al que adjuntar. Esto es lo mismo que la dirección Ethereum del player, para aquellos players conectados con un wallet de Ethereum. Si no se especifica, adjunta la entidad al avatar del player local.

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

📔 Nota: Si quieres que todos los players en la escena vean un objeto adjunto al mismo player, por ejemplo, para que todos vean que el Player A recogió un objeto y lo sostiene en su mano izquierda, entonces debes proporcionar un valor a avatarId. Si no se especifica, entonces todos los players 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 players 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,
  })

  // Otros components

  syncEntity(entity, [AvatarAttach.componentId])

}

Los siguientes anchor points están disponibles en el AvatarAnchorPointType enum:

• AAPT_RIGHT_HAND: Fijo en la mano derecha del player

• AAPT_LEFT_HAND: Fijo en la mano izquierda del player

• AAPT_HEAD: Fijo en el centro de la cabeza del player.

• AAPT_NECK: Fijo en la base del cuello del player.

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

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

• AAPT_SPINE2: Fijo en la sección inferior de la columna vertebral.

• AAPT_HIP: Fijo en el hueso de la cadera.

• AAPT_LEFT_SHOULDER: Fijo en el hombro izquierdo.

• AAPT_LEFT_ARM: Fijo en el primer hueso del brazo izquierdo, a la altura del hombro.

• AAPT_LEFT_FOREARM: Fijo en el hueso del antebrazo izquierdo.

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

• AAPT_RIGHT_SHOULDER: Fijo en el hombro derecho.

• AAPT_RIGHT_ARM: Fijo en el primer hueso del brazo derecho, a la altura del hombro.

• AAPT_RIGHT_FOREARM: Fijo en el hueso del antebrazo derecho.

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

• AAPT_LEFT_UP_LEG: Fijo en el hueso superior de la pierna izquierda.

• AAPT_LEFT_LEG: Fijo en el hueso inferior de la pierna izquierda.

• AAPT_LEFT_FOOT: Fijo en el tobillo de la pierna izquierda.

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

• AAPT_RIGHT_UP_LEG: Fijo en el hueso superior de la pierna derecha.

• AAPT_RIGHT_LEG: Fijo en el hueso inferior de la pierna derecha.

• AAPT_RIGHT_FOOT: Fijo en el tobillo de la pierna derecha.

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

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

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

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

> **📔 Nota**: `AAPT_POSITION` está obsoleto. Para seguir la posición general del player, lo mejor es hacer que la entidad sea child de la Avatar Entity. Consulta el inicio de esta sección para ver un ejemplo. >

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

El renderizado de la entidad se determina localmente en cada instancia de la escena. Adjuntar una entidad a un player no la hace visible para otros players que estén viendo a ese player. Si una entidad está adjunta al player local predeterminado, cada player 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 player sale de tu escena, cualquier entidad adjunta dejará de renderizarse hasta que el player vuelva a entrar. Los Smart wearables no tienen esta limitación.

El AvatarAttach El componente sobrescribe los valores en el Transform componente. Cualquier valor que pongas en el Transform componente se reemplaza por la posición relativa de la entidad respecto a la Transform del player; estos valores se actualizan frame por frame mientras el player se mueve y anima.

Si necesitas posicionar una entidad con un offset desde el anchor point en el avatar, o con una rotación o escala diferente, hazlo mediante una entidad parent.

1. Crea una entidad invisible con solo un Transform y un AvatarAttach componente. Sus valores de Transform se sobrescribirán a medida que el player se mueva

2. Establece la entidad que quieres adjuntar como child de este parent. Sus valores de Transform pueden describir el offset desde el anchor point.

// Crear entidad parent
const parentEntity = engine.addEntity()

// Adjuntar entidad parent al player
AvatarAttach.create(parentEntity, {
	anchorPointId: AvatarAnchorPointType.AAPT_NAME_TAG,
})

// Crear entidad child
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 player o causar efectos de jitter. Es posible que quieras deshabilitar la physics layer de los colliders de la entidad adjunta. Consulta Collision layers

📔 Nota: Si tienes una entidad child y quieres conocer su Position y/o Rotation globales, puedes usar las getWorldPosition y getWorldRotation funciones. Puedes consultarlas en la Obtener Position y Rotation globales .

Adjuntar a otros players

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

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

📔 Nota: Para aquellos players conectados con un wallet de Ethereum, su userId es el mismo que su dirección Ethereum.

Obtén el userId de todos los demás players cercanos mediante 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 player 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,
            })
        }
    })

Consulta otras formas de obtener los IDs de otros usuarios en Obtener datos del player.

Límites de la scene

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 que pertenecen a otros players.

Si alguna parte de tus modelos se extiende más allá de estos límites al ejecutar una preview, esas partes que sobresalgan se recortarán 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 a medida que se mueven; si una entidad sale de la escena y luego vuelve, se eliminará y después se renderizará 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 x y z eje, y hasta 20 en el y eje. Eres libre de colocar entidades bajo tierra, por debajo de 0 en el y eje.

💡 Consejo: Si tu escena necesita más parcels, puedes añadirlas en el scene.json archivo del proyecto. Consulta Scene metadata para obtener instrucciones. Una vez añadidas, deberías ver cómo la cuadrícula se extiende para cubrir las parcels adicionales.