Attention: Here be dragons

This is the latest (unstable) version of this documentation, which may document features not available in or compatible with released stable versions of Godot.

Checking the stable version of the documentation...

CGS 노드 소개

게임에서는 명확하고 유익하면서도 시각적으로 만족스러운 사용자 인터페이스를 플레이어에게 제공하는 것이 필수적입니다. Control 노드는 기본적으로 상당히 기능적인 외관을 갖추고 있지만 항상 고유성과 케이스별 튜닝의 여지가 있습니다. 이러한 목적을 위해 Godot 엔진에는 사용자 정의 컨트롤을 포함하여 사용자 인터페이스의 모든 컨트롤의 모양을 사용자 정의할 수 있는 GUI 스키닝(또는 테마 지정)용 시스템이 포함되어 있습니다.

다음은 이 시스템이 작동하는 예입니다. 즉, 엔진의 기본 UI 테마와 근본적으로 다른 GUI를 사용한 게임입니다.

../../_images/tank-kings-by-winterpixel-games.png

"기어업!" Tank Kings의 화면, Winterpixel Games 제공

이 시스템을 사용하면 게임에 고유한 모양을 부여하는 것 외에도 개발자가 접근성 설정을 포함하여 최종 사용자에게 사용자 정의 옵션을 제공할 수 있습니다. UI 테마는 계단식 방식으로 적용됩니다(즉, 상위 컨트롤에서 해당 자식 노드로 전파됨). 이는 색맹 사용자를 위한 글꼴 설정이나 조정이 단일 위치에 적용되어 전체 UI 트리에 영향을 미칠 수 있음을 의미합니다. 물론 이 시스템은 게임플레이 목적으로도 사용될 수 있습니다. 영웅 기반 게임은 선택한 플레이어 캐릭터에 맞게 스타일을 변경할 수 있고, 팀 기반 프로젝트의 측면에 다양한 특징을 부여할 수 있습니다.

테마의 기본

스키닝 시스템은 Theme 리소스에 의해 구동됩니다. 모든 Godot 프로젝트에는 내장 컨트롤 노드에서 사용되는 설정이 포함된 고유한 기본 테마가 있습니다. 이것이 컨트롤에 상자 밖에서 독특한 모양을 제공하는 것입니다. 그러나 테마는 구성만 설명하며 해당 구성을 표시하는 데 필요한 방식으로 사용하는 것은 여전히 각 개별 컨트롤의 작업입니다. :ref:`사용자 정의 컨트롤 <doc_custom_gui_controls>`을 구현할 때 이 점을 기억하는 것이 중요합니다.

참고

Godot 편집기 자체도 기본 테마에 의존합니다. 하지만 기본 테마 위에 고도로 사용자 정의된 자체 테마를 적용하기 때문에 Godot 프로젝트와 동일해 보이지 않습니다. 원칙적으로 이는 :ref:`below <doc_gui_theme_in_project>`에 설명된 대로 게임에서와 똑같이 작동합니다.

테마

테마에 저장되는 구성은 테마 항목으로 구성됩니다. 각 항목에는 고유한 이름이 있으며 다음 데이터 유형 중 하나여야 합니다.

  • 색깔

    글꼴 및 배경에 자주 사용되는 color 값입니다. 색상은 컨트롤과 아이콘의 변조에도 사용할 수 있습니다.

  • 상수

    컨트롤의 숫자 속성(예: :ref:`BoxContainer <class_BoxContainer>`의 항목 구분) 또는 부울 플래그(예: :ref:`Tree <class_Tree>`의 관계 선 그리기)에 사용할 수 있는 정수 값입니다.

  • 안개:

    텍스트를 표시하는 컨트롤에서 사용되는 font 리소스입니다. 글꼴에는 크기와 색상을 제외한 대부분의 텍스트 렌더링 설정이 포함되어 있습니다. 또한 정렬과 텍스트 방향은 개별 컨트롤로 제어됩니다.

  • 안개:

    텍스트가 표시되어야 하는 크기를 결정하기 위해 글꼴과 함께 사용되는 정수 값입니다.

  • 버전

    일반적으로 아이콘을 표시하는 데 사용되는 texture 리소스(예: Button).

  • 스타일

    UI 패널이 표시되는 방식을 정의하는 구성 옵션 모음인 StyleBox 리소스입니다. 이는 Panel 컨트롤에만 국한되지 않습니다. 스타일박스는 배경과 오버레이를 위해 많은 컨트롤에서 사용되기 때문입니다.

    컨트롤에 따라 StyleBox가 다른 방식으로 적용됩니다. 특히 focus 스타일 상자는 다른 스타일 상자(예: normal 또는 pressed)에 *오버레이*로 그려져 기본 스타일 상자가 계속 표시되도록 합니다. 이는 포커스 스타일 상자가 윤곽선이나 반투명 상자로 디자인되어 배경이 계속 표시될 수 있음을 의미합니다.

명명된 타입

