Posicionamento de Entidades

Como definir a posição, rotação e escala de uma entidade em uma cena

Você pode definir a position, rotation e scale de qualquer entidade usando o Transform componente. Isso pode ser usado em qualquer entidade no espaço 3D, afetando onde a entidade é renderizada. Isso inclui formas primitivas (cube, sphere, plane, etc), 3D text shapes, NftShape, e modelos 3D (GltfContainer).

Use o Scene Editor no Creator Hub

Ao adicionar um item à sua cena via o Scene Editor, ele implicitamente inclui um Transform componente. Então você altera os valores no Transform da entidade implicitamente mudando a posição, rotação ou escala de uma entidade. Você também pode usar a UI do Scene Editor para fornecer valores numericamente para mais precisão.

Essenciais de código

// Crie uma nova entidade
const ball = engine.addEntity()

// Dê a essa entidade uma forma, para torná-la visível
MeshRenderer.setSphere(ball)

// Dê a essa entidade um componente Transform
Transform.create(ball, {
	position: Vector3.create(5, 1, 5),
	scale: Vector3.create(1, 1, 1),
	rotation: Quaternion.Zero(),
})

Para mover, rodar ou redimensionar uma entidade na sua cena ao longo de um período de tempo, altere os valores neste componente incrementalmente, quadro a quadro. Veja Mover entidades para mais detalhes e melhores práticas.

📔 Nota: espera um e normalHit devem ser importados via

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

Veja Imports para como lidar com estes facilmente.

Position

position é um vetor 3D, ele define a posição do centro da entidade nos três eixos, x, y, e z. Veja Tipos de geometria para mais detalhes.

// Crie uma nova entidade
const ball = engine.addEntity()

