Posicionamiento de Entities
Cómo establecer la posición, rotación y escala de una Entity en una escena
Puedes establecer la posición, rotación y escala de cualquier entity usando el Transform component. Esto puede usarse en cualquier entity en el espacio 3D, afectando dónde se renderiza la entity. 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
Cuando añades un elemento a tu Scene mediante el Scene Editor, incluye implícitamente un Transform component. Luego cambias los valores en el Transform component de la entity de forma implícita 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 más precisión.
Conceptos básicos del código

Para mover, rotar o redimensionar una entity en tu Scene a lo largo del tiempo, cambia los valores de este component de forma incremental, frame a frame. Consulta Mover entities para más detalles y buenas prácticas.
📔 Nota: Vector3 y Quaternion deben importarse mediante
import { Vector3, Quaternion } from "@dcl/sdk/math"
Consulta Imports para ver cómo manejarlos fácilmente.
Position
posición es un vector 3D, establece la posición del centro de la entity en los tres ejes, x, yy z. Consulta Tipos de geometría para más detalles.
Al establecer una posición, ten en cuenta las siguientes consideraciones:
Los números en un vector de posición representan metros (salvo que la entity sea hija de una entity escalada).
Una Scene formada por un solo 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á formada por varios Parcels, entonces el centro variará según su disposición.x:0, y:0, z:0se refiere a la suroeste esquina del Parcel base de la Scene, a nivel del suelo.Consejo: Al ver una vista previa de la Scene, aparece una brújula en el punto (0,0,0) de la Scene con etiquetas para cada eje como referencia.
Nota: Puedes cambiar el Parcel base de una Scene editando el
baseatributo de scene.json.Para orientarte mejor, usa tu mano izquierda :
tu dedo índice (apuntando hacia delante) 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 entity es hija de otra, entonces
x:0, y:0, z:0se refiere al centro de su entity padre, dondequiera que esté en la Scene.Cada entity en tu Scene debe mantenerse en todo momento dentro de los límites de los Parcels que ocupa. Si una entity sale de esos límites, se producirá un error.
Consejo: Al ver una Scene en modo de vista previa, las entities que están fuera de límites se resaltan en rojo.
Tu Scene también está limitada en altura. Cuantos más Parcels formen la Scene, más alto puedes construir. Consulta las limitaciones de la Scene para más detalles.
Rotation
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 -1 a 1. Consulta Tipos de geometría para más detalles.
También puedes establecer el campo rotation con ángulos de Euler ángulos, la notación más común con números que van de 0 a 360, con la que la mayoría de las personas está familiarizada. Para usar ángulos de Euler, usa una de las siguientes notaciones: x, y y z // Crear transform con una rotación predefinida en ángulos de Euler
Vector3 vector 3D para representar ángulos de Euler, x, y y z representa la rotación en ese eje, medida en grados. Un giro completo requiere 360 grados.
Cuando recuperas la rotación de una entity, devuelve un quaternion de forma predeterminada. Para obtener la rotación expresada como en ángulos de Euler, usa Quaternion.toEulerAngles():
Obtener la posición global y la rotación global de una Entity
Las getWorldPosition y getWorldRotation funciones devuelven la posición global y la rotación global de una entity. Eso significa que devuelven la posición o rotación percibida en la que el player verá el objeto, ignorando cualquier jerarquía de parent.
getWorldPosition(engine, entity: Entity): Vector3Type: Esta función devuelve la posición global de una entity, teniendo en cuenta todas las posiciones de las entities parent, si la propia entity tiene alguna, devolviendo{x: 0, y: 0, z: 0}si la entity no tiene Transform.
getWorldRotation(engine, entity: Entity): QuaternionType: Esta función devuelve la rotación global de una entity, teniendo en cuenta todas las rotaciones de las entities parent, si la propia entity tiene alguna. Devuelve unQuaterniontipo, devolviendo el quaternion identidad{x: 0, y: 0, z: 0, w: 1}si la entity no tiene Transform.
Haz que mire al player
Añade un Billboard component a una entity para que siempre gire para mirar al player.
Los Billboards eran una técnica común en los juegos 3D de los 90, donde la mayoría de las entities eran planos 2D que siempre miraban al player. La misma idea también puede usarse para rotar un modelo 3D.
Puedes configurar cómo se comporta el billboard con los siguientes parámetros:
billboardMode: Usa un valor deBillboardModepara establecer qué ejes de rotación giran automáticamente para mirar al player:BillboardMode.BM_ALL: La entity gira para mirar al player en todos sus ejes de rotación. Si el player está muy por encima de la entity, la entity mirará hacia arriba.BillboardMode.BM_NONE: La entity no girará en absoluto.BillboardMode.BM_X: La entity solo gira en su x eje de rotación.BillboardMode.BM_Y: La entity solo gira en su y eje de rotación. Solo gira a izquierda y derecha, no arriba y abajo. Permanece perpendicular al suelo si el player está por encima o por debajo de la entity.BillboardMode.BM_Z: La entity solo gira en su z eje de rotación.
targetEntity: (opcional) Una entity hacia la que el billboard gira para mirar, en lugar de la cámara del player. Si la entity referenciada no existe (por ejemplo, aún no se ha creado o se eliminó), el billboard deja de girar y mantiene su última orientación hasta que la entity vuelva a existir. Establecer esto enengine.CameraEntityes equivalente a dejarlo sin establecer.
Las rotación El valor del Transform component de la entity no cambia mientras el billboard sigue a los players.
Si una entity tiene tanto un Billboard component y Transform component con rotación valores, los players verán la entity girando como un Billboard. Si el billboard no afecta a todos los ejes, el eje restante girará según el Transform component.
📔 Nota: Si hay varios players presentes al mismo tiempo, cada uno verá las entities con modo billboard mirándolos. Las rotaciones de Billboard se calculan localmente para cada player y no afectan a lo que ven los demás. Esto no se aplica a los billboards con un targetEntity: ya que la posición del target forma parte de la Scene, todos los players ven esos billboards orientados de la misma manera.
Mirar hacia un conjunto de coordenadas
Para que la entity A mire a la entity B:
Scale
escala también es un vector 3D, almacenada 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, tanto si es una primitiva como 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 reducirla.
Heredar transformaciones del parent
Cuando una entity está anidada dentro de otra, las entities child heredan componentes de sus parents. Esto significa que, si una entity parent está posicionada, escalada o rotada, sus children también se ven afectados. Los valores de posición, rotación y escala de las entities child no anulan los de sus parents, sino que se combinan.
Asignas una entity como parent de otra estableciendo el parent campo en la Transform component.
Si una entity parent se escala, todos los valores de posición de sus children también se escalan.
En este ejemplo, la entity child se reducirá a 0.5, ya que su parent tiene esa escala. La posición de la entity 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 la posición final del child, ya que cambia el eje en el que se desplaza el child.
Si una entity 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 entity invisible sin un shape component como parent, para envolver un conjunto de otras entities. Esta entity no será visible en la Scene renderizada, pero puede usarse para agrupar a sus children y aplicar un Transform a todas ellas.
Adjuntar una entity a un avatar
Hay tres métodos para adjuntar una entity al player:
Hazla child de la Avatar Entity
Hazla child de la Camera Entity
Usa el AvatarAttach component
La forma más sencilla de adjuntar una entity al avatar es establecer el parent como la entity reservada engine.PlayerEntity. Entonces la entity se moverá junto con la posición del player.
También puedes establecer una entity en la entity reservada engine.CameraEntity. Cuando se usa la entity de cámara en primera persona, la entity 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 a la vista, incluso cuando la cámara apunta hacia arriba.
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 entity.
Puedes elegir distintos puntos de anclaje en el avatar; la mayoría de estos puntos están vinculados al armature del player y siguen sus animaciones. Por ejemplo, al usar el punto de anclaje de la mano derecha, la entity adjunta se moverá cuando el avatar salude o balancee los brazos mientras corre, como si el player estuviera sosteniendo la entity en su mano.
Cuando crees un AvatarAttach component, pasa un objeto con los siguientes datos:
avatarId: Opcional El ID del player al que adjuntar. Es el mismo que la dirección de Ethereum del player, para aquellos players conectados con una wallet de Ethereum. Si no se especifica, adjunta la entity al avatar del player local.anchorPointId: Qué punto de anclaje del esqueleto del avatar usar para adjuntar la entity, utilizando un valor del enumAvatarAnchorPointType.
📔 Nota: Si quieres que todos los players de la Scene 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, todos los players verán el objeto adjunto a sus propios avatars.
El siguiente ejemplo coloca una entity adjunta a un avatar concreto, para que todos los demás players la vean adjunta a ese mismo avatar.
Los siguientes puntos de anclaje están disponibles en el AvatarAnchorPointType enum:
AAPT_RIGHT_HAND: Fijo en la mano derecha del jugadorAAPT_LEFT_HAND: Fijo en la mano izquierda del jugadorAAPT_HEAD: Fijo en el centro de la cabeza del jugador.AAPT_NECK: Fijo en la base del cuello del jugador.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 al hueso de la cadera.AAPT_LEFT_SHOULDER: Fijo al hombro izquierdo.AAPT_LEFT_ARM: Fijo al primer hueso del brazo izquierdo, a la altura del hombro.AAPT_LEFT_FOREARM: Fijo al hueso del antebrazo izquierdo.AAPT_LEFT_HAND_INDEX: Fijo a la punta del dedo índice izquierdo.AAPT_RIGHT_SHOULDER: Fijo al hombro derecho.AAPT_RIGHT_ARM: Fijo al primer hueso del brazo derecho, a la altura del hombro.AAPT_RIGHT_FOREARM: Fijo al hueso del antebrazo derecho.AAPT_RIGHT_HAND_INDEX: Fijo a la punta del dedo índice derecho.AAPT_LEFT_UP_LEG: Fijo al hueso superior de la pierna izquierda.AAPT_LEFT_LEG: Fijo al hueso inferior de la pierna izquierda.AAPT_LEFT_FOOT: Fijo al tobillo de la pierna izquierda.AAPT_LEFT_TOE_BASE: Fijo a la punta del dedo del pie de la pierna izquierda.AAPT_RIGHT_UP_LEG: Fijo al hueso superior de la pierna derecha.AAPT_RIGHT_LEG: Fijo al hueso inferior de la pierna derecha.AAPT_RIGHT_FOOT: Fijo al tobillo de la pierna derecha.AAPT_RIGHT_TOE_BASE: Fijo a la punta del dedo del pie de la pierna derecha..AAPT_NAME_TAG: Flota justo encima de la etiqueta de nombre del jugador y no se ve afectado por las animaciones del jugador.Nota: La altura de la etiqueta de nombre se ajusta dinámicamente según la altura de los wearables que lleve un jugador. Así, un jugador que use un sombrero alto tendrá su etiqueta de nombre un poco más alta que los demás.
AAPT_POSITIONOBSOLETO: La posición general del jugador. Esto aparece a una altura de 0.8 por encima de los pies del jugador.
> **📔 Nota**: `AAPT_POSITION` está obsoleto. Para seguir la posición general del jugador, lo mejor es hacer que la Entity sea hija de Avatar Entity. Consulta el inicio de esta sección para ver un ejemplo. >

