gohud 설치

가장 빠른 길 — AI 에게 설치를 맡긴다

아래 글을 그대로 Claude Code·Codex·Cursor·Gemini CLI 에 붙여 넣으면 스킬과 애드온을 함께 설치하고 gohud 를 설명까지 해 준다. 그 길로 가면 이 카드 아래의 것은 하나도 필요 없다.

AI SKILL 페이지 열기 →

설치

애드온 폴더를 프로젝트에 넣기만 하면 된다.

배포 ZIP 또는 애셋 스토어

프로젝트 루트에 풀어 res://addons/gohud/ 가 되게 한다. 그것이 전부다. 필요하면 프로젝트 → 프로젝트 설정 → 플러그인 → gohud 를 켠다.

git submodule 로

git submodule add https://github.com/thruthesky/gohud.git addons/gohud
git submodule update --init
git -C addons/gohud checkout v1.0.0   # 선택: 태그나 커밋에 고정

저장소 루트가 곧 애드온 폴더라 Godot 이 기대하는 자리에 그대로 떨어진다. 그 자리에서 고치고 addons/gohud 안에서 커밋·push 한 뒤, 게임 저장소에서 서브모듈 포인터를 커밋한다.

Godot 4.6 이상이 필요하다. DPITexture·FoldableContainer·접근성 속성처럼 4.5 에서 들어온 API 를 쓰기 때문에 그보다 낮은 엔진에서는 파싱 단계에서 죽는다. 지원 하한 4.6 은 GoUi.MIN_ENGINE 에 적혀 있다.

빠른 시작

전부 .new() 로 만들어 add_child() 하면 된다. 씬 파일도, 오토로드도 필요 없다.

UI 를 만들기 전에 생김새를 고른다(선택)

GoUi.use_preset(GoThemePresets.SCIFI_DARK)   # 고르지 않으면 default_dark

확인창을 `await` 로 받는다

var dialogs := GoDialogs.new()
add_child(dialogs)
if await dialogs.confirm("저장 삭제", "되돌릴 수 없습니다."):
    delete_save()

마지막 인자 destructive 를 true 로 주면 확인 버튼이 채워진 위험 버튼으로 그려진다.

검색 칸과 바닥 버튼이 고정된 바텀 시트

var sheet := GoSheet.new()
add_child(sheet)
sheet.open("인벤토리")
sheet.toolbar().add_child(GoStyle.line_edit("검색…"))
sheet.toolbar().visible = true
for item in items:
    sheet.body.add_child(GoStyle.list_button(GoIconSet.BOX, item.name, _use.bind(item),
        Color.TRANSPARENT, item.description, false))
sheet.footer().add_child(GoStyle.button("닫기", sheet.close, GoStyle.Tone.PRIMARY))
sheet.footer().visible = true

고정 줄과 스크롤 본문을 나누는 이유. 확인·취소를 body 에 넣으면 목록이 길어질 때 화면 밖으로 밀린다. footer() 는 언제나 보인다.

HUD 모서리에 체력 막대

var corner := GoHudAnchor.new()
corner.spot = GoHudAnchor.Spot.TOP_LEFT
corner.landscape_spot = GoHudAnchor.Spot.TOP_RIGHT   # 가로에서는 다른 자리로
add_child(corner)

var hp := GoBar.new()
hp.label_text = "HP"
hp.ink = GoUi.color(GoTheme.DANGER_FILL)             # 채움 전용 토큰
corner.add_child(hp)
hp.set_values(320, 500)

본문이 HUD 를 비켜 가게

form.avoid_hud = true                  # 보이는 GoHudAnchor 를 모두 피한다
joystick_anchor.reserve_space = false  # 손을 얹을 때만 나타나는 것은 빼고
notice_anchor.avoid_peers = true       # 알림은 고정 HUD 를 덮지 않고 그 아래로 내려앉는다

칸마다 잃는 면적이 가장 작은 방향으로 피한다 — 세로 화면에서는 아래로, 가로 화면에서는 옆으로. HUD 가 서로 비키는 방식 →

실행해 볼 수 있는 예제

코드를 쓰기 전에 gohud 를 보는 세 가지 방법 — 어느 것도 서버나 오토로드가 필요 없다.

예제	여는 법	보여 주는 것
갤러리	`examples/gallery/gallery.tscn` · F6	모든 위젯, 설치된 프리셋 전부를 고르는 선택기, 아이콘 전체
중세	`examples/medieval/medieval.tscn` · F6	캐릭터 정보·인벤토리·퀘스트 일지. 버튼으로 철·양피지를 바꾸고 아이템 설명을 연다
데모 앱	`cd examples/demo && godot`	갤러리·19장면 자동 시연·쇼케이스·중세 화면을 한 창에서 고르는 홈 화면. 만져 보는 위젯 카드와 클래스별 한 줄 소개가 함께 있다

cd examples/demo && godot                             # 홈 화면. 첫 실행에서 링크와 임포트를 스스로 한다
bash examples/demo/run.sh                               # 애드온 루트에서 같은 앱을 연다
bash examples/demo/run.sh -- --open=gallery             # 홈을 건너뛰고 바로 그 화면으로
bash examples/demo/run.sh -- --explore=surfaces         # 위젯 하나를 탐색 모드로 바로 연다
bash examples/demo/run.sh --record /tmp/gohud-demo.avi  # 전체 시연 1080p / 60fps 녹화

데모 앱은 준비할 것이 없다. 애드온 링크나 임포트 캐시가 없으면 그 사실을 화면에 적고, 폴더를 고치고, 창을 스스로 다시 연다. 홈 화면은 예제를 같은 창 안에서 연다 — 1~4 를 누르거나 줄을 누르고, 위쪽 줄로 돌아온다.

자동 시연에서 C 는 촬영 모드, F11 은 전체 화면, Space 는 일시정지(탐색 중에는 현재 위젯 시연), 화살표는 장면 이동, Esc 는 시작 화면이다.

AI 코딩 에이전트를 쓴다면 세 가지 모두 명령 한 줄로 열 수 있다 →