gohud

Giao diện game, chạy bằng một tài nguyên duy nhất

gohud là bộ HUD và UI cho Godot 4.6 trở lên. Cửa sổ nổi, bảng trượt dưới, hộp thoại, biểu mẫu, snackbar, coach mark, thanh HUD, ô nhanh và cần điều khiển ảo đều chạy từ một theme và một bộ biểu tượng thay được, đồng thời tự lo vùng an toàn, bàn phím ảo, RTL và vùng chạm cho bạn. Sáu preset — mặc định, sci-fi và trung cổ, mỗi loại có bản tối và sáng — đổi màu sắc lẫn hình dáng trong một dòng.

Godot 4.6+ v1.0.1 GDScript thuần Không cần autoload MIT 6 preset 21 ngôn ngữ Kèm 100 biểu tượng

Trông thế nào khi vào game

Preset trung cổ và sci-fi — bảng nhân vật, túi đồ và nhiệm vụ; biểu mẫu, lưới và prompt card; tấm nền góc cạnh và điều khiển cảm ứng. Đổi preset chỉ tốn một dòng code.

Theme trung cổ của gohud — bảng nhân vật với thanh máu, mana và thể lực, một túi đựng các ô nhanh và sổ nhiệm vụ trong khung vàng rèn
Trung cổ — nhân vật, túi đồ và nhiệm vụ
Theme trung cổ của gohud — bảng nhập liệu với ô tên, công tắc, hộp kiểm và thanh trượt âm lượng, một lưới các ô, và prompt card mời vào tổ đội với Chấp nhận và Từ chối
Trung cổ — biểu mẫu, lưới và prompt card
Theme sci-fi của gohud — tấm điều khiển cảm ứng vát góc với cần điều khiển hình lục giác, công tắc Fixed / Follow / Relative và các nút hành động tròn
Sci-fi — tấm nền góc cạnh và điều khiển cảm ứng

Cả sáu preset và cách chuyển giữa chúng →

Những việc nó gánh thay bạn

Thứ ngốn nhiều thời gian nhất khi làm UI game không phải hình dáng của một cái nút — mà là tất cả những gì lệch dần giữa các thiết bị. gohud xử lý chỗ lệch đó ở một nơi duy nhất.

Mọi số đo đều là một token

Khoảng cách, góc bo và cỡ chữ được gọi theo tên chứ không viết thành số. Đổi theme là cả màn hình đổi theo.

Cỡ nhìn thấy ≠ cỡ bấm được

Nút đóng trông chỉ 36dp nhưng vùng chạm của nó là 48dp. Khi các ô chen nhau và vùng chạm chồng lên nhau, ô nào có tâm gần hơn sẽ nhận cú bấm.

Tai thỏ và bàn phím

Các mảnh HUD nằm gọn trong vùng an toàn, và ô nhập liệu tự nâng lên trên bàn phím ảo khi bàn phím hiện ra.

Back chỉ đóng một thứ

Phím Escape và nút Back của Android chỉ đóng lớp trên cùng. Các cửa sổ xếp chồng không biến mất cùng lúc.

Thông báo không cướp thao tác

Bấm xuyên qua một snackbar thì nút nằm dưới vẫn nhận được. Focus cũng không bị lấy mất.

Biểu tượng được gọi theo tên

Widget chỉ biết GoIconSet.CLOSE. Đổi bộ biểu tượng là mọi hình vẽ đổi theo mà không phải sửa một dòng code nào.

Sáu diện mạo, một dòng

GoUi.use_preset() đổi cùng lúc theme, skin và biểu tượng — khung bo tròn, khung vát góc kiểu sci-fi hay khung rèn kiểu trung cổ.

Dễ đọc là thứ đo được

Mọi theme đều được đối chiếu với WCAG, kể cả các trạng thái của nút và những tấm HUD bán trong suốt đặt trên nền trắng tinh lẫn đen tuyền.

Mọi thứ đều chạy mà không cần bật plugin. Bật lên thì có thêm autoload GoRuntime theo dõi kích thước cửa sổ, tỉ lệ dp và chiều cao bàn phím, cùng vài mục project setting cho tài nguyên cấu hình và preset — đó là tiện ích, không phải điều kiện bắt buộc.

Cài đặt gohud

Hai lối vào. Để tác nhân AI làm hộ, hoặc thả thư mục vào dự án — không còn gì phải cấu hình.

Cài đặt

Bắt đầu nhanh

Năm dòng là có một màn hình đã gắn theme. Toàn bộ các bước nằm ở trang cài đặt.

Bắt đầu nhanh

Đổi diện mạo — cả màu sắc lẫn hình dáng

