Camera

Aprende cómo controlar la camera del player

Como creador, puedes tener control total sobre la cámara del jugador. De forma predeterminada, los jugadores pueden elegir libremente entre un modo de cámara en 1.ª o 3.ª persona mientras exploran tu scene, pero puedes imponer una modalidad de cámara diferente.

Las cámaras virtuales pueden ser estáticas, pueden rotar para mirar siempre al jugador o a alguna otra entity, o pueden estar adjuntas al jugador o a alguna otra entity para que siempre lo acompañen.

📔 Nota: Para cambiar entre las cámaras predeterminadas en 1.ª y 3.ª persona, consulta Áreas de modificador de cámara.

Modos de cámara en 1.ª y 3.ª persona

Normalmente los jugadores pueden cambiar entre la cámara en primera y tercera persona pulsando V en el teclado. Usa una CameraModeArea para forzar el modo de cámara a 1.ª o 3.ª persona para todos los jugadores que estén dentro de un área específica de tu scene.

const entity = engine.addEntity()

CameraModeArea.create(entity, {
	area: Vector3.create(4, 3, 4),
	mode: CameraType.CT_FIRST_PERSON,
})

Si el modo de cámara actual de un jugador no coincide con el de la CameraModeArea, cambiarán a ese modo de cámara. Aparecerá un toast en pantalla para aclarar que este cambio se debe a la scene. Mientras estén dentro, los jugadores no pueden cambiar su modo de cámara. Cuando un jugador sale de la CameraModeArea, su modo de cámara se restaura al que tenía antes de entrar.

Usa CameraModeArea en regiones donde los jugadores tendrían una experiencia significativamente mejor usando un modo de cámara específico. Por ejemplo, la primera persona es ideal si el jugador necesita hacer clic en un objeto pequeño, o la tercera persona puede ser útil para que los jugadores noten alguna entity que tu scene haya adjuntado sobre su cabeza. No asumas que los jugadores saben cómo cambiar de modo de cámara; muchos jugadores nuevos quizá no sepan que tienen esa opción, o no recuerden la tecla para hacerlo.

📔 Nota: Las áreas de modificador de cámara se ven afectadas por el position y rotation del componente Transform de la entidad anfitriona, pero no se ven afectadas por el scale.

📔 Nota: Si superpones varias áreas de modificador de cámara, la última en ser instanciada por el código de tu scene tendrá prioridad sobre las demás.

Al crear un CameraModeArea component, debes proporcionar lo siguiente:

• area: Tamaño del área modificadora

• cameraMode: Qué modo de cámara forzar en esta área, desde el CameraType enum.

Los modos de cámara compatibles son:

• CameraType.CT_FIRST_PERSON

• CameraType.CT_THIRD_PERSON

Consultar el modo de cámara

Puedes consultar el modo de cámara del jugador usando el CameraMode component en el engine.CameraEntity.

const cameraMode = CameraMode.get(engine.CameraEntity)
if (cameraMode.mode === CameraType.CT_FIRST_PERSON) {
	console.log('El jugador está usando la cámara en 1.ª persona')
} else {
	console.log('El jugador está usando la cámara en 3.ª persona')
}

También puedes suscribirte a los cambios en el modo de cámara usando el onChange función en el CameraMode componente.

CameraMode.onChange(engine.CameraEntity, (cameraMode) => {
	if (!cameraMode) return
	console.log('El modo de cámara del jugador cambió a', cameraMode.mode)
})

Usar cámaras virtuales

Para usar un comportamiento de cámara personalizado en tu scene, necesitas dos cosas:

• Crear una Virtual Camera: crea una entity en tu scene y asígnale una VirtualCamera.

• Asignar esa cámara virtual: añade una MainCamera component al reserved entity engine.CameraEntity, con una referencia a la entity con la VirtualCamera componente.

La cámara quedará entonces adjunta a la entity con el VirtualCamera component. Si la entity se mueve o rota, la cámara se moverá con ella.

function main() {
	const myCustomCamera = engine.addEntity()
	Transform.create(myCustomCamera, {
		position: Vector3.create(1, 2, 1),
	})
	VirtualCamera.create(myCustomCamera, {})

	const mainCamera = MainCamera.createOrReplace(engine.CameraEntity, {
		virtualCameraEntity: myCustomCamera,
	})
}

En este ejemplo, la cámara siempre estará en una posición fija en la scene, siempre que el jugador permanezca dentro de los límites de la scene. En cuanto el jugador salga de los límites de la scene, se restaurará el comportamiento de cámara predeterminado.

Tu scene puede incluir tantas entities con un VirtualCameracomponent como quieras, y cambiar dinámicamente entre varias cámaras virtuales a medida que el jugador se mueve, o mientras realiza ciertas acciones. Solo una cámara virtual está activa en un momento dado, y esta se asigna mediante el MainCamera component en engine.CameraEntity.