// Crie transform com uma posição pré-definida
Transform.create(ball, {
	  position: Vector3.create(5, 1, 5)
}

// Busque uma versão mutável do transform
const mutableTransform = Transform.getMutable(ball)

// Defina a posição com um objeto
mutableTransform.position = { x: 5, y: 1, z: 5 }

// Defina a posição com um objeto (sintaxe alternativa)
mutableTransform.position = Vector3.create(2, 1, 4)

// Defina cada eixo individualmente
mutableTransform.position.x = 3
mutableTransform.position.y = 1
mutableTransform.position.z = 3

Ao definir uma posição, tenha as seguintes considerações em mente:

• Os números em um vetor de posição representam metros (a menos que a entidade seja filha de uma entidade escalada).

• Uma cena composta por um único parcel mede 16m x 16m. O centro da cena (no nível do chão) está em x:8, y:0, z:8. Se a cena for composta por múltiplos parcels, então o centro variará dependendo da sua disposição.

• x:0, y:0, z:0 refere-se ao South-West canto do parcel base da cena, no nível do chão.

  Dica: Ao visualizar um preview da cena, uma bússola aparece no ponto (0,0,0) da cena com rótulos para cada eixo como referência.

  Nota: Você pode alterar o parcel base de uma cena editando o base atributo de scene.json.

• Para melhor se orientar, use sua left mão:

  • seu dedo indicador (apontando para frente) é o z eixo

  • seu dedo médio (apontando para o lado) é o x eixo

  • seu polegar (apontando para cima) é o y eixo.

• Se uma entidade for filha de outra, então x:0, y:0, z:0 refere-se ao centro da sua entidade pai, onde quer que ela esteja na cena.

• Toda entidade na sua cena deve ser posicionada dentro dos limites dos parcels que ocupa o tempo todo. Se uma entidade sair desses limites, isso vai gerar um erro.

  Dica: Ao visualizar uma cena em modo preview, entidades fora dos limites são destacadas em red.

• Sua cena também é limitada em altura. Quanto mais parcels compõem a cena, maior é permitido construir. Veja limitações da cena para mais detalhes.

Rotação

rotation é armazenada como um quaternion, um sistema de quatro números, x, y, z e w. Cada um desses números vai de 0 a 1. Veja Tipos de geometria para mais detalhes.

// Crie uma nova entidade
const cube = engine.addEntity()

// Crie transform com uma rotação pré-definida de 0
Transform.create(cube, {
	  rotation: Quaternion.Zero()
}

// Busque uma versão mutável do transform
const mutableTransform = Transform.getMutable(cube)

// Defina a rotação com um objeto, a partir de ângulos euler
mutableTransform.rotation = Quaternion.fromEulerDegrees(0, 90, 0)

// Defina a rotação com um objeto
mutableTransform.rotation = { x: 0.1, y: 0.5, z: 0.5, w: 0 }

// Defina cada eixo individualmente
mutableTransform.rotation.x = 0
mutableTransform.rotation.y = 1
mutableTransform.rotation.z = 0.3
mutableTransform.rotation.w = 0

Você também pode definir o campo rotation com Euler ângulos, a notação mais comum com números que vão de 0 a 360 com a qual a maioria das pessoas está familiarizada. Para usar ângulos Euler, use uma das seguintes notações: x, y e z // Crie transform com uma rotação pré-definida em ângulos Euler

rotation: Quaternion.fromEulerDegrees(0, 90, 0)
Transform.create(cube, {
	  Ao usar um
}

// Busque uma versão mutável do transform
const mutableTransform = Transform.getMutable(cube)

// Defina a rotação com um objeto, a partir de ângulos euler
mutableTransform.rotation = Quaternion.fromEulerDegrees(0, 90, 0)

para representar ângulos Euler, vetor 3D representam a rotação naquele eixo, medida em graus. Uma volta completa requer 360 graus. x, y e z Quando você recupera a rotação de uma entidade, ela retorna um quaternion por padrão. Para obter a rotação expressa em ângulos Euler, use

.toEuler() // Busque uma versão somente leitura do transform:

const transform = Transform.getMutable(cube)
const eulerAngle = Quaternion.toEuler(transform.rotation)

// Defina a rotação com um objeto, a partir de ângulos euler
Obtendo Posição e Rotação Global de uma Entidade

getWorldPosition

O getWorldRotation e funções retornam a posição e rotação globais de uma entidade. Isso significa que retorna a posição ou rotação percebida que o jogador verá o item, ignorando quaisquer hierarquias parentais. getWorldPosition(engine, entity: Entity): Vector3Type

• : Esta função retorna a posição World de uma entidade, levando em consideração todas as posições das entidades pai, se a entidade tiver alguma, retornando{x: 0, y: 0, z: 0} se a entidade não tiver Transform. const worldPos = getWorldPosition(engine, childEntity)

console.log(`World position: ${worldPos.x}, ${worldPos.y}, ${worldPos.z}`)
getWorldRotation(engine, entity: Entity): QuaternionType

• : Esta função retorna a rotação World de uma entidade, levando em consideração todas as rotações das entidades pai, se a entidade em si tiver alguma. Ela retorna umtype, retornando quaternion identidade normalHit {x: 0, y: 0, z: 0, w: 1} const worldRot = getWorldRotation(engine, childEntity) const worldPos = getWorldPosition(engine, childEntity)

console.log(`World rotation: ${worldRot.x}, ${worldRot.y}, ${worldRot.z}, ${worldRot.w}`)
Nota:

Posição global e rotação global são relativas às coordenadas dentro da cena e não a Genesis City. Encarar o jogador

componente para uma entidade de forma que ela sempre rote para encarar o jogador.

Adicione um Billboard Billboards foram uma técnica comum usada em jogos 3D dos anos 90, onde a maioria das entidades eram planos 2D que sempre encaravam o jogador. A mesma ideia também pode ser usada para rodar um modelo 3D.

// Dê à entidade uma forma visível

// Crie uma nova entidade
const cube = engine.addEntity()

MeshRenderer.setBox(cube)
// Dê à entidade um componente Billboard

// Crie transform com uma posição pré-definida
Transform.create(cube, {
	  position: Vector3.create(5, 1, 5)
}

Billboard.create(cube, {})
Você pode configurar como o billboard se comporta com os seguintes parâmetros:

billboardMode

• : Usa um valor doBillboardMode para definir seu comportamento: BillboardMode.BM_ALL

  • : A entidade rotaciona para encarar o jogador em todos os seus eixos de rotação. Se o jogador estiver bem acima da entidade, a entidade ficará voltada para cima.BillboardMode.BM_NONE

  • : A entidade não rotacionará.BillboardMode.BM_X

  • : A entidade tem seueixo de rotação fixo. x BillboardMode.BM_Y

  • eixo de rotação fixo. Ele só rotaciona para a esquerda e direita, não para cima e baixo. Permanece perpendicular ao chão se o jogador estiver acima ou abaixo da entidade.eixo de rotação fixo. y BillboardMode.BM_Z

  • // billboard planoeixo de rotação fixo. z BillboardMode.BM_Y

const perpendicularPlane = engine.addEntity()
Transform.create(perpendicularPlane, {

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

Billboard.create(perpendicularPlane, {

billboardMode: BillboardMode.BM_Y,
	// rótulo 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)
})

: Billboards são muito úteis para adicionar a

💡 Tipentidades, pois isso as torna sempre legíveis. texto valor do

O rotation componente da entidade não muda enquanto o billboard segue os jogadores. Transform Se uma entidade tiver tanto um

componente com Billboard componente e Transform valores, os jogadores verão a entidade rotacionando como um billboard. Se o billboard não afetar todos os eixos, os eixos restantes serão rotacionados de acordo com o rotation : Se houver múltiplos jogadores presentes ao mesmo tempo, cada um verá as entidades com o modo billboard voltado para eles. As rotações do billboard são calculadas localmente para cada jogador, e não afetam o que os outros veem. Transform component.

📔 NotaEncarar um conjunto de coordenadas

Para que a entidade A olhe para a entidade B:

1) Subtraia a posição da entidade A da entidade B para obter um vetor que descreve a distância entre elas.

2) Normalize esse vetor, para que ele tenha comprimento 1, mantendo sua direção.
3) Use `Quaternion.lookRotation` para obter uma rotação Quaternion que descreve rotacionar nessa direção.
4) Defina esse Quaternion como a rotação da entidade A
export function turn(entity: Entity, target: ReadOnlyVector3) {

const difference = Vector3.subtract(target, transform.position)
	const transform = Transform.getMutable(entity)
	const normalizedDifference = Vector3.normalize(difference)
	transform.rotation = Quaternion.lookRotation(normalizedDifference)
	Escala
}

é também um

scale , armazenado como um vetor 3Dobjeto, incluindo o fator de escala no espera um eixo. A forma da entidade é escalada de acordo, seja ela uma primitiva ou um modelo 3D. x, y e z A escala padrão é 1, então atribua um valor maior que 1 para esticar uma entidade ou menor que 1 para encolhê-la.

scale: Vector3.create(5, 5, 5)

// Crie uma nova entidade
const ball = engine.addEntity()

// Crie transform com uma posição pré-definida
Transform.create(ball, {
	  // Defina a escala com um Vector3
}

// Busque uma versão mutável do transform
const mutableTransform = Transform.getMutable(ball)

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

mutableTransform.scale = { x: 5, y: 1, z: 5 }

// Defina a posição com um objeto
mutableTransform.scale.x = 3

// Defina cada eixo individualmente
mutableTransform.scale.y = 3
mutableTransform.scale.z = 2
Herdar transformações do pai

Quando uma entidade está aninhada dentro de outra, as entidades filhas herdam componentes dos pais. Isso significa que se uma entidade pai for posicionada, escalada ou rotacionada, seus filhos também são afetados. Os valores de posição, rotação e escala das entidades filhas não substituem os dos pais; em vez disso, estes são compostos.

Você atribui uma entidade como pai de outra definindo o campo

no componente parent da entidade filha Transform component.

Se uma entidade pai for escalada, todos os valores de posição de seus filhos também são escalados.

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

// Crie um transform para o pai
Transform.create(parentEntity, {
	position: Vector3.create(3, 1, 1),
	scale: Vector3.create(0.5, 0.5, 0.5),
})

// Crie um transform para o filho, e atribua-o como filho
Transform.create(childEntity, {
	position: Vector3.create(0, 1, 0),
	parent: parentEntity,
})

Neste exemplo, a entidade filha será reduzida para 0.5, já que sua entidade pai tem essa escala. A posição da entidade filha também será relativa ao seu pai. Temos que somar a posição do pai mais a do filho. Neste caso, como o pai está escalado pela metade, a transformação do filho também é reduzida proporcionalmente. Em termos absolutos, o filho está posicionado em { x: 3, y: 1.5, z: 1 }. Se o pai tivesse um rotation, isso também afetaria a posição final do filho, pois altera o eixo no qual o filho é deslocado.

Se uma entidade filha não tiver position no seu Transform, o padrão é 0,0,0, o que a deixará posicionada na mesma posição que seu pai.

Você pode usar uma entidade invisível sem componente de forma como pai, para agrupar um conjunto de outras entidades. Essa entidade não será visível na cena renderizada, mas pode ser usada para agrupar seus filhos e aplicar um transform a todos eles.

Anexar uma entidade a um avatar

Existem três métodos para anexar uma entidade ao jogador:

• Torná-la filha do Avatar Entity

• Torná-la filha do Camera Entity

• Use o Você não pode atingir diretamente o avatar do jogador ou o de outros jogadores com um raio, mas o que você pode fazer como solução alternativa é posicionar uma entidade invisível ocupando o mesmo espaço que um jogador usando o

A maneira mais simples de anexar uma entidade ao avatar é definir o pai como a entidade reservada engine.PlayerEntity. A entidade então se moverá junto com a posição do jogador.

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,
})

Você também pode definir uma entidade como entidade reservada O exemplo a seguir traça um raio a partir da posição da câmera do jogador para frente, usando a. Ao usar a Camera Entity em primeira pessoa, a entidade anexada seguirá os movimentos da câmera. Isso é ideal para manter algo sempre à vista, por exemplo manter o modelo 3D da arma sempre visível, mesmo quando a câmera aponta para cima.

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 anexar um objeto a um dos ossos do avatar, e fazê-lo se mover junto com as animações do avatar, adicione um AvatarAttach componente à entidade.

Você pode escolher diferentes pontos de ancoragem no avatar; a maioria desses pontos está ligada ao armature do jogador e segue as animações do jogador. Por exemplo, ao usar o ponto de ancoragem da mão direita, a entidade anexada se moverá quando o avatar acenar ou balançar os braços enquanto corre, assim como se o jogador estivesse segurando a entidade na mão.

// Anexar ao jogador principal; se avatarId não for definido, engine.PlayerEntity é usado por padrão
AvatarAttach.create(myEntity, {
	anchorPointId: AvatarAnchorPointType.AAPT_NAME_TAG,
})

// Anexar a um jogador por ID
AvatarAttach.create(myEntity, {
	avatarId: '0xAAAAAAAAAAAAAAAAA',
	anchorPointId: AvatarAnchorPointType.AAPT_NAME_TAG,
})

Ao criar um AvatarAttach componente, passe um objeto com os seguintes dados:

• avatarId: Opcional O ID do jogador para anexar. Isso é o mesmo que o endereço Ethereum do jogador, para aqueles jogadores conectados com uma wallet Ethereum. Se não especificado, anexa a entidade ao avatar do jogador local.

• anchorPointId: Qual ponto de ancoragem no esqueleto do avatar para anexar a entidade, usando um valor do enum AvatarAnchorPointType.

📔 Nota: Se você quiser que todos os jogadores na cena vejam um objeto anexado ao mesmo jogador, por exemplo para que todos vejam que o Jogador A pegou um objeto e o segura na mão esquerda, então você deve fornecer um valor para avatarId. Se não for especificado então todos os jogadores verão o objeto anexado aos seus próprios avatares.

O exemplo a seguir posiciona uma entidade anexada a um avatar específico, para que todos os outros jogadores a vejam anexada àquele mesmo 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,
  })

  // Outros componentes

  syncEntity(entity, [AvatarAttach.componentId])

}