Một Theme chỉ đổi được dáng vẻ của những gì engine tự vẽ. StyleBoxFlat chỉ có duy nhất một kiểu góc là bo tròn, còn cần điều khiển, ô nhanh và coach mark thì do code vẽ ra — nên riêng theme không bao giờ đổi được hình dáng của chúng. Vì vậy gohud kèm sẵn preset: một theme, một skin và một bộ biểu tượng chọn thành một khối.

GoUi.use_preset(GoThemePresets.MEDIEVAL_DARK)   # theme, skin và biểu tượng cùng lúc
PresetDiện mạo
default_darkgohud nguyên bản — góc bo tròn, màu nhấn xanh dịu
default_lightVẫn hình dáng đó trên bảng màu sáng
scifi_darkGóc vát, viền neon lam và ánh sáng tỏa, cần điều khiển hình lục giác, khung ngắm góc
scifi_lightVẫn hình dáng góc cạnh đó trong bảng màu bản vẽ kỹ thuật sáng
medieval_darkSắt tối và da thuộc, khung vàng cổ, đinh tán, biểu tượng khắc chìm, tiêu đề Cinzel
medieval_lightGiấy da, mực và đồng thau với vẫn những khung rèn đó
Màn hình gallery của gohud với preset default_dark — góc bo tròn, màu nhấn xanh
default_dark — góc bo tròn, màu nhấn xanh dịu
Preset default_light — vẫn hình dáng đó trên bảng màu sáng
default_light — cùng hình dáng, bảng màu sáng
Preset scifi_dark — góc vát và neon lam
scifi_dark — góc vát, neon lam
Preset scifi_light — vẫn hình dáng góc cạnh đó trong bảng màu bản vẽ kỹ thuật
scifi_light — cùng hình dáng góc cạnh, bảng màu bản vẽ

Bốn ảnh đó là cùng một màn hình gallery. Không khác nhau một dòng code nào — chỉ khác tên preset. Góc nút, hình công tắc, hàng danh sách và viền ô nhập đều đổi theo cùng lúc.

Bộ sưu tập trung cổ

medieval_dark ghép sắt và da thuộc với vàng cổ; medieval_light dùng giấy da và mực. Khung menu mang một chiếc đinh tán và một hoa văn góc nhỏ, còn HUD luôn hiện thì giữ nét trầm; 16 biểu tượng khắc chìm vẽ lại các món đồ, và chỉ tiêu đề với phụ đề mới dùng font Cinzel kèm theo.

medieval_dark — bảng nhân vật, túi đựng ô nhanh và sổ nhiệm vụ
medieval_dark — sắt và da thuộc
medieval_light — vẫn các màn hình nhân vật, túi đồ và nhiệm vụ đó trên nền giấy da
medieval_light — giấy da và mực

Cả hai ảnh đều là examples/medieval/medieval.tscn, dựng từ các widget tiêu chuẩn. Hướng dẫn trung cổ và cách tạo vương quốc của riêng bạn →

Cùng một màn hình trên điện thoại và trên máy để bàn

Các ảnh gallery là điện thoại ở chế độ dọc. Bên dưới là cùng đoạn code đó ở 1280×800 — nội dung dừng lại ở bề ngang dễ đọc (480dp) rồi canh giữa, còn HUD vẫn nằm ở các góc. Biểu mẫu bước tránh các mảnh HUD nổi, nhưng không nhúc nhích khi nó vốn đã không vướng: cứ đẩy bừa thì trên màn hình rộng nội dung sẽ lệch khỏi tâm.

default_dark ở 1280x800 — nội dung canh giữa, HUD ở các góc
default_dark · 1280×800
scifi_dark ở 1280x800 — cùng bố cục với tấm nền vát góc và neon
scifi_dark · 1280×800

Cùng một bảng trượt, khác diện mạo

Một bảng trượt dưới ở default_dark
Mặc định — thẻ bo tròn, hàng tìm kiếm và chân trang cố định
Một bảng trượt dưới ở scifi_dark — viền nhấn neon chạy dọc mép trên
Sci-fi — viền nhấn ở mép trên, góc cắt, ánh sáng tỏa

Chọn một preset trong Project Settings → gohud → Theme → Preset, hoặc đặt GoConfig.preset. Điền thẳng theme, skin hay icons thì giá trị đó thắng preset, nên bạn có thể lấy một preset rồi ghi đè đúng một phần của nó.

Một theme mới chỉ là một file JSON. new_theme.py kingdom --from medieval_dark ghi ra một bảng màu liệt kê rõ từng giá trị kế thừa; make_theme.py kingdom dựng theme, phần hình vẽ cho các control và các núm chỉnh của skin, rồi preset hiện ra trong danh sách chọn. Mọi thiết lập và núm chỉnh →

Skin — nơi Theme không với tới

Skin nắm cần điều khiển, mặt các ô nhanh, vòng coach mark, chip, skeleton, alert, đường kẻ chia và tiêu đề mục. Kế thừa nó rồi chỉ ghi đè đúng phần bạn muốn đổi.

class_name MySkin extends GoSkin

func slot_box(accent: Color, lit: bool) -> StyleBox:
    var box := GoStyleBoxCut.new()
    box.bg_color = accent
    box.cut = 6.0
    box.edge_color = accent
    return box
LớpHình dáng nó tạo ra được
GoStyleBoxCutGóc cắt chéo (vát), một cạnh nhấn dày lên, ánh sáng tỏa ra ngoài
GoStyleBoxBracketChỉ dấu ở bốn góc, không bao kín nội dung
GoStyleBoxMedievalKhung rèn với đinh tán, hoa văn khắc ở góc, vệt sáng vát cạnh và vân vật liệu

Cả ba đều tuần tự hóa được vào một tài nguyên Theme — chính điều đó cho phép một theme đổi hình dáng, chứ không chỉ đổi màu. GoSkinSciFiGoSkinMedieval là hai lớp con có sẵn.

GoStyle.box() luôn trả về một StyleBoxFlat, vì phía gọi nhận nó rồi chỉnh bg_color hoặc corner_radius. Hãy dùng GoStyle.surface() khi cần giữ nguyên một hình dáng tùy biến.

Widget

Toàn bộ các mảnh, gói trong một bảng. Chi tiết từng cái →

LớpLớp chaLàm gì
GoSurfaceControlVỏ thẻ nổi — đặt ở giữa, ở đáy hoặc neo vào một control, đầu và chân trang cố định, thân cuộn được, kéo để đổi kích thước
GoSheetCanvasLayerTrang trồi lên từ đáy, nằm trên lớp riêng nên luôn ở trên HUD
GoDialogsNodeHộp thoại xác nhận và cảnh báo mà bạn await; destructive cho các thao tác không thể hoàn tác
GoFormMarginContainerBiểu mẫu giới hạn bề ngang, tránh bàn phím ảo và, với avoid_hud, tránh cả HUD
GoScrollScrollContainerCuộn bằng ngón tay; thanh cuộn nép vào phần đệm sẵn có của thẻ
GoNoticePanelContainerSnackbar không nhận thao tác cũng không nhận focus
GoPromptCardPanelContainerMột câu hỏi không chặn game lại
GoCoachMarkControlChuyến tham quan có hướng dẫn chỉ vào các control thật; bấm đúng mục tiêu là sang bước kế
GoHudAnchorControlGhim các mảnh HUD vào một trong chín vị trí trong vùng an toàn
GoBarControlThanh máu, mana và kinh nghiệm với chuyển động mượt
GoSlotButtonMột ô nhanh — biểu tượng, số lượng, hồi chiêu và phím tắt trên cùng một mặt
GoJoystickControlCần điều khiển ảo ở chế độ cố định, đi theo hoặc tương đối
GoIconButtonButtonTrông nhỏ, bấm rộng
GoStylestaticNút, hàng danh sách, ô nhập, chip, bảng, tab và nhiều thứ khác, làm ra theo một cách thống nhất

Chờ đợi, báo tin, đếm

LớpLớp chaLàm gì
GoSnackbarNodelời nhắn tự tìm lấy chỗ đứng
GoSpinnerControlcuộc chờ chưa thấy điểm dừng
GoBadgePanelContainerchấm chưa đọc, nhãn MỚI, con số 99+

Biểu mẫu và danh sách

LớpLớp chaLàm gì
GoFieldVBoxContainercái hàng có thể sai
GoInputGroupHBoxContainerô nhập hàn liền với cái nút của nó
GoComboboxButtonbộ chọn có tìm kiếm
GoCodeInputVBoxContainermã coupon và mã quà tặng
GoTableVBoxContainertiêu đề cột sắp xếp được, hàng chọn được
GoPaginationHBoxContainertrang số, hoặc một hàng Xem thêm

Những hình dạng mà game thật sự dùng

LớpLớp chaLàm gì
GoRewardCalendarVBoxContainerđiểm danh hằng ngày
GoRadar · GoDonutControlchỉ số nhìn một cái là thấy
GoCarouselVBoxContainerbanner và màn chọn nhân vật
GoKbdHBoxContainergợi ý phím không nói dối

Nằm đè lên màn hình

LớpLớp chaLàm gì
GoDrawerCanvasLayerbảng bên hông
GoPopoverRefCountedtấm thẻ ghim vào một chỗ
GoContextMenuRefCountednhấn giữ và bấm chuột phải
GoConsoleCanvasLayerbảng điều khiển của lập trình viên

