마우스 움직임

플레이어의 마우스 움직임에 실시간으로 반응하여 드래그 제스처를 구현하고, 오브젝트를 회전시키고, 커스텀 카메라를 조작하세요.

당신의 씬은 매 프레임 플레이어의 원시 마우스 이동을 읽고, 이를 사용해 실시간 상호작용을 구현할 수 있습니다: 드래그 및 스와이프 제스처, 플레이어가 끄는 동안 오브젝트를 회전시키거나 미끄러지게 하는 것, 또는 1인칭 슈팅 게임처럼 사용자 정의 카메라를 조작하는 것.

이를 위해 다음을 읽으세요 screenDelta 의 속성 PrimaryPointerInfo 다음에 있는 컴포넌트 engine.RootEntity. 이 속성은 Vector2 로, 마지막 프레임 이후 마우스가 몇 픽셀 이동했는지 보고합니다. 양수 x 값은 마우스가 오른쪽으로 이동했음을 의미하고, 양수 y 값은 아래로 이동했음을 의미하며, 화면의 원점이 왼쪽 위 모서리에 있는 것과 일치합니다 — 다음과 같은 동일한 좌표 공간입니다: UiTransform 및 UiCanvasInformation. 마우스가 움직이지 않는 프레임에서는 두 값이 모두 0입니다.

import { engine, PrimaryPointerInfo } from '@dcl/sdk/ecs'

engine.addSystem(() => {
	const delta = PrimaryPointerInfo.getOrNull(engine.RootEntity)?.screenDelta
	if (!delta) return
	console.log(`마우스 이동: ${delta.x}, ${delta.y}`)
})

왜냐하면 screenDelta 단일 프레임의 이동만 담고 있으므로, 항상 다음 안에서 읽으세요: 시스템, 프레임 사이의 이동이 놓치지 않도록.

📔 참고: 다음을 참조하지 마세요 engine.RootEntity 초기 씬 로딩 시에는 엔티티가 아직 초기화되지 않았다면 오류가 발생할 수 있습니다. 이 문제를 피하려면 항상 시스템 안에서 엔티티를 참조하세요. 시스템의 첫 실행은 씬이 이미 제대로 초기화된 뒤에 호출되므로, 엔티티는 항상 사용할 수 있습니다.

📔 참고: 이 문서에서 설명하는 내용은 데스크톱 플레이어에게만 해당합니다. 다음의 모바일 앱, 입력은 터치 기반이고 자유롭게 움직이는 커서가 없으므로 screenDelta 항상 0을 반환합니다. 다음을 참조하세요: 모바일에서의 입력 터치 기기에서 입력이 어떻게 동작하는지에 대해서는 다음을, 그리고 플랫폼 감지 를 참조해 모바일 플레이어에게 대체 조작을 제공하세요.

커서가 잠겨 있을 때의 마우스 이동

screenDelta 다음의 다른 속성과는 다르게 동작합니다 PrimaryPointerInfo 커서가 잠겨 있을 때: screenCoordinates 화면 중앙에 고정되고 worldRayDirection 항상 화면 중앙의 레이를 반환하지만, screenDelta 커서가 잠겨 있어도 매 프레임 원시 마우스 이동을 계속 보고합니다. 따라서 커서가 잠겨 있는 동안 마우스 이동을 읽는 유일한 방법이며, 이는 사용자 정의 카메라나 조준 컨트롤에 정확히 필요한 것입니다.

오브젝트를 드래그해 회전시키기

다음 예제에서는 포인터 버튼을 누른 채 마우스를 좌우로 드래그하면 플레이어가 큐브를 회전시킬 수 있습니다:

import {
	engine,
	InputAction,
	inputSystem,
	MeshCollider,
	MeshRenderer,
	PrimaryPointerInfo,
	Transform,
} from '@dcl/sdk/ecs'
import { Quaternion, Vector3 } from '@dcl/sdk/math'

const DRAG_SENSITIVITY = 0.5

export function main() {
	const cube = engine.addEntity()
	Transform.create(cube, { position: Vector3.create(8, 1, 8) })
	MeshRenderer.setBox(cube)
	MeshCollider.setBox(cube)

	engine.addSystem(() => {
		// 포인터 버튼을 누르고 있는 동안에만 회전
		if (!inputSystem.isPressed(InputAction.IA_POINTER)) return

		const delta = PrimaryPointerInfo.getOrNull(engine.RootEntity)?.screenDelta
		if (!delta || delta.x === 0) return

		const transform = Transform.getMutable(cube)
		transform.rotation = Quaternion.multiply(
			transform.rotation,
			Quaternion.fromEulerDegrees(0, delta.x * DRAG_SENSITIVITY, 0)
		)
	})
}

같은 패턴은 모든 드래그 상호작용에 적용할 수 있습니다: 레일을 따라 엔티티를 이동시키는 데 delta.x 를 오프셋으로 사용하거나, 애니메이션을 스크러빙하거나, 큰 delta 값으로 빠른 스와이프를 감지할 수 있습니다.

마우스룩 카메라 컨트롤

왜냐하면 screenDelta 커서가 잠겨 있어도 계속 작동하므로, 다음을 위한 마우스룩 컨트롤을 만들 수 있습니다: 가상 카메라. 이를 위해 마우스 이동을 yaw와 pitch 각도로 누적한 다음, 매 프레임 카메라의 회전에 적용하세요.

