UI 편집기

코드가 아닌 캔버스 위에서, Creator Hub에서 씬의 화면 UI를 시각적으로 디자인하세요.

UI Editor를 사용하면 레이아웃 코드를 직접 쓰는 대신 위젯을 캔버스로 드래그해 씬의 화면 인터페이스를 만들 수 있습니다. 이는 씬에 실제 파일을 기록하므로, 여기서 만든 모든 것은 코드로 계속 편집할 수 있는 일반 SDK7 UI입니다.

열기

사용하세요 2D / 3D 편집기 왼쪽 패널 상단의 전환 스위치. 3D 는 이미 알고 있는 씬 캔버스입니다. 2D 는 UI Editor입니다.

3D가 선택된 2D 및 3D 탭 전환.

📔 주의: UI Editor는 다음이 필요합니다 @dcl/sdk 버전 7.26.0 이상이 씬에 있어야 합니다. 더 오래된 씬에서는 2D 탭에 UI Editor를 사용할 수 없음 라는 알림이 캔버스 대신 표시되며, SDK 업데이트 버튼으로 씬을 업그레이드할 수 있고, 나중에 버튼으로 닫을 수 있습니다.

Creator Hub는 씬을 2D 또는 3D 중 어디에서 끝냈는지 기억하고 같은 방식으로 다시 엽니다. 이는 프로젝트별로 저장되며 씬과 함께 게시되지 않습니다.

Bevy 씬 렌더러를 사용하는 경우, 2D 로 전환하면 실행 중인 씬이 일시 중지되고, 3D 로 돌아가면 이전에 실행 중이었다면 다시 재개됩니다.

첫 UI 만들기

1. 다음으로 전환하세요 2D 탭입니다.

2. 를 클릭하세요 새 GUI, 빈 캔버스 가운데의 버튼이나 + 옆의 GUIs 으로 전환하세요. GUI는 하나의 UI 구성 요소이며, 자체 파일에 저장됩니다.

3. 아래 팔레트에서 위젯을 캔버스로 드래그하세요. 전체 화면 은 처음 시작하기 좋은 위젯으로, 화면을 덮는 루트를 제공합니다. 그런 다음 그 안에 다른 위젯을 놓으세요.

4. 위젯을 선택하고 오른쪽 패널에서 속성을 설정하세요.

저장 버튼은 없습니다. 편집기는 작업하면서 변경 내용을 디스크에 기록하고, 툴바 왼쪽의 배지는 모든 변경 사항이 저장됨.

2D 모드의 UI Editor: 왼쪽의 GUIs 및 Nodes 패널에는 MainUI라는 GUI가 표시되고 Container 안에 Label과 Button이 들어 있으며, 가운데 캔버스에는 Button이 선택된 Container와 그 주위의 크기 조절 핸들이 보이고, 오른쪽의 Properties 탭에는 Button의 위치와 레이아웃이 표시되며, 아래쪽에는 위젯 팔레트가 이어진다.

패널

• 왼쪽: GUIs, UI 구성 요소 목록과 노드, 선택한 항목의 트리입니다. 검색 상자로 둘 다 필터링할 수 있습니다. 노드에 마우스를 올리면 잠금, 숨기기 또는 삭제할 수 있습니다.

• 오른쪽: 속성 탭은 선택한 노드의 것이고, 로직 탭입니다.

• 아래쪽: 위젯 팔레트입니다. 카드를 캔버스로 드래그해 추가하세요.

• 가운데: 캔버스입니다. 노드를 드래그해 이동하고, 핸들로 크기를 조절하며, 마우스 휠이나 드래그로 자유롭게 화면을 이동할 수 있습니다.

캔버스 오른쪽 아래 구석에는 두 개의 떠 있는 컨트롤 그룹이 있습니다:

• 해당 미리보기 그룹은 모바일 HUD 가이드와 안전 영역 가이드를 토글하고, 데스크톱 미리보기 및 모바일 미리보기.

