Heroes of the
Seventh Year

The player commands the defense of a great wall — the most critical barrier between the kingdom and the forces that would destroy it. Appointed by the king himself, the player holds the second most powerful position in all the realm.

Every year, a new cohort of volunteers arrives at the wall. These are not conscripts — they are ambitious men and women who see service as a path to upward mobility in a world with few such opportunities. The promise is simple: survive and defend for seven years, and you return home a hero. Many will die. A rare few will become legends.

The wall is described as vital to the kingdom's survival. The king has a vested interest in its success and will intervene with additional resources when things go badly — but no resource drop replaces the loss of battle-hardened veterans.

Geography & Isolation

The kingdom occupies a valley entirely enclosed by impassable mountains. There is one way in and one way out — the valley mouth, where the wall stands. There is no outside world to flee to, no distant ally to call upon, no alternative. The people have always known this. It shapes everything about how they live and what they value.

The kingdom is predominantly agrarian — farmers, herders, and small-holders working land that has been in families for generations. The only settlement of any size is simply called the City. A small middle class of traders, merchants, and craftspeople operates primarily there. The nobility is tiny and largely ceremonial; real power flows from the king and the wall.

Tone

The world is grim but not hopeless. The threat of the raiders is not an abstraction — everyone understands that if the wall falls, the kingdom ends. This understanding sits quietly in the back of every citizen's mind from childhood onward. It does not paralyze them. It makes them serious.

The Wall in the Cultural Psyche

The wall is the single most important structure in the kingdom — militarily, economically, and psychologically. Every citizen grows up knowing what it is and what it means. Parents tell children about the wall before they can read. Tavern songs recount famous battles. The raiders are referred to simply as the enemy, the invaders, or — in stories told to children — the monsters. They have no other name. They need none.

Adolescents who show promise train and apprentice with the explicit hope of one day qualifying as recruits. Service at the wall is the most direct path to meaningful social advancement in a society with few such paths. To be selected is already an honor.

Seven-Year Heroes

Recruits who survive seven full years of service and are released honorably are known as heroes — not as a courtesy title, but in the fullest sense the culture understands the word. They return home to land grants and property deeds from the crown. Their names are known everywhere. Children ask to hear their stories. Taverns hang their names on the wall. They are the living proof that the wall can be held and that ordinary people can become extraordinary ones.

This hero culture is not incidental — it is the kingdom's primary mechanism for maintaining morale and a steady supply of volunteers across generations. Without it, the wall would not stand.

Key Figures

The Enemy

The forces that assault the wall are referred to as the raiders or the invaders. They have no known name, civilization, or recorded history in kingdom lore — only the pattern of their attacks and the destruction they leave behind. To children they are simply called the monsters. No recruit has ever returned from behind enemy lines. No one knows what lies beyond the valley mouth except death.

Flavor System

Each recruit receives a bespoke bio and greeting organized by gender (M/F) and age (young/old). Approximately 250 bespoke bios are planned, targeting meaningful emotional investment in individual soldiers. This system is in progress.

The game is structured as a series of years. Each year consists of exactly two phases: an Off Season and a Battle. The game runs for 10, 20, or 30 years depending on chosen difficulty.

Recruits cycle through multiple generations over the course of the game. Players will outlast several cohorts of soldiers, which creates tension between emotional attachment and strategic detachment.

The off season is a pure resource allocation phase — not a spatial building or city-management sim. Players decide how to spend their gold across competing priorities. The phase is structured as a linear wizard with Next and Previous buttons, allowing unidirectional progress while preserving the ability to revisit prior decisions. Gold is spent first, then recruits arrive, then deployments are set.

Gold Economy

Each off season the player receives:

• — Base tax: 100, 150, or 200 gold — rolled randomly at the start of each off season (equal probability)
• — +1 gold per missing wall HP across all segments (comeback mechanic)
• — +200 gold per fully destroyed wall segment (a breached segment is a significant silver lining)

Recruit Arrival

After all gold is spent, new recruits arrive to fill every empty housing slot across all buildings. The composition is random but skewed to balance the current roster:

• — The system checks the current ratio of unit types (e.g. 5 Warriors vs 15 Archers)
• — Incoming recruits skew toward underrepresented types. The goal is an even final split within each building's capacity, ±1 unit per type. Full rules in Section VI — Recruit Generation Rules.
• — Only archetypes supported by existing buildings can appear (no Mages without a Library)
• — Masons and Scouts fill their own specialist housing (Artisan Workshop, Scout Academy) and are not part of the combat unit distribution logic

