arma-modlist-tools/docs/huong-dan-su-dung.md

Hướng dẫn sử dụng Arma Mod Manager

Tài liệu này dành cho người dùng chưa biết gì về dự án. Bạn không cần kiến thức lập trình để sử dụng ứng dụng này.

---

Mục lục

1. Arma Mod Manager là gì?
2. Yêu cầu hệ thống
3. Khởi động lần đầu — Trình thiết lập
4. Giao diện chính
5. Tổng quan (Dashboard) — Quy trình cơ bản
6. Danh sách Mod
7. Công cụ nâng cao
   • Check Names
   • Update Mods
   • Link Mods
   • Sync / Report Missing
   • Clean Orphans
8. Nhật ký (Logs)
9. Cài đặt
10. Đổi sang giao diện tiếng Việt
11. Xử lý sự cố thường gặp
12. Bảng thuật ngữ

---

1. Arma Mod Manager là gì?

Arma Mod Manager là công cụ giúp bạn tải về và quản lý các mod cho Arma 3 Server từ một máy chủ lưu trữ riêng (Caddy server). Thay vì tải từng mod thủ công, bạn chỉ cần:

1. Xuất danh sách mod từ Arma 3 Launcher dưới dạng tệp HTML (gọi là preset)
2. Chọn preset trong ứng dụng
3. Nhấn nút Chạy toàn bộ quy trình

Ứng dụng sẽ tự động:

• Đọc danh sách mod từ các preset
• So sánh, tìm mod dùng chung và mod riêng giữa các preset
• Di chuyển các thư mục mod đã tải về sang đúng nhóm mới (tránh tải lại khi đổi phiên bản preset)
• Tải mod từ máy chủ về máy tính của bạn (chỉ những mod thực sự chưa có)
• Tạo liên kết (junction/symlink) để Arma 3 Server nhận ra các mod

---

2. Yêu cầu hệ thống

Yêu cầu	Thông tin
Hệ điều hành	Windows 10/11 (64-bit)
Python	3.9 trở lên
Arma 3 Server	Đã cài đặt trên máy
Kết nối mạng	Cần thiết để tải mod từ máy chủ

Cài đặt thư viện cần thiết (chỉ cần làm một lần):

Mở Command Prompt, điều hướng tới thư mục ứng dụng, chạy:

pip install -r requirements.txt

---

3. Khởi động lần đầu — Trình thiết lập

Khi khởi động ứng dụng lần đầu (chưa có tệp config.json), cửa sổ Thiết lập sẽ tự động hiện ra gồm 3 bước:

Bước 1 / 3 — Kết nối máy chủ

Trường	Mô tả
URL máy chủ	Địa chỉ đầy đủ của máy chủ Caddy lưu mod, ví dụ: https://mods.example.com/
Tên đăng nhập	Tài khoản được cấp bởi người quản trị máy chủ
Mật khẩu	Mật khẩu tương ứng

• Nhấn Kiểm tra kết nối để xác nhận thông tin trước khi tiếp tục.
  • ✓ Đã kết nối — thành công, nhấn Tiếp theo →
  • ✗ HTTP 401 — sai tên đăng nhập hoặc mật khẩu
  • ✗ ... — lỗi mạng hoặc URL sai

Bước 2 / 3 — Thư mục Arma 3 Server

Nhấn Duyệt để chọn thư mục gốc của Arma 3 Server trên máy tính (thư mục chứa arma3server.exe).

Ví dụ: C:\servers\arma3

Các thư mục khác (downloads, presets) sẽ tự động được tạo bên cạnh ứng dụng.

Bước 3 / 3 — Xem lại & Lưu

Kiểm tra thông tin đã nhập rồi nhấn Lưu & Mở. Ứng dụng sẽ lưu cấu hình và mở giao diện chính.

Mẹo: Để mở lại trình thiết lập bất cứ lúc nào, vào Cài đặt → Mở trình thiết lập.

---

4. Giao diện chính

Giao diện gồm thanh điều hướng bên trái và khu vực nội dung bên phải.

┌─────────────────┬──────────────────────────────────┐
│  Arma Mod       │                                  │
│  Manager        │   Khu vực nội dung               │
│─────────────────│   (thay đổi theo mục chọn)       │
│  Tổng quan      │                                  │
│  Danh sách Mod  │                                  │
│  Công cụ        │                                  │
│  Nhật ký        │                                  │
│  Cài đặt        │                                  │
└─────────────────┴──────────────────────────────────┘

