Intermediate읽기 시간: 10분최근 수정: 2026. 4. 14

Interaction 개요

플레이어가 월드 안의 물체와 상호작용하는 방식을 결정하는 Grabbable Module, Sittable, Attach Point 컴포넌트와 관련 Event Function 을 소개합니다.

상호작용이 가능한 오브젝트에 반응해 기능을 구현하려면 VIVEN 이 제공하는 세 가지 핵심 컴포넌트 — Grabbable Module, Sittable, Attach Point — 를 조합합니다.

Viven Grabbable Module

플레이어가 물체를 잡고, 던지고, 배치할 수 있는 기본 상호작용을 제공합니다. 네트워크를 통해 RigidBody 가 자동으로 동기화됩니다. 추가 데이터를 동기화하려면 VivenBehaviour 의 RPC 를 사용하세요.

Grab 모드

플레이어가 물체를 손에 쥐고 이동할 수 있는 모드입니다. Grab 가능한 물체는 주황색 Outline 으로 활성화됩니다.

플랫폼	잡기	놓기
PC	물체를 바라보고 마우스 좌클릭	액션 버튼을 다시 눌러 Release
VR	물체에 손을 대고 Grip 버튼	Grip 릴리즈

Grab 중에는 액션 버튼(짧게/길게)으로 커스텀 기능을 트리거할 수 있습니다. Release 시 PhysicsType 이 Physics 면 던지기가 동작합니다.

Place 모드

물체를 원하는 위치에 배치하거나 다른 오브젝트에 붙일 수 있는 모드입니다.

플랫폼	진입 방법
PC	물체를 바라보고 마우스 우클릭
VR	물체에 손을 대고 Trigger 버튼

Place 모드에서는 VObject 로 생성한 오브젝트를 삭제할 수도 있습니다. 맵에 미리 배치된 오브젝트는 삭제할 수 없습니다.

📖

참고:

Place 모드 중에는 Grabbable Event 가 호출되지 않습니다.

⚠️

주의사항:

GrabbableModule 을 포함한 GameObject 는 상호작용 과정에서 Layer 가 변경됩니다. Layer 변경을 방지해야 하는 자식 오브젝트는 excludeLayerObjects 에 등록해주세요.

주요 Field

필드	설명
`objectGrabType`	잡았을 때 RigidBody 상태. `Kinematic`(충돌 무시) 또는 `Velocity`(물리 영향)
`parentToHandOnGrab`	`true` 면 잡는 순간 물체의 parent 가 interactor 가 됨
`longClickTimeThreshold`	액션 버튼 "길게 누름" 기준 초. 예: `1.5` 이면 1.5초 이상
`placePivot`	벽에 붙을 때 기준이 되는 축 (기본 `Vector3.up`)
`grabPoints`	잡히는 위치를 커스텀 좌표로 지정
`vivenAttachPoints`	이 오브젝트에 붙어 있는 모든 Attach Point

Grabbable Event Function

Viven Lua Behaviour 에서 아래 이벤트 함수를 정의해 반응을 구현합니다.

-- 물체를 잡았을 때
function onGrab(interactor)
  interactor.InteractingInteractable.Transform:Translate(Vector(0, 1, 0))
end

-- 물체를 놓았을 때
function onRelease(interactor)
  print("released")
end

-- 잡은 상태에서 액션 버튼을 짧게 눌렀을 때
function objectShortClickAction(interactor)
  -- 예: 총 발사, 사진 찍기 등 짧은 액션
end

-- 잡은 상태에서 액션 버튼을 길게 눌렀을 때
-- (기준: longClickTimeThreshold)
function objectLongClickAction(interactor)
  -- 예: 조준 모드 진입, 차징 샷 등
end

⚠️

주의사항:

HoldAction 과 ClickAction 을 동시에 사용할 경우 실행 순서를 보장할 수 없습니다. 두 이벤트를 함께 쓰는 것은 권장되지 않습니다.

Viven Sittable

해당 컴포넌트가 붙은 물체에 앉을 수 있게 합니다. (현재 PC 모드만 지원)

앉기 실행 시 캐릭터가 vivenSitPoint 로 이동 후 앉는 모션 재생
앉은 상태에서는 이동 불가, Yaw 회전만 가능
다른 Grabbable 과 상호작용은 앉은 상태에서도 가능

📖

참고:

Viven Sittable 은 추후 설계가 변경될 예정입니다. 필드 이름이 바뀔 수 있으니 릴리즈 노트를 확인하세요.

주요 Field

필드	설명
`vivenSitPoint`	캐릭터가 앉기 모션 전 이동할 Transform

Viven Attach Point

한 물체에 다른 물체를 붙이는 지점을 정의합니다. Collider 기반으로 동작하며, GrabbableModule 이 부착된 오브젝트의 하위 계층에만 추가할 수 있습니다. 붙여지는 오브젝트 역시 GrabbableModule 을 가져야 합니다.

화이트리스트 / 블랙리스트

VObject 빌드 시 ContentId 를 기반으로 허용 여부를 결정합니다. 둘 다 설정된 경우 화이트리스트가 우선합니다.

필드	설명
`attachablePrefabs`	이 지점에 붙일 수 있는 오브젝트의 ContentId 리스트. 비어 있으면 모두 허용
`notAttachablePrefabs`	이 지점에 붙일 수 없는 오브젝트의 ContentId 리스트

예를 들어 활 오브젝트의 Attach Point 에 화살만 붙이고 싶다면 attachablePrefabs 에 화살의 ContentId 를 등록하면 됩니다.

다음 단계

Network 개요 — VObject · View · RPC 로 상호작용 데이터를 동기화하는 방법