Os seguintes pontos de ancoragem estão disponíveis no AvatarAnchorPointType enum:

• AAPT_RIGHT_HAND: Fixado na mão direita do jogador

• AAPT_LEFT_HAND: Fixado na mão esquerda do jogador

• AAPT_HEAD: Fixado ao centro da cabeça do jogador.

• AAPT_NECK: Fixado à base do pescoço do jogador.

• AAPT_SPINE: Fixado à seção superior da coluna vertebral.

• AAPT_SPINE1: Fixado à seção média da coluna vertebral.

• AAPT_SPINE2: Fixado à seção inferior da coluna vertebral.

• AAPT_HIP: Fixado ao osso do quadril.

• AAPT_LEFT_SHOULDER: Fixado ao ombro esquerdo.

• AAPT_LEFT_ARM: Fixado ao primeiro osso do braço esquerdo, na altura do ombro.

• AAPT_LEFT_FOREARM: Fixado ao osso do antebraço esquerdo.

• AAPT_LEFT_HAND_INDEX: Fixado na ponta do dedo indicador esquerdo.

• AAPT_RIGHT_SHOULDER: Fixado ao ombro direito.

• AAPT_RIGHT_ARM: Fixado ao primeiro osso do braço direito, na altura do ombro.

• AAPT_RIGHT_FOREARM: Fixado ao osso do antebraço direito.