• 해당 줌 그룹에는 빼기와 더하기 버튼, 그리고 퍼센트 표시가 있습니다. 퍼센트를 클릭하면 보기가 초기화됩니다.

2D 및 3D 탭, 검색 상자, MainUI가 들어 있는 GUIs 목록, 그리고 Container 안에 Label과 Button이 표시된 Nodes 트리가 보이며, Button 행에는 잠금, 숨기기, 삭제 아이콘이 있는 UI Editor의 왼쪽 패널.

선택한 Button에 대한 UI Editor의 Properties 탭으로, Visibility, Interaction States, Constraints, Position, Z-Index가 있는 Position 섹션과 Size, Min Size, Max Size, Padding, Margin이 있는 Layout 섹션이 보인다.

위젯

UI Editor 아래쪽의 위젯 팔레트로, Full Screen, Container, Image, Label, Button, Input, Dropdown 카드가 보인다.

팔레트는 위젯을 세 가지 범주로 나눕니다:

• 컨테이너: 전체 화면, 컨테이너, 이미지

• 텍스트: 레이블, 버튼

• 입력: 입력, 드롭다운

전체 화면 은/는 내부에 놓인 것을 무엇이든 채우는 컨테이너로, 화면 전체를 덮는 UI의 시작점으로 좋습니다.

이동 및 크기 조절

툴바에는 세 가지 도구 모드가 있습니다:

• Free: 이동 및 크기 조절, 일반 용도 모드입니다.

• 이동: 드래그만.

• 크기 조절: 핸들만.

위치는 10픽셀 격자에 맞춰 스냅됩니다. Shift 를 누른 채 드래그하면 격자를 무시하고 자유롭게 이동할 수 있습니다. 도구 버튼 옆의 작은 화살표를 누르면 스냅 을 완전히 끄는 체크박스가 있는 메뉴가 열립니다.

2D 툴바로, 모든 변경 사항이 저장됨 배지, 실행 취소와 다시 실행, Free, Move, Resize 도구, 그리고 스냅 드롭다운이 열려 체크된 Snap 옵션이 보이며, 그 뒤로 재생 및 중지 버튼이 이어진다.

레이아웃: 흐름 배치와 자유 배치

어디에 노드가 놓이는지는 두 개의 별도 속성이 결정합니다. 이것들을 제대로 이해하면 많은 혼란을 줄일 수 있습니다.

흐름 는 컨테이너 에 설정되며, 자식 요소를 어떻게 배치할지 결정합니다:

• Free: 자식은 놓아 둔 위치에 그대로 유지됩니다.

• 행 / 행 반전: 자식은 왼쪽에서 오른쪽으로, 또는 오른쪽에서 왼쪽으로 배치됩니다.

• 열 / 열 반전: 자식은 위에서 아래로, 또는 아래에서 위로 쌓입니다.

• 자식 줄바꿈: 자식이 공간에 맞지 않을 때 여러 줄로 넘치게 할 수 있습니다.

레이아웃 흐름 무시 는 자식 에 설정되며, 해당 노드가 부모의 배치를 따르지 않을지 결정합니다. 끄면 부모가 위치를 정합니다. 켜면 Anchor와 Position 값으로 직접 고정합니다.

이로부터 두 가지 결과가 생깁니다:

• 위젯을 Free 컨테이너에 넣으면, 놓은 그 자리에 정확히 유지됩니다.

• 방향이 설정된 컨테이너에 넣으면 흐름에 합류해 줄에서 자기 자리를 차지합니다.

컨테이너를 Free 로 바꾸면 기존 자식이 현재 있는 위치에 고정되므로 아무것도 튀지 않습니다.

GUI의 루트는 항상 자유롭게 배치됩니다.

알아두면 좋은 다른 속성

• 불투명도: 100%는 완전 불투명, 0%는 완전 투명입니다. 기본값은 100%입니다.