항목 구성을 돕기 위해 각 테마는 유형으로 구분되며 각 항목은 단일 유형에 속해야 합니다. 즉, 각 테마 항목은 이름, 데이터 유형 및 테마 유형으로 정의됩니다. 이 조합은 테마 내에서 고유해야 합니다. 예를 들어 Label``라는 유형에는 ``font_color``라는 두 개의 색상 항목이 있을 수 없지만 ``LineEdit 유형에는 또 다른 font_color 항목이 있을 수 있습니다.

기본 Godot 테마는 UI 스키닝을 사용하는 모든 내장 컨트롤 노드에 대해 하나씩 이미 정의된 여러 테마 유형과 함께 제공됩니다. 위의 예에는 기본 테마에 있는 실제 테마 항목이 포함되어 있습니다. 각 컨트롤에 대한 클래스 참조의 테마 속성 섹션을 참조하여 해당 컨트롤과 해당 하위 클래스에 사용할 수 있는 항목을 확인할 수 있습니다.

참고

하위 클래스는 상위 클래스에 대해 정의된 테마 항목을 사용할 수 있습니다(Button 및 그 파생 항목이 좋은 예임). 실제로 모든 컨트롤은 필요한 경우 모든 테마 유형의 모든 테마 항목을 사용할 수 있습니다(그러나 명확성과 예측 가능성을 위해 엔진에서는 이를 방지하려고 합니다).

어린이 수업의 경우 해당 프로세스가 자동화된다는 점을 기억하는 것이 중요합니다. 기본 제공 컨트롤이 테마에서 테마 항목을 요청할 때마다 테마 유형을 생략할 수 있으며 해당 클래스 이름이 대신 사용됩니다. 또한 상위 클래스의 클래스 이름도 차례로 사용됩니다. 이를 통해 ``Button``와 같은 상위 클래스에 대한 변경 사항이 모든 파생 클래스를 사용자 정의할 필요 없이 모든 파생 클래스에 영향을 미칠 수 있습니다.

또한 자신만의 테마 유형을 정의하고 기본 제공 컨트롤과 자신만의 컨트롤을 추가로 사용자 지정할 수도 있습니다. 기본 제공 컨트롤에는 사용자 정의 테마 유형에 대한 정보가 없으므로 해당 항목에 액세스하려면 스크립트를 활용해야 합니다. 모든 컨트롤 노드에는 적용된 테마에서 테마 항목을 가져올 수 있는 여러 가지 방법이 있습니다. 이러한 메서드는 테마 유형을 인수 중 하나로 받아들입니다.

var accent_color = get_theme_color("accent_color", "MyType")
label.add_theme_color_override("font_color", accent_color)

더 많은 사용자 정의 기회를 제공하기 위해 유형을 유형 변형으로 함께 연결할 수도 있습니다. 이는 사용자 정의 테마 유형의 또 다른 사용 사례입니다. 예를 들어 테마에는 기본 Label 유형의 변형으로 표시될 수 있는 Header 유형이 포함될 수 있습니다. 그러면 해당 유형에 대해 Header 변형을 사용하도록 개별 Label 컨트롤을 설정할 수 있으며, 테마에서 테마 항목이 요청될 때마다 이 변형이 다른 유형보다 먼저 사용됩니다. 이를 통해 단일 Theme 리소스에 컨트롤 노드의 동일한 클래스에 대한 테마 항목의 다양한 사전 설정을 저장할 수 있습니다.

경고

기본 테마에서 사용 가능하거나 사용자 정의 프로젝트 테마에 정의된 변형만 인스펙터 독에 옵션으로 표시됩니다. 두 위치 외부에 정의된 변형의 이름을 수동으로 입력할 수도 있지만 모든 변형을 프로젝트 테마에 유지하는 것이 좋습니다.

:ref:`전용 기사 <doc_gui_theme_type_variations>`에서 테마 유형 변형 생성 및 사용에 대해 자세히 알아볼 수 있습니다.

컨트롤 사용자 정의

각 컨트롤 노드는 테마를 사용하지 않고도 직접 사용자 정의할 수 있습니다. 이를 로컬 재정의라고 합니다. 컨트롤 클래스 참조의 모든 테마 속성은 인스펙터 독 또는 스크립트를 사용하여 컨트롤 자체에서 직접 재정의될 수 있습니다. 이를 통해 이 컨트롤의 자식 노드를 포함하여 프로젝트의 다른 항목에는 영향을 주지 않으면서 UI의 특정 부분을 세밀하게 변경할 수 있습니다.

../../_images/themecheck.webp

로컬 재정의는 특히 일관성을 목표로 하는 경우 사용자 인터페이스의 시각적 효과에 덜 유용합니다. 그러나 노드 레이아웃의 경우 이는 필수적입니다. BoxContainer 및 :ref:`GridContainer <class_GridContainer>`와 같은 노드는 자식 노드 사이의 구분을 정의하기 위해 테마 상수를 사용하고 :ref:`MarginContainer <class_MarginContainer>`는 테마에 사용자 정의 가능한 여백을 저장합니다. 항목.

컨트롤에 로컬 테마 항목 재정의가 있을 때마다 이 값이 사용됩니다. 테마에서 제공하는 값은 무시됩니다.

프로젝트 생성하기