Para volver al comportamiento de cámara predeterminado, establece el valor en undefined en MainCamera.virtualCameraEntity. El jugador entonces puede cambiar libremente entre las cámaras en 1.ª y 3.ª persona. Si quieres que el jugador use solo uno de esos dos modos, puedes usar una Áreas de modificador de cámara para forzar uno de los dos.

📔 Nota: Las áreas de modificador de cámara solo tienen efecto en el jugador si no hay cámaras virtuales activas. Si la scene está usando actualmente una cámara virtual y el jugador entra en un área de modificador de cámara, no ocurre nada.

Si un modelo 3D incluye un camera node como parte de su contenido, esto no puede ser usado por el SDK. Debes crear todas las cámaras como entities con el SDK.

function main() {
	// cámara virtual personalizada
	const myCustomCamera = engine.addEntity()
	Transform.create(myCustomCamera, {
		position: Vector3.create(1, 2, 1),
	})
	VirtualCamera.create(myCustomCamera, {})

	const mainCamera = MainCamera.createOrReplace(engine.CameraEntity, {
		virtualCameraEntity: myCustomCamera,
	})

	// cubo clicable
	const clickCube = engine.addEntity()
	Transform.create(clickCube, { position: Vector3.create(8, 0, 8) })
	MeshRenderer.setBox(clickCube)
	MeshCollider.setBox(clickCube)
	pointerEventsSystem.onPointerDown(
		{
			entity: clickCube,
			opts: { button: InputAction.IA_POINTER, hoverText: 'Reset camera' },
		},
		() => {
			// restablecer la cámara al comportamiento predeterminado
			const mainCamera = MainCamera.getMutable(engine.CameraEntity)
			mainCamera.virtualCameraEntity = undefined
		}
	)
}

💡 Consejo: Cuando la cámara se aleja del avatar, a menudo es una buena práctica congelar también los movimientos del avatar. De esa manera, el jugador no se mueve a ciegas hacia obstáculos. Ver Input Modifiers

Vista de pájaro

Puedes usar una cámara virtual para ver la scene desde una vista cenital; esta puede ser una variación divertida de la perspectiva normal de tu avatar y permitir diferentes mecánicas de juego.

Debes evitar colocar una cámara mirando en una dirección perfectamente vertical hacia abajo. En su lugar, inclina siempre la cámara ligeramente; incluso 1 grado es suficiente. Esto se debe a que los controles de dirección del jugador se basan en la perspectiva de la cámara, no en la orientación del avatar. Si la cámara mira desde una vista de pájaro perfecta, no hay una definición clara de qué dirección es cuál. Una inclinación imperceptible de 1 grado es suficiente para establecer una dirección hacia adelante.

function main() {
	// cámara de vista de pájaro
	const myCustomCamera = engine.addEntity()
	Transform.create(myCustomCamera, {
		position: Vector3.create(8, 5, 8),
		rotation: Quaternion.Euler(0, 0, 91) 
		// Ten en cuenta que la rotación es 91º, no 90º
	})
	VirtualCamera.create(myCustomCamera, {})

	const mainCamera = MainCamera.createOrReplace(engine.CameraEntity, {
		virtualCameraEntity: myCustomCamera,
	})
}

Transiciones de cámara

Siempre que la scene cambia entre cámaras virtuales, o entre el comportamiento de cámara predeterminado y las cámaras virtuales, los jugadores ven una transición. La posición, la rotación y cualquier otro parámetro de la cámara virtual cambian suavemente durante un período de tiempo.

Los ajustes de transición de una cámara virtual determinan cómo haces la transición hacia esa cámara, desde cualquier otra cámara de la scene, incluida la predeterminada. No afectan a cómo haces la transición fuera de esa cámara.

VirtualCamera.create(myCustomCamera1, {
	defaultTransition: { transitionMode: VirtualCamera.Transition.Time(6) },
})

💡 Consejo: Para evitar tener una transición y cambiar instantáneamente a una cámara, establece el tiempo o la velocidad de transición en 0.

Según tu caso de uso, puede que prefieras establecer la velocidad de la transición en lugar de la duración:

• Tiempo fijo: Estableces la duración de la transición; la cámara se moverá tan rápido como sea necesario para completar el recorrido en ese período de tiempo.

• Velocidad fija: Estableces qué tan rápido quieres que se mueva la cámara virtual durante la transición; la duración dependerá de la distancia. El valor usado para la velocidad se interpreta como metros por segundo.

A continuación hay ejemplos de ambos modos de transición:

// duración fija
VirtualCamera.create(myCustomCamera1, {
	defaultTransition: { transitionMode: VirtualCamera.Transition.Time(6) },
})

// velocidad fija
VirtualCamera.create(myCustomCamera1, {
	defaultTransition: { transitionMode: VirtualCamera.Transition.Speed(3) },
})