Off Season Priorities

Off Season Wizard Flow

The off season proceeds as a multi-step wizard. Players navigate with Next and Previous buttons. State is preserved when going back — no choices reset unless explicitly changed. Each step is described below.

Character Generation

Recruit generation is triggered after building choices are confirmed in Step 5. The full rules governing class distribution, name assignment, portrait allocation, and bio selection are documented in Section VI — Recruit Generation Rules.

The off season does not begin with gold counts or building menus. It begins with the dead, and then with the heroes. This is the cultural spine of the kingdom made tangible — the moment the player is asked to hold, however briefly, what the last battle actually cost and what it produced.

The two ceremonies are sequential and separate. Steps 1 and 2 of the off season wizard. Each is skipped automatically if there is nothing to show.

Part One — The Fallen

The first screen of every off season (except Year 1, when there has been no prior battle) presents all soldiers who died in the most recent battle as a list. If no soldiers died, this screen is skipped entirely.

Part Two — The Heroes

Immediately following the fallen ceremony (or opening the off season directly if no one died), the game presents any soldiers who completed their seventh year of service. A soldier who survived their seventh battle is a hero by right. If no soldiers reached hero status this year, this screen is skipped entirely.

New recruits are generated at the moment the player confirms their building and spending choices (Off Season Step 6). Every empty housing slot across all buildings is filled. The process follows a strict sequence: determine class distribution first, then generate each individual recruit in that class.

Step 1 — Determine Total Incoming Recruits

Count empty housing slots across all buildings after spending is confirmed. Each empty slot produces exactly one recruit. Slot counts are building-type-specific:

• — Barracks — Each level provides 10 housing slots. Slots are shared between Warriors and Archers.
• — Library — Each level provides 5 housing slots. Slots are shared between Mages and Healers.
• — Artisan Workshop — Each level provides 10 Mason housing slots. Masons fill their own pool independently.
• — Siege Workshop — Each level provides 1 Engineer housing slot.
• — Officer Academy — Each level provides 1 Captain housing slot (max 5 total Captains).
• — Scout Academy — Each level provides 1 Scout housing slot.

Step 2 — Determine Class Split (Barracks & Library)

For buildings that house two classes (Barracks: Warriors/Archers; Library: Mages/Healers), incoming recruits are distributed using a roster-balancing algorithm. Each pairing is calculated independently.

Algorithm: The goal is an even final split within that building's total capacity, ±1 unit per type. Count the current number of living soldiers of each class within the pair. Determine how many of each class are needed to reach an even split of the building's total capacity. Assign the incoming recruits accordingly. The result is that after recruits arrive, each class occupies between (capacity/2 − 1) and (capacity/2 + 1) slots. The same logic applies independently to Mages vs Healers within Library slots.

Step 3 — Generate Each Recruit

Once class counts are determined, each recruit is generated individually in sequence. Portrait is assigned first because the portrait pool is divided by gender and age — drawing a portrait determines those attributes, which then drive name and bio selection.

Greetings

Each soldier has a greeting drawn from a data table keyed by class × year of service (years 1–7). The greeting is selected randomly from the pool matching the soldier's current class and current year of service. A new greeting is selected each off season — it is not fixed at generation time.

Greetings are displayed on the character detail screen (accessed from the Personnel table in Step 7) in the format:

"Commander [playername], [greeting]"

The greeting pool covers all eight classes across all seven years of service. Year 1 greetings reflect the uncertainty and ambition of a new recruit; later years reflect the weight of experience and survival. The same pool is used regardless of gender or age.

Generation Order & Edge Cases

Year of Service Tracking

Year of Service is a persistent integer on each soldier object, incremented at the end of each battle they survive. A soldier who arrives at the start of Year 3 and survives through Year 9 has 7 years of service and becomes a hero at the end of Year 9's off season ceremony. The wall's promise is seven survived battles — not seven calendar years of enrollment.

Each year brings one battle. The wall is divided into three sections. Units assigned to a wall section cannot move during battle — they hold their ground. Warriors and Captains are never assigned to wall sections; they are always held in reserve. The player's real-time tactical decisions come from managing reserves and adjusting targeting preferences.

Map & Wall Layout

