heros/README.md

Heroes of Three Kingdoms

Godot 4 tactical RPG prototype inspired by classic turn-based Romance of the Three Kingdoms games. The current editor baseline is Godot 4.6.

Current Slice

• Sixty-seven campaign scenarios.
• Campaign chapters group the scenario order into story arcs.
• Grid movement.
• Unit selection.
• Move, attack, wait, end turn.
• Enemy AI with movement, damage-aware physical attacks, multiple MP tactic choices, and scenario target priorities that events can retune mid-battle.
• Hover tile and unit info with class, movement type, AGI, movement, range, and equipped gear.
• Enemy threat range overlay with tile-level threat source, physical damage hints, and hostile tactic hints.
• Damage forecast for selected-unit attacks.
• Terrain defense and avoid affect physical attack damage and hit chance.
• Min/max attack ranges and counterattack forecasts.
• MP tactics with low/high damage options, area damage/healing/status options, ally support buffs, enemy debuffs, movement and accuracy/evasion modifiers, poison damage-over-time, seal/snare/disarm action locks, a skill list menu, previews, and target overlays.
• Campaign inventory consumables with an item menu, HP/MP recovery, poison/seal/snare/disarm and debuff cure previews, and target overlay.
• Weapon, armor, and accessory rewards can be stored, displayed, compared, equipped, and unequipped from the battle HUD; some weapons deal bonus physical damage against matching move types.
• First named equipment rewards exist in the northern campaign arc and show a [Named] or Named tag in reward, inventory, shop, Armory, and equipment menus.
• Scenario-specific pre-battle shop purchases, optional finite shop stock, and 50% sell-back save immediately and sync into the upcoming battle inventory.
• Pre-battle shop rows emphasize item artwork, compact price/status badges, and hover details instead of dense inline text.
• Pre-battle Talk can list scenario camp conversations by officer or topic, branch them from saved campaign choices, grant one-time pre-battle supplies, and shop stock can include merchant flavor lines before a battle.
• Pre-battle Armory equipment changes, including unequipping gear back into stock, save immediately and sync roster equipment plus inventory stock, with portrait and item-icon rows plus hover change details.
• Pre-battle Roster can move optional officers between sortie and reserve within scenario limits, using portrait rows, compact status badges, and hover details.
• Pre-battle Formation lets deployed officers swap starting positions inside scenario-defined cells, with portrait rows, coordinate badges, and hover placement instructions.
• Pre-battle briefing shows the campaign chapter, chapter battle number, location, victory/defeat summary, and first-clear reward preview.
• Pre-battle Chapters overview shows story-arc progress and can open completed or current battles.
• Pre-battle Save menu can write and load one manual campaign checkpoint separate from the automatic save.
• The title screen exposes Start, Load, and Settings, and Load now lets the player choose between the automatic record and the manual checkpoint.
• Victory results show compact reward icons for gold, items, and officer roster changes, with hover details for the full reward text.
• Escort scenarios can include required, non-controllable protected units.
• Campaign saves joined officers, future deployments can require prior recruitment, and choices can make officers leave.
• Completed saves reconcile officer join/leave rewards on load without replaying gold or items.
• Post-battle choices save a scenario-to-choice id ledger for safer future branch migrations.
• Reloading during a pending post-battle choice returns to the choice panel instead of skipping the branch.
• Qingzhou victory can recruit Dian Wei, backed by a new Warrior class.
• Puyang uses Dian Wei as a required joined officer and introduces a Lu Bu branch choice.
• Dingtao consumes the Puyang branch flags and rewards a stronger axe.
• Wan Castle consumes the imperial escort branch flags and adds a protected Cao Ang escape map.
• Xiapi consumes the Wan Castle branch flags and adds a flood-gate siege against Lu Bu.
• Xiapi victory recruits Guo Jia, and White Horse starts the northern campaign with a decoy-line battle.
• Yan Ford consumes the White Horse branch flags and adds Wen Chou's countercharge before Guandu.
• Guandu consumes the Yan Ford branch flags and adds Yuan Shao's main assault.
• Wuchao consumes the Guandu branch flags and adds a depot-burning raid with seized in-battle supplies.
• Cangting consumes the Wuchao branch flags, breaks Yuan Shao's rear guard, and recruits Zhang He.
• Ye consumes the Cangting branch flags and lets Zhang He deploy against the Yuan heirs.
• Ye Siege consumes the Ye campaign branch flags and stages an inner-gate breach.
• Ye Surrender consumes the siege branch flags and settles the city before the Yuan heirs flee north.
• Northern Pursuit consumes the Ye surrender branch flags and pushes Yuan Shang's rearguard north from Ye.
• Nanpi Pressure consumes the Northern Pursuit branch flags and breaks Yuan Tan's outer line.
• Nanpi Surrender consumes the Nanpi Pressure branch flags and settles Yuan Tan's last loyalists.
• Bohai Remnants consumes the Nanpi Surrender branch flags and scatters the Yuan brothers' covering force.
• Liaoxi Pursuit consumes the Bohai Remnants branch flags and intercepts Yuan envoys seeking Wuhuan support.
• White Wolf Mountain consumes the Liaoxi Pursuit branch flags and breaks the first Wuhuan command ridge backing the Yuan exiles.
• Liaodong Pursuit consumes the White Wolf Mountain branch flags and forces the Yuan fugitives against Liaodong's border.
• Xinye Advance consumes the Liaodong Pursuit branch flags and opens Cao Cao's southern advance into Jing Province.
• Changban Pursuit consumes the Xinye Advance branch flags and forces Liu Bei's bridge guard at Changban.
• Jiangling Chase consumes the Changban Pursuit branch flags and seizes Jing Province's river storehouses.
• Xiakou Pursuit consumes the Jiangling Chase branch flags and pushes the river campaign toward Red Cliffs.
• Red Cliffs Fleet consumes the Xiakou Pursuit branch flags and tests Cao Cao's chained fleet against the coalition vanguard.
• Red Cliffs Fire consumes the Red Cliffs Fleet branch flags and turns the chained-fleet battle into a fire attack.
• Huarong Retreat consumes the Red Cliffs Fire branch flags and forces Cao Cao through the coalition roadblock after the fleet burns.
• Jiangling Rearguard consumes the Huarong Retreat branch flags and steadies Cao Cao's southern withdrawal before the next front.
• Tong Pass Vanguard consumes the Jiangling Rearguard branch flags and opens the western campaign against Ma Chao's riders.
• Ma Chao Counterstroke consumes the Tong Pass Vanguard branch flags and tests Cao Cao's pass line against the western cavalry charge.
• Weishui Camps consumes the Ma Chao Counterstroke branch flags and turns the Wei River line into a test of ground and alliance trust.
• Weishui Crossing consumes the Weishui Camps branch flags and turns the western campaign from river defense into a Guanzhong foothold.
• Guanzhong Foothold consumes the Weishui Crossing branch flags and turns the seized riverbank into a western base against Ma Chao's rearguard.
• Ma Chao Retreat consumes the Guanzhong Foothold branch flags and drives the western campaign toward Guanzhong pacification or the Hanzhong front.
• Hanzhong Approach consumes the Ma Chao Retreat branch flags and opens Zhang Lu's mountain gate campaign.
• Hanzhong Gate consumes the Hanzhong Approach branch flags and opens Zhang Lu submission or Hanzhong pacification follow-up choices.
• Hanzhong Settlement consumes the Hanzhong Gate branch flags and turns the basin toward a Hanzhong garrison or Ruxu pivot.
• Ruxu Advance consumes the Hanzhong Settlement branch flags and opens Ruxu bank or Sun Quan river-line follow-up choices.
• Ruxu River Line consumes the Ruxu Advance branch flags and introduces water-move enemy boats along the riverbank.
• Ruxu Crossing consumes the Ruxu River Line branch flags and turns Ruxu toward an eastern crossing base or Fancheng relief.
• Fancheng Relief consumes the Ruxu Crossing branch flags and uses a protected Fancheng messenger defense objective.
• Jingzhou Supply Line consumes the Fancheng Relief branch flags and cuts Guan Yu's supply road after the siege break.
• Maicheng Pursuit consumes the Jingzhou Supply Line branch flags and seals Guan Yu's retreat road toward Maicheng.
• Jing Province Settlement consumes the Maicheng Pursuit branch flags and settles the Jing Province command post before the next court summons.
• Luoyang Summons consumes the Jing Province Settlement branch flags and opens the court road toward Wei's next transition.
• Wei Succession consumes the Luoyang Summons branch flags and secures the succession dais before the next frontier decision.
• Eastern Front Alarm consumes the Wei Succession branch flags and returns the campaign to the Ruxu river front as Wu tests the transition.
• Wu River Line consumes the Eastern Front Alarm branch flags and breaks open the Ruxu river line for an anchored fleet or Jianye pressure.
• Jianye Approach consumes the Wu River Line branch flags and presses the lower Yangtze approach toward a secured route or forced Wu counterstroke.
• Wu Counterstroke consumes the Jianye Approach branch flags and breaks Wu's forward answer into a held lower Yangtze route or Jianye gate pressure.
• Jianye Gate consumes the Wu Counterstroke branch flags and breaks the outer gate line toward a secured gate road or forced capital sortie.
• Jianye Sortie consumes the Jianye Gate branch flags and contains the capital sortie toward a held siege road or inner-city pressure.
• Inner Jianye consumes the Jianye Sortie branch flags and opens the inner city toward a secured road or forced Wu last stand.
• Jianye Command consumes the Inner Jianye branch flags and breaks the command district toward secured city order or forced Wu surrender.
• Wu Surrender consumes the Jianye Command branch flags and turns the command district victory toward accepted surrender or pursued Wu holdouts.
• Southern Holdouts consumes the Wu Surrender branch flags and clears the southern canal camp toward settled holdouts or a pressed Nanhai route.
• Nanhai Route consumes the Southern Holdouts branch flags and cuts the coastal passage toward a secured route or pressed southern fleet.
• Southern Fleet consumes the Nanhai Route branch flags and breaks the coastal anchorage toward a secured fleet or pressed Hainan coast.
• Hainan Coast consumes the Southern Fleet branch flags and breaks the shore road toward a secured coast or pressed final harbor.
• Final Harbor consumes the Hainan Coast branch flags and ends the southern harbor line toward secured order or pursued last captains.
• Last Captains consumes the Final Harbor branch flags and settles the remaining captain ledgers toward registered order or pursued sea exiles.
• Sea Exiles consumes the Last Captains branch flags and breaks the outer coast toward settled exiles or pressed outer islands.
• Outer Islands consumes the Sea Exiles branch flags and breaks the island refuge toward secured islands or pressed hidden coves.
• Post-battle choices can save campaign flags that branch later briefing text, shop stock, and scenario events.
• Scenario post-battle dialogue can play before the victory result panel.
• Basic battle EXP, level-ups, and core first-tier class promotion routes.
• Victory results split rewards, roster changes, saved growth, campaign status, and pending choices into readable sections.
• Scenario events for battle start, battle-begin dialogue, turn start, movement-triggered ambushes, unit-defeat reactions, after_event prerequisites, objective updates with HUD notices, item and gold pickups, reinforcements, scripted unit withdrawals, and AI target-priority shifts.
• Scenario briefing before battle with a campaign battle header and objective summary.
• Victory rewards and consumed inventory saved into a campaign state.
• Scenario-defined victory and defeat conditions.
• Destination-style victory conditions with single-tile, multi-cell, and event-gated objective map markers.
• Protected-unit defeat conditions for escort battles.
• Turn-limit defeat conditions with turn-limit HUD display.
• Live objective panels in the active HUD and briefing split objective, progress, and risk details, including gated unlocks, destination markers, defeated enemy counts, named protected-unit safety, and turns remaining.
• Next-battle flow after victory.
• Campaign completion screen.
• New campaign save reset.
• Manual campaign checkpoint save/load.
• Cinematic title screen uses the battlefield backdrop and Cao Cao portrait art, offers start/load/settings, leads new campaigns through a short Cao Cao and Xiahou Dun opening prologue, exposes the same audio/edge-scroll settings from the top in-game toolbar, and persists BGM/SFX volume, sound toggles, and edge-scroll preference in user://heros_settings.json.
• Victory and defeat result overlay.
• Dialogue portrait slot with officer default image paths, optional per-line overrides, and speaker-initial fallback.
• Initial AI-generated photorealistic officer portraits for Cao Cao, Xiahou Dun, Xiahou Yuan, Cao Ren, Dian Wei, Guo Jia, and Zhang He.
• AI-generated scenario battlefield backgrounds, transparent class units, transparent generic-enemy units, and transparent item icon assets live under art/backgrounds, art/units, and art/items.
• Battle HUD portrait thumbnails show the selected unit, or a hovered unit when nothing is selected.
• Selected and hovered unit focus text shows combat role, movement type, current terrain move cost, terrain bonuses, core stats, and status effects.
• Dialogue lines can place the portrait on the left or right side of an expanded visual-novel-style dialogue panel with progress and previous-line controls.
• Placeholder menu/battle BGM plus UI, movement, attack, tactic, item, victory, and defeat SFX.
• Floating combat text for damage, recovery, misses, support effects, poison ticks, action locks, level-ups, and promotions.
• Short unit slide animation for board movement.
• Board attacks now request class-specific motion profiles, with infantry strikes, archer traces, cavalry charges, command flashes, and heavy warrior/bandit impacts drawn by the battle scene.
• Damage, healing, and support tactics now request distinct cast motion profiles with flare, sigil, and banner-style battlefield effects.
• Battle maps can use a high-resolution background image with translucent terrain overlays, terrain-specific detail patterns, connected roads, shoreline/castle/forest/hill edge blends, transparent generic-enemy class art, and token marks.
• Hover target preview badges for attacks, tactics, and items.
• Low-HP board unit warning rings, HP bar color states, and board status pips plus HUD duration summaries for support, debuff, poison, seal, snare, and disarm effects.
• Data-driven scenario setup through JSON definitions and deployments.

Run

1. Install Godot 4.
2. Open this folder as a Godot project.
3. Run the project. The main scene is res://scenes/battle_scene.tscn.

Campaign order and chapter ranges live at res://data/campaign/campaign.json. Scenarios live under res://data/scenarios/, with reusable officers, classes, items, skills, and terrain definitions under res://data/defs/. Generated visual assets live under res://art/portraits/, res://art/units/, res://art/items/, and res://art/backgrounds/. Placeholder BGM and SFX live under res://audio/.

Data files and item icon cutouts can be checked with powershell -NoProfile -ExecutionPolicy Bypass -File tools\validate_data.ps1.

Godot 4.6 migration readiness can be checked with powershell -NoProfile -ExecutionPolicy Bypass -File tools\check_godot46_readiness.ps1. The migration checklist lives in docs/GODOT_4_6_MIGRATION.md.

Direction

The project should grow from a small playable battle into a campaign tactics RPG:

• Battle system first.
• Scenario and event scripting second.
• Progression, equipment, and class depth third.
• Portraits, cutscenes, and campaign presentation after the core loop is fun.

The code keeps portraits and other visual assets replaceable so generated original assets can be upgraded without changing battle rules.