La renderización de Entity se determina localmente en cada instancia de la escena. Adjuntar una entidad a un jugador no la hace visible para otros jugadores que están viendo a ese jugador. Si una entidad se adjunta al jugador local predeterminado, cada jugador experimentará la entidad como si estuviera adjunta a su propio avatar.
📔 Nota: Las Entities 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 Entity adjunta deja de renderizarse hasta que el jugador vuelva a entrar. Los Smart wearables no tienen esta limitación.
Las 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 Entity con respecto al Transform del jugador; estos valores se actualizan frame a frame a medida que el jugador se mueve y se anima.
Si necesitas posicionar una Entity con un desplazamiento desde el anchor point del avatar, o con una rotación o escala diferente, hazlo a través de una entidad padre.
Crea una Entity invisible con solo un
Transformy unAvatarAttachcomponent. SusTransformvalores se sobrescribirán a medida que el jugador se muevaConfigura la Entity que quieres adjuntar como hija de este padre. Sus
Transformvalores pueden describir el desplazamiento desde el anchor point.
📔 Nota: Si la entidad adjunta tiene colliders, estos colliders podrían bloquear el movimiento del jugador o causar efectos entrecortados. Quizás quieras desactivar la capa de física de los colliders de la entidad adjunta. Consulta Capas de colisión
📔 Nota: Si tienes una entidad hija y quieres conocer su Position y/o Rotation globales, puedes usar las getWorldPosition y getWorldRotation functions. Puedes consultarlas en la Obtener la posición y rotación globales sección.
Adjuntar a otros jugadores
Puedes usar el AvatarAttach component para adjuntar una entidad a otro jugador. Para ello, 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 formas de obtener estos datos.
📔 Nota: Para aquellos jugadores conectados con una Wallet de Ethereum, su userId es el mismo que su dirección de Ethereum.
Obtén el userId de todos los demás jugadores cercanos mediante getPlayer()
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:
Consulta otras formas de obtener los IDs de otros usuarios en Obtener datos del jugador.
Límites de la escena
Todas las entidades de tu escena deben caber dentro de los límites de la escena, ya que lo que queda fuera de esos límites son parcelas de terreno que pertenecen a otros jugadores.
Si alguna parte de tus modelos se extiende más allá de estos límites al ejecutar un Preview, esas partes que sobresalgan se recortarán y no se renderizarán, tanto en el Preview como en la escena publicada.
La posición de las entidades en tu escena se está comprobando constantemente a medida que se mueven; si una entidad sale de la escena y luego regresa, se eliminará y luego se renderizará normalmente de nuevo.
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.
Última actualización