The battlefield is 12 tiles wide × 16 tiles tall, rendered at 46 pixels per tile (canvas: 552 × 736 px). The wall sits at row 11 (0-indexed from the top), giving approximately 10 rows of enemy approach space and 4 rows of player territory behind the wall.

Wall Protection

The wall is a barrier with HP. Enemies cannot reach player units until the wall is breached (HP reaches zero). Only ranged enemies (Goblins, Catapults) can damage player units directly while the wall stands. Goblins cannot damage the wall itself — they are purely a unit-killing threat.

Melee enemies (Orcs, Ogres, Generals) attack the wall directly. Catapults deal AoE damage that hits both wall HP and player units on the wall; AoE splash does not affect units currently standing on the wall (the wall provides cover).

The wall grants a damage reduction bonus to all player units on it equal to 1% per foot of wall height:

When the wall falls, all units on it drop to ground level and lose the damage reduction bonus. Breaching enemies then target the nearest ground unit. Engineers and reserve units on the player side become valid targets after any breach.

Targeting Rules

Player Units

Enemy Units

Enemy targeting override: if any wall is breached or any player unit crosses into enemy territory, all wall-targeting enemies switch to targeting the nearest player unit instead. This reverts to wall-targeting if neither condition holds.

Targeting Preferences (Player Control)

Players can override default targeting for three groups via dropdowns displayed below the battle canvas. Preferences are saved to localStorage and persist between sessions.

Healer is excluded from targeting preferences — it targets friendly units for healing, not enemies.

Battle Start — Countdown

Each battle begins with a 3–2–1–FIGHT! countdown (1 second per number, 0.7 seconds for "FIGHT!"). The game loop is frozen during the countdown so the player can review and adjust targeting preferences before combat begins.

Slow Motion

A Slow Mo checkbox appears to the right of the targeting controls. When enabled, game time runs at 25% speed. Useful for studying unit behavior and making deployment decisions under pressure. State persists between sessions alongside targeting preferences.

Surprise Tactics

If the player has any tactics stockpiled, a button strip appears below the targeting controls bar. Each available tactic is shown as a button with a distinct icon and label. Buttons are visible from the start of the battle. Activating a tactic consumes it immediately — the button is removed and the effect fires at once. The strip is hidden if the stockpile is empty. See Section VIII-C — Surprise Tactics for full effect descriptions.

Year Win Condition — Enemy Retreat

Enemies retreat (rout) when all Ogres, Generals, and Catapults are dead AND remaining enemy count is below 50% of the year's starting total AND player units outnumber remaining enemies. Retreating enemies run toward the top of the screen and can still be attacked as they flee. The round ends when either:

• — All active enemies have left the screen (player victory)
• — All player units are dead — wall units, reserves, and Engineers (total wipe = game over)

When rout triggers, all mobile player units (non-stationary, non-reserve) are released from any hold orders so they can give chase, including reinforce-hold warriors waiting behind the wall.

Enemy Compositions

Each year has 3 possible enemy composition variations (options A, B, C) randomly selected at the start of battle. Compositions are defined per year in src/data/compositions.js and include lane assignments, reserve slots, deployment logic, and a scouting report string. Years 1–3 are fully defined; remaining years use a placeholder stress test until authored.

Reserve System

Three reserve slots exist on both the player side (rows 14–15) and enemy side (rows 0–1). Reserve units are inert until deployed — they are skipped by targeting, movement, and attack logic and cannot be targeted by the opposing side.

Player Reserve Deployment

Pre-assigned before battle, deployed via an in-battle Deploy button. Tapping Deploy opens a 2-row selection grid:

Deployment is one-way — there is no recall. All undeployed player reserves are automatically released on wall breach.

Enemy Reserve Deployment

Enemy reserves deploy based on per-composition logic:

• — wait_for_breach — Deploys when any wall section is breached
• — left / center / right_after_delay — Deploys after 20 seconds OR on any wall breach, whichever comes first; all timed slots share a single 20-second timer so they release simultaneously, but each slot advances toward its own designated wall section independently

Alarm condition: if any player unit crosses into rows 0–7 (deep enemy territory), all undeployed enemy reserves release immediately.

Engineer Placement

Engineers are stationary and deployed on the player side of the wall (row 12), not on the wall itself. Their range of 11 tiles covers nearly the full map length, allowing them to fire trebuchet-style over the wall at enemies on approach.

Elite Enemy Kill Announcements