AI SKILL

gohud có sẵn một AI skill: toàn bộ API, mẫu chạy được ngay và trình mở xem trước. Dán một khối dưới đây vào tác nhân lập trình của bạn, nó sẽ cài gohud và biết cách dùng.

AI SKILL

Dễ đọc là đo được, không phải ước lượng bằng mắt

"Đẹp" là chuyện gu; "dễ đọc" thì đo được. Chữ xám nhạt trông ổn trên màn hình tốt và biến mất trên điện thoại giữa ban ngày — chọn bằng mắt thì sớm muộn cũng dính.

python3 addons/gohud/tools/check_contrast.py

Mọi cặp màu và nhãn của từng trạng thái nút trên chính tấm nền nó nằm lên đều được đo theo WCAG, trên cả sáu theme. Màu bán trong suốt được ghép lên nền thật của nó trước — đo thẳng vào chúng sẽ cho tỉ số đẹp hơn những gì màn hình thật sự hiển thị.

Vì vậy màu chữ là thứ suy ra, không phải chọn: trình dựng lấy màu trong bảng màu làm điểm xuất phát rồi đẩy độ sáng của nó lên cho tới khi vượt ngưỡng trên mọi bề mặt mà nó có thể rơi vào. Đổi bảng màu thì độ tương phản đi theo. Các quy tắc và những cái bẫy phía sau chúng →

Kiểm tra, phát hành và trang web này

Một điểm vào chạy mọi lượt kiểm tra; mỗi phần thấy được thứ mà các phần kia không thấy.

bash addons/gohud/tools/check_all.sh
Lượt kiểm traBắt được gì
run_tests.sh ở bốn cỡ màn hìnhHành vi và bố cục widget, vị trí khi RTL, focus bàn phím, độ tương phản của skin lúc chạy, mọi preset
new_project_check.shNhững phụ thuộc ngầm vào dự án chủ; với --zip là bản phát hành đúng như khi giao, với --export là một bản build Web
check_contrast.pyĐộ tương phản WCAG của từng file theme, tính cả trạng thái nút và tấm nền bán trong suốt
check_generated.py · check_scaffold.shTheme sinh ra khớp với bảng màu của nó; một theme dùng xong bỏ dựng được và qua được kiểm tra tương phản
check_package.pyPhiên bản lấy từ package.json, việc chuyển mục changelog và nội dung file ZIP, trên các bản sao tạm
check_site.pyLiên kết, neo, ngôn ngữ trang, bảng thuật ngữ và bảng núm chỉnh của trang này
Lượt chạy gần nhất được ghi lại — 2026-09-13, Godot 4.7.2, macOS, renderer Compatibility. 438 trên 438 lượt kiểm tra ở 390×844, 844×390, 768×1024 và 1280×800 trong một dự án trống; lại 438 trên 438 khi có autoload GoRuntime; một bản export Web; không một lỗi tương phản nào trên cả sáu theme. Godot 4.6 và thiết bị Android hay iOS thật không nằm trong lượt chạy này.

Phiên bản phát hành

cat addons/gohud/package.json       # { "version": "1.1.0" }
bash addons/gohud/tools/package.sh  # 1.1.0 → builds/1.1.0/gohud-1.1.0.zip

Phiên bản chính là số ghi trong package.json — việc đóng gói không bao giờ tự tăng nó. Muốn phát hành phiên bản mới, hãy đổi số đó trước. Một lượt chạy thành công đặt plugin.cfgGoUi.VERSION theo giá trị đó, và chỉ ở lần đầu đóng gói phiên bản ấy mới chuyển phần ghi chú Unreleased trong CHANGELOG.md thành một mục có ngày tháng. Đóng gói lại cùng phiên bản sẽ dựng lại file ZIP và thay thế file cũ. Lượt chạy hỏng thì không đổi gì cả. File ZIP không chứa trang web này, phần kiểm thử, các công cụ và package.json.

Trang web này

python3 addons/gohud/tools/make_site.py            # bảng thuật ngữ và bảng núm chỉnh của skin, sinh ra từ mã nguồn
python3 addons/gohud/tools/check_site.py           # liên kết, neo, ngôn ngữ, bảng thuật ngữ, bảng được sinh ra
bash addons/gohud/tools/site_shots.sh /tmp/shots   # ảnh chụp mọi trang ở cỡ máy để bàn và điện thoại

Các trang là HTML thuần trong www/ — tiếng Anh ở thư mục gốc, tiếng Hàn trong ko/. Một workflow GitHub Actions xuất bản thư mục đó làm gốc của trang web.