# KeyRota documentation

> KeyRota is a Windows and macOS app that presses a World of Warcraft rotation. Besides the game's own suggestion
> (the "Blizzard" profile) it runs advanced rotations written in KRC (KeyRota Customization): a priority list of rules
> over up to 12 slots (buttons), up to 12 auras (your buffs and your debuffs on the target), resources in percent,
> the enemy count, the distance to the target and quick panel toggles. This index points AI agents to the full
> documentation, the rotation JSON format, its JSON Schema and real example rotations, in every language of the site.

Key facts for writing a rotation:
- A rotation file is JSON with "format": "keyrota-rotation" and "version": 1. Unknown fields are rejected, so do not add "$schema".
- Rules are checked top-down; the first rule whose conditions hold and whose spell can be used now is pressed. A rule whose spell cannot be used (cooldown, resource, range, no target) falls through to the next rule.
- A rule holds when any of its groups ("when": OR) holds; a group holds when all its conditions ("all": AND) hold. No not, != or parentheses: use up/down, ready/oncd, glow/noglow, inverse operators and several groups.
- Limits: 12 slots, 12 auras, 16 groups per rule, 16 conditions per group, condition numbers are integers 0-100.
- Resources, health, aura time left and cooldowns are percentages. Combo points out of 7: "at least 5" is Combo_Points >= 70, "at most 3" is Combo_Points < 50.
- An absent aura has duration 0 and stacks 0: refresh a DoT with X.up and X.duration <= 30 plus a separate X.down group. One stack reads as 0.
- An unknown value makes every condition that reads it false (both X.up and X.down).
- cd == 1 is the Burst button, not a spell cooldown (a slot's cooldown is X.cd). defensives == 1 is the Healing / defense button (off by default). aoe/st are the target mode: Auto is aoe == 0 and st == 0.
- Slot flags: offGcd (O) presses at once, even mid-GCD; offGcd + queue (OQ) waits for the spell queue window at the end of the GCD (macros whose second line is on the GCD, buttons that need the previous hit's result); channel (C) presses nothing while it channels; manual (M) is never pressed. queue requires offGcd.
- Use real spell IDs from Wowhead for every slot and aura; an aura's ID is the buff or debuff ID, which can differ from the spell that applies it.
- Labels, rule names and comments may be in any language; aliases (the names used in conditions) are best kept in plain English.

## Advanced rotations (English)

- [Overview](https://keyrota.app/documentation/en/advanced): what an advanced rotation is, how KeyRota chooses and presses a button
- [Rotation builder](https://keyrota.app/documentation/en/editor): the editor page by page, the Better Assistant profile, a worked example
- [Rotation JSON](https://keyrota.app/documentation/en/rotation-json): every field, defaults, spec IDs and resources, slot flags, names, limits, errors, KRC text
- [Conditions](https://keyrota.app/documentation/en/conditions): every condition type, operators, percentages, combo point table, toggles, unknown values
- [Pattern examples](https://keyrota.app/documentation/en/patterns): complete small rotations in text and JSON for common tasks
- [Building with an AI agent](https://keyrota.app/documentation/en/ai): prompt template, log analysis, testing and iteration
- [Advanced FAQ and troubleshooting](https://keyrota.app/documentation/en/faq): why a rule doesn't fire, presses early or late, breaks a channel

## Using KeyRota (English)

- [Documentation overview](https://keyrota.app/documentation/en/): where to start
- [First steps](https://keyrota.app/documentation/en/start): download, install, the first launch, the licence, connecting the game, F1
- [Questions and answers](https://keyrota.app/documentation/en/questions): everyday problems: Better Assistant not visible, Logitech G HUB, the game folder, nothing is pressed, updates, language

## Machine-readable

- [JSON Schema of the rotation JSON (draft 2020-12)](https://keyrota.app/documentation/keyrota-rotation.schema.json)
- [Advanced rotations documentation in English, one Markdown file](https://keyrota.app/documentation/krc-guide.en.md)
- [Advanced rotations documentation in Russian, one Markdown file](https://keyrota.app/documentation/krc-guide.ru.md)
- [Advanced rotations documentation in German, one Markdown file](https://keyrota.app/documentation/krc-guide.de.md)
- [Advanced rotations documentation in French, one Markdown file](https://keyrota.app/documentation/krc-guide.fr.md)
- [Advanced rotations documentation in Spanish, one Markdown file](https://keyrota.app/documentation/krc-guide.es.md)
- [Advanced rotations documentation in Italian, one Markdown file](https://keyrota.app/documentation/krc-guide.it.md)
- [Advanced rotations documentation in Portuguese (Brazil), one Markdown file](https://keyrota.app/documentation/krc-guide.pt.md)
- [Advanced rotations documentation in Korean, one Markdown file](https://keyrota.app/documentation/krc-guide.ko.md)
- [Advanced rotations documentation in Chinese (Simplified), one Markdown file](https://keyrota.app/documentation/krc-guide.zh.md)
- [Advanced rotations documentation in Chinese (Traditional), one Markdown file](https://keyrota.app/documentation/krc-guide.zh-TW.md)

## Examples (English; every example also exists as <name>.<language>.json and .txt for en, ru, de, fr, es, it, pt, ko, zh, zh-TW)

- [Assassination raid rotation, 15 rules](https://keyrota.app/documentation/examples/assassination-raid.en.json) ([KRC text](https://keyrota.app/documentation/examples/assassination-raid.en.txt))
- [Minimal rotation](https://keyrota.app/documentation/examples/minimal.en.json) ([KRC text](https://keyrota.app/documentation/examples/minimal.en.txt))
- [Outlaw raid and Mythic+ rotation, flags O, OQ and C](https://keyrota.app/documentation/examples/outlaw-raid.en.json) ([KRC text](https://keyrota.app/documentation/examples/outlaw-raid.en.txt))
- [Starter Assassination rotation (the builder walkthrough)](https://keyrota.app/documentation/examples/starter-assassination.en.json) ([KRC text](https://keyrota.app/documentation/examples/starter-assassination.en.txt))
- [Syntax sample with every condition and flag, not for combat](https://keyrota.app/documentation/examples/syntax-every-condition.en.json) ([KRC text](https://keyrota.app/documentation/examples/syntax-every-condition.en.txt))

## Other languages

- [Russian: Продвинутые ротации (KRC)](https://keyrota.app/documentation/ru/advanced)
- [German: Erweiterte Rotationen (KRC)](https://keyrota.app/documentation/de/advanced)
- [French: Rotations avancées (KRC)](https://keyrota.app/documentation/fr/advanced)
- [Spanish: Rotaciones avanzadas (KRC)](https://keyrota.app/documentation/es/advanced)
- [Italian: Rotazioni avanzate (KRC)](https://keyrota.app/documentation/it/advanced)
- [Portuguese (Brazil): Rotações avançadas (KRC)](https://keyrota.app/documentation/pt/advanced)
- [Korean: 고급 로테이션(KRC)](https://keyrota.app/documentation/ko/advanced)
- [Chinese (Simplified): 高级循环（KRC）](https://keyrota.app/documentation/zh/advanced)
- [Chinese (Traditional): 進階循環（KRC）](https://keyrota.app/documentation/zh-TW/advanced)

The documentation has an address for every site language (/documentation/en/, /documentation/ru/, /documentation/de/, /documentation/fr/, /documentation/es/, /documentation/it/, /documentation/pt/, /documentation/ko/, /documentation/zh/, /documentation/zh-TW/); a page not translated yet shows the English text there.