Mục	Chức năng
Tổng quan	Chọn preset, xem trạng thái pipeline, chạy quy trình tải mod
Danh sách Mod	Xem tất cả mod theo nhóm, trạng thái tải/liên kết/máy chủ
Công cụ	Các tác vụ bảo trì nâng cao
Nhật ký	Xem toàn bộ output của pipeline và công cụ
Cài đặt	Cấu hình giao diện, ngôn ngữ, mở lại trình thiết lập

---

5. Tổng quan (Dashboard) — Quy trình cơ bản

Đây là trang chính bạn sẽ dùng thường xuyên nhất.

5.1 Thêm tệp preset

Preset là tệp HTML xuất từ Arma 3 Launcher chứa danh sách mod bạn đang dùng.

Cách xuất preset từ Arma 3 Launcher:

1. Mở Arma 3 Launcher
2. Vào tab Mods
3. Nhấn Preset → Export to HTML
4. Lưu tệp vào máy tính

Thêm preset vào ứng dụng:

1. Ở mục Tệp Preset, nhấn + Thêm tệp Preset
2. Chọn tệp .html vừa xuất
3. Tệp sẽ xuất hiện trong danh sách với ô tick

5.2 Chọn preset để xử lý

• Tick vào các preset bạn muốn so sánh (cần ít nhất 2 preset)
• Nhấn Tất cả để chọn tất cả, hoặc Bỏ chọn để bỏ hết
• Nhãn Đã chọn X / Y cho biết số lượng đã chọn:
  • Màu xanh: đã chọn đủ (≥ 2)
  • Màu vàng: mới chọn 1
  • Màu đỏ: chưa chọn

5.3 Trạng thái Pipeline

Cột bên phải hiển thị 5 bước của quy trình:

Bước	Mô tả	Dấu hiệu hoàn thành
Phân tích preset	Đọc danh sách mod từ tệp HTML	Có ≥ 2 preset được chọn
So sánh preset	Tìm mod chung và riêng	Tệp comparison.json tồn tại
Di chuyển nhóm mod	Chuyển thư mục mod sẵn có sang đúng nhóm mới	Tự động (không cần tải lại)
Tải mod	Tải tệp mod thực sự còn thiếu từ máy chủ	Có thư mục mod trong downloads/
Liên kết với Arma	Tạo junction tới thư mục Arma 3	Thư mục Arma 3 Server tồn tại

Biểu tượng ✓ (xanh) = đã xong, ○ (xám) = chưa xong.

5.4 Chạy toàn bộ quy trình

1. Đảm bảo đã chọn ít nhất 2 preset
2. Nhấn ▶ Chạy toàn bộ quy trình
3. Ứng dụng tự động chuyển sang tab Nhật ký và hiển thị tiến trình
4. Chờ cho đến khi thấy dòng ✓ Pipeline complete. (hoặc tiếng Việt: ✓ Hoàn thành)

Lưu ý: Quá trình này có thể mất vài phút đến hàng giờ tùy số lượng và kích thước mod.

---

6. Danh sách Mod

Trang này hiển thị tất cả mod được nhóm theo preset (tab).

Các tab nhóm

• shared (X) — Mod có mặt trong tất cả preset đã chọn
• [tên preset] (X) — Mod chỉ có trong preset đó

Nhấn vào tên tab để chuyển nhóm.

Các cột thông tin

Cột	Ý nghĩa
Tên Mod	Tên mod theo danh sách preset
Đã tải	✓ = đã có trong thư mục downloads · ✗ = chưa tải
Đã liên kết	✓ = đã tạo junction tới Arma 3 · ✗ = chưa · — = chưa tải nên không liên kết được
Trạng thái máy chủ	Xem bên dưới

Trạng thái máy chủ

Nhấn nút ☁ Kiểm tra cập nhật để kiểm tra từng mod với máy chủ:

Trạng thái	Ý nghĩa
✓ Đã cập nhật	Tệp local khớp với máy chủ
⚠ X tệp cũ	Có X tệp cần cập nhật, nhấn Cập nhật ở cuối hàng
Không có trên máy chủ	Mod này không tồn tại trên máy chủ
—	Mod chưa được tải về
✗ Lỗi	Không thể kiểm tra (lỗi mạng)

Tìm kiếm mod

Gõ vào ô Tìm kiếm: để lọc mod theo tên trong tab đang xem.

---

7. Công cụ nâng cao

Trang Công cụ có 5 tab phụ cho các tác vụ bảo trì. Mỗi tab đều có nút chạy ở góc phải phía dưới, output hiển thị trong Nhật ký.