• Scene Inset: GUI가 화면의 어느 부분에 놓일지.

  • 전체 화면 는 렌더링 가능한 전체 화면을 사용합니다.

  • Gameplay Safe Area 는 채팅, 미니맵, HUD 표시기 등 클라이언트 자체 인터페이스를 피해 배치됩니다.

  • Device Safe Area 는 노치나 시스템 바 같은 물리적 방해 요소도 피합니다. 이 옵션은 캔버스가 모바일 미리보기일 때 제공됩니다.

GUI 루트에 고정 픽셀 너비와 높이를 주면, 캔버스는 이를 화면이 아니라 정확히 그 크기의 아트보드로 프레임 처리합니다.

휴대폰에서 UI 확인하기

캔버스 오른쪽 아래의 컨트롤로 미리보기를 데스크톱 화면과 휴대폰 사이에서 전환할 수 있습니다. 모바일 미리보기에서는 노치가 있는 휴대폰 프레임 안에 캔버스가 그려져, 화면 경계가 실제로 어디인지 볼 수 있습니다.

플레이어가 볼 수 있고 닿을 수 있는 위치에 요소를 배치하는 데 도움이 되는 두 종류의 가이드가 있습니다:

• 안전 영역 가이드 는 GUI가 제한되는 화면 영역을 윤곽선으로 보여 주며, Scene Inset 에서 선택한 설정과 일치합니다. Scene Inset이 Device Safe Area 또는 Gameplay Safe Area 인 동안에는 전체 화면 윤곽선은 GUI가 잘리는 기준이므로 항상 켜져 있습니다. Scene Inset을

• HUD 가이드 는 조이스틱, 점프 및 액션 버튼, 이모트 휠, 프로필, 채팅, 나침반 등 모바일 클라이언트의 자체 컨트롤을 그립니다. 이는 참고용일 뿐이며 선택하거나 이동할 수 없습니다. 게임 컨트롤러 버튼으로 켜고 끌 수 있으며, 모바일 미리보기에서만 나타나고, Scene Inset이 안전 영역일 때 기본적으로 가이드가 표시됩니다.

안전 영역 밖에 배치된 콘텐츠는 숨겨지지 않고 윤곽선 바깥에 그려집니다. 그 오버플로는 경고입니다. 실제 클라이언트에서는 게임의 HUD 아래에 놓이게 됩니다.

📔 주의: 이 가이드는 편집기 전용 근사치입니다. 실제 영역은 런타임에 클라이언트가 보고하며 기기마다 다르므로 항상 실제 휴대폰에서 확인하세요. 다음을 참조하세요 모바일에서 미리보기.

모바일 컨트롤 사용자 지정

모바일 클라이언트에서 플레이어는 조이스틱, 십자선, 그리고 액션 버튼 줄과 같은 기본 제공 화면 컨트롤을 통해 이동하고 행동합니다. MobileHUD 항목을 사용하면 코드 없이 HUD를 다시 구성할 수 있으며, 진행하면서 결과를 캔버스에 표시합니다.

씬에 적어도 하나의 GUI가 있으면, MobileHUD 가 GUIs 목록의 첫 번째 행으로 표시되며,

세 개의 체크박스로 HUD의 전체 부분을 숨길 수 있습니다:

• 조이스틱 숨기기: 이동 스틱을 제거합니다.

• 십자선 숨기기: 조준선(레티클)을 제거합니다.

• 입력 액션 숨기기: 모든 액션 버튼을 한 번에 제거합니다.

그 아래의 입력 액션 섹션에는 화면 슬롯을 채우는 순서대로 여덟 개의 버튼이 나열됩니다:

액션	화면상의 버튼
IA_JUMP	기본값으로 중앙의 큰 버튼
IA_POINTER	상호작용 버튼
IA_PRIMARY (E)	E 버튼
IA_SECONDARY (F)	F 버튼
IA_ACTION_3 (1) 을 IA_ACTION_6 (4)	숫자 버튼

각 행은 세 가지를 제공합니다:

