Hướng dẫn sử dụng Combat Simulator Web

Tài liệu này hướng dẫn cấu hình một trận, chạy mô phỏng và đọc kết quả. Giao diện web là công cụ thử nghiệm dựa trên các tham số simulator hiện hỗ trợ; nó không đại diện cho toàn bộ tính năng của game.

• Đặc tả file JSON cấu hình

1. Cấu hình hai bên

Trong GUI Builder, nhập thông tin cho Left và Right:

Mặc định có 1 Infantry T5 bên Left và 1 Infantry T1 bên Right để chạy thử ngay. Có thể thay toàn bộ quân hoặc import cấu hình của bạn.

• Troop count: số lượng cho từng loại lính và từng tier. Để 0 hoặc bỏ trống nếu không dùng loại/tier đó. Mỗi bên có tối đa 20 triệu lính theo contract.
• Castle Level: cấp lâu đài, từ 1 đến 75. Cấp này dùng khi xác định khả năng tiếp nhận đội hình quân; nếu không biết nên dùng giá trị phù hợp với fixture hoặc để giá trị mặc định.
• Formation: chọn một trong sáu preset có tên tiếng Anh trong game; số trong ngoặc là giá trị được lưu trong JSON. Tên tiếng Việt chính thức chưa được xác minh, và tên preset không bảo đảm kết quả chiến đấu cụ thể. Các lựa chọn: Infantry Phalanx (0), Ranged Phalanx (1), Cavalry Phalanx (2), Infantry Wedge (3), Ranged Wedge (4), Cavalry Wedge (5).
• Stat bonuses: các chỉ số điều chỉnh áp dụng mặc định cho bên đang cấu hình. Giá trị nhập là raw value, không phải số phần trăm viết trực tiếp.
• Per-kind stat overrides: tùy chọn thay giá trị bonus mặc định cho một loại lính cụ thể. Ô trống kế thừa bonus chung; nhập số, kể cả 0, thay riêng channel đó cho loại lính ấy. Đây không phải khoản cộng thêm.
• Advantages (counters): khắc chế riêng cho mỗi bên: Infantry → Ranged, Cavalry → Infantry, Ranged → Cavalry. Nhập số nguyên raw 0–100000; ô trống dùng mặc định 0 và không lưu key, nhập 0 lưu giá trị 0 rõ ràng. Siege không có ô này.
• Heroes / Pets: thêm slot rồi chọn tên tiếng Anh kèm ID, cùng rank/star hoặc level tương ứng. Danh sách trong selector chỉ là các ID có hỗ trợ đã xác nhận, không phải roster đầy đủ. Giới hạn hiện tại là tối đa 5 hero và 5 pet mỗi bên. Không phải mọi tổ hợp đều đã được kiểm chứng; simulator có thể từ chối tổ hợp không hỗ trợ.

Các lựa chọn resource có giới hạn là có chủ ý: không tự suy ra tên hay hành vi chưa được xác nhận. Để nhập trường nâng cao không có trong builder, dùng tab Raw JSON.

Tên được lấy từ tài nguyên game đã xác minh. “Đã ánh xạ tên”, “core hỗ trợ” và “có trận oracle kiểm chứng” là ba trạng thái riêng. Tên không làm thay đổi ID trong JSON; runtime thiếu catalog vẫn dùng được nhãn số.

2. Bonus và đơn vị nhập

Với các trường bonus dùng raw value, quy ước là 100 = 1% giá trị modifier; ví dụ 5000 tương đương 50% modifier. Hạn mức chính xác khác nhau theo channel và được liệt kê trong JSON reference.

Các nhóm channel được đặt tên để người dùng nhận diện mục đích:

• attack, defence, hp: điều chỉnh attack, defence hoặc HP.
• reduce_attack, reduce_defence, reduce_hp: channel giảm tương ứng.
• curse_attack, curse_defence, curse_hp: channel curse tương ứng.
• add_damage, reduce_damage: điều chỉnh channel damage bổ sung/giảm damage.
• magic: channel magic.
• advantages: tương quan khắc chế giữa Infantry, Ranged và Cavalry, nhập trong phần Advantages (counters) của mỗi bên hoặc Raw JSON. Đây là object riêng, không nằm trong bonuses hay kind_bonuses.

