아바타를 UI에서 표현하기

# 학습 과정 소개

AvatarGUIRendererComponent를 활용하면 UI에 캐릭터 정보를 보여줄 수 있습니다. 본 과정을 통해 AvatarGUIRendererComponent 활용 방법을 알아봅시다.

##### 참고 가이드

[아바타 애니메이션 제어하기](docs/?postId=820)

##### 참고 API Reference

[AvatarGUIRendererComponent](/apiReference/Components/AvatarGUIRendererComponent)

#### AvatarGUIRendererComponent 프로퍼티

AvatarGUIRendererComponent의 주요 프로퍼티를 살펴봅시다.

[{"프로퍼티":"Color","설명":"색상을 조절합니다."},{"프로퍼티":"FlipX","설명":"X축을 기준으로 반전 여부를 결정합니다."},{"프로퍼티":"FlipY","설명":"Y축을 기준으로 반전 여부를 결정합니다."},{"프로퍼티":"PlayRate","설명":"아바타 애니메이션 재생 속도를 지정할 수 있습니다.  0 이상의 값을 지원하며 숫자가 클수록 속도가 빨라집니다."},{"프로퍼티":"PreserveAvatar","설명":"None: 원본 비율과 관계없이 자유롭게 크기를 조절합니다. AspectOnly: 원본 비율을 유지하며 크기를 조절합니다. NativeSize: 원본 크기를 유지합니다."},{"프로퍼티":"RaycastTarget","설명":"true로 설정할 경우 화면 터치 또는 마우스 클릭 대상이 됩니다. AvatarGUIRendererComponent 뒤에 가려진 UI는 화면 터치와 마우스 클릭 입력을 받지 못합니다."}]

# 예제

AvatarGUIRendererComponent의 프로퍼티를 조절하거나 함수를 활용하여 UI에 보이는 아바타의 모습을 변경해 봅시다

#### UI에서 아바타 보여주기

간단하게 UI에서 아바타를 보여주는 방법을 살펴봅시다.

  1. UI 에디터를 연 뒤, [이미지] 버튼을 눌러 엔티티를 추가합니다. 본 예제에서는 DefaultGroup에 추가하겠습니다. [png](16734983895969a0457ac51754fd2923c7d97e8360a34)

  2. 추가한 이미지 엔티티의 이름을 MyInfoWindow로 변경하고 ImageRUID에 아래 내용을 입력합니다. 이후 RectSize에 적당한 값을 입력합니다.

     * ImageRUID : 8122dd6f67f3d9b4db8a3152172f9063
     * RectSize : X = 350, Y : 460
  3. Hierarchy에서 콘텍스트 메뉴를 열고 Create Entity - Create UIEmpty를 클릭해서 UIEmpty를 만듭니다.

  4. UIEmpty의 이름을 MyInfo로 변경하고 프로퍼티 에디터에서 CostumeManagerComponent와 AvatarGUIRendererComponent를 추가합니다. [png](16747841322955b99b98e5ecc4c569cf74afef544d15b)

  5. RectSize에 적당한 값을 입력합니다. 그리고 MyInfoWindow 위의 적당한 곳에 위치를 잡아줍니다.

     * RectSize : X = 270, Y : 400 [png](16747852539050f91bb139c244f2190199e8436edaf5c)
  6. Hierarchy에서 MyInfo의 위치를 MyInfoWindow 하위로 옮깁니다. [png](16734988019776451e912fdc64b22947bb1f22db571c0)




#### UI 아바타 옷 변경하기

