Unity MCP로 AI Studio HUD를 건강 이벤트에 연결하기

HUD가 Unity에 있고, 바가 제대로 보이지만 전투가 이를 움직이지 않는다면, 보통 프리팹은 문제가 없고 UI와 게임플레이가 동일한 건강 이벤트를 공유하지 않기 때문입니다. 디자인은 이미 VberAI Studio에서 메인 HUD를 Canvas / Prefab으로 내보냈습니다. 게임플레이에서는 열린 프로젝트에서 Unity MCP를 사용하여 PlayerHealth 변경 사항을 Slider / Image.fillAmount에 연결한 다음 Play 모드에서 확인해야 합니다.

이 글은 해당 연결만 다룹니다—Figma 내보내기나 MCP 설치는 다루지 않습니다.

단계	도구	결과
HUD 구조를 엔진으로	AI Studio	안정적인 이름을 가진 HUD 프리팹
스크립트 연결, 참조 바인딩, 씬 편집	Cursor (또는 Claude Code) + Unity MCP	PlayerHealth ↔ HudHealthView
수락	Unity Play	데미지/힐 시 바 길이 변경

관련 자료:

• Figma to Unity UI (AI Studio)
• Unity MCP 설치
• Unity MCP with Claude Code and Cursor

폴리싱 전에 이름 합의

AI Studio 내보내기 후, 코드는 경로 또는 직렬화된 참조를 통해 바를 찾아야 합니다. 내보내기 전(또는 가져온 직후)에 이름을 안정적으로 유지하세요:

역할	제안 이름	참고
HUD 루트	HUD_Root	씬에서 고유
건강 채움	HUD_HealthFill	Image (Filled) 또는 Slider.fillRect 아래
선택적 값 텍스트	HUD_HealthText	TextMeshProUGUI, 예: 80/100
선택적 데미지 플래시	HUD_DamageFlash	전체 화면 또는 테두리 Image, 기본 투명

Rectangle 42 또는 Group 3 같은 디자인 기본값을 피하세요—MCP와 수동 스크립트 모두 그 혼란을 물려받게 됩니다.

1단계: HUD가 씬에 있는지 확인

1. 플레이어 씬(예: Game)을 엽니다
2. Hierarchy에 HUD_Root(또는 이에 상응하는 것)가 건강 Image / Slider와 함께 있어야 합니다
3. Canvas Render Mode와 카메라 설정이 올바른지 확인합니다 (Screen Space - Overlay가 가장 간단)

MCP를 통한 읽기 전용 스모크 테스트(씬을 편집하지 않음):

활성 씬에서 이름에 HUD가 포함된 GameObject를 나열하고, 해당 GameObject의 UI 컴포넌트 유형을 나열하세요. 아무것도 수정하지 마세요.

목록이 비어 있으면: AI Studio에서 다시 내보내기/동기화하거나, 프리팹이 잘못된 씬에 드롭되었는지 확인하세요.

2단계: 게임플레이가 건강 변경을 노출—UI를 Find하지 마세요

건강을 플레이어에 유지하고 C# 이벤트(또는 UnityEvent)로 브로드캐스트하세요. HUD는 구독만 하며, Find("Player")를 통해 로직을 구동해서는 안 됩니다.

Cursor에서 Unity MCP에 요청하세요 (경로는 프로젝트에 맞게 조정 가능):

Assets/Scripts/Combat/PlayerHealth.cs 생성:
- maxHealth, currentHealth (float)
- event Action<float,float> OnHealthChanged(current, max)
- TakeDamage(float), Heal(float); 0..max로 클램프
- 데미지 후 current<=0이면 OnHealthChanged를 다시 발생시키고 선택적으로 OnDied 발생
- 씬의 Player에 연결; Start에서 한 번 브로드캐스트
HUD 노드를 수정하지 마세요.

참조 구현 (생성 후 검토):

using System;
using UnityEngine;

public class PlayerHealth : MonoBehaviour
{
    [SerializeField] float maxHealth = 100f;
    float currentHealth;

    public event Action<float, float> OnHealthChanged;
    public event Action OnDied;

    void Awake() => currentHealth = maxHealth;

    void Start() => OnHealthChanged?.Invoke(currentHealth, maxHealth);

    public void TakeDamage(float amount)
    {
        if (amount <= 0f || currentHealth <= 0f) return;
        currentHealth = Mathf.Max(0f, currentHealth - amount);
        OnHealthChanged?.Invoke(currentHealth, maxHealth);
        if (currentHealth <= 0f) OnDied?.Invoke();
    }

    public void Heal(float amount)
    {
        if (amount <= 0f || currentHealth <= 0f) return;
        currentHealth = Mathf.Min(maxHealth, currentHealth + amount);
        OnHealthChanged?.Invoke(currentHealth, maxHealth);
    }
}

연결용 임시 데미지 키 (나중에 삭제):

Player에 임시 DebugDealDamage.cs 추가: H 키를 누르면 같은 오브젝트의 PlayerHealth에 10 데미지를 줍니다. 연결 수락 전용입니다.

3단계: HUD 뷰는 듣고 바만 업데이트

직렬화된 참조를 가진 뷰 스크립트를 추가하세요. Update에서 매 프레임 GameObject.Find를 사용하지 마세요.

Assets/Scripts/UI/HudHealthView.cs 생성:
- Serialize Image healthFill (Filled, Horizontal)
- 선택적 TMP_Text healthText
- Serialize PlayerHealth playerHealth (또는 Awake에서 유일한 PlayerHealth 해결)
- OnEnable에서 OnHealthChanged 구독; OnDisable에서 구독 해제
- 콜백에서: healthFill.fillAmount = current/max; 텍스트 $"{current:0}/{max:0}"
- HUD_Root에 연결; HUD_HealthFill Image를 healthFill에 할당
- Player의 PlayerHealth를 playerHealth에 할당

