eagle0/docs/TUTORIAL_CONTENT.md

Tutorial Content Guide

This document describes tutorial content. The active tutorial experience is driven by the narrative dialogue JSON files under src/main/csharp/net/eagle0/clients/unity/eagle0/Assets/Resources/Dialogues/.

The older step-based modal/overlay content in TutorialContentDefinitions.cs is currently dormant: RegisterAll() returns before registering any sequences. Keep that in mind when editing this file; changing TutorialContentDefinitions.cs will not affect the live tutorial until the early return is removed and the overlap with dialogue triggers is audited.

---

Onboarding Sequence

Shown to first-time players. Guides them through the basics of strategic and tactical gameplay.

Step	ID	Display	Trigger	Title	Description
1	welcome	Modal	Auto (game start)	Welcome to Eagle0	Command your armies, recruit heroes, and conquer provinces in this turn-based strategy game. Let's walk through the basics!
2	select_province	Overlay	Completes on: province_selected	The Strategic Map	This is your kingdom. Each colored region is a province. Tap a province you control (shown in your color) to see what you can do there.
3	province_panel	Modal	Button click	Province Information	This panel shows province details: its name, terrain, any armies present, and the commands available to you. Commands let you move troops, recruit heroes, and more.
4	try_march	Overlay	Completes on: command_issued	Issue a Command	Try issuing a March command to move your army to an adjacent province. Select a destination and confirm the order.
5	turn_cycle	Modal	Button click	The Turn Cycle	Eagle0 uses simultaneous turns. All players give orders at the same time, then turns resolve together. When all players are ready, the server processes everyone's commands and shows the results.
6	wait_for_battle	Hidden	Completes on: first_battle_available	(none)	(Invisible step - waits for a battle to become available)
7	battle_intro	Modal	Button click	Battle Time!	When armies collide, you'll fight tactical battles on a hex grid. You command individual units - infantry, cavalry, archers, and heroes with special abilities.
8	enter_battle	Overlay	Completes on: battle_entered	Enter the Battle	Tap the Battle button to enter tactical combat.
9	tactical_overview	Modal	Button click	Tactical Combat	Each unit has movement points and attack power. Position your troops wisely! Units attack adjacent enemies. Flanking (attacking from multiple sides) deals bonus damage.
10	move_unit	Overlay	Completes on: battle_action	Move Your Units	Tap one of your units to select it, then tap a highlighted hex to move there. Blue hexes show where you can move.
11	attack_enemy	Overlay	Completes on: battle_action	Attack!	Move next to an enemy unit, then tap the enemy to attack. Red highlights show valid attack targets.
12	end_turn	Overlay	Completes on: turn_ended	End Your Turn	When you've moved all units or want to pass, tap End Turn. The enemy will then take their turn.
13	complete	Modal	Button click (no skip)	You're Ready!	You now know the basics of Eagle0! Explore diplomacy, recruit powerful heroes, and conquer the realm. Good luck, commander!

Notes on Onboarding Flow

• Steps 1-5 cover strategic gameplay
• Step 6 is invisible - just waits for a battle
• Steps 7-12 cover tactical combat
• Step 13 celebrates completion

Questions to consider:

• Should we skip tactical tutorial if player skips to first battle themselves?
• Should there be a "skip all" option visible from step 1?
• Is the step order correct for typical first-game flow?

---

Strategic Contextual Tutorials

Triggered when players encounter features for the first time.

Diplomacy Introduction

Field	Value
ID	diplomacy_intro
Trigger	diplomacy_available (diplomacy commands appear)
Display	Modal
Title	Diplomacy
Description	You can negotiate with other factions! Offer alliances, declare war, or propose tribute. Your diplomatic choices shape the realm.

Hero Recruitment

Field	Value
ID	hero_recruitment
Trigger	hero_recruitment_available (free heroes detected)
Display	Modal
Title	Heroes Available
Description	Free heroes wander the realm seeking a lord to serve. Recruit them to lead your armies! Heroes have unique abilities and grow stronger with experience.

Weather Control

Field	Value
ID	weather_control
Trigger	weather_control_available (weather command appears)
Display	Overlay
Title	Weather Magic
Description	Your mages can influence the weather! Rain slows movement, storms disrupt enemies, and clear skies speed your march.

Prisoner Management

Field	Value
ID	prisoner_management
Trigger	prisoner_command_issued (player uses prisoner command)
Display	Modal
Title	Prisoners Captured
Description	You've captured enemy soldiers! You can ransom them for gold, recruit them into your army, or execute them as a warning.

---

Tactical Contextual Tutorials

Triggered during battles when players encounter spells, terrain, or abilities.

Lightning Bolt Spell

Field	Value
ID	spell_lightning
Trigger	spell_lightning_available
Display	Tooltip
Title	Lightning Bolt
Description	Your mage can cast Lightning Bolt! This spell strikes a single target for heavy damage. Great for eliminating key enemy units.

Meteor Strike Spell

Field	Value
ID	spell_meteor
Trigger	spell_meteor_available
Display	Modal
Title	Meteor Strike
Description	Meteor is a devastating area spell! It takes a turn to cast: first select target, then it lands next turn. Plan ahead!

