Tham chiếu JSON cấu hình trận (schema 2)

Tài liệu dành cho người dùng cần lưu, chia sẻ hoặc chỉnh sửa cấu hình ngoài các control của GUI Builder. Chỉ các trường nêu ở đây nằm trong phạm vi hỗ trợ đã công bố; JSON hợp lệ về cú pháp vẫn có thể bị từ chối nếu giá trị hoặc tổ hợp không được hỗ trợ.

• Hướng dẫn sử dụng Web UI

Khung cấu hình tối thiểu

{
  "schema": 2,
  "init": {
    "seed": 1,
    "gap": 1,
    "tier_factor": 10000,
    "threshold": 0
  },
  "mode": 1,
  "wall": null,
  "left": {
    "level": 25,
    "formation": 0,
    "troops": [
      {"type": "infantry", "tier": 5, "count": 1}
    ],
    "bonuses": {}
  },
  "right": {
    "level": 25,
    "formation": 0,
    "troops": [
      {"type": "infantry", "tier": 1, "count": 1}
    ],
    "bonuses": {}
  }
}

schema, init, mode, wall, left và right là thành phần cấp cao nhất. Schema 2 yêu cầu init có đủ seed, gap, tier_factor, threshold; mỗi bên cần có level, formation, troops và bonuses. wall có thể là null. Các số nguyên phải là integer JSON: không dùng chuỗi, số thập phân hoặc boolean.

Có thể thêm "description": "..." làm ghi chú. Đây chỉ là metadata, không thay đổi trận.

Tham số chung

Seed và gap không phải bonus chiến đấu. Với mục đích so sánh hai cấu hình, giữ chúng giống nhau; thay đổi chúng có thể làm thay đổi chuỗi random sử dụng.

Cấu hình mỗi bên

Troop record

{"type": "infantry", "tier": 1, "count": 1000}

• type: infantry, ranged, cavalry hoặc siege.
• tier: số nguyên 1–5.
• count: số nguyên dương, tối đa 20 triệu quân tổng mỗi bên.
• Mỗi cặp type/tier chỉ được khai báo một lần. Bỏ hẳn record hoặc đặt count thành 0 không hợp lệ; không dùng record đó nếu không có quân ở tier ấy.

Bonus thông thường

Các giá trị dưới đây là raw value. Quy ước hiển thị là 100 raw tương ứng 1% modifier; giới hạn là giới hạn đầu vào, không phải gợi ý về giá trị nên dùng.

Ví dụ:

"bonuses": {
  "attack": 5000,
  "hp": 10000,
  "reduce_damage": 2500
}

Channel bị bỏ qua dùng giá trị mặc định 0. Chỉ dùng tên channel được liệt kê; channel lạ không được xem là ghi chú.

Override theo troop kind

kind_bonuses là map giữa troop kind và một object chỉ chứa các channel muốn override:

"bonuses": {
  "attack": 1000,
  "hp": 2000
},
"kind_bonuses": {
  "infantry": {"attack": 5000},
  "ranged": {"hp": 0}
}

Trong ví dụ này, Infantry dùng attack 5000 và kế thừa HP 2000; Ranged kế thừa attack 1000 và dùng HP 0; các loại lính không có entry kế thừa cả hai giá trị chung. Giá trị override thay thế, không cộng với bonus chung. Entry {} có nghĩa là kế thừa toàn bộ. Các channel và giới hạn giống bảng bonus thông thường.

Khắc chế (advantages)

advantages là tham số riêng, không nằm trong bonuses hoặc kind_bonuses. Chu trình được tài liệu hóa là Infantry khắc chế Ranged, Ranged khắc chế Cavalry, Cavalry khắc chế Infantry. Object nhận các khóa infantry, cavalry, ranged; mỗi giá trị nguyên 0–100000 raw.

"advantages": {
  "infantry": 5000,
  "cavalry": 5000,
  "ranged": 5000
}

Siege không có khóa advantages trong contract này. GUI Builder có ba ô trong phần Advantages (counters) của mỗi bên. Ô trống bỏ key (mặc định core là 0), nhập 0 giữ key với giá trị 0; 100 raw tương đương 1%. Nạp JSON giữ nguyên các giá trị thưa, kể cả 0. Xóa ô đã nạp loại bỏ riêng key đó khi xuất cấu hình.

Heroes và pets

"heroes": [{"id": 1, "rank": 1, "star": 5}],
"pets": [{"id": 26, "level": 1}],
"hero_ultra": 0

• Hero: id, rank (1–255), star (1–5); tối đa 5 record mỗi bên và tối đa 4 hero cùng troop kind. Selector giao diện liệt kê ID 1, 2, 3, 5, 7, 8, 9, 16, 54; danh sách đó không phải roster đầy đủ.
• Pet: id, level (1–10); tối đa 5 record. Selector liệt kê các ID 13, 17, 19, 24, 26, 28, 29, 30, 31, 32, 36, 41, 43, 48, 49, 50, 58, 59, 67.
• Khi bật wall, pet được chọn trong GUI bị giới hạn ở 19, 24, 26, 28, 29, 30, 31, 32, 41, 43, 50.
• Danh sách và số slot không bảo đảm mọi kết hợp đều hợp lệ. Runtime sẽ trả lỗi nếu resource, hiệu ứng hoặc tổ hợp chưa được hỗ trợ.

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