When an Ogre, General, or Catapult is destroyed, a kill announcement displays on screen identifying the player unit that landed the killing blow. Killing blow XP for these units is tripled (6 XP).

Combat Resolution

Combat is auto-battler style. Each unit follows its targeting rules and behavior patterns; outcomes are driven by matchups, levels, positioning, and building bonuses. The player controls deployment, timing, and targeting preferences — not individual unit actions.

Battle Outcomes

Recruits arrive as generalists and specialize based on buildings available. Each archetype is enabled by a corresponding building. Without the building, that unit type cannot be recruited or developed. Attack speed values are given as seconds per attack; the floor is 0.5s regardless of bonuses.

Combat Unit Stats

Noncombatant Units

Visual Indicators

Units within the aura radius of a friendly Captain or enemy General display a dim gold border (postFX glow). This helps players immediately identify which of their units are receiving the damage bonus — and which enemy units are benefiting from a General's presence. The gold glow is temporarily replaced by a blue glow when a Healer heals a unit.

Fully Developed Stats (Level 5, All Buildings Maxed)

For reference — reaching this state requires significant long-term investment across multiple building trees.

Experience & Deployment Risk

Units earn XP through combat actions. A killing blow awards 2 XP; an assist (minimum 30% of target HP dealt) awards 1 XP; taking damage awards 1 XP (awarded to surviving units at battle end); Healers earn 1 XP per 50 HP healed. Killing blow XP is tripled (6 XP) when the target is an Ogre, General, or Catapult.

On each level-up, a unit also randomly gains either +1–3 bonus HP or +1–3 bonus DMG (50/50 chance). This bonus is permanent and stacks with the fixed per-level stat increases shown in the table above.

All player units have a 5% base critical hit chance on every attack. A critical hit deals triple damage. Enemies do not crit. Sharpshooter Archers raise their personal crit chance to 30%. On a crit, the target briefly flashes a bright red glow.

Engineers gain a maximum of one level per battle, regardless of XP earned.

Attack Speed Floor

Minimum attack interval is 0.5 seconds regardless of building bonuses.

When a unit reaches Level 3, they become eligible to specialize. Specialization is a permanent, one-time choice that meaningfully changes how a unit fights. There are two paths per class, each expressed as an adjective before the class name (e.g. Mounted Warrior, Sharpshooter Archer).

How Specialization Works

• — When a unit levels to 3 in battle, a brief announcement fires: "[Name] reached Veteran rank!"
• — The actual specialization choice is deferred to the next off season's Training & Specialization step (Step 3).
• — Specialization stats are applied at battle spawn time alongside building bonuses.
• — The choice is permanent — no respec is available.

Visual Identity

Specialized units use a distinct color tint on their sprite so they are recognizable in the field while their base class icon (bow, sword, staff, etc.) remains unchanged. The base class is always readable; the tint communicates which path was chosen.

Specialization Paths

Once per year, King Aldric sends one of his generals to the wall to train the defenders in a surprise tactic. This award is presented during the Gold Summary step of the off-season wizard (Step 4), starting with Year 2. The flavor text acknowledges last year's battle outcome — the king is paying attention, and his help is a direct response to what the wall endured.

Stockpile Rules

• — Year 1's battle begins with no tactics available. The stockpile starts empty.
• — One random tactic is awarded each year at the Gold Summary step (Year 2 onward).
• — Stockpile maximum is 3. If already at 3, no new tactic is awarded that year.
• — Unused tactics carry over between battles.
• — Each tactic is single-use: consumed immediately on activation.

Battle Activation

All available tactics appear as buttons in a strip below the targeting controls bar. Each button has a distinct icon and label. When a tactic is activated, the button is removed and the effect fires immediately. The strip is hidden when the stockpile is empty.

Surprise Tactic List (V1 — Complete Set)

Enemy forces escalate over the course of the campaign, introducing new unit types and tactical approaches that require the player to adapt their defenses year over year.

Enemy Unit Stats

Move Speeds

Move speed values in tiles per second (Sprint 1 starting values — subject to playtesting tuning):

Elite Unit DPS Scaling

Enemy Compositions

Each year has three possible enemy compositions (A, B, C) randomly selected at battle start. Each composition defines unit assignments per lane (left, center, right), reserve slot contents, reserve deployment logic, and a scouting report string for the Scout Academy. Compositions for Years 1–3 are implemented in src/data/compositions.js. Years 4 and beyond fall back to a hardcoded stress test until authored.

Elite Kill Announcements