Tab	Chức năng tóm tắt
Check Names	Kiểm tra và sửa tên thư mục mod
Update Mods	Tải lại tệp mod đã thay đổi trên máy chủ
Link Mods	Tạo / xóa junction tới Arma 3 Server
Sync / Report Missing	Đồng bộ và báo cáo mod còn thiếu
Clean Orphans	Xóa thư mục mod thừa từ preset cũ

Tab "Check Names" — Kiểm tra tên thư mục

Quét thư mục mod trên máy tính và so sánh với máy chủ. Báo cáo các vấn đề:

Vấn đề	Ý nghĩa
MISMATCH	Tên thư mục local khác với tên trên máy chủ
NOT_ON_SERVER	Thư mục local không tìm thấy trên máy chủ
ID_COLLISION	Tệp meta.cpp chứa Steam ID sai

Tùy chọn:

• --fix: Tự động đổi tên thư mục sai → Dùng cẩn thận, sẽ di chuyển tệp
• --fix-ids: Tự động sửa Steam ID trong meta.cpp → Dùng cẩn thận, sẽ ghi đè tệp

Tab "Update Mods" — Cập nhật mod

Tải lại các tệp mod có kích thước khác với bản trên máy chủ.

• Nhóm: Chọn Tất cả nhóm hoặc một nhóm cụ thể
• Thư mục mod: Nhập tên thư mục cụ thể (ví dụ @ace) nếu muốn cập nhật một mod
• --force: Tải lại tất cả tệp bất kể kích thước — cẩn thận với mod nặng

Tab "Link Mods" — Quản lý liên kết

Tạo hoặc xóa junction giữa thư mục downloads/ và thư mục Arma 3.

Lệnh	Chức năng
Status	Hiển thị trạng thái liên kết hiện tại
Link	Tạo junction còn thiếu
Unlink	Xóa junction (tệp mod KHÔNG bị xóa)

Lưu ý: Phải chọn một nhóm cụ thể trước khi chạy Unlink.

Tab "Sync Missing" — Đồng bộ mod thiếu

Thử tải lại các mod bị thiếu từ lần chạy pipeline trước. Hữu ích khi máy chủ vừa bổ sung mod mới sau khi bạn đã chạy pipeline.

Tab "Report Missing" — Báo cáo mod thiếu

Kiểm tra mod nào trong comparison.json chưa có trên máy chủ và lưu báo cáo vào missing_report.json. Dùng để theo dõi mod cần yêu cầu admin bổ sung.

Tab "Clean Orphans" — Dọn dẹp mod thừa

Khi bạn đổi preset và chạy lại pipeline, các mod của preset cũ vẫn còn trong thư mục downloads/ nhưng không được dùng nữa — gọi là mod thừa (orphan). Tab này giúp tìm và xóa chúng để giải phóng dung lượng ổ đĩa.

Cách dùng:

1. Nhấn Quét mod thừa — ứng dụng sẽ so sánh thư mục downloads/ với comparison.json hiện tại
2. Danh sách mod thừa hiện ra kèm tên nhóm và dung lượng
3. Dùng Chọn tất cả hoặc tick thủ công từng mục
4. Nhấn Xóa đã chọn — xuất hiện hộp thoại xác nhận
5. Nhấn Xác nhận xóa để thực hiện; danh sách sẽ tự động quét lại sau khi xóa

Lưu ý an toàn: Ứng dụng chỉ xóa thư mục @ModName trong downloads/, không đụng tới thư mục Arma 3 Server. Junction (liên kết) sẽ bị xóa đúng cách mà không làm mất tệp gốc.

Yêu cầu: Cần có comparison.json (chạy pipeline ít nhất một lần trước).

---

8. Nhật ký (Logs)

Trang này hiển thị toàn bộ output khi chạy pipeline hoặc công cụ.

• Sao chép: Copy toàn bộ nội dung nhật ký vào clipboard
• Xóa: Xóa sạch nội dung nhật ký

Output được giữ nguyên khi bạn chuyển sang trang khác và quay lại.

Ký hiệu trong log:

• ✓ — bước hoàn thành thành công
• ✗ — có lỗi xảy ra
• SKIP — bỏ qua (ví dụ preset không được chọn)

---

9. Cài đặt

Cấu hình máy chủ & đường dẫn

Nhấn Mở trình thiết lập để thay đổi URL máy chủ, tài khoản, hoặc thư mục Arma 3.

Giao diện

Chọn chế độ hiển thị: Dark (tối), Light (sáng), hoặc System (theo hệ thống).

Ngôn ngữ

Xem phần 10. Đổi sang giao diện tiếng Việt.

Cấu hình hiện tại