Khi bật wall, cấu trúc có dạng:

"wall": {
  "defence": 1,
  "maximum": 0,
  "force": [0, 0, 0, 0, 1, 0, 0, 0, 0, 0, 0, 0],
  "health": 10000,
  "attributes": {"attack": 5000}
}

• defence, maximum: số nguyên không âm trong giới hạn u32 của contract.
• force: đúng 12 số nguyên theo thứ tự Trap0 T1–T4, Tower T1–T4, Trap2 T1–T4. Tổng số lượng force tối đa 20 triệu.
• health: tùy chọn, 0–1000000; tham số WallHealth riêng, mặc định 10000.
• attributes: tùy chọn, bonus dùng chung cho các defence unit. Hỗ trợ attack, defence, hp, reduce_attack, reduce_defence, reduce_hp, curse_attack, curse_defence, curse_hp trong 0–1000000 và add_damage, reduce_damage trong 0–100000. Không hỗ trợ magic hoặc override riêng theo category.

Đặt "wall": null nếu không có wall. Wall mode được xác định từ cấu hình lính; không cần tự đặt một trường wall mode.

Import, export và kiểm tra lỗi

Tên resource là lớp hiển thị từ catalog tiếng Anh đã xác minh. JSON chỉ dùng ID/index và thứ tự force hiện tại; tên không phải key nhập và không mở mechanic.

• Web UI Import battle JSON file nhận file JSON schema 2, điền các trường nhận biết vào GUI và giữ các trường nâng cao trong Raw JSON. Dữ liệu không thể biểu diễn nguyên vẹn trong builder được báo lỗi trước khi thay cấu hình; Raw JSON vẫn cho phép nhập nguyên cấu hình để core kiểm tra.
• Export JSON tải cấu hình đang hoạt động. Nếu đang ở tab Raw JSON, nội dung xuất ra là nội dung JSON ở tab đó; ở GUI, export gồm các giá trị form và giữ các trường nâng cao đã nạp mà GUI không có control.
• JSON sai cú pháp, thiếu trường bắt buộc, sai kiểu số, khóa không hỗ trợ, khai báo lặp cùng troop type/tier hoặc combination ngoài phạm vi hỗ trợ có thể bị từ chối. Đọc thông báo lỗi runtime và sửa đúng trường được nêu.
• Khi chỉnh Raw JSON, giữ nguyên các key/giá trị chưa rõ thay vì xóa tùy tiện.

File Army Profiles, Battle Presets và library backup

Các file thư viện dùng envelope version 1, tách khỏi combat JSON schema 2. Envelope không gửi tới /api/run. Import to library nhận envelope hoặc JSON trận schema 2; Import battle JSON file chỉ nạp trận schema 2 vào builder.

Ví dụ Army Profile hợp lệ:

{
  "format": "combat-simulator-army-profile",
  "version": 1,
  "profile": {
    "name": "Infantry army",
    "notes": "",
    "army": {
      "level": 25,
      "formation": 0,
      "troops": [{"type": "infantry", "tier": 5, "count": 1000}],
      "bonuses": {},
      "advantages": {"infantry": 0}
    }
  }
}

profile.army là toàn bộ object của một bên, không có wrapper left/right, init hay wall. Các trường side tùy chọn dùng cùng contract ở trên.

Battle Preset có format: "combat-simulator-battle-preset", version: 1 và object preset gồm name, notes, battle. preset.battle là toàn bộ trận schema 2, gồm wall và cả hai đội quân. Export JSON của trận hiện tại vẫn trả riêng schema 2, không có metadata thư viện.

Library backup có format: "combat-simulator-library", version: 1, mảng armies và presets. Mỗi record có id, name, notes, created_at, updated_at (timestamp dạng chuỗi), cùng army hoặc battle. Import tạo ID mới, thêm hậu tố cho tên trùng và giữ timestamp từ backup; không ghi đè dữ liệu cũ. Tên phải khác nhau trong từng loại (không phân biệt hoa/thường), tối đa 100 ký tự; notes là chuỗi tối đa 2000 ký tự, có thể rỗng.

Toàn bộ file được kiểm tra trước khi ghi. Version chưa hỗ trợ, key JSON trùng, numeric token thập phân/exponent, số nguyên không biểu diễn chính xác hay cấu trúc builder không biểu diễn được đều bị từ chối. Các trường combat nâng cao được giữ; core vẫn kiểm tra mechanic khi chạy. Dữ liệu thư viện chỉ lưu trong trình duyệt theo địa chỉ site; xem hướng dẫn để backup và phục hồi storage.

Kết quả đầu ra

Giao diện hiển thị bên thắng, thời gian/tick, weighted loss và casualties theo loại/tier. Nếu có wall, defence loss được hiển thị riêng. Playback cho xem các tick đã ghi nhận và trạng thái quan sát được. Weighted loss là chỉ số loss của simulator, không được tài liệu hóa như điểm Might/KVK.