모바일 안전 영역

씬 UI가 모바일에서 안전하게 배치될 수 있는 영역 — 기기의 하드웨어 여백과 클라이언트 자체 컨트롤이 닿지 않는 곳입니다.

휴대폰에서는 UI가 안전하게 사용할 수 있는 화면 공간을 갉아먹는 서로 무관한 두 가지가 있습니다:

기기의 하드웨어 여백 — 노치나 카메라 컷아웃, 상태 표시줄, 홈 인디케이터, 둥근 모서리입니다. 그 아래에 그려진 UI는 일부가 가려지거나 탭하기 어렵습니다.
Decentraland 클라이언트 자체의 컨트롤 — 조이스틱, 채팅, 프로필, 카메라 컨트롤, 액션 버튼입니다. 그 아래에 배치된 씬 UI는 시각적으로 충돌하고 같은 탭을 두고 경쟁하게 됩니다.

둘 중 어느 것도 직접 측정할 필요가 없습니다. 클라이언트가 런타임에 두 영역을 모두 보고하며 SDK는 당신이 선택한 영역 안에 UI를 배치합니다. 다음과 같은 screenInset 렌더러 옵션:

원하는 것

전달할 값

하드웨어 여백을 피함

없음 — screenInset: 'device' 가 기본값입니다

하드웨어 여백을 피함 및 클라이언트 컨트롤

screenInset: 'interactable'

화면 전체를 사용하며, 여백은 직접 처리합니다

screenInset: 'none'

// 모바일 컨트롤과 충돌하면 안 되는 씬 UI에 권장
ReactEcsRenderer.setUiRenderer(uiComponent, { screenInset: 'interactable' })

클라이언트 지원: 'interactable' 모바일 클라이언트가 필요합니다 1.12.1 이상이어야 합니다. 더 पुराने 클라이언트에서는 해당 영역이 0으로 보고되어 UI가 화면 전체를 덮도록 되돌아갑니다. 또한 같은 릴리스에서 다음이 정규화됩니다. 'device' 영역이 Android와 iOS 간에.

데스크톱에서도 무시되는 것은 아닙니다 — 데스크톱 클라이언트는 화면 왼쪽 약 25%를 자체 UI용으로 예약하므로 'interactable' 데스크톱 레이아웃도 변경됩니다. 다음을 사용해 분기하세요: isMobile() 휴대폰에서만 인셋을 적용하고 싶다면.

참고 화면 인셋 영역 전체 참고 자료: 실제 기기에서 세 영역을 나란히 보는 모습, 렌더러별 동작, 그리고 다음과의 관계를 가상 화면.

클라이언트 컨트롤이 있는 위치

'interactable' 영역을 제공합니다 각 익스플로러가 씬 UI용으로 지정한 — 이는 모든 클라이언트 컨트롤이 그 밖에 있다는 보장을 의도적으로 의미하지 않습니다. 모바일 클라이언트에서는 왼쪽 열(채팅, 프로필, 조이스틱, 이모트)을 제외한 기기 세이프 영역이며, 오른쪽 아래의 액션 버튼은 그 영역 위에 그려집니다 의도적으로.

Scene UI inset to the area the mobile client reports as free of its own HUD

따라서 'interactable', 이 부분은 혼잡하다고 생각하세요:

오른쪽 아래 — 액션 버튼과 상호작용 버튼이 위에 그려집니다. 여기에 배치한 것은 여전히 도달 가능하지만, 탭을 두고 경쟁하게 됩니다.
오른쪽 위 — 프로필과 카메라 컨트롤이 영역 바로 바깥에 위치하므로, 그 모서리에 붙인 UI는 클라이언트 HUD의 일부처럼 보입니다.

영역에 무엇이 포함되는지는 각 익스플로러의 판단이며 버전마다 달라질 수 있습니다. 런타임에 읽어 오고, 절대 하드코딩하지 말며, 대상 플랫폼에서 확인하세요.