When an Ogre, General, or Catapult is destroyed, a kill announcement is displayed on screen identifying which player unit landed the killing blow. XP awarded for killing blow on these units is tripled (6 XP) instead of the standard 2 XP.

Enemy Battle Strategies

Enemies commit to an overarching strategy per year, then execute adaptively within that plan:

• — Full Assault — Throw everything at the walls simultaneously across all sections
• — Focused Strike — Heavy pressure on one or two sections to force reserve commitment
• — Artillery Standoff — Hang back and pound the wall with Catapults before advancing
• — Feint & Flank — Pressure one section to draw reserves, then commit hard to another

V2 Deferred

Enemy Mages are deferred to V2. Ladder mechanics and wall height gameplay effects also deferred to V2.

The Seven-Year Arc

Every recruit who survives seven years earns the right to leave as a hero. By default, a veteran has a 25% chance of choosing to stay. The Monument building tracks hero names and applies the attack speed bonus accordingly — each hero who stayed is recorded, making the Monument both a mechanical tracker and a piece of narrative history. Financial incentives (stipends, bonuses) can further raise retention chances.

Veterans Who Stay

Veterans who choose to stay remain on the active roster as high-level soldiers. They are the same unit type they always were, but with accumulated XP, levels, and battle experience. There are no special super-unit mechanics — their value is their combat effectiveness and the XP bonus they provide to the roster each off season.

The Mentorship / Legacy System

Veterans who depart as heroes may leave behind a lasting influence on future recruit cohorts — a passive buff to incoming soldiers in their archetype, a shared technique, or improved early leveling. This ties long-term investment to multi-generational payoff and rewards players who protect and develop their veterans.

See Section VI for the full XP curve and level thresholds.

Buildings are the primary gate for unit types, capacity, and special abilities. They operate on two layers: a dependency/unlock system determines what can be built, and quantity + level are managed separately for each structure type. All building costs are in gold unless otherwise noted.

Building Reference

Building Dependency Tree

• — Barracks → Archery Range → Scout Academy
• — Barracks → Sparring Ground → Officer Academy → Monument
• — Library → Mage Workshop / Hospital
• — Artisan Workshop → Armory / Weaponsmith / Siege Workshop (Siege Workshop also requires Archery Range)

Wall Upgrade Levels

The wall is upgraded per segment independently. Ladder mechanics are deferred to V2 — wall height has no gameplay effect in V1 beyond the damage reduction bonus.

Players choose their difficulty at the start of the game. This primarily determines how many years they must survive, not the speed of enemy escalation. The first ten years are the learning ramp regardless of difficulty — the same threat curve applies, the campaigns simply end at different points.

Two sources of variance ensure each playthrough feels distinct:

Enemy Variance

Each year's enemy composition is randomly selected from three options at battle start. One campaign may emphasize Catapults and Generals; another may rely on Ogre-led assaults with Goblin swarms. Players must read enemy development and adapt their building and recruitment decisions accordingly — no single strategy is universally optimal.

Recruit Variance

The annual recruit pool varies in composition. Some years bring melee-heavy cohorts; others skew toward healers or casters. Players must adapt their building and training priorities to make the most of what they receive.

Primary Win Condition: Survive to the end of the campaign. Game over occurs only when all player units are dead (total wipe).

Score: Total number of soldiers who achieved hero status (survived seven full years and were released honorably). This differentiates between "barely survived" and "truly excelled."

The game targets browser-native deployment on desktop. Mobile layout is deferred to a later sprint.

Core Technologies

File Structure

Architecture Pattern

Phaser owns the battle phase canvas entirely. The off season is rendered as standard HTML/CSS positioned alongside the canvas. A central GameState object holds all persistent data — unit rosters, building levels, resources, year count — and is read and written by both layers. Game logic (combat resolution, targeting, XP math) runs in JavaScript; Phaser handles visual playback only.

The following is a suggested build order for implementing the off season UI. Tasks are sequenced to allow each step to be tested in isolation before the next layer is added. Claude Code should treat this as a to-do list and adapt sequencing as needed based on implementation realities.

Phase A — Data & State Foundation

Phase B — Wizard Shell & Navigation

Phase C — Wall & Building Investment

Phase D — Personnel Table & Assignment

Phase E — Deployment Preview

Phase F — Scout Phase

Phase G — Integration & Handoff

The following design questions remain unresolved and should be addressed during or after playtesting: