Cámara

Aprende cómo controlar la cámara del jugador

Como creador, puedes tener control total sobre la cámara del jugador. Por defecto, los jugadores son libres de elegir entre un modo de cámara en 1.ª o 3.ª persona mientras exploran tu escena, pero puedes imponer una modalidad de cámara diferente.

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

📔 Nota: Para cambiar entre las cámaras por defecto en 1.ª y 3.ª persona, consulta Áreas modificadoras 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 un 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 en tu escena.

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 del CameraModeArea, harán la transición a ese modo de cámara. Aparece un mensaje en pantalla para aclarar que este cambio se debe a la escena. Mientras estén dentro, los jugadores no pueden cambiar su modo de cámara. Cuando un jugador sale del 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 objetos pequeños, o la tercera persona puede ser útil para que los jugadores noten alguna entidad que tu escena haya colocado sobre su cabeza. No asumas que los jugadores saben cómo cambiar los modos de cámara; muchos jugadores que lo prueban por primera vez podrían no saber que tienen la opción, o no recordar la tecla para hacerlo.

📔 Nota: Las áreas modificadoras de cámara se ven afectadas por el posición y rotación del componente Transform de su entidad anfitriona, pero no se ven afectadas por la escala.

📔 Nota: Si solapas múltiples áreas modificadoras de cámara, la última que instancie el código de tu escena tendrá prioridad sobre las demás.

Al crear un CameraModeArea componente, debes proporcionar lo siguiente:

• area: Tamaño del área modificadora

• cameraMode: Qué modo de cámara forzar en esta área, a partir del 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 componente en el El siguiente ejemplo traza un rayo desde la posición de la cámara del jugador hacia adelante, usando la entidad.

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

Uso de cámaras virtuales

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

• Crear una Cámara Virtual: Crea una entidad en tu escena y asígnale un VirtualCamera.

• Asignar esa cámara virtual: Añade un MainCamera componente al entidad reservada El siguiente ejemplo traza un rayo desde la posición de la cámara del jugador hacia adelante, usando la entidad, con una referencia a la entidad con el VirtualCamera componente.

La cámara quedará entonces adjunta a la entidad con el VirtualCamera componente. Si la entidad se mueve o rota, la cámara se mueve 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 estará siempre en una posición fija en la escena, mientras el jugador permanezca dentro de los límites de la escena. En cuanto el jugador salga de los límites de la escena, se restaurará el comportamiento de cámara por defecto.

Tu escena puede incluir tantas entidades con un VirtualCameracomponente como quieras, y cambiar dinámicamente entre múltiples cámaras virtuales a medida que el jugador se mueve, o realiza ciertas acciones. Solo una cámara virtual está activa en un momento dado, esto se asigna mediante el MainCamera componente en El siguiente ejemplo traza un rayo desde la posición de la cámara del jugador hacia adelante, usando la entidad.

Para volver al comportamiento de cámara por defecto, establece el valor a undefined en MainCamera.virtualCameraEntity. Entonces el jugador será libre de cambiar entre cámaras en 1.ª y 3.ª persona. Si quieres que el jugador use solo uno de estos dos modos, puedes usar un Áreas modificadoras de cámara para forzar uno de los dos.

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

Si un modelo 3D incluye un camera nodo como parte de su contenido, esto no puede ser usado por el SDK. Debes crear todas las cámaras como entidades 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 clickable
	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: 'Restablecer cámara' },
		},
		() => {
			// restablecer la cámara al comportamiento por defecto
			const mainCamera = MainCamera.getMutable(engine.CameraEntity)
			mainCamera.virtualCameraEntity = undefined
		}
	)
}

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

Vista aérea

Puedes usar una cámara virtual para ver la escena desde una perspectiva cenital; esto 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 perpendicular 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 perfectamente cenital, no hay una definición clara de qué dirección es cuál. Una ligera inclinación imperceptible de 1 grado es suficiente para establecer una dirección hacia adelante.

function main() {
	// cámara vista aérea
	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 escena cambia entre cámaras virtuales, o entre el comportamiento de cámara por defecto y 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 de forma suave durante un periodo de tiempo.

Los ajustes de transición en una cámara virtual determinan cómo haces la transición hacia esa cámara, desde cualquier otra cámara en la escena, 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 a 0.

Dependiendo de 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 la trayectoria en ese periodo 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 para 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 clickable
	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: 'Restablecer cámara' },
		},
		() => {
			// restablecer la cámara al comportamiento por defecto
			const mainCamera = MainCamera.getMutable(engine.CameraEntity)
			mainCamera.virtualCameraEntity =
				mainCamera.virtualCameraEntity == myCustomCamera1
					? myCustomCamera2
					: myCustomCamera1
		}
	)
}

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

Seguimiento de la cámara

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

Esto se puede lograr con el lookAtEntity propiedad en el VirtualCamera componente. Para seguir al jugador, usa el entidad reservada engine.PlayerEntity.

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

Si una entidad está siendo seguida por la cámara, 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 entidad con el VirtualCamera componente no cambia. Sin embargo, puedes leer la rotación de la cámara desde el Transform en El siguiente ejemplo traza un rayo desde la posición de la cámara del jugador hacia adelante, usando la entidad. La rotación y la posición de esta entidad serán absolutas; no estarán condicionadas por las de la entidad con el VirtualCamera componente. La rotación de este transform se ve afectada también por el comportamiento de lookAtEntity .

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

Adjuntar al jugador

Otro uso de la cámara virtual es seguir al jugador desde una distancia o ángulo personalizado, adjuntando una cámara virtual a la entidad del jugador. Ten en cuenta que el jugador no puede cambiar libremente la rotación de la cámara, por lo que en este caso la rotación de la cámara quedará fija a la de la cámara virtual. Esto podría ser útil, por ejemplo, en juegos de carreras, donde se espera que el jugador siempre mire 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 tercera persona, la cámara puede ser bloqueada por colliders o no, dependiendo de las capas de colisión asignadas a las entidades. Ten esto en cuenta al diseñar tu escena; puede que quieras evitar que la cámara atraviese paredes u otras entidades.

Ver Colliders para más detalles sobre cómo configurar colliders para tu escena.