Hiển thị các đường dẫn đang dùng: URL máy chủ, thư mục Arma, thư mục downloads, thư mục presets.

---

10. Đổi sang giao diện tiếng Việt

1. Nhấn Cài đặt ở thanh bên trái
2. Cuộn xuống đến mục Ngôn ngữ
3. Chọn Tiếng Việt từ danh sách thả xuống
4. Giao diện sẽ chuyển sang tiếng Việt ngay lập tức — không cần khởi động lại

Để chuyển lại tiếng Anh, chọn English trong cùng mục đó.

Lựa chọn ngôn ngữ được lưu vào config.json và sẽ được ghi nhớ cho lần khởi động tiếp theo.

---

11. Xử lý sự cố thường gặp

Không kết nối được máy chủ

Triệu chứng: Wizard hiển thị ✗ HTTP 401 hoặc ✗ [lỗi kết nối]

Kiểm tra:

• URL có bắt đầu bằng https:// không?
• URL có dấu / ở cuối không? (ví dụ https://mods.example.com/)
• Tên đăng nhập và mật khẩu có đúng không? (kiểm tra phân biệt hoa thường)
• Máy tính có kết nối internet không?
• Máy chủ có đang hoạt động không? (hỏi admin)

Pipeline chạy xong nhưng không tải được mod

Triệu chứng: Log hiển thị missing from server hoặc NOT_ON_SERVER

Giải thích: Mod tồn tại trong preset nhưng chưa có trên máy chủ.

Xử lý:

• Vào Công cụ → Report Missing để tạo báo cáo
• Gửi báo cáo cho admin để bổ sung mod
• Sau khi mod được thêm, vào Công cụ → Sync Missing để tải về

Mod tải về rồi nhưng không liên kết được

Triệu chứng: Cột "Đã tải" là ✓ nhưng "Đã liên kết" là ✗

Xử lý:

• Vào Công cụ → Link Mods, chọn lệnh Link, chọn nhóm tương ứng, nhấn Tạo liên kết
• Nếu vẫn lỗi, kiểm tra quyền ghi vào thư mục Arma 3 (có thể cần chạy ứng dụng với quyền Administrator)

Tên thư mục mod bị sai

Triệu chứng: Arma 3 Server không nhận ra mod dù đã tạo junction

Xử lý:

• Vào Công cụ → Check Names, nhấn Chạy kiểm tra tên
• Xem log để tìm dòng MISMATCH
• Nếu muốn tự động sửa, tick vào Tự động sửa tên thư mục rồi chạy lại

Ứng dụng không khởi động / lỗi Python

Triệu chứng: Màn hình đen nháy tắt ngay

Xử lý:

• Mở Command Prompt, chạy python gui.py để xem thông báo lỗi
• Đảm bảo đã cài đủ thư viện: pip install -r requirements.txt
• Kiểm tra phiên bản Python: python --version (cần ≥ 3.9)

---

12. Bảng thuật ngữ

Thuật ngữ	Giải thích
Preset	Tệp HTML xuất từ Arma 3 Launcher chứa danh sách mod
Pipeline	Chuỗi 5 bước tự động: phân tích → so sánh → di chuyển nhóm → tải → liên kết
Junction / Symlink	Liên kết thư mục ảo — Arma 3 thấy mod trong thư mục của mình nhưng tệp thực sự nằm ở downloads/
Shared mods	Mod xuất hiện trong tất cả preset đã chọn
Unique mods	Mod chỉ có trong một preset cụ thể
Caddy server	Phần mềm máy chủ lưu trữ tệp mod (HTTP file server)
meta.cpp	Tệp metadata của mỗi mod, chứa publishedid (Steam Workshop ID)
Steam ID / publishedid	Mã định danh mod trên Steam Workshop
comparison.json	Tệp kết quả so sánh preset, lưu danh sách mod theo nhóm
missing_report.json	Báo cáo mod có trong preset nhưng chưa có trên máy chủ
downloads/	Thư mục chứa tệp mod đã tải về
Di chuyển nhóm mod	Bước tự động chuyển thư mục mod từ nhóm cũ sang nhóm mới theo comparison.json — tránh tải lại khi đổi phiên bản preset
Mod thừa (Orphan)	Thư mục mod còn trong downloads/ nhưng không còn trong preset nào đang dùng
config.json	Tệp cấu hình lưu thông tin máy chủ và đường dẫn

---

Phiên bản tài liệu: 2026-04 (cập nhật: thêm bước Di chuyển nhóm mod, pipeline 5 bước). Nếu có vấn đề, liên hệ người quản trị máy chủ.