Combat Simulator Web User Guide

This guide explains how to configure a battle, run it, and review the results. The web interface uses the simulator's currently supported parameters; it does not represent every feature available in the game.

• Battle JSON reference

1. Configure both sides

In GUI Builder, enter the setup for Left and Right:

The starter battle has one Left Infantry T5 and one Right Infantry T1, ready to run. Replace those counts or import your own configuration.

• Troop count: the number of troops for each type and tier. Leave a value at 0 or blank when that type/tier is not part of the army. The supported total is up to 20 million troops per side.
• Castle Level: a value from 1 to 75. The level is used when determining capacity for the army setup; use the appropriate level for your fixture or keep the default if unsure.
• Formation: choose one of the six presets shown with its English in-game name; the number in parentheses is the value stored in JSON. Official Vietnamese names have not been verified, and a preset name does not guarantee a particular battle outcome. Presets: Infantry Phalanx (0), Ranged Phalanx (1), Cavalry Phalanx (2), Infantry Wedge (3), Ranged Wedge (4), Cavalry Wedge (5).
• Stat bonuses: default adjustments for the side being configured. Values are raw values, not percentages typed directly.
• Per-kind stat overrides: optionally replace a default bonus for one troop kind. A blank field inherits the side bonus; an entered value, including 0, replaces that channel for that kind. It is not an additional bonus.
• Advantages (counters): separate inputs for Infantry → Ranged, Cavalry → Infantry and Ranged → Cavalry on each side. Enter raw integers 0–100000. Blank uses the default 0 and omits the key; entering 0 stores an explicit zero. Siege has no counter input.
• Heroes / Pets: add a slot and select an English name with its ID, rank/star or level. The selector lists only IDs with confirmed support, not a complete roster. The current limit is five heroes and five pets per side. Not every combination has been verified, and the simulator may reject unsupported combinations.

The resource lists are intentionally limited; names and behavior that have not been confirmed are not inferred. Use Raw JSON for parameters that do not have a builder control.

Names come from verified game resources. Name mapping, core support and individual oracle battle coverage are separate statuses. Names do not change JSON IDs; packages without the optional catalog retain numeric labels.

2. Bonuses and input units

For raw bonus values, 100 = 1% modifier; for example, 5000 corresponds to a 50% modifier. Exact limits differ by channel and are listed in the JSON reference.

The channel names are intended to identify the type of adjustment:

• attack, defence, hp: attack, defence, or HP adjustments.
• reduce_attack, reduce_defence, reduce_hp: corresponding reduction channels.
• curse_attack, curse_defence, curse_hp: corresponding curse channels.
• add_damage, reduce_damage: additional-damage or damage-reduction channels.
• magic: magic channel.
• advantages: the Infantry, Ranged and Cavalry counter relationship, entered under Advantages (counters) or through Raw JSON. It is separate from bonuses and kind_bonuses.

The curse_* and add_damage channels set by one side affect the corresponding channel of the opposing troop kind; reduce_* and reduce_damage belong to the side that sets them.

You do not need to fill every channel. If you do not have a supported value, leave it at 0 or blank as indicated instead of guessing a bonus.

3. Save and load configurations

Army Profiles save one army independently of its side: level, formation, troops, bonuses, overrides, advantages, heroes, pets, hero-ultra and retained advanced fields. Choose Save Left as profile or Save Right as profile, enter a name and optional notes, then Save. You can save one army while the other is still being corrected.

Search names/notes and select a profile to preview it. Selection does not change the battle. Apply to Left, Apply to Right and Apply to Both create independent copies. Editing Left after applying Both changes neither Right nor the saved profile. Global parameters and the wall are outside an Army Profile.

Open Manage selected profile → Edit to change its name, notes or Army JSON. Use current Left/Right army replaces the editor draft; only Save updates the stored profile. Duplicate opens a new profile draft; Save as new copy keeps an edited draft under a new identity. Delete → Confirm delete removes the saved copy and keeps the current battle. Cancel or Escape discards dialog changes.

Battle Presets save the full configuration: both armies, seed/gap/tier factor/threshold, mode, wall/force/attributes, description and advanced fields. Save current battle reads the active tab, including Raw JSON. Load preset restores a copy into GUI and Raw JSON while retaining the active tab. Later battle edits do not update storage; use Edit → Use current battle → Save to update explicitly. Presets also support search, rename, duplicate, delete and individual export.