Các channel curse_* và add_damage được cấu hình ở một bên để tác động lên channel tương ứng của loại lính đối diện; reduce_* và reduce_damage thuộc phía đang cấu hình.

Không cần điền tất cả channel. Nếu chưa có giá trị đã biết, để 0/trống theo hướng dẫn của trường thay vì tự đặt một bonus.

3. Lưu và nạp cấu hình

Army Profiles lưu một đội quân độc lập với phe: level, formation, troops, bonuses, overrides, advantages, heroes, pets, hero-ultra và các trường nâng cao đã nạp. Dùng Save Left as profile hoặc Save Right as profile, đặt tên, thêm ghi chú rồi nhấn Save. Có thể lưu riêng một bên khi bên kia đang nhập dở.

Tìm theo tên/ghi chú rồi chọn hồ sơ để xem tóm tắt. Chọn hồ sơ chưa thay đổi trận; Apply to Left, Apply to Right hoặc Apply to Both mới áp dụng. Mỗi bên nhận một bản sao độc lập: sửa Left sau khi áp dụng Both không sửa Right hay hồ sơ gốc. Wall và tham số chung không thuộc Army Profile.

Trong Manage selected profile, dùng Edit để đổi tên, ghi chú hoặc Army JSON. Use current Left/Right army đưa quân đang chỉnh vào bản nháp; chỉ Save mới cập nhật hồ sơ đã lưu. Duplicate tạo bản nháp hồ sơ mới; Save as new copy lưu riêng bản nháp khi đang Edit. Delete cần Confirm delete và không xóa quân đang dùng trong trận. Cancel hoặc Escape bỏ thay đổi trong dialog.

Battle Presets lưu toàn bộ cấu hình, gồm hai phe, seed/gap/tier factor/threshold, mode, wall/force/attributes, description và các trường nâng cao. Dùng Save current battle để lưu tab đang hoạt động, kể cả Raw JSON. Load preset nạp bản sao vào GUI và Raw JSON, giữ tab đang chọn. Sửa trận sau khi tải không cập nhật preset; muốn cập nhật, dùng Edit → Use current battle → Save. Preset cũng có tìm kiếm, đổi tên, nhân bản, xóa và xuất riêng.

Left → Right, Right → Left và Swap armies sao chép/hoán đổi toàn bộ dữ liệu của đội quân, gồm các trường nâng cao. Tham số chung và wall vẫn thuộc trận; wall luôn gắn với Right theo schema hiện tại.

Thư viện lưu trong trình duyệt, theo địa chỉ site (protocol, hostname và port), không lưu trên server hoặc đồng bộ giữa máy/trình duyệt. Đổi port cũng tạo vùng lưu khác. Xuất backup trước khi chuyển địa chỉ, xóa dữ liệu trình duyệt hoặc dùng chế độ riêng tư.

• Import to library nhận Army Profile, Battle Preset, library backup version 1 hoặc JSON trận schema 2 (tạo preset). Import thêm các bản sao với ID mới; tên trùng được thêm hậu tố, không ghi đè hồ sơ có sẵn và không tự áp dụng vào trận.
• Export library backup xuất toàn bộ thư viện thành combat-simulator-library.json. Export trong mục quản lý xuất riêng hồ sơ hoặc preset bằng envelope version 1; các envelope này khác JSON combat schema 2.
• Tên dài tối đa 100 ký tự, ghi chú tối đa 2000. Tên phải khác nhau trong cùng loại hồ sơ/preset, không phân biệt hoa/thường.
• Nếu storage đầy/không khả dụng hoặc file import sai, UI giữ dữ liệu cũ và bản nháp chưa lưu. Refresh library đọc lại dữ liệu; sửa đồng thời cùng hồ sơ ở tab khác sẽ báo xung đột, có thể lưu bản nháp bằng Save as new copy.
• Thư viện hỏng không tự bị xóa. Export stored data for recovery xuất nguyên nội dung trước khi dùng Reset unreadable library… → Confirm reset. Sau reset, có thể nhập lại backup hợp lệ.

Để chia sẻ hoặc nạp ngay một trận hiện tại, dùng nhóm dưới builder:

• Export JSON tải cấu hình hiện tại thành combat-simulator-config.json.
• Import battle JSON file nạp file cấu hình schema 2. Các trường builder nhận biết được điền lại vào GUI; những trường nâng cao không có control được giữ trong Raw JSON.
• File sai JSON hoặc không có cấu trúc schema 2 cần thiết sẽ hiện thông báo lỗi; file đó không thay cấu hình đang dùng.
• Khi dùng Raw JSON, hãy xuất file lúc đang ở tab Raw JSON để lưu đúng nội dung vừa sửa. Khi ở GUI, file xuất phản ánh các control của GUI cùng các trường nâng cao được giữ lại.

Raw JSON dành cho các trường nâng cao chưa có control. Lưu/tải thư viện dùng cùng kiểm tra cấu trúc như import GUI, không cắt slot hay gộp troop trùng. Việc lưu thành công không bảo đảm tổ hợp combat được core chấp nhận.

4. Wall và lực lượng phòng thủ

Bật Configure a wall để cấu hình wall và lực lượng phòng thủ phía Right:

• Wall defence, maximum và WallHealth là các tham số wall riêng; chúng không phải số lượng lính.
• Defence force gồm 12 ô theo thứ tự: Trap0 T1–T4, Tower T1–T4, Trap2 T1–T4. Mỗi ô hiển thị tên tiếng Anh đã xác minh của công trình theo tier.
• Shared defence attributes áp dụng cấu hình chung cho các công trình trong force. Các channel wall được hỗ trợ và hạn mức có trong JSON reference.
• Pet dùng cùng wall chỉ cho một tập ID giới hạn; UI hiển thị lựa chọn và cảnh báo nếu file nhập có lựa chọn chưa hỗ trợ cùng wall.

Core quyết định wall mode dựa trên cấu hình trận. Chỉ nên bật wall khi cấu hình lính và force tương ứng; nhập tổ hợp không được hỗ trợ sẽ trả lỗi khi chạy.

5. Chạy trận và xem kết quả

Nhấn Run Battle. Nếu cấu hình không hợp lệ hoặc runtime không sẵn sàng, khu vực kết quả sẽ hiện lỗi thay vì kết quả trận.

Phần kết quả có thể gồm:

• Bên thắng, thời gian mô phỏng và terminal tick.
• Weighted loss và casualties theo bên, loại lính, tier.
• Với trận có wall: losses riêng cho Trap0, Tower và Trap2.
• Playback các tick, điều khiển play/pause, tua, chọn tốc độ và chọn unit.
• Timeline state hiện có cho troop, hero, pet, work và defence. Các mã trạng thái chưa được diễn giải đầy đủ có thể được hiển thị dưới dạng mã.
• Observed changes: lọc theo subsystem và nhảy đến sample bằng nút Previous/Next hoặc tick trong danh sách. Với sample cách nhau nhiều tick, thay đổi chỉ được xác nhận trong khoảng đó; tick chính xác chưa biết.

GUI kiểm tra số nguyên và giới hạn trước khi chạy. Import không cắt danh sách vượt năm slot hoặc gộp troop trùng: cấu hình không biểu diễn được sẽ báo lỗi, giữ nguyên cấu hình hiện tại. Raw JSON giữ và gửi nguyên cấu hình nâng cao cho core xác thực.

Tốc độ playback chỉ thay tốc độ xem animation; nó không cấu hình lại trận. Weighted loss là chỉ số loss do simulator trả về, không nên tự coi là điểm Might hoặc điểm KVK.

6. Giới hạn hiện tại

• Không phải mọi mechanic hoặc combination của game đều được hỗ trợ.
• Hero/pet selector là danh sách giới hạn; ID có trong game không đồng nghĩa đã được xác nhận dùng được trong mọi tổ hợp.
• Formation được chọn theo index và hiển thị bằng tên tiếng Anh trong game; không có cam kết về lợi thế chiến thuật cụ thể.
• Tùy chọn JSON chưa có control và tổ hợp ngoài builder cần Raw JSON.
• Combat được thực thi bởi runtime C++; giao diện web nhận cấu hình và trình bày kết quả, không thay thế game client.

Khi simulator báo fixture không hỗ trợ, hãy giữ nguyên thông báo và bỏ trường hoặc combination chưa được xác nhận; không suy diễn giá trị thay thế.