씬 UI를 배치할 위치

화면 중앙 — 사용자가 읽고 응답해야 하는 대화 상자 등.
상단 중앙 — 동작이 필요 없는 메시지, 상태, 알림.
하단 중앙, 상호작용 버튼 위 — 상황에 맞는 힌트.
오른쪽 아래 모서리는 아님 — 상호작용 가능 영역 안쪽이라도, 그곳은 액션 버튼의 자리입니다.

대신 UI의 일부를 감싸세요

다음으로 제외했다면 screenInset: 'none' 그리고 UI의 일부만 보호하고 싶다면, 다음으로 감싸세요: ScreenInsetArea 또는 InteractableArea 컴포넌트입니다. 각 컴포넌트는 해당 영역을 읽어 자식에게 적용합니다. 다음에서 가져오세요: @dcl/sdk/react-ecs:

import ReactEcs, { ReactEcsRenderer, UiEntity, ScreenInsetArea } from '@dcl/sdk/react-ecs'
import { Color4 } from '@dcl/sdk/math'

export function setupUi() {
  ReactEcsRenderer.setUiRenderer(() => (
    <ScreenInsetArea>
      {/* 100% × 100% 크기의 자식은 안전한 인셋 영역을 정확히 채웁니다 */}
      <UiEntity
        uiTransform={{ width: '100%', height: '100%' }}
        uiBackground={{ color: Color4.create(0, 0, 0, 0.5) }}
      />
    </ScreenInsetArea>
  ), { screenInset: 'none' })
}

두 컴포넌트는 클라이언트가 보고하는 값을 사용해 절대 위치를 지정하므로, positionType 및 위치 그들의 필드 uiTransform 는 예약되어 있으며 — 여기에 설정한 값은 무시됩니다. 그 외의 모든 uiTransform 속성(padding, flexDirection, alignItems, …) 및 UI 컴포넌트(uiBackground, onMouseDown, …)는 평소처럼 동작합니다. 회전하거나 시스템 바가 나타나거나 사라질 때처럼 영역이 바뀌면 자동으로 반응하며, 다음을 보정합니다: UI 배율 계수, 따라서 가상 화면 크기가 무엇이든 여백이 올바르게 적용됩니다.

📔 인셋을 두 번 적용하지 마세요: 다음 screenInset: 'none' 위 코드 조각의 이 부분이 중요합니다. 렌더러가 이미 일치하는 인셋을 적용하는데 UI를 컴포넌트로 감싸면, UI가 여백의 두 배만큼 안쪽으로 밀립니다. 둘 중 하나만 선택하세요.

📱 모바일 전용: 기기 인셋은 다음에서만 실제 값을 가집니다: 모바일 클라이언트. 다음에서는 데스크톱 클라이언트 그 값은 (0, 0, 0, 0), 따라서 screenInset: 'device' 및 ScreenInsetArea 컴포넌트는 그곳에서 아무런 영향을 주지 않으며, UI는 그것들이 없을 때와 정확히 동일하게 렌더링됩니다. 상호작용 가능 영역은 기기 인셋과 달리 일 때 데스크톱에서 0이 아닙니다.

왜 중요한가

클라이언트 컨트롤과 겹치는 씬 UI는 다음과 같은 문제가 생깁니다:

조이스틱, 상호작용 버튼, 또는 카메라 컨트롤 뒤에 일부가 가려집니다.
그 컨트롤들과 탭을 두고 경쟁하게 됩니다 — 플레이어가 실수로 둘 중 하나를 눌러버릴 수 있습니다.
모바일에서 씬이 망가진 것처럼 느껴지게 하여, 피처링과 유지율에 악영향을 줍니다.

항상 실제 기기에서 다음을 사용해 확인하세요: 미리보기 QR 코드.

클라이언트 컨트롤이 있는 위치

씬 UI를 배치할 위치

대신 UI의 일부를 감싸세요

왜 중요한가

관련