특정 오브젝트에 부딪히면 캐릭터의 옷이 바뀌고, UI에 보이는 아바타 옷도 바뀌는 예제를 살펴보겠습니다.

  1. Preset List에서 아무 오브젝트나 배치한 뒤, SpriteRUID에 아래의 값을 입력합니다. 그리고 오브젝트의 이름을 Pinkbean으로 변경합니다.

     * SpriteRUID : 5a81ed24c1354d08b38f8db4b497b607 [png](1673503382686e463830b58984fe0a02931f0950220a3)
  2. BaseEnvironment - NativeScripts - Component - TriggerComponent의 콘텍스트 메뉴에서 Extend를 클릭합니다.

  3. 확장한 스크립트 컴포넌트의 이름을 ChangeUIAvatar으로 변경합니다.

  4. 위에서 배치한 오브젝트인 Pinkbean에 ChangeUIAvatar 컴포넌트를 추가합니다.

  5. ChangeUIAvatar 스크립트를 열고 아래와 같이 프로퍼티를 추가합니다.
         
         @Component
         script OutfitChanger extends Component
         property Entity myInfo = "/ui/DefaultGroup/MyInfoWindow/MyInfo"
         property string changeCap = "1e6e49a6ecf94cc6872926598dcf179c"
         property string changeLongcoat = "22ab95fb9c3c4539b04d6a540f464e79"
         property string changeOHWeapon = "bbe63d40682c4f8ebcdbc22e7d92a5eb"
         end
         



    
    
       
    6. **Overridable Function**에서 `OnEnterTriggerBody()` 함수를 추가하고 아래와 같이 작성합니다.
        ```lua
    @Component
    script TriggerEquipmentChanger extends Component
        override method void OnEnterTriggerBody(TriggerEnterEvent enterEvent)
        __base:OnEnterTriggerBody(enterEvent)
    
        -- 오브젝트와 충돌한 대상(플레이어)를 받아옴
        local player = enterEvent.TriggerBodyEntity
    
        -- 오브젝트와 충돌한 대상에게 AvatarRendererComponent가 없으면 의상 변경 되지 않음
        local costumeManager = player.CostumeManagerComponent
        if costumeManager == nil then
            return
        end
    
        -- 내 캐릭터 장비 변경
        costumeManager.CustomCapEquip = self.changeCap
        costumeManager.CustomLongcoatEquip = self.changeLongcoat
        costumeManager.CustomOneHandedWeaponEquip = self.changeOHWeapon
    
        if self:IsServer() then 
            return 
        end
    
        -- UI 아바타 장비 변경
        local myInfo = self.myInfo
        local myInfoCostumeManager = myInfo.CostumeManagerComponent
    
        myInfoCostumeManager.CustomCapEquip = self.changeCap
        myInfoCostumeManager.CustomLongcoatEquip = self.changeLongcoat
        myInfoCostumeManager.CustomOneHandedWeaponEquip = self.changeOHWeapon
        end
    end
    
    
    
    

  7.  [시작] 버튼을 누른 뒤 테스트해 봅시다. 핑크빈 오브젝트에 캐릭터가 닿으면 캐릭터의 의상과 UI 아바타의 의상이 모두 변경되는 것을 확인합니다. [gif](16735057387005fe75284eb82440fa0f179c088110d32)



#### 아바타 색상 변경

스크립트로 AvatarGUIRendererComponent의 Color 프로퍼티를 변경해봅시다. 버튼을 누르면 UI에 보이는 아바타의 색상 값이 랜덤하게 변경되는 예제를 살펴보겠습니다.

  1. UI 에디터에서 버튼을 추가한 뒤 이름을 SetColorBtn으로 입력합니다. [png](1673836836089d930239e5f034b8785e475aa09296d7c)

  2. SetColorBtn에 TextComponent를 추가하고 프로퍼티를 아래와 같이 수정합니다.

[{"컴포넌트":"TextComponent","프로퍼티":"Text","값":"SetColor"},{"컴포넌트":"TextComponent","프로퍼티":"FontColor","값":"#FFFFFF"}]

  3. ChangeUIAvatar 스크립트 컴포넌트에 `SetColor()` 함수를 추가하고 아래와 같이 작성합니다. 실행 공간은 client only로 설정합니다.
         
         @Component
         script AvatarColorRandomizer extends Component
         @ExecSpace("ClientOnly")
         method void SetColor()
         local r = _UtilLogic:RandomDouble()
         local g = _UtilLogic:RandomDouble()
         local b = _UtilLogic:RandomDouble()
         local a = _UtilLogic:RandomDouble()
         self.myInfo.AvatarGUIRendererComponent.Color = Color(r,g,b,a)
         end
         end
         



    
    
        
    4. 새로 **TestUIBtn** 스크립트 컴포넌트를 생성합니다. 
        그리고 **SetColorBtn**에 **TestUIBtn** 컴포넌트를 추가합니다.
        
    5. **TestUIBtn** 스크립트를 열고 아래와 같이 프로퍼티를 추가합니다.
        ```lua
    @Component
    script UIAvatarChanger extends Component
        property any changeUIAvatar = "/maps/map01/Pinkbean"
    end
    
    
    
    > **Tip.**
    > 프로퍼티 타입을 ChangeUIAvatar로 설정하려면, 프로퍼티 타입에서 Component를 클릭한 뒤 ChangeUIAvatar 컴포넌트를 검색해서 추가하면 됩니다.
    

  6. TestUIBtn 스크립트의 이벤트 핸들러에 ButtonClickEvent를 추가하고 아래와 같이 작성합니다. 
         
         @Component
         script AvatarColorButtonHandler extends Component
         @EventSender("Self")
         handler HandleButtonClickEvent(ButtonClickEvent event)
         --Parameters
         local Entity = event.Entity
         --------------------------------
         local name = Entity.Name
         local changeUIAvatar = self.changeUIAvatar
         
         --Property
         if name == "SetColorBtn" then
          changeUIAvatar:SetColor()
         end
         end
         end
         



    
    
        
    7.  **[시작]** 버튼을 누른 뒤 테스트해 봅시다. 
        **[SetColor]** 버튼을 누를 때마다 UI 아바타의 색상 값이 변경됩니다.
        [gif](1673935701110863dae7d69624a3bb8f1f747cd007fbf)
    
    #### 파츠 색상 변경
    버튼을 누르면 UI에 보이는 아바타 파츠 색상 값이 랜덤하게 변경되는 예제입니다.
    
    1. **SetColorBtn** 버튼의 콘텍스트 메뉴에서 **Duplicate**를 클릭해 복제합니다.
        
    2. 버튼의 위치를 적당히 옮기고 이름을 **SetPartColorBtn**으로 변경합니다.
        
    3. **SetPartColorBtn - TextComponent - Text** 프로퍼티에 **SetPartColor**를 입력합니다.
        
    4. **ChangeUIAvatar** 스크립트 컴포넌트에 `SetPartColor()` 함수를 추가하고 아래와 같이 작성합니다. 실행 공간은 **client only**로 설정합니다.
        ```lua
    @Component
    script AvatarPartColorRandomizer extends Component
        @ExecSpace("ClientOnly")
        method void SetPartColor()
        local parts = 
        {
        	MapleAvatarItemCategory.Body,
        	MapleAvatarItemCategory.Cap,
        	MapleAvatarItemCategory.Cape,
        	MapleAvatarItemCategory.Coat,
        	MapleAvatarItemCategory.Ear,
        	MapleAvatarItemCategory.EarAccessory,
        	MapleAvatarItemCategory.EyeAccessory,
        	MapleAvatarItemCategory.Face,
        	MapleAvatarItemCategory.FaceAccessory,
        	MapleAvatarItemCategory.Glove,
        	MapleAvatarItemCategory.Hair,
        	MapleAvatarItemCategory.Head,
        	MapleAvatarItemCategory.Longcoat,
        	MapleAvatarItemCategory.OneHandedWeapon,
        	MapleAvatarItemCategory.Pants,
        	MapleAvatarItemCategory.Shoes,
        	MapleAvatarItemCategory.SubWeapon,
        	MapleAvatarItemCategory.TwoHandedWeapon
        }
    
        local r = _UtilLogic:RandomDouble()
        local g = _UtilLogic:RandomDouble()
        local b = _UtilLogic:RandomDouble()
        local a = _UtilLogic:RandomDouble()
    
        local index = _UtilLogic:RandomIntegerRange(1,18)
    
        self.myInfo.AvatarGUIRendererComponent:SetAvatarPartColor(parts[index], r, g, b, a)
        end
    end
    
    
    
    

  5. TestUIBtn 스크립트의 ButtonClickEvent에 아래 내용을 추가합니다. 
         
         @Component
         script AvatarColorController extends Component
         @EventSender("Self")
         handler HandleButtonClickEvent(ButtonClickEvent event)
         --Parameters
         local Entity = event.Entity
         --------------------------------
         local name = Entity.Name
         local changeUIAvatar = self.changeUIAvatar
         
         --Property
         if name == "SetColorBtn" then
          changeUIAvatar:SetColor()
         -- 아래 내용 추가
         elseif name == "SetPartColorBtn" then
             changeUIAvatar:SetPartColor()
         end
         end
         end
         



    
    
        
    6.  **[시작]** 버튼을 누른 뒤 테스트해 봅시다. 
        **[SetPartColorBtn]** 버튼을 누를 때마다 UI 아바타 랜덤 파츠의 색상 값이 변경됩니다.
        [gif](167393592286102105ba6e40f42b099350d3a70dfb1f4)
    
    #### 감정 표현 변경
    버튼을 누르면 UI에 보이는 아바타 감정 표현이 랜덤하게 변경되는 예제입니다.
    
    1. **SetColorBtn** 버튼의 콘텍스트 메뉴에서 **Duplicate**를 클릭해 복제합니다.
        
    2. 버튼의 위치를 적당히 옮기고 이름을 **SetEmotionBtn**으로 변경합니다.
        
    3. **SetEmotionBtn - TextComponent - Text** 프로퍼티에 **SetEmotion**을 입력합니다.
        
    4. **ChangeUIAvatar** 스크립트 컴포넌트에 `SetEmotion()` 함수를 추가하고 아래와 같이 작성합니다. 실행 공간은 **client only**로 설정합니다.
        ```lua
    @Component
    script RandomEmotionPlayer extends Component
        @ExecSpace("ClientOnly")
        method void SetEmotion()
        local emotions = 
        {
        	EmotionalType.Hit,
        	EmotionalType.Smile,
        	EmotionalType.Troubled,
        	EmotionalType.Cry,
        	EmotionalType.Angry,
        	EmotionalType.Bewildered,
        	EmotionalType.Stunned,
        	EmotionalType.Vomit,
        	EmotionalType.Oops,
        	EmotionalType.Cheers,
        	EmotionalType.Chu,
        	EmotionalType.Wink,
        	EmotionalType.Pain,
        	EmotionalType.Glitter,
        	EmotionalType.Despair,
        	EmotionalType.Love,
        	EmotionalType.Shine,
        	EmotionalType.Blaze,
        	EmotionalType.Hum,
        	EmotionalType.Bowing,
        	EmotionalType.Hot,
        	EmotionalType.Dam,
        	EmotionalType.qBlue
        }
    
        local index = _UtilLogic:RandomIntegerRange(1, 23)
        self.myInfo.AvatarGUIRendererComponent:PlayEmotion(emotions[index], 3)
        end
    end
    
    
    
    

  5. TestUIBtn 스크립트의 ButtonClickEvent에 아래 내용을 추가합니다. 
         
         @Component
         script AvatarCustomizationHandler extends Component
         @EventSender("Self")
         handler HandleButtonClickEvent(ButtonClickEvent event)
            --Parameters
            local Entity = event.Entity
            --------------------------------
            local name = Entity.Name
            local changeUIAvatar = self.changeUIAvatar
         
            --Property
            if name == "SetColorBtn" then
             changeUIAvatar:SetColor()
         elseif name == "SetPartColorBtn" then
             changeUIAvatar:SetPartColor()
            -- 아래 내용 추가
            elseif name == "SetEmotionBtn" then
             changeUIAvatar:SetEmotion()
            end
         end
         end
         



    
    
        
    6.  **[시작]** 버튼을 누른 뒤 테스트해 봅시다. 
        **[SetEmotion]** 버튼을 누를 때마다 UI 아바타 감정 표현이 변경됩니다.
        [gif](16739360881637f9ea067d7444efd8b7148aafc5cb01c)