eagle0/docs/TUTORIAL_PLAYTHROUGH.md

# Tutorial Playthrough Notes

This is a working guide for playing through the Eagle0 tutorial without losing. It is written from live text-client
testing, so treat it as a practical checklist rather than a complete design reference.

## Core Rule

Do not risk Sadar Rakon unless the outcome is overwhelmingly favorable. In tutorial games, Sadar is the human faction
leader; if he is captured, the server treats the human player as defeated and the game ends.

## Strategic Goals

- Survive the opening tutorial battle.
- Rebuild Onmaa enough to stabilize support and loyalty.
- Expand carefully from Onmaa/Nikemi with enough force to avoid leader capture.
- Trigger the major strategic tutorial event where The Eagle appears. In code, this happens when Sadar controls at
  least four provinces or Hedrick's faction has no provinces.

## Tactical Safety Rules

- Avoid sending Sadar alone into a tactical battle.
- If a battle turns into a long chase, reassess instead of blindly sweeping the map.
- Prefer preserving Sadar over forcing a marginal province capture.
- When the text client shows no attack command, do not assume the enemy is helpless; they may still be able to win by
  holding, hiding, or outlasting the attacker.

## Known Failure

In one previous Kojaria attempt, Sadar attacked with one battalion, chased Hedrick across the map, failed to force a
decisive win, and was captured. The client did not clearly announce game over at the time; the save later showed Kojaria
held by Hedrick and Sadar listed under `captured_heroes`.

## Live Run Log

### Fresh Tutorial Run

- Started: game `-3568010721410464682`.
- Leader: Sadar Rakon.
- Current objective: start the tutorial from the opening battle and record safe choices.
- Opening battle setup:
  - Rakon's Loyalists at `(8,10)`.
  - Onmaa Defenders at `(7,10)`.
  - Hunters of the Steppe at `(8,11)`.
  - Rationale: keep the two infantry units together on the west-facing line and keep the longbowmen directly behind
    them. Tarn's force begins west/southwest of the defender setup area, and Elena/John arrive later, so the opening
    goal is to preserve the core army rather than overextend.
- Opening battle, day 1: no attacks were available. Ended the turn rather than starting fires or moving forward.
- Opening battle, day 2:
  - Used Hunters of the Steppe for an archery attack against the visible unit at `(7,9)`.
  - Used Rakon's Loyalists for an archery attack against the unit at `(6,10)`.
  - Used Onmaa Defenders for melee against the unit at `(6,10)`.
  - Avoided the offered duel from Rakon's Loyalists against the unit at `(7,9)`. If that unit is Tarn, the duel risks
    Sadar directly before reinforcements have arrived.
- Opening battle, days 3-5:
  - On day 3, only Rakon's Loyalists and Hunters of the Steppe had commands. Used both for archery against the unit at
    `(6,10)`.
  - On days 4 and 5, only Hunters of the Steppe had commands. Used archery against the nearest non-Tarn pressure unit
    rather than retreating or entering melee.
  - This is a danger signal: if Sadar's unit disappears from the command list this early, the opening formation may have
    absorbed too much damage. Keep future attempts more defensive and consider moving Sadar back instead of using every
    available attack.
- Elena Fyar arrived on day 6 as actor `7`, confirming the `elena_reinforcement_round_5` tutorial event. She spawned
  far southwest of the fight with Holy Wave available. Moved her toward the battle first instead of spending Holy Wave
  while isolated; the move consumed her action for the turn.
- John Ranil arrived on day 8 as actor `8`, confirming the `ranil_reinforcement_round_7` tutorial event.
- After John arrived:
  - Moved Hunters of the Steppe back to `(10,11)` instead of taking a weak melee attack.
  - Moved Elena to `(8,7)` to close with the enemy line.
  - Moved John to `(6,4)` to approach from the west.
  - Do not expect reinforcements to appear in immediate melee range. They need one or more turns of marching before they
    can rescue the original defender units.
- Day 10 Holy Wave timing:
  - Moved John adjacent to Elena first.
  - Used Elena's Holy Wave only after John was adjacent, so the action could inspire more than Elena herself.
  - If Holy Wave is available immediately when Elena appears, do not spend it unless she is already adjacent to a
    friendly unit or there is a specific emergency reason.
