Reference
How it works
The engine, the order triggers resolve in, determinism, saved data, performance and what stays stable across versions.
AutoBattleKit has four layers. Each depends only on the layers above it in this list, so you can replace the lower ones (for example, use your own UI) without touching the engine.
| Layer | Folder | Assembly | What it does |
|---|---|---|---|
| Engine | Scripts/Runtime/Core | AutoBattleKit.Runtime | Runs a battle from plain C# data: teams, rules, seed. No Unity objects needed. |
| Blocks | Scripts/Runtime/Abilities | AutoBattleKit.Runtime | Conditions and effects that abilities are made of, plus their plain-English text. |
| Content | Scripts/Runtime/Content | AutoBattleKit.Runtime | ScriptableObject assets (items, statuses, classes, enemies, rulesets, databases) that turn into engine data. |
| Presentation | Scripts/Runtime/Presentation | AutoBattleKit.Runtime | Sound cues, placeholder sounds, procedural animation, tooltips. Reads the battle log; never changes a battle. |
| Editor | Scripts/Editor | AutoBattleKit.Editor | The Hub window, inspectors, settings, importers, doc generator. |
| Demos | Demos | AutoBattleKit.Samples (+ .Editor) | Everything under Demos can be deleted without breaking the kit. |
| Tests | Scripts/Tests | AutoBattleKit.Tests.Editor | Edit-mode tests. Compiled only when the Test Framework package is installed. |
How a battle runs
- Each side is a
TeamSetup: units (front to back) and side-wide relics. A 1v1 battle is two teams of one. new BattleEngine(player, enemy, statuses, rules, seed).Run()plays the whole battle and returns aBattleResult(winner, rounds, log entries, events).- Everything that happens is an event (a trigger plus who it happened to). When an event fires, every listening ability on every unit is collected, sorted and resolved:
- higher
priorityfirst, - then the unit the event happened to (or the player side, see
listenerOrder), - then passives, items (slot order), statuses (in the order they were gained),
- then the order they were found.
- Effects that cause new events (damage causes Damaged, OnHit, OnStruck...) queue them. The queue resolves after the current action, first in, first out. "Before" events (BeforeStrike, BeforeStruck, BeforeDamaged, BeforeDeath) resolve immediately, so their abilities can cancel or change the action.
- The same content, rules and seed always give the same battle. Randomness comes only from the battle's own seeded generator.
Determinism and the fingerprint
The kit ships a regression guard: Tools › AutoBattleKit › Demos › Engine Fingerprint runs 11,520 sample battles and hashes every log line. If you change the engine and the hash changes, a battle somewhere now plays out differently. If that's intended, update the baseline in EngineRegression.cs.
Logging off for speed
Set engine.Logging = false (or pass log: false) for simulations. Outcomes are identical; nothing is recorded, and battles run several times faster. The Balance Lab also runs battles on every CPU core, which is safe because each battle owns all of its state.
Saved data
Conditions and effects are saved with [SerializeReference], which stores their class name, namespace and assembly. Keep the AutoBattle namespace and the AutoBattleKit.Runtime assembly name for your own blocks (or use [MovedFrom] when renaming), and only ever add new enum values at the end: enums are saved as numbers.
Versioning and API stability
From 1.0, the kit follows semantic versioning. Within 1.x nothing public is removed or changed: Scripts/Tests/Editor/PublicApi.txt lists every public type and member, and a test fails if any of them disappears. New types, members and blocks can still be added. When something has to go, it's first marked [Obsolete] and removed only in 2.0. Blocks are saved in your items by class name, so a renamed block always carries [MovedFrom] and your items keep working.
Performance
Hub › Performance measures battles per second and memory per battle with your own content and rules. A battle is pure C#: no scene objects, no Unity update loop. It runs in well under a millisecond with typical content, so compute it when a fight starts and animate the log afterwards. Games without replays can turn the log off (BattleEngine.Logging = false) for a large speed-up and much less garbage.