• AAPT_RIGHT_HAND_INDEX: Fixado na ponta do dedo indicador direito.

• AAPT_LEFT_UP_LEG: Fixado ao osso superior da perna esquerda.

• AAPT_LEFT_LEG: Fixado ao osso inferior da perna esquerda.

• AAPT_LEFT_FOOT: Fixado ao tornozelo da perna esquerda.

• AAPT_LEFT_TOE_BASE: Fixado na ponta do dedo do pé da perna esquerda.

• AAPT_RIGHT_UP_LEG: Fixado ao osso superior da perna direita.

• AAPT_RIGHT_LEG: Fixado ao osso inferior da perna direita.

• AAPT_RIGHT_FOOT: Fixado ao tornozelo da perna direita.

• AAPT_RIGHT_TOE_BASE: Fixado na ponta do dedo do pé da perna direita.

• .AAPT_NAME_TAG: Flutua logo acima da name tag do jogador, não é afetado pelas animações do jogador.

  Nota: A altura da name tag é ajustada dinamicamente com base na altura das wearables que um jogador usa. Portanto, um jogador usando um chapéu alto terá a sua name tag um pouco mais alta que as dos outros.

• AAPT_POSITION DEPRECATED: A posição geral do jogador. Isso aparece a uma altura de 0.8 acima dos pés do jogador.

> **📔 Nota**: O `AAPT_POSITION` está deprecated. Para seguir a posição geral do jogador, é melhor tornar a entidade filha da Avatar Entity. Veja o início desta seção para um exemplo. >

💡 Tip: Para usar esses valores, escreva AvatarAnchorPointType. e o VS Code exibirá a lista completa de opções em um dropdown.

A renderização de entidades é determinada localmente em cada instância da cena. Anexar uma entidade a um jogador não a torna visível para outros jogadores que estão vendo esse jogador. Se uma entidade estiver anexada ao jogador local padrão, cada jogador experimentará a entidade como anexada ao seu próprio avatar.

📔 Nota: Entidades anexadas a um avatar devem permanecer dentro dos limites da cena para serem renderizadas. Se um jogador sair da sua cena, quaisquer entidades anexadas deixam de ser renderizadas até que o jogador retorne. Smart wearables não têm essa limitação.

O AvatarAttach componente sobrescreve os valores no Transform componente. Quaisquer valores que você colocar no Transform componente são substituídos pela posição relativa da entidade à do Transform do jogador; esses valores são atualizados quadro a quadro à medida que o jogador se move e anima.

Se você precisa posicionar uma entidade com um offset do ponto de ancoragem no avatar, ou uma rotação ou escala diferente, faça isso via uma entidade pai.