- Day 11 reinforcement attack:
  - Elena got melee commands against `(7,9)` and `(8,10)`. Chose `(8,10)` first because `(7,9)` had repeatedly looked
    like the Tarn/front-leader unit.
  - Moved John to `(9,9)`, which opened a charge against `(8,10)`.
  - Used John's charge and then his follow-up melee against `(8,10)`.
  - Practical rule: once Elena and John arrive, pair their attacks on the same non-Tarn unit before taking leader-risky
    engagements.
- Probable defeat/reset signal:
  - Continued John melee attacks against `(8,10)` through day 14.
  - After the day-14 melee, the Shardok stream emitted `shardok-reset` for the same battle id
    `ce7be1272b8b4456_1_df540967`.
  - The battle token reset to `6` and commands returned to the original opening placement commands, while Eagle status
    still reported `BATTLE_IN_PROGRESS`.
  - This most likely means the battle was lost, but the text client did not surface the loss explicitly. Treat a reset
    after a long battle as a probable defeat signal unless server state proves otherwise.
  - For the live run, replay the reset battle with a more conservative setup and keep Sadar out of the first contact
    line.
- Replay setup after reset:
  - Rakon's Loyalists at `(10,11)`.
  - Onmaa Defenders at `(8,10)`.
  - Hunters of the Steppe at `(9,11)`.
  - Rationale: put Sadar deep, use Onmaa Defenders as the first contact screen, and keep archers close enough to shoot
    without becoming the front line.
- Replay tactical adjustment:
  - Day 2: enemy units still reached Sadar quickly. Moved Rakon's Loyalists away instead of dueling or meleeing.
  - Day 3: moved Sadar again, then moved Hunters of the Steppe out of melee contact.
  - Day 4-5: continued withdrawing Sadar north/east and pulled the archer back instead of trading melee.
  - Elena arrived with Sadar still alive and mobile. Move Elena east immediately; do not spend Holy Wave while isolated.
  - John arrived after Elena. Use Elena for contact, march John east, and let Sadar contribute only with archery while
    he remains out of melee.
- Second probable defeat/reset:
  - The replay kept Sadar alive through both reinforcements and reached day 20.
  - After repeated John melee against the remaining contact at `(6,7)`, Shardok emitted another `shardok-reset` for the
    same battle id and returned to the original placement command list.
  - This reproduced the reset behavior from the first attempt and likely means the replay was also lost. Stop treating
    the current live game as a successful tutorial source until the loss condition is visible in the text client or
    confirmed from server state.
- Failed castle-hold variant:
  - Onmaa castle tiles are `(6,12)`, `(8,11)`, and `(10,11)`.
  - Rakon's Loyalists at `(10,11)`.
  - Onmaa Defenders at `(8,11)`.
  - Hunters of the Steppe at `(6,12)`.
  - Early result: this was much stronger than the previous formations. When no attacks were available, ended turn
    instead of moving off castles. When longbow shots were offered, used Hunters of the Steppe from `(6,12)`. When
    enemies stepped adjacent, used ordinary castle melee, but continued to avoid duels.
  - What failed:
    - The battle still reset after day 22, returning the same battle id to token `6`.
    - The late phase degraded into too much Holy Wave/Reduce and too little direct pressure. Treat that as the wrong
      plan for this tutorial battle.

### Successful Opening Battle

- Won in game `-3568010721410464682`, battle `ce7be1272b8b4456_1_df540967`.
- Winning setup:
  - Sadar/Rakon's Loyalists at `(10,11)`.
  - Onmaa Defenders at `(8,11)`.
  - Hunters of the Steppe at `(6,12)`.
- Main rule: hold the three castle tiles with the starting units until the enemy gives useful attacks. Do not walk the
  starting units off the castles just because movement commands are available.
- Early turns:
  - End the first defender turn when only movement/fire commands are available.
  - Use Hunters of the Steppe for archery whenever possible, usually into the non-Ikhaan targets at `(5,10)`,
    `(5,11)`, or `(7,10)`.
  - Use ordinary melee from castle tiles when the enemy steps adjacent.
  - Sadar may duel non-Ikhaan targets. In the winning run, actor `4` used `CHALLENGE_DUEL` against targetUnit `2`.
  - Avoid Sadar's duel against targetUnit `3` at `(9,10)`; that target behaved like Ikhaan Tarn. Ordinary melee into
    that adjacent target was still used later, but the duel was skipped every time.
