Gỡ lỗi
Những lỗi đã gặp, vì sao xảy ra và cách xử lý. Trang này lớn dần theo từng bản.
Game văng với hộp "Error compiling shader file"Đã sửa từ bản 0.1.8
Triệu chứng
Đang chơi thì hiện hộp "Error compiling shader file … E4002: Failed to open …", sau đó game văng và hỏi có muốn thu thập file báo lỗi không.
Nguyên nhân
Gặp cảnh cần một shader chưa có sẵn, game tự biên dịch nó. Wine dùng trình biên dịch shader của chính Wine thay cho bản Microsoft đi kèm game, và bản đó không mở được các file phụ của shader.
Cách xử lý
- Cập nhật kegPlay lên bản mới nhất. Từ bản 0.1.11, mọi game mang theo trình biên dịch shader của Microsoft (d3dcompiler_47.dll) đều được kegPlay tự cho dùng bản đó, ngay khi game tải xong.
- Lần đầu gặp chỗ cần shader mới, game có thể khựng vài giây. Như vậy là bình thường.
- Nếu game hỏi bật Safe Mode ở lần mở sau, chọn No để giữ cấu hình đồ hoạ.
Game văng khi vào màn chơi, log báo "Null program bound" hoặc "E5016"Đã sửa từ bản 0.1.14
Triệu chứng
Game mở được menu nhưng văng khi bắt đầu chơi (vd Kenshi lúc bấm New Game), hiện hộp lỗi "page fault on execute access" của Wine. Log của game có dòng "Cannot compile … E5016: Object of type 'Texture2D' must be bound to register type 't'" rồi "Null program bound".
Nguyên nhân
Trình biên dịch shader của Wine khắt khe hơn bản Microsoft, từ chối shader của game. Game thiếu shader nên văng. Game có mang theo trình biên dịch của Microsoft (vd D3DCompiler_43.dll ở Kenshi) nhưng kegPlay trước 0.1.14 chỉ dùng bản _47.
Cách xử lý
- Cập nhật kegPlay lên 0.1.14 trở lên. kegPlay tự cho game dùng trình biên dịch Microsoft đi kèm (mọi bản d3dcompiler_NN.dll) khi bạn bấm Chơi hoặc mở Steam.
- Mở lại game là chạy, không cần làm gì thêm.
Không đăng nhập được Steam, mã QR không hiệnĐã sửa từ bản 0.1.0
Triệu chứng
Màn hình đăng nhập Steam hiện ô mã QR mờ kèm biểu tượng tải lại, hoặc đăng nhập bằng tài khoản thì quay mãi.
Nguyên nhân
DNS của một số nhà mạng Việt Nam trả lời "tên không tồn tại" cho các máy chủ đăng nhập của Steam (steamserver.net). Steam bản Windows tự hỏi DNS của máy, không đi qua bộ vượt chặn.
Cách xử lý
- Cập nhật kegPlay lên bản mới nhất: app đã kèm "DNS dự phòng", tự hỏi lại 1.1.1.1 khi DNS của máy báo không có tên.
- Bấm Tắt Steam rồi Mở Steam để áp dụng.
- Cách tạm nếu chưa cập nhật được: đổi DNS của máy sang 1.1.1.1 trong Cài đặt hệ thống › Mạng.
Steam mở ra cửa sổ đenĐã sửa từ bản 0.1.13
Triệu chứng
Cửa sổ Steam hiện lên nhưng bên trong toàn màu đen, không thấy nút hay danh sách game.
Nguyên nhân
Giao diện Steam là một trình duyệt nhúng, và phần tăng tốc đồ hoạ của nó không chạy được trong Wine trên Mac.
Cách xử lý
- kegPlay tự vá lỗi này mỗi lần mở Steam, và từ bản 0.1.13 tự vá lại khi Steam vừa tự cập nhật (Steam sẽ tự tắt rồi mở lại một lần).
- Nếu vẫn đen: bấm Tắt Steam, chờ vài giây rồi Mở Steam.
Tải game báo "No internet connection"
Triệu chứng
Steam trong kegPlay đã đăng nhập, nhưng bấm cài game thì báo không có mạng.
Nguyên nhân
Steam bản Mac đang mở cùng tài khoản. Hai bản tranh nhau một phiên đăng nhập và bản trong kegPlay bị đá ra.
Cách xử lý
- Thoát hẳn Steam bản Mac (Cmd+Q).
- Trong kegPlay bấm Tắt Steam rồi Mở Steam.
Bấm phím di chuyển thì hiện ô chữ trắng, nhân vật đi khựngĐã sửa từ bản 0.1.0
Triệu chứng
Trong game, bấm W A S D thì một ô trắng có chữ kiểu "wddddaw" hiện ở góc màn hình.
Nguyên nhân
Bộ gõ tiếng Việt (Telex, VNI) hoặc bộ gõ Trung, Nhật, Hàn của macOS đang bật. Nó giữ phím lại để ghép chữ.
Cách xử lý
- Để app kegPlay mở trong lúc chơi: app tự chuyển bàn phím sang ABC khi bạn vào cửa sổ game và trả lại bộ gõ cũ khi rời đi.
- Kiểm công tắc "Tự chuyển bộ gõ sang ABC khi vào game" trong Cài đặt của app.
- Hoặc tự đổi sang bàn phím ABC trước khi chơi.
"Could not create OpenGL context" khi mở gameĐã sửa từ bản 0.1.0
Triệu chứng
Bấm Play thì hiện hộp "Graphics driver error: Could not create OpenGL context". Gặp ở Mount & Blade II: Bannerlord.
Nguyên nhân
Trình khởi chạy (launcher) của game xin OpenGL theo kiểu mà Wine trên Mac từ chối, dù macOS đáp ứng được.
Cách xử lý
- Chọn công nghệ DXMT trong kegPlay (bản vá chỉ có ở DXMT).
- Bấm Tắt Steam, Mở Steam rồi chạy lại game.
Game cũ báo "Unable to set the video mode", chớp hoặc màn hình đenĐã sửa từ bản 0.1.5
Triệu chứng
Mở game thì hiện hộp "Error - Unable to set the video mode", hoặc cửa sổ game chớp đen, hoặc không hiện gì. Gặp ở Red Alert 2 / Yuri's Revenge và các game DirectDraw đời cũ.
Nguyên nhân
Game đòi màn hình 640x480 hoặc 800x600 toàn màn hình. Màn hình Mac không có các chế độ đó, và DirectDraw của Wine trên Mac vẽ loại game này không ổn.
Cách xử lý
- Cập nhật kegPlay lên bản mới nhất. Với các game đã được hỗ trợ (hiện có Red Alert 2 và Yuri's Revenge), kegPlay tự sửa khi bạn bấm Mở Steam hoặc Chơi; bạn không phải làm gì.
- Game chạy trong một cửa sổ, ở đúng độ phân giải màn hình của bạn: menu nằm giữa cửa sổ, vào trận thì kín màn hình.
- Đừng chọn độ phân giải nhỏ hơn trong Options của game và đừng kéo góc cửa sổ để đổi cỡ: các nút trong menu sẽ lệch hoặc biến mất. Nếu lỡ đổi, thoát game rồi bấm Chơi lại từ kegPlay.
- Game cũ khác gặp lỗi này mà chưa được hỗ trợ: báo tên game trên GitHub để chúng tôi thêm vào.
Launcher của game chớp đen liên tụcĐã sửa từ bản 0.1.0
Triệu chứng
Cửa sổ launcher lúc hiện hình, lúc đen, lặp lại nhiều lần mỗi giây. Gặp ở Bannerlord.
Nguyên nhân
Launcher vẽ bằng OpenGL rồi chép ảnh sang một cửa sổ trong suốt. Wine trên Mac hiện cả hai lớp đè lên nhau.
Cách xử lý
- Cập nhật kegPlay và chọn DXMT.
- Lúc mới mở vẫn có thể nháy nền đen dưới một giây; đó là bình thường.
"Failed to load steamui.dll"Đã sửa từ bản 0.1.0
Triệu chứng
Lần đầu mở Steam sau khi cài thì hiện hộp lỗi này rồi thoát.
Nguyên nhân
Steam chưa kịp tải phần lõi của nó ở lần chạy đầu tiên.
Cách xử lý
- Bản mới tự xử lý: lần đầu kegPlay để Steam tải đủ rồi mới mở lại. Lần đầu có thể mất vài phút.
- Nếu đang ở bản cũ: bấm Mở Steam lại một lần nữa.
Trang Store trắng hoặc không tải đượcĐã sửa từ bản 0.1.15
Triệu chứng
Thư viện game vào được nhưng tab Store trắng, hoặc hiện "Something went wrong while displaying this content… Unable to preload CSS for https://store.fastly.steamstatic.com/…"; ảnh trong Workshop không hiện.
Nguyên nhân
Nhà mạng chặn store.steampowered.com, và từ 11/2026 chặn cả máy chủ ảnh/CSS của Steam (*.steamstatic.com, steamusercontent.com, akamaihd.net). Bản 0.1.0 còn có lỗi làm công tắc "Vượt chặn Store" không có tác dụng.
Cách xử lý
- Cập nhật lên kegPlay 0.1.15 trở lên (bản này vượt chặn cả máy chủ ảnh/CSS).
- Bật công tắc "Vượt chặn Store" trong kegPlay.
- Bấm Tắt Steam rồi Mở Steam (có hiệu lực từ lần mở sau).
macOS không cho mở kegPlay
Triệu chứng
Mở app lần đầu thì macOS báo không xác minh được nhà phát triển.
Nguyên nhân
kegPlay chưa được ký bằng tài khoản Apple Developer (dự án miễn phí, chưa mua).
Cách xử lý
- Mở Cài đặt hệ thống › Quyền riêng tư & Bảo mật, kéo xuống và bấm "Vẫn mở" cho Kegplay.
- Chỉ phải làm một lần. Mã nguồn công khai trên GitHub nếu bạn muốn tự kiểm.
Game cần DirectX 12
Triệu chứng
kegPlay ghi "Cần DirectX 12 — chưa chạy được" dưới tên game, hoặc game báo thiếu DirectX 12 rồi thoát.
Nguyên nhân
kegPlay dịch DirectX 9, 10 và 11 sang Metal. Đường dịch DirectX 12 trên Mac hiện chỉ có trong bộ công cụ của Apple, mà kegPlay không được phép đóng gói lại.
Cách xử lý
- Nếu game có tuỳ chọn khởi động bằng DirectX 11 (thường trong Steam: chuột phải vào game › Properties › Launch Options, ví dụ -dx11), hãy thử.
- Nếu không có, hiện chưa chơi được game này bằng kegPlay.
Game DirectX 9 chạy chậm
Triệu chứng
kegPlay ghi "Game DirectX 9 — có thể chạy chậm" dưới tên game; game chạy được nhưng giật hoặc FPS thấp.
Nguyên nhân
DXMT chỉ lo DirectX 10 và 11. Game DirectX 9 đi qua WineD3D, dịch sang OpenGL, mà OpenGL trên Mac đã cũ nên chậm hơn.
Cách xử lý
- Hạ độ phân giải và chất lượng đồ hoạ trong game.
- Báo game này trong Issues trên GitHub để được ưu tiên thử.
Game có anti-cheat
Triệu chứng
kegPlay ghi "Có anti-cheat — chơi online có thể không vào được"; chế độ chơi đơn có thể vẫn chạy.
Nguyên nhân
Phần mềm chống gian lận (Easy Anti-Cheat, BattlEye…) kiểm tra Windows ở mức sâu, và thường chặn khi chạy qua Wine.
Cách xử lý
- Thử chế độ chơi đơn hoặc chế độ offline nếu game có.
- Chế độ online cần nhà phát triển game cho phép Wine/Proton; kegPlay không vượt qua được.
Game bị văng, kegPlay chưa biết nguyên nhân
Triệu chứng
Game tự đóng; kegPlay hiện dải "<tên game> vừa bị văng" với nút Gửi báo cáo lên GitHub.
Nguyên nhân
Wine bắt được một lỗi trong game (thường là truy cập bộ nhớ sai) mà kegPlay chưa có trong bộ nhận diện.
Cách xử lý
- Bấm Gửi báo cáo lên GitHub. Trang báo cáo đã điền sẵn phiên bản kegPlay, macOS, chip, tên game và đoạn log; tên tài khoản và đường dẫn riêng đã được xoá. Xem lại, ghi thêm bạn đã làm gì, rồi bấm Submit.
- Trong lúc chờ: thử đổi DXMT ↔ DXVK rồi mở lại game.
- Mỗi lỗi được tìm ra sẽ thành một luật mới; bản kegPlay kế tiếp tự xử lý cho mọi người.
Thiếu thành phần Windows mà game cần
Triệu chứng
Game không mở hoặc văng ngay; kegPlay báo "Thiếu một thành phần Windows mà game cần".
Nguyên nhân
Game cần một thư viện của Windows (thường là bộ Visual C++ hoặc .NET) mà bottle chưa có. Steam thường tự cài khi chạy game lần đầu, nhưng đôi khi bước này bị bỏ qua.
Cách xử lý
- Trong Steam: chuột phải vào game › Properties › Installed Files › Verify integrity, rồi mở lại game để Steam cài lại phần phụ.
- Nếu vẫn lỗi, bấm Gửi báo cáo lên GitHub; báo cáo có sẵn tên thư viện còn thiếu.
Không thấy lỗi của bạn? Báo lỗi trên GitHub
kegPlay