1. Crie uma entidade invisível com apenas um Transform e um AvatarAttach componente. Seus Transform valores serão sobrescritos conforme o jogador se move

2. Defina a entidade que você quer anexar como filha desse pai. Seus Transform valores podem descrever o offset a partir do ponto de ancoragem.

// Crie a entidade pai
const parentEntity = engine.addEntity()

// Anexe a entidade pai ao jogador
AvatarAttach.create(parentEntity, {
	anchorPointId: AvatarAnchorPointType.AAPT_NAME_TAG,
})

// Crie a entidade filha
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: Se a entidade anexada tiver colliders, esses colliders podem bloquear o movimento do jogador ou causar efeitos de jitter. Você pode querer desabilitar a physics layer dos colliders da entidade anexada. Veja Collision layers

📔 Nota: Se você tem uma entidade filha e quer saber a Posição e/ou Rotação global dela, você pode usar as getWorldRotation e funções retornam a posição e rotação globais de uma entidade. Isso significa que retorna a posição ou rotação percebida que o jogador verá o item, ignorando quaisquer hierarquias parentais. funções. Você pode checá-las em Obtendo Posição e Rotação Global seção.

Anexar a outros jogadores

Você pode usar o AvatarAttach componente para anexar uma entidade a outro jogador. Para fazer isso, você deve saber o id do jogador.

Para anexar uma entidade ao avatar de outro jogador, você deve fornecer o ID do usuário no campo avatarId. Existem várias maneiras de obter esses dados.

📔 Nota: Para aqueles jogadores conectados com uma wallet Ethereum, seu userId é o mesmo que seu endereço Ethereum.

Busque o userId para todos os outros jogadores próximos via getPlayer()

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

Usando isso junto com AvatarAttach, você poderia usar o código a seguir para adicionar um cubo flutuando sobre a cabeça de cada outro jogador na cena:

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,
            })
        }
    })

Veja outras maneiras de buscar os IDs de outros usuários em Obter Dados do Jogador.

Limites da scene

Todas as entidades na sua cena devem caber dentro dos limites da cena, pois o que está fora desses limites são parcels de terra que pertencem a outros jogadores.

Se qualquer parte dos seus modelos se estender além desses limites ao executar um preview, essas partes que se estendem serão cortadas e não renderizadas, tanto ao executar um preview quanto na cena publicada.

A posição das entidades na sua cena está sendo constantemente verificada enquanto elas se movem; se uma entidade sair da cena e então retornar, ela será removida e depois renderizada normalmente novamente.

Uma grade no chão da cena mostra os limites da cena, que por padrão vão de 0 a 16 no eixo x e z , e até 20 no eixo y . Você pode colocar entidades no subsolo, abaixo de 0 no y eixo.

💡 Tip: Se a sua cena precisar de mais parcels, você pode adicioná-los no arquivo do projeto scene.json . Veja Metadados da cena para instruções. Depois de adicionados, você deverá ver a grade estender-se para cobrir os parcels adicionais.