- Reinforcements:
  - Elena arrived as actor `7`. March her directly toward the castle line instead of spending Holy Wave while isolated:
    `(11,3)`, `(8,5)`, `(8,8)`, then `(8,11)`.
  - John arrived as actor `8`. Rush him toward the castles: `(6,4)`, `(10,7)`, then `(8,10)`.
  - Once John and Elena reach the line, use their melee attacks immediately. In the winning run both repeatedly attacked
    the non-Ikhaan target at `(7,10)`.
  - After that target dropped, chase the remaining left-side contact with John and Elena together. John moved to
    `(4,11)`, Elena to `(5,10)`, and John finished the battle with melee at `(5,11)`.
- Do not make Holy Wave or Reduce the plan. The successful run won without using Holy Wave or Reduce in the decisive
  phase; direct archery, castle melee, and reinforcement melee were enough.
- Post-battle aftermath:
  - The battle resolved to Eagle commands and offered three captured heroes: `201`, `202`, and `203`.
  - Recruit attempts were refused for all three, then each was imprisoned.
  - After the captured-hero prompts cleared, normal strategic commands returned at province `14`, starting with
    `ImproveAvailableCommand`.

### Strategic Play After Opening Battle

- Immediate recovery priorities:
  - Improve Onmaa's economy and agriculture before starting a war.
  - Use Alms sparingly if support is low, but watch food and treasury.
  - Train existing heroes/units before marching. The opening win leaves enough time to build before attacking.
- Troop organization notes:
  - Onmaa initially exposed only `LightInfantry` and `Longbowmen` as constructible in the command surface.
  - An invalid organize attempt tried to top up preexisting heavy units and hit the server error
    `HeavyInfantry was not among constructible battalion types Vector(LightInfantry, Longbowmen)`.
  - Safe commands in the live run were:
    - Top up the existing light infantry battalion.
    - Create a new longbow battalion. The text-client payload that worked used numeric enum value `4` for Longbowmen.
  - Do not assume existing heavy battalions can be reinforced just because they already exist in the province.
- Marching rule:
  - Do not march Sadar in the first expansion army. Leave him in Onmaa and send the non-leader army instead.
  - The live run sent Elena, John, Agamemnon, and Old Marek from Onmaa to Nikemi, then on to Kojaria.
  - Send supplies forward after the army reaches Nikemi; do not strand the field army without food.

### Failed Hedrick Attack

- Target: Kojaria, held by Hedrick the Hedge-Merchant's faction.
- Army: four non-Sadar heroes, about 1954 troops, including the new untrained longbow battalion.
- Strategic safety result:
  - This was better than marching Sadar alone. A reset here did not immediately imply player defeat because Sadar
    stayed home.
  - It still appears to be a losing tactical plan.
- Tactical setup:
  - Placed the army on the west edge and advanced toward Hedrick's single 1000-troop stack.
  - A first attempt surrounded Hedrick and used repeated melee. It reset after an infantry melee, likely a loss.
  - A second attempt used more spacing:
    - Move John/engineer to the firing lane first.
    - Use archery whenever it appears.
    - Move cavalry into contact only after ranged damage is available.
    - Avoid actor 0 infantry melee and avoid making Reduce/Holy Wave the core plan.
- What worked better:
  - The stable pattern was archery from actor 0 when available, archery from the new longbows when available, and
    cavalry melee from Old Marek.
  - Extinguishing fire with the longbows was useful when the enemy lit the cavalry contact square.
- What failed:
  - Even with repeated archery and cavalry melee, the battle dragged to day 12 and then reset after another cavalry
    melee.
  - A single late Reduce did not visibly break the stalemate.
  - The new longbow battalion had `0.0` training and `0.0` armament in the stale strategic snapshot, so it may have
    contributed much less than its troop count suggested.
- Practical conclusion:
  - Do not attack Hedrick immediately after creating a raw longbow battalion.
  - Build a stronger army first: train and arm the new longbows, improve the economy/agriculture enough to support
    better reinforcements, and consider taking easier provinces or waiting until the army has more developed units.
  - If attacking Hedrick, treat his 1000-stack as a boss fight. The current safe-looking four-hero army was not enough
    to finish it reliably.