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.
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.
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.
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.
Đổ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
| Preset | Diện mạo |
|---|---|
default_dark | gohud nguyên bản — góc bo tròn, màu nhấn xanh dịu |
default_light | Vẫn hình dáng đó trên bảng màu sáng |
scifi_dark | Gó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_light | Vẫn hình dáng góc cạnh đó trong bảng màu bản vẽ kỹ thuật sáng |
medieval_dark | Sắ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_light | Giấy da, mực và đồng thau với vẫn những khung rèn đó |
default_dark — góc bo tròn, màu nhấn xanh dịu
default_light — cùng hình dáng, bảng màu sáng
scifi_dark — góc vát, neon lam
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 — sắt và da thuộc
medieval_light — giấy da và mựcCả 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 · 1280×800
scifi_dark · 1280×800Cùng một bảng trượt, khác diện mạo
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ó.
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ớp | Hình dáng nó tạo ra được |
|---|---|
GoStyleBoxCut | Gó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 |
GoStyleBoxBracket | Chỉ dấu ở bốn góc, không bao kín nội dung |
GoStyleBoxMedieval | Khung 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. GoSkinSciFi và GoSkinMedieval 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ớp | Lớp cha | Làm gì |
|---|---|---|
GoSurface | Control | Vỏ 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 |
GoSheet | CanvasLayer | Trang trồi lên từ đáy, nằm trên lớp riêng nên luôn ở trên HUD |
GoDialogs | Node | Hộ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 |
GoForm | MarginContainer | Biể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 |
GoScroll | ScrollContainer | Cuộn bằng ngón tay; thanh cuộn nép vào phần đệm sẵn có của thẻ |
GoNotice | PanelContainer | Snackbar không nhận thao tác cũng không nhận focus |
GoPromptCard | PanelContainer | Một câu hỏi không chặn game lại |
GoCoachMark | Control | Chuyế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ế |
GoHudAnchor | Control | Ghim các mảnh HUD vào một trong chín vị trí trong vùng an toàn |
GoBar | Control | Thanh máu, mana và kinh nghiệm với chuyển động mượt |
GoSlot | Button | Mộ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 |
GoJoystick | Control | Cần điều khiển ảo ở chế độ cố định, đi theo hoặc tương đối |
GoIconButton | Button | Trông nhỏ, bấm rộng |
GoStyle | static | Nú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ớp | Lớp cha | Làm gì |
|---|---|---|
GoSnackbar | Node | lời nhắn tự tìm lấy chỗ đứng |
GoSpinner | Control | cuộc chờ chưa thấy điểm dừng |
GoBadge | PanelContainer | chấm chưa đọc, nhãn MỚI, con số 99+ |
Biểu mẫu và danh sách
| Lớp | Lớp cha | Làm gì |
|---|---|---|
GoField | VBoxContainer | cái hàng có thể sai |
GoInputGroup | HBoxContainer | ô nhập hàn liền với cái nút của nó |
GoCombobox | Button | bộ chọn có tìm kiếm |
GoCodeInput | VBoxContainer | mã coupon và mã quà tặng |
GoTable | VBoxContainer | tiêu đề cột sắp xếp được, hàng chọn được |
GoPagination | HBoxContainer | trang số, hoặc một hàng Xem thêm |
Những hình dạng mà game thật sự dùng
| Lớp | Lớp cha | Làm gì |
|---|---|---|
GoRewardCalendar | VBoxContainer | điểm danh hằng ngày |
GoRadar · GoDonut | Control | chỉ số nhìn một cái là thấy |
GoCarousel | VBoxContainer | banner và màn chọn nhân vật |
GoKbd | HBoxContainer | gợi ý phím không nói dối |
Nằm đè lên màn hình
| Lớp | Lớp cha | Làm gì |
|---|---|---|
GoDrawer | CanvasLayer | bảng bên hông |
GoPopover | RefCounted | tấm thẻ ghim vào một chỗ |
GoContextMenu | RefCounted | nhấn giữ và bấm chuột phải |
GoConsole | CanvasLayer | bả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.
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 tra | Bắt được gì |
|---|---|
run_tests.sh ở bốn cỡ màn hình | Hà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.sh | Nhữ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.sh | Theme 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.py | Phiê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.py | Liê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 |
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.cfg và
GoUi.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.