다음 예제에서는 플레이어가 상자를 클릭해 마우스로 조작할 수 있는 가상 카메라로 전환하고, 보조 버튼(F 또는 마우스 오른쪽 버튼)을 눌러 기본 카메라로 돌아갑니다. 가상 카메라가 활성화되어 있는 동안 씬은 커서도 잠그고, 아바타를 다음으로 고정합니다: 입력 수정자, 따라서 플레이어가 카메라를 조작하는 동안 무작정 돌아다니지 않게 됩니다.

import {
	engine,
	Entity,
	InputAction,
	InputModifier,
	inputSystem,
	MainCamera,
	MeshCollider,
	MeshRenderer,
	PointerEventType,
	pointerEventsSystem,
	PointerLock,
	PrimaryPointerInfo,
	Transform,
	VirtualCamera,
} from '@dcl/sdk/ecs'
import { Quaternion, Vector3 } from '@dcl/sdk/math'

// 마우스 이동 픽셀당 카메라 회전 각도
const SENSITIVITY = 0.15

let cameraEntity: Entity
let cameraActive = false
let yaw = 0
let pitch = 0

export function main() {
	// 카메라가 따라가는 엔티티
	cameraEntity = engine.addEntity()
	Transform.create(cameraEntity, { position: Vector3.create(8, 3, 8) })
	VirtualCamera.create(cameraEntity, {
		defaultTransition: { transitionMode: VirtualCamera.Transition.Time(0.5) },
	})

	// 이 상자를 클릭하면 마우스 룩 모드로 전환됩니다
	const box = engine.addEntity()
	Transform.create(box, { position: Vector3.create(8, 1, 4) })
	MeshRenderer.setBox(box)
	MeshCollider.setBox(box)
	pointerEventsSystem.onPointerDown(
		{
			entity: box,
			opts: { button: InputAction.IA_POINTER, hoverText: '카메라 조작' },
		},
		() => activateCamera(true)
	)

	// 마우스로 카메라를 조작
	engine.addSystem(() => {
		if (!cameraActive) return
		if (!PointerLock.getOrNull(engine.CameraEntity)?.isPointerLocked) return

		const delta = PrimaryPointerInfo.getOrNull(engine.RootEntity)?.screenDelta
		if (!delta) return

		yaw += delta.x * SENSITIVITY
		// 카메라가 뒤집히지 않도록 pitch를 제한
		pitch = Math.max(-85, Math.min(85, pitch + delta.y * SENSITIVITY))

		Transform.getMutable(cameraEntity).rotation = Quaternion.fromEulerDegrees(pitch, yaw, 0)
	})

	// 보조 버튼으로 마우스 룩 모드를 종료
	engine.addSystem(() => {
		if (!cameraActive) return
		if (inputSystem.isTriggered(InputAction.IA_SECONDARY, PointerEventType.PET_DOWN)) {
			activateCamera(false)
		}
	})
}

function activateCamera(active: boolean) {
	cameraActive = active

	// 가상 카메라를 할당하거나 해제
	MainCamera.createOrReplace(engine.CameraEntity, {
		virtualCameraEntity: active ? cameraEntity : undefined,
	})

	// 카메라를 조작하는 동안 아바타를 고정
	InputModifier.createOrReplace(engine.PlayerEntity, {
		mode: InputModifier.Mode.Standard({ disableAll: active }),
	})

	// 커서를 잠가 마우스가 즉시 카메라를 조작하도록 함
	PointerLock.createOrReplace(engine.CameraEntity, { isPointerLocked: active })
}

이 예제에서 알아둘 점:

• 시스템은 다음을 더합니다: delta.y 를 pitch에 더합니다. 마우스를 위로 움직이면 음수 delta.y, 즉 pitch가 낮아지고 카메라가 위로 기울어집니다. 세로 조작을 반전하고 싶다면 부호를 뒤집으세요.

• pitch는 -85도에서 85도 범위로 제한되므로, 카메라가 뒤로 완전히 뒤집힐 수 없습니다.

• 이 SENSITIVITY 상수는 마우스 이동 픽셀당 회전 각도를 나타내므로, 원하는 대로 조정하세요.

💡 팁: 플레이어는 언제든지 다음을 눌러 커서를 잠금 해제할 수 있습니다: Esc 또는 마우스 오른쪽 버튼을 클릭하면 카메라가 마우스에 반응하지 않게 됩니다. 위 예제의 보조 버튼처럼, 플레이어가 카메라 모드를 완전히 종료할 수 있는 명확한 방법을 항상 제공하세요. 코드로 커서를 다시 잠글 수도 있습니다. 다음을 참조하세요: 커서를 잠그거나 잠금 해제하기.

관련 주제

커서의 이동이 아니라 화면상의 절대 위치를 읽으려면 다음을 사용하세요: screenCoordinates 같은 컴포넌트의 속성입니다. 다음을 참조하세요: 플레이어의 커서 위치 확인하기.

커서 아래에 어떤 엔티티가 있는지 알아보려면 다음을 결합하세요: worldRayDirection 속성을 레이캐스트와 함께 사용하세요. 다음을 참조하세요: 레이캐스팅.

💡 팁: 포인터 상태의 동작 예제는 다음을 참조하세요: 0,5-primary-cursor-info 테스트 씬으로, 다음을 읽고 PrimaryPointerInfo 매 프레임 이를 읽어 다음에 전달합니다: worldRayDirection 레이캐스트에; 31,20-pointer-lock-control, 다음을 써서 커서 캡처를 요청하고 해제합니다: PointerLock.isPointerLocked; 그리고 32,20-virtual-camera-mouse-look, 다음을 보여줍니다: screenDelta 잠금 상태에서도 여전히 이동을 보고하면서 screenCoordinates 잠금 중 화면 중앙에 고정되어 있습니다.