기본적으로 각 프로젝트는 Godot에서 제공하는 기본 프로젝트 테마를 채택합니다. 기본 테마 자체는 일정하며 변경할 수 없지만 해당 항목은 사용자 정의 테마로 재정의될 수 있습니다. 사용자 정의 테마는 두 가지 방법, 즉 프로젝트 설정으로 적용하거나 노드 제어 트리 전체에 걸쳐 노드 속성으로 적용할 수 있습니다.

전체 프로젝트에 영향을 미치도록 조정할 수 있는 두 가지 프로젝트 설정이 있습니다. :ref:`GUI > Theme > Custom<class_ProjectSettings_property_gui/theme/custom>`를 사용하면 사용자 정의 프로젝트 전체 테마를 설정할 수 있고, :ref:`GUI > Theme > Custom Font<class_ProjectSettings_property_gui/theme/custom_font>`는 기본 대체 글꼴에 동일한 작업을 수행합니다. 컨트롤 노드에서 테마 항목을 요청하면 사용자 정의 프로젝트 테마(있는 경우)가 먼저 확인됩니다. 항목이 없는 경우에만 기본 테마가 선택됩니다.

이를 통해 단일 테마 리소스로 모든 Godot 컨트롤의 기본 모양을 구성할 수 있지만 그보다 더 세부적으로 이동할 수 있습니다. 모든 컨트롤 노드에는 theme 속성도 있으며, 이를 통해 해당 컨트롤로 시작하는 노드 분기에 대한 사용자 지정 테마를 설정할 수 있습니다. 이는 컨트롤과 해당 자식 노드 및 자식 노드 전체가 프로젝트 및 기본 테마로 돌아가기 전에 먼저 해당 사용자 정의 테마 리소스를 확인한다는 것을 의미합니다.

참고

프로젝트 설정을 변경하는 대신 사용자 정의 테마 리소스를 전체 UI 분기의 최상위 컨트롤 노드로 설정하여 거의 동일한 효과를 얻을 수 있습니다. 실행 중인 프로젝트에서는 예상대로 작동하지만 개별 장면을 미리 보거나 직접 실행할 때 기본 테마를 사용하여 계속 표시됩니다. 이 문제를 해결하려면 동일한 테마 리소스를 각 개별 씬의 루트 컨트롤에 설정할 수 있습니다.

예를 들어, 프로젝트 테마의 버튼에는 특정 스타일이 있지만 팝업 대화 상자 내부의 버튼에는 다른 모양이 필요할 수 있습니다. 사용자 정의 테마 리소스를 팝업의 루트 컨트롤로 설정하고 해당 리소스 내의 버튼에 대해 다른 스타일을 정의할 수 있습니다. 팝업 루트와 버튼 사이의 제어 체인 노드가 중단되지 않는 한 해당 버튼은 가장 가까운 테마 리소스에 정의된 스타일을 사용합니다. 다른 모든 컨트롤은 여전히 프로젝트 전체 테마와 기본 테마 스타일을 사용하여 스타일이 지정됩니다.

당신의 최종 씬은 이렇게 보여야 할 것입니다.

  1. 동일한 데이터 유형 및 이름의 로컬 대체를 확인하십시오.

  2. 컨트롤의 유형 변형, 클래스 이름 및 상위 클래스 이름 사용:

    1. 자체적으로 시작하는 모든 컨트롤을 확인하고 테마 속성이 설정되어 있는지 확인하세요.

    2. 그렇다면 해당 테마에서 동일한 이름, 데이터 및 테마 유형과 일치하는 항목이 있는지 확인하세요.

    3. 사용자 정의 테마가 없거나 항목이 없는 경우 상위 컨트롤로 이동합니다.

    4. a~c 단계를 반복합니다. 트리의 루트에 도달하거나 비제어 노드에 도달할 때까지.

  3. 컨트롤의 유형 변형, 클래스 이름 및 상위 클래스 이름을 사용하여 프로젝트 전체 테마가 있는지 확인합니다.

  4. 컨트롤의 유형 변형, 클래스 이름 및 상위 클래스 이름을 사용하여 기본 테마를 확인합니다.

항목이 테마에 존재하지 않더라도 해당 데이터 유형에 해당하는 기본값이 반환됩니다.

통제를 넘어서

당연히 테마는 시각적인 구성을 저장하는 데 이상적인 리소스 유형입니다. 테마 지원은 제어 노드에 내장되어 있지만 다른 노드도 다른 리소스와 마찬가지로 이를 사용할 수 있습니다.

컨트롤 범위를 넘어서는 테마를 사용하는 예로는 전략 게임에서 서로 다른 팀의 동일한 유닛에 대한 스프라이트 변조를 들 수 있습니다. 테마 리소스는 색상 컬렉션을 정의할 수 있으며 스프라이트(스크립트의 도움을 받아)는 해당 색상을 사용하여 텍스처를 그릴 수 있습니다. 가장 큰 이점은 레드, 블루, 그린 팀에 대해 동일한 테마 항목을 사용하여 서로 다른 테마를 만들고 단일 리소스 변경으로 교체할 수 있다는 것입니다.