A continuación hay un ejemplo completo con dos cámaras virtuales y transiciones entre ellas:

function main() {
	// cámara virtual personalizada 1
	const myCustomCamera1 = engine.addEntity()
	Transform.create(myCustomCamera1, {
		position: Vector3.create(1, 2, 1),
	})
	VirtualCamera.create(myCustomCamera1, {
		defaultTransition: { transitionMode: VirtualCamera.Transition.Time(1) },
	})

	// cámara virtual personalizada 2
	const myCustomCamera2 = engine.addEntity()
	Transform.create(myCustomCamera2, {
		position: Vector3.create(1, 2, 1),
	})
	VirtualCamera.create(myCustomCamera2, {
		defaultTransition: { transitionMode: VirtualCamera.Transition.Time(3) },
	})

	const mainCamera = MainCamera.createOrReplace(engine.CameraEntity, {
		virtualCameraEntity: myCustomCamera,
	})

	// cubo clicable
	const clickCube = engine.addEntity()
	Transform.create(clickCube, { position: Vector3.create(8, 0, 8) })
	MeshRenderer.setBox(clickCube)
	MeshCollider.setBox(clickCube)
	pointerEventsSystem.onPointerDown(
		{
			entity: clickCube,
			opts: { button: InputAction.IA_POINTER, hoverText: 'Reset camera' },
		},
		() => {
			// restablecer la cámara al comportamiento predeterminado
			const mainCamera = MainCamera.getMutable(engine.CameraEntity)
			mainCamera.virtualCameraEntity =
				mainCamera.virtualCameraEntity == myCustomCamera1
					? myCustomCamera2
					: myCustomCamera1
		}
	)
}

Las transiciones siempre se mueven en línea recta, sin considerar ningún obstáculo en el recorrido. En su lugar, podrías crear manualmente una transición usando otra cámara virtual como intermediaria; de esa manera tendrías control total sobre sus movimientos. Esta cámara virtual intermediaria podría realizar una Tween desde la posición de la primera cámara hasta la posición de la segunda cámara, o seguir una ruta más personalizada que evite obstáculos o haga un desvío cinematográfico.

Seguir la cámara

Puedes configurar una cámara virtual para que siempre mire en la dirección del jugador, o de alguna entity específica de la scene. La posición de la cámara permanecerá estática, pero su rotación cambiará para mantener siempre centrada a esta entity.

Esto se puede lograr con el lookAtEntity propiedad en el VirtualCamera component. Para seguir al jugador, usa el reserved entity engine.PlayerEntity.

const myCustomCamera1 = engine.addEntity()
Transform.create(myCustomCamera1, {
	position: Vector3.create(1, 2, 1),
})
VirtualCamera.create(myCustomCamera1, {
	lookAtEntity: engine.PlayerEntity,
})

Si la cámara sigue a una entity, esto solo cambiará la rotación, no la posición de la cámara.

A medida que la cámara rota, el Transform de la entity con el VirtualCamera component no cambia. Sin embargo, puedes leer la rotación de la cámara desde el Transform en engine.CameraEntity. La rotación y la posición de esta entity serán absolutas; no estarán condicionadas por las de la entity con el VirtualCamera component. La rotación de este transform se ve afectada por el comportamiento de lookAtEntity .

📔 Nota: Si configuras la cámara virtual con un lookAtEntity que hace referencia a la misma entity que contiene la cámara virtual, o a la entity engine.MainCamera , el comportamiento resultante será el mismo que no asignar ninguna entity en absoluto.

Adjuntar al jugador

Otro uso de la cámara virtual es seguir al jugador desde una distancia o ángulo personalizados, adjuntando una cámara virtual a la entity del jugador. Ten en cuenta que el jugador no puede cambiar libremente la rotación de la cámara, así que en este caso la rotación de la cámara quedará fijada a la de la cámara virtual. Esto podría ser útil, por ejemplo, para juegos de carreras, donde se espera que el jugador mire siempre hacia adelante.

function main() {
	const myCustomCamera = engine.addEntity()
	Transform.create(myCustomCamera, {
		position: Vector3.create(0, 1, 5),
		parent: engine.PlayerEntity,
	})
	VirtualCamera.create(myCustomCamera, {
		defaultTransition: { transitionMode: VirtualCamera.Transition.Time(2) },
	})

	const mainCamera = MainCamera.createOrReplace(engine.CameraEntity, {
		virtualCameraEntity: myCustomCamera,
	})
}

Cámaras y colliders

Cuando la cámara de un jugador se mueve en modo de tercera persona, la cámara puede ser bloqueada por colliders o no, dependiendo de las collision layers asignadas a las Entities. Ten esto en cuenta al diseñar tu scene; puede que quieras evitar que la cámara atraviese paredes u otras Entities.

Consulta Colliders para más detalles sobre cómo configurar colliders para tu scene.