참조:

using TMPro;
using UnityEngine;
using UnityEngine.UI;

public class HudHealthView : MonoBehaviour
{
    [SerializeField] PlayerHealth playerHealth;
    [SerializeField] Image healthFill;
    [SerializeField] TMP_Text healthText;

    void OnEnable()
    {
        if (playerHealth == null) return;
        playerHealth.OnHealthChanged += HandleHealthChanged;
        // Start 이후에 구독하면 한 번 당겨옵니다; 여기서는 PlayerHealth.Start에 의존합니다.
    }

    void OnDisable()
    {
        if (playerHealth == null) return;
        playerHealth.OnHealthChanged -= HandleHealthChanged;
    }

    void HandleHealthChanged(float current, float max)
    {
        float t = max > 0f ? current / max : 0f;
        if (healthFill != null) healthFill.fillAmount = t;
        if (healthText != null) healthText.text = $"{Mathf.CeilToInt(current)}/{Mathf.CeilToInt(max)}";
    }
}

Image가 Filled가 아닌 경우: MCP에 Image Type = Filled, Fill Method = Horizontal로 설정하도록 한 다음 fillAmount를 바인딩하세요. Slider를 사용하는 경우 slider.value = t (minValue=0, maxValue=1)로 작성하세요—동일한 패턴입니다.

4단계: Unity MCP가 직렬화된 참조를 채우도록 하기

컴파일 후 Cursor에서 명시적으로 지시하세요:

활성 씬에서:
1. Player에 PlayerHealth가 있고, HUD_Root에 HudHealthView가 있는지 확인
2. HudHealthView.healthFill을 HUD_HealthFill이라는 Image에 연결
3. HudHealthView.playerHealth를 Player의 PlayerHealth에 연결
4. HUD_HealthText가 있으면 TMP_Text 할당
5. 씬 저장
그런 다음 해당 두 컴포넌트에 남아 있는 None 직렬화 필드를 나열하세요.

읽기 전용 확인:

HudHealthView와 PlayerHealth 참조를 검사: 누락된 스크립트나 None 필드가 있나요? 보고만 하고 씬을 편집하지 마세요.

5단계: Play 수락 체크리스트

Play에 들어가서 연결이 완료되었다고 판단하기 전에 다음을 모두 체크하세요:

1. 진입 시: 바가 가득 차 있거나 current/max와 일치해야 하며, 비어 있거나 오래된 상태가 아니어야 함
2. H 키 누름 (또는 플레이어 공격): fillAmount가 감소; 텍스트가 있으면 업데이트
3. 데미지로 0 도달: 바가 비어 있음; 사망 상태가 안정적; HUD가 흔들리지 않음
4. 힐: 바가 상승 (임시 키 또는 픽업)
5. Play 종료 후 재진입: 참조가 여전히 유효; Missing Script 없음

수락 프롬프트:

Play 모드에서 HUD 연결을 수락합니다. Console에 NullReferenceException이 표시되면 PlayerHealth인지 HudHealthView인지, 어떤 직렬화 필드가 None인지 말하세요. 먼저 진단하고 최소 수정을 제안하며, 편집 전에 내 승인을 기다리세요.

일반적인 문제 지점

증상	먼저 확인할 것
Play에서 바가 전혀 움직이지 않음	OnHealthChanged가 구독되지 않았거나; 데미지가 TakeDamage에 도달하지 않음
Play 진입 시 NRE	healthFill / playerHealth가 여전히 None
바가 반전되거나 점프	Image가 Filled가 아님; 잘못된 Rect가 채움으로 사용됨
텍스트가 고정됨	잘못된 TMP; 컴포넌트에 폰트 에셋 누락 오류
AI가 잘못된 오브젝트를 편집	프롬프트: “HUD_Root / Player만 건드리고, 레벨 지오메트리를 움직이지 마세요”

규칙: 게임플레이가 건강을 변경하고, UI는 듣기만 합니다. PlayerCombat 내부에서 Find("HUD_HealthFill")를 사용하지 마세요—다음 AI Studio 재내보내기에서 이름이 바뀌면 전투도 깨집니다.

HUD 재내보내기와 함께 살아가기

디자인이 AI Studio에서 재내보낼 때:

1. 가능하면 HUD_HealthFill / HUD_Root 이름을 유지하세요
2. 재가져온 후 4단계 참조 확인만 다시 실행하세요—MCP가 PlayerHealth를 다시 작성하게 하지 마세요
3. 뷰 스크립트를 프로젝트에 유지하고, Prefab 변형 참조가 지워진 경우 다시 바인딩하세요

한 줄 경계 프롬프트:

이번 패스는 손실된 UI Prefab 참조만 수정합니다. Assets/Scripts/Combat 아래의 게임플레이 스크립트를 변경하지 마세요.

요약

1. AI Studio가 HUD 구조를 Unity로 전달
2. PlayerHealth가 (current, max)를 브로드캐스트
3. HudHealthView가 구독하고 fillAmount / 텍스트 업데이트
4. Unity MCP가 컴포넌트 연결, 직렬화된 참조 채움, 최소한의 Console 수정 적용
5. 데미지 키 + Play 체크리스트로 수락—“스크립트 생성 성공”이 아님

이것으로 반복 가능한 루프가 닫힙니다: UI를 엔진으로 → 이벤트 연결 → Play 수락. 가방, 마나 바, 보스 바도 동일한 패턴을 복사할 수 있습니다.