Left → Right, Right → Left and Swap armies move all army fields, including advanced data. Global parameters and the wall stay with the battle; the wall always belongs to Right under the current schema.

The library is stored in this browser for the site's protocol, hostname and port. It has no server or cross-device synchronization; changing the port uses a different storage area. Export a backup before moving addresses, clearing browser data or relying on a private browser session.

• Import to library accepts an Army Profile, Battle Preset, version 1 library backup, or schema 2 battle (saved as a preset). Imports add copies with new IDs and suffix duplicate names, leaving existing records and the current battle intact. Import does not automatically apply a configuration.
• Export library backup downloads combat-simulator-library.json. Export under each management section downloads an individual profile or preset in a version 1 envelope, distinct from combat schema 2 JSON.
• Names are limited to 100 characters and notes to 2000. Names must be unique within profiles or presets, ignoring case.
• Storage quota/access failures and invalid imports keep previous data and unsaved editor drafts. Refresh library rereads storage. Concurrent edits of the same record report a conflict; Save as new copy preserves your draft.
• Corrupt stored data is never reset automatically. Export stored data for recovery downloads its original text before Reset unreadable library… → Confirm reset. A valid backup can then be imported.

To exchange or immediately load the current battle, use the controls below the builder:

• Export JSON downloads the current configuration as combat-simulator-config.json.
• Import battle JSON file loads a schema 2 configuration. Fields recognized by the builder are populated in the GUI; advanced fields without controls remain in Raw JSON.
• Invalid JSON or a file missing the required schema 2 structure produces an error and does not replace the current configuration.
• When using Raw JSON, export while the Raw JSON tab is active to save the edited content. In GUI mode, export reflects the builder controls and retains imported advanced fields.

Use Raw JSON for advanced fields without builder controls. Library saves/loads use the GUI import preflight and reject unrepresentable data without clipping slots or merging troops. Saving a configuration does not establish combat support for its combination.

4. Wall and defence forces

Enable Configure a wall to configure a wall and the Right-side defence forces:

• Wall defence, maximum, and WallHealth are wall parameters, not troop counts.
• The defence force has 12 slots in this order: Trap0 T1–T4, Tower T1–T4, and Trap2 T1–T4.
• Shared defence attributes apply to the configured defence units. Supported channels and limits are listed in the JSON reference.
• Only a limited pet ID set is selectable with a wall. An imported unsupported wall/pet choice remains visible with a warning.

The core determines the effective wall mode from the battle configuration. Configure troops and force consistently; unsupported combinations are rejected when the battle is run.

5. Run a battle and review results

Click Run Battle. If the configuration is invalid or the runtime is unavailable, the result area displays an error instead of a battle result.

Results may include:

• Winner, simulation time, and terminal tick.
• Weighted loss and casualties by side, troop kind, and tier.
• Separate Trap0, Tower, and Trap2 losses for battles with a wall.
• Tick playback with play/pause, seek, speed selection, and unit selection.
• Available troop, hero, pet, work, and defence observer timelines. State codes whose meaning is not fully mapped may be shown as numeric codes.
• Observed changes: filter by subsystem and jump to a sample using Previous/Next or the listed tick. Changes between sparse samples are known only within that interval; the exact intervening tick is unknown.

GUI fields check integer values and bounds before running. Import reports unrepresentable data, including more than five resource slots or duplicate troops, while preserving the previous configuration. Raw JSON retains advanced input for authoritative core validation.

Playback speed changes only how the animation is viewed; it does not change the battle setup. Weighted loss is a simulator loss metric and should not be assumed to be Might or KVK score.

6. Current limitations

• Not every game mechanic or combination is supported.
• Hero and pet selectors are limited; an in-game ID is not automatically valid in every combination.
• Formations are selected by index and displayed using English in-game names; the interface does not promise a tactical advantage.
• Advanced JSON fields without controls and combinations outside the builder require Raw JSON.
• Battles are executed by the C++ runtime. The web interface configures and presents results; it does not replace the game client.

If the simulator rejects a fixture, use its error message and remove or adjust the unsupported field or combination. Do not guess a replacement value.