Holy Wave Spell

Field	Value
ID	spell_holywave
Trigger	spell_holywave_available
Display	Tooltip
Title	Holy Wave
Description	Holy Wave heals your units and damages undead! Position your troops carefully to maximize its effect.

Raise Dead Spell

Field	Value
ID	spell_raisedead
Trigger	spell_raisedead_available
Display	Modal
Title	Raise Dead
Description	Dark magic can raise fallen soldiers as undead! They fight for you, but beware - they may crumble if your necromancer falls.

Fire Terrain

Field	Value
ID	terrain_fire
Trigger	terrain_fire_encountered (fire damage occurs)
Display	Tooltip
Title	Fire Hazard
Description	Fire spreads across the battlefield! Units in burning hexes take damage. Use fire to block enemy routes or avoid it yourself.

Water Crossing

Field	Value
ID	terrain_water
Trigger	terrain_water_encountered (water crossing attempted)
Display	Tooltip
Title	Water Crossing
Description	Units can cross shallow water, but it's risky. Crossing takes extra movement and may fail. Some units swim better than others.

Cavalry Charge

Field	Value
ID	ability_charge
Trigger	ability_charge_available
Display	Overlay
Title	Cavalry Charge
Description	Your cavalry can Charge! Charging deals bonus damage based on distance traveled. Use open terrain for maximum impact.

---

Post-Battle Dialogue (Narrative Dialogues)

These fire after the first tutorial battle ends and the player returns to the strategic map. They use the narrative dialogue system (DialogueManager / tutorial_strategic.json) rather than the modal tutorial system.

Battle Aftermath

Field	Value
ID	post_battle_aftermath
Trigger	tutorial_battle_ended (battle removed from RunningShardokGameModels)
Speaker	Old Marek the Learned
Panel Position	top

Dialogue (Marek):

That was closer than I'd like to admit. We held — barely. But Tarn... Tarn is gone. Not retreated — gone. The men say he vanished from the field. Some claim sorcery. Others say he slipped away in the chaos. Whatever the truth, no one can find him.

But we captured some of his lieutenants. These are soldiers, Sadar — they followed orders, same as we once did. They're not to blame for Tarn's madness. See if you can bring them to our cause, or at least hold them until they come around.

Instructions: (none — Handle Captured Heroes UI is self-explanatory)

Rebuild Support

Field	Value
ID	post_battle_rebuild
Trigger	tutorial_rebuild_support (fires when available commands no longer include HandleCapturedHeroCommand)
Speaker	Old Marek the Learned
Panel Position	top

Dialogue (Marek):

Good. Now we need to rebuild our support here in Onmaa. The people are shaken — a battle on their doorstep will do that. We need them behind us if we're going to hold this province.

Any of our heroes can develop the land or give alms to the people — nothing wins hearts faster than a full belly. Engineers like John Ranil are especially effective at improving a province, and paladins like Elena Fyar are the best at winning hearts. Either way, we need the people's support before the tax collectors come round in January.

Instructions: John Ranil's step highlights ImproveProvinceButton and explains Improve. Elena Fyar's step highlights GiveAlmsButton and explains Give Alms. You must have at least 40 support in the province by January in order to collect gold and food in taxes.

Highlight targets: ImproveProvinceButton, GiveAlmsButton

Implementation Notes

• Both dialogues are defined in tutorial_strategic.json.
• tutorial_battle_ended fires from TutorialTriggerRegistry.CheckTutorialBattleEnded() when the opening battle is gone and strategic commands are available. It also handles the server-side auto-resolve path where the Unity client never observed a running Shardok model.
• tutorial_rebuild_support fires from TutorialTriggerRegistry.CheckTutorialRebuildSupport() when available commands no longer include HandleCapturedHeroCommand and the notification panel has no visible info.
• ImproveProvinceButton and GiveAlmsButton are runtime command-button targets registered by CommandButtonPanelController.

---

Display Modes

Mode	Description	Use For
Modal	Full popup with dimmed background, blocks interaction	Important concepts, multi-paragraph explanations
Overlay	Semi-transparent overlay, can highlight UI elements	Guiding player to interact with specific UI
Tooltip	Small popup near target element	Quick tips, less important info
Hint	Pulsing dot indicator only	Subtle suggestions
None	Invisible, just waits for event	Transition steps

---

Adding New Tutorials

1. Add entry to this document
2. For active tutorial content, add or edit a script in Assets/Resources/Dialogues/tutorial_strategic.json or tutorial_battle.json.
3. Ensure the trigger event exists in TutorialTriggerRegistry.cs or is fired directly by the relevant controller.
4. If reviving the dormant step-UI system, remove the early return in TutorialContentDefinitions.RegisterAll() only after auditing duplicate trigger coverage with the dialogue JSON.
5. Test the flow.

---

Content Guidelines

• Keep descriptions to 2-3 short paragraphs max
• Use <br><br> for paragraph breaks (renders as newlines in Unity)
• Avoid jargon - explain game terms when first introduced
• Be encouraging, not condescending
• Focus on "what to do" not exhaustive "how it works"