• 주요: 이 액션을 중앙의 큰 버튼으로 만드는 라디오 버튼입니다. IA_JUMP 기본적으로 주요이며, 한 번에 하나의 액션만 주요로 설정할 수 있습니다.

• 하나의 눈 아이콘 은 해당 버튼을 표시하거나 숨깁니다. 하나를 숨기면 아래의 버튼들이 위로 올라와 빈자리를 채웁니다.

• 사용자 지정 아이콘: 버튼의 글리프를 .png, .jpg 또는 .jpeg 이미지로 바꿉니다.

기본적으로 아무것도 숨겨져 있지 않고 IA_JUMP 이 주요 버튼인데, HUD를 건드리지 않는 씬에서 플레이어가 받는 기본값과 정확히 같습니다.

💡 팁: 숫자 버튼은 일반적으로 "+" 오버플로 토글 뒤에 있습니다. 더 높은 번호 버튼을 충분히 숨기면 직접 표시됩니다. 채워지는 슬롯 방식은 다음을 참조하세요 화면 컨트롤 에서 확인하세요.

쓰는 파일

변경 사항은 src/mobile-hud.ts에 기록되며, 여기에는 setupMobileHud() 함수가 내장되어 있고 SDK의 TouchScreenControls 컴포넌트를 사용합니다:

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

export function setupMobileHud() {
  TouchScreenControls.createOrReplace(engine.RootEntity, {
    hideJoystick: true,
    hideCrosshair: false,
    mainAction: InputAction.IA_PRIMARY,
    touchInputs: [
      { inputAction: InputAction.IA_ACTION_3, hide: true },
    ],
  })
}

편집기는 가져오기와 호출도 당신의 src/index.ts:

import { setupMobileHud } from './mobile-hud'

setupMobileHud()

이 파일은 말할 것이 있을 때만 존재합니다. 모든 것을 기본값으로 되돌리거나 마지막 GUI를 삭제하면 Creator Hub는 src/mobile-hud.ts 을 삭제하고 해당 두 줄도 다시 제거합니다.

📔 주의: 선택되어 있는 동안 MobileHUD 위젯 팔레트는 비활성화되고 미리보기 컨트롤은 숨겨집니다. 배치할 것이 없고 HUD는 모바일 전용이기 때문입니다. 자신의 GUI 중 하나를 선택하면 다시 나타납니다.

파일이 들어가는 위치

UI Editor는 씬의 실제 소스 파일을 편집합니다. 별도의 저장 형식은 없습니다.

• 각 GUI는 하나의 .tsx 파일로 src/ui/.

• src/ui/index.tsx 는 편집기가 이들을 모으도록 생성합니다. 직접 편집하지 마세요.

• src/mobile-hud.ts 에는 모바일 컨트롤이 들어 있습니다, 변경했다면. 이는 의도적으로 src/ui/ 밖에 위치하므로 GUI로 취급되지 않습니다.

씬에 예전 단일 src/ui.tsx 파일이 있으면, 편집기는 UI Editor를 처음 열 때 이를 src/ui.tsx.bak 으로 백업합니다.

이 파일들은 일반 파일이므로, 언제든지 코드 편집기 에서 열 수 있습니다. 다음을 참조하세요 UI 에서 기본 코드가 하는 일을 확인하세요.

편집기가 편집할 수 없는 코드

편집기는 특정한 형태의 UI 코드를 이해합니다. 예를 들어 루프나 조건문 안에서 만들어지거나, 사용자 지정 컴포넌트나 spread props를 사용하는 등 다른 방식으로 작성된 노드는 캔버스에 회색 블록으로 표시되며 표준이 아님, 코드로 편집 배지가 붙습니다. 그 자식들은 표시되지 않으며, 대신 코드에서 편집합니다.

그 밖의 GUI는 정상적으로 계속 작동합니다.

관련 페이지

• UI: 코드를 사용해 씬 UI를 작성합니다.

• 코드와 결합: 씬을 코드 편집기에서 여세요.

• 엔티티와 컴포넌트: 편집기의 3D 측면.