eagle0/docs/TUTORIAL_BATTLE_SYSTEM.md

Tutorial Battle System

This document describes the current opening tutorial battle. It is based on the live implementation in TutorialGameCreation.scala, TutorialBattleController.cpp, ShardokGamesManager.cpp, ResolveBattleAction.scala, and the Unity dialogue scripts.

For the Unity tutorial UI/dialogue architecture, see TUTORIAL_SYSTEM.md. For copy and content notes, see TUTORIAL_CONTENT.md.

---

Current Flow

When a player creates a tutorial game at the default OpeningBattle phase:

1. TutorialGameCreation.createTutorialGame() creates a GameType.Tutorial(TutorialPhase.OpeningBattle) game starting in RoundPhase.BattleRequest.
2. Province 14, Onmaa, belongs to Sadar Rakon's faction and already has a defending army.
3. Bregos Fyar's faction has a hostile attacking army, led by Ikhaan Tarn, already moving from province 31 to Onmaa.
4. RequestBattlesAction immediately creates the Shardok battle and tags tutorial reinforcement hero IDs 100 and 101.
5. GamesManager stores the generated TutorialBattleConfig for this game and passes it to Shardok when the battle starts.
6. Shardok creates the battle with the configured timed reinforcement events.
7. Unity plays the active dialogue scripts from tutorial_strategic.json and tutorial_battle.json.

There is also a tutorial phase-start path. Starting after OpeningBattle applies precomputed tutorial setup results from TutorialPhaseResultsLoader; this is why the Unity post-battle trigger logic handles a "battle was never observed" auto-resolve path.

---

Battle Setup

Defender: Sadar Rakon's Faction

Configured in src/main/resources/net/eagle0/eagle/tutorial_parameters.json:

• Faction ID: 3
• Province: 14, Onmaa
• Starting support: 23
• Starting resources: 50 gold, 4000 food
• Heroes: Sadar Rakon, Old Marek the Learned, Agamemnon
• Battalions:
  • Rakon's Loyalists: Light Infantry, 529 size, 80 training, 75 armament
  • Onmaa Defenders: Light Infantry, 311 size, 80 training, 60 armament
  • Hunters of the Steppe: Longbowmen, 478 size, 80 training, 60 armament

Attacker: Bregos Fyar's Faction

The opening attacking army is configured under Bregos Fyar's attackingArmies:

• Faction ID: 2
• Origin province: 31
• Destination province: 14, Onmaa
• Heroes: Ikhaan Tarn, Tall Edgtheow, Waylaid Julius, Luke the Prank-tricker
• Battalions:
  • Doomriders: Heavy Cavalry, 592 size, 80 training, 80 armament
  • The Shardok's Guard: Heavy Infantry, 507 size, 80 training, 80 armament
  • Bowmen of Nikemi: Longbowmen, 291 size, 80 training, 80 armament
  • Swift Sabres: Light Cavalry, 450 size, 80 training, 80 armament

Tarn's unit is made visible to the defender from the start through TutorialBattleConfig.initial_visibilities.

---

Reinforcements

The current tutorial config has two timed reinforcement events. It does not currently configure a scripted Tarn flee event.

Event ID	Trigger	Hero ID	Hero	Battalion
elena_reinforcement_round_5	End of round 5 or later	101	Elena Fyar	Fyar's Vanguard, Heavy Infantry, 535 size, 75 training, 75 armament
ranil_reinforcement_round_7	End of round 7 or later	100	John Ranil	Ranil's Riders, Heavy Cavalry, 458 size, 80 training, 80 armament

Shardok creates reinforcement units at battle creation time with PENDING_REINFORCEMENT status. TutorialBattleController activates them when their event triggers and returns a TUTORIAL_REINFORCEMENTS_ARRIVED action result. Unity maps that action to profession-specific dialogue triggers:

• tutorial_reinforcement_paladin for Elena Fyar
• tutorial_reinforcement_engineer for John Ranil

The reinforcement action includes an attacker_starting_position_index; Shardok resolves that to currently open map positions and starts a reinforcement placement phase.

---

Scripted Event Controller

TutorialBattleController is a generic event-driven controller, even though the current tutorial battle only uses timed reinforcements.

Supported trigger types:

• after_round
• units_lost
• damage_taken
• unit_killed

Supported action types:

• flee
• reinforcements

Events are checked at the end of each round, evaluated in config order, and each event_id fires at most once.

---

Battle Resolution

RequestBattlesAction marks tutorial opening battles with reinforcementHeroIds = Set(100, 101). ResolveBattleAction uses that metadata so reinforcement heroes are accepted when battle results return, even though they were not part of the original defending army.

After the opening battle resolves, ResolveBattleAction applies TutorialTarnDisappearsAction for GameType.Tutorial(TutorialPhase.OpeningBattle). Tarn is removed from captured/unaffiliated province state and from his faction's leaders list, matching the post-battle dialogue that he has vanished.

TutorialBattleAutoResolve provides a synthetic defender victory for tutorial setup paths that skip past the opening battle. In that synthetic result:

• The defender wins.
• Reinforcement heroes 100 and 101 survive.
• Tarn is marked outlawed/escaped.
• Other attacker heroes are captured.
• Defender battalions take about 30% casualties.
• Attacker battalions are destroyed.

---

Unity Dialogue Hooks

Strategic tutorial dialogue:

• game_started: opening Onmaa monologue, ending with FightButton highlighted.
• tutorial_battle_ended: post-battle aftermath.
• tutorial_rebuild_support: support rebuilding guidance after captured-hero handling is done.

Battle tutorial dialogue:

• shardok_placement_started: placement and unit overview.
• shardok_battle_running: first player turn guidance.
• Ability/terrain triggers such as archery_available, melee_available, ability_charge_available, start_fire_available, thunderstorm, duel_available, hide_available, and engineer_near_enemy.
• Reinforcement triggers tutorial_reinforcement_paladin and tutorial_reinforcement_engineer.
• Capture triggers enemy_hero_captured and friendly_hero_captured.
• shardok_battle_reset: replay dialogue after a battle reset.

---

Files To Check First

File	Purpose
src/main/resources/net/eagle0/eagle/tutorial_parameters.json	Tutorial map, factions, starting provinces, armies
src/main/scala/net/eagle0/eagle/service/new_game_creation/TutorialGameCreation.scala	Opening battle setup and TutorialBattleConfig creation
src/main/protobuf/net/eagle0/common/tutorial_battle_config.proto	Scripted event config schema
src/main/cpp/net/eagle0/shardok/server/ShardokGamesManager.cpp	Adds pending reinforcement units and applies initial visibility
src/main/cpp/net/eagle0/shardok/library/tutorial/TutorialBattleController.cpp	Evaluates scripted events and creates Shardok action results
src/main/scala/net/eagle0/eagle/library/actions/impl/action/RequestBattlesAction.scala	Creates the opening battle and tags reinforcement hero IDs
src/main/scala/net/eagle0/eagle/library/actions/impl/action/ResolveBattleAction.scala	Resolves reinforcements and applies Tarn disappearance
src/main/scala/net/eagle0/eagle/service/tutorial/TutorialBattleAutoResolve.scala	Synthetic result for phase-start paths after the opening battle
src/main/csharp/net/eagle0/clients/unity/eagle0/Assets/Tutorial/Triggers/TutorialTriggerRegistry.cs	Converts strategic and tactical events into dialogue triggers
src/main/csharp/net/eagle0/clients/unity/eagle0/Assets/Resources/Dialogues/tutorial_battle.json	Active battle dialogue content

---

Testing Checklist

• Tutorial game starts in BattleRequest and creates an Onmaa battle immediately.
• Opening strategic dialogue highlights the Fight button.
• Tarn's unit is visible to the defender from battle start.
• Placement dialogue fires during setup.
• First-turn battle-running dialogue fires on the player's first active turn.
• Elena Fyar arrives from the configured round-5 event.
• John Ranil arrives from the configured round-7 event.
• Reinforcement arrival dialogues fire once per hero.
• Battle reset clears battle dialogue completion for replay.
• Post-battle aftermath fires after the battle leaves RunningShardokGameModels.
• Rebuild-support dialogue waits until captured-hero handling and visible notifications are done.
• Starting a tutorial at a later phase uses precomputed setup